objc2_metal/generated/

MTL4CommandQueue.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
#[cfg(feature = "dispatch2")]
use dispatch2::*;
use objc2::__framework_prelude::*;
use objc2_foundation::*;

use crate::*;

/// Enumeration of kinds of errors that committing an array of command buffers instances can produce.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4commandqueueerror?language=objc)
// NS_ENUM
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct MTL4CommandQueueError(pub NSInteger);
impl MTL4CommandQueueError {
    /// Indicates the absence of any problems.
    #[doc(alias = "MTL4CommandQueueErrorNone")]
    pub const None: Self = Self(0);
    /// Indicates the workload takes longer to execute than the system allows.
    #[doc(alias = "MTL4CommandQueueErrorTimeout")]
    pub const Timeout: Self = Self(1);
    /// Indicates a process doesn’t have access to a GPU device.
    #[doc(alias = "MTL4CommandQueueErrorNotPermitted")]
    pub const NotPermitted: Self = Self(2);
    /// Indicates the GPU doesn’t have sufficient memory to execute a command buffer.
    #[doc(alias = "MTL4CommandQueueErrorOutOfMemory")]
    pub const OutOfMemory: Self = Self(3);
    /// Indicates the physical removal of the GPU before the command buffer completed.
    #[doc(alias = "MTL4CommandQueueErrorDeviceRemoved")]
    pub const DeviceRemoved: Self = Self(4);
    /// Indicates that the system revokes GPU access because it’s responsible for too many timeouts or hangs.
    #[doc(alias = "MTL4CommandQueueErrorAccessRevoked")]
    pub const AccessRevoked: Self = Self(5);
    /// Indicates an internal problem in the Metal framework.
    #[doc(alias = "MTL4CommandQueueErrorInternal")]
    pub const Internal: Self = Self(6);
}

unsafe impl Encode for MTL4CommandQueueError {
    const ENCODING: Encoding = NSInteger::ENCODING;
}

unsafe impl RefEncode for MTL4CommandQueueError {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

extern "C" {
    /// [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4commandqueueerrordomain?language=objc)
    pub static MTL4CommandQueueErrorDomain: &'static NSErrorDomain;
}

extern_class!(
    /// Represents options to configure a commit operation on a command queue.
    ///
    /// You pass these options as a parameter when you call ``MTL4CommandQueue/commit:count:options:``.
    ///
    /// - Note Instances of this class are not thread-safe. If your app modifies a shared commit options instance from
    /// multiple threads simultaneously, you are responsible for providing external synchronization.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4commitoptions?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct MTL4CommitOptions;
);

extern_conformance!(
    unsafe impl NSObjectProtocol for MTL4CommitOptions {}
);

impl MTL4CommitOptions {
    extern_methods!(
        #[cfg(all(feature = "MTL4CommitFeedback", feature = "block2"))]
        /// Registers a commit feedback handler that Metal calls with feedback data when available.
        ///
        /// - Parameter block: ``MTL4CommitFeedbackHandler`` that Metal invokes.
        ///
        /// # Safety
        ///
        /// `block` must be a valid pointer.
        #[unsafe(method(addFeedbackHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn addFeedbackHandler(&self, block: MTL4CommitFeedbackHandler);
    );
}

/// Methods declared on superclass `NSObject`.
impl MTL4CommitOptions {
    extern_methods!(
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub fn init(this: Allocated<Self>) -> Retained<Self>;

        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub fn new() -> Retained<Self>;
    );
}

impl DefaultRetained for MTL4CommitOptions {
    #[inline]
    fn default_retained() -> Retained<Self> {
        Self::new()
    }
}

extern_class!(
    /// Groups together parameters for the creation of a new command queue.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4commandqueuedescriptor?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct MTL4CommandQueueDescriptor;
);

extern_conformance!(
    unsafe impl NSCopying for MTL4CommandQueueDescriptor {}
);

unsafe impl CopyingHelper for MTL4CommandQueueDescriptor {
    type Result = Self;
}

extern_conformance!(
    unsafe impl NSObjectProtocol for MTL4CommandQueueDescriptor {}
);

impl MTL4CommandQueueDescriptor {
    extern_methods!(
        /// Assigns an optional label to the command queue instance for debugging purposes.
        #[unsafe(method(label))]
        #[unsafe(method_family = none)]
        pub fn label(&self) -> Option<Retained<NSString>>;

        /// Setter for [`label`][Self::label].
        ///
        /// This is [copied][objc2_foundation::NSCopying::copy] when set.
        #[unsafe(method(setLabel:))]
        #[unsafe(method_family = none)]
        pub fn setLabel(&self, label: Option<&NSString>);

        #[cfg(feature = "dispatch2")]
        /// Assigns a dispatch queue to which Metal submits feedback notification blocks.
        ///
        /// When you assign a dispatch queue via this method, Metal requires that the queue parameter you provide is a serial queue.
        ///
        /// If you set the value of property to `nil`, the default, Metal allocates an internal dispatch queue to service feedback
        /// notifications.
        ///
        /// # Safety
        ///
        /// This is not retained internally, you must ensure the object is still alive.
        #[unsafe(method(feedbackQueue))]
        #[unsafe(method_family = none)]
        pub unsafe fn feedbackQueue(&self) -> Option<Retained<DispatchQueue>>;

        #[cfg(feature = "dispatch2")]
        /// Setter for [`feedbackQueue`][Self::feedbackQueue].
        ///
        /// # Safety
        ///
        /// - `feedback_queue` possibly has additional threading requirements.
        /// - This is unretained, you must ensure the object is kept alive while in use.
        #[unsafe(method(setFeedbackQueue:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setFeedbackQueue(&self, feedback_queue: Option<&DispatchQueue>);
    );
}

/// Methods declared on superclass `NSObject`.
impl MTL4CommandQueueDescriptor {
    extern_methods!(
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub fn init(this: Allocated<Self>) -> Retained<Self>;

        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub fn new() -> Retained<Self>;
    );
}

impl DefaultRetained for MTL4CommandQueueDescriptor {
    #[inline]
    fn default_retained() -> Retained<Self> {
        Self::new()
    }
}

/// Groups together arguments for an operation to update a sparse texture mapping.
///
/// When performing a sparse mapping update, you are responsible for issuing a barrier against stage `MTLStageResourceState`.
///
/// You can determine the sparse texture tier by calling ``MTLTexture/sparseTextureTier``.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4updatesparsetexturemappingoperation?language=objc)
#[cfg(all(feature = "MTLResourceStateCommandEncoder", feature = "MTLTypes"))]
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct MTL4UpdateSparseTextureMappingOperation {
    /// The mode of the mapping operation to perform.
    ///
    /// When mode is ``MTLSparseTextureMappingMode/MTLSparseTextureMappingModeMap``,
    /// Metal walks the tiles in the region in X, Y, then Z order, assigning the next
    /// tile from the heap in increasing order, starting at ``heapOffset``.
    ///
    /// When mode is ``MTLSparseTextureMappingMode/MTLSparseTextureMappingModeUnmap``,
    /// Metal unmaps the tiles in the region, ignoring the contents of member ``heapOffset``.
    pub mode: MTLSparseTextureMappingMode,
    /// The region in the texture to update, in tiles.
    ///
    /// When ``textureLevel`` is equal to the texture's ``MTLTexture/firstMipmapInTail``,
    /// set `origin.y` to `0` and `size.height` to `1`.
    pub textureRegion: MTLRegion,
    /// The index of the mipmap level in the texture to update.
    ///
    /// Provide a value between `0` and the texture's ``MTLTexture/firstMipmapInTail``.
    pub textureLevel: NSUInteger,
    /// The index of the array slice in the texture to update.
    ///
    /// Provide `0` in this member if the texture type is not an array.
    pub textureSlice: NSUInteger,
    /// The starting offset in the heap, in tiles.
    pub heapOffset: NSUInteger,
}

#[cfg(all(feature = "MTLResourceStateCommandEncoder", feature = "MTLTypes"))]
unsafe impl Encode for MTL4UpdateSparseTextureMappingOperation {
    const ENCODING: Encoding = Encoding::Struct(
        "?",
        &[
            <MTLSparseTextureMappingMode>::ENCODING,
            <MTLRegion>::ENCODING,
            <NSUInteger>::ENCODING,
            <NSUInteger>::ENCODING,
            <NSUInteger>::ENCODING,
        ],
    );
}

#[cfg(all(feature = "MTLResourceStateCommandEncoder", feature = "MTLTypes"))]
unsafe impl RefEncode for MTL4UpdateSparseTextureMappingOperation {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

/// Groups together arguments for an operation to copy a sparse texture mapping.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4copysparsetexturemappingoperation?language=objc)
#[cfg(feature = "MTLTypes")]
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct MTL4CopySparseTextureMappingOperation {
    /// The region in the source texture, in tiles.
    ///
    /// The tiles remain mapped in the source texture.
    ///
    /// When ``sourceLevel`` is equal to the source texture's ``MTLTexture/firstMipmapInTail``,
    /// set `origin.y` to `0` and `size.height` to `1`.
    pub sourceRegion: MTLRegion,
    /// The index of the mipmap level in the source texture.
    ///
    /// Provide a value between `0` and the source texture's ``MTLTexture/firstMipmapInTail``.
    ///
    /// When ``sourceLevel`` is equal to the source texture's ``MTLTexture/firstMipmapInTail``,
    /// set ``destinationLevel`` to the destination texture's ``MTLTexture/firstMipmapInTail``.
    pub sourceLevel: NSUInteger,
    /// The index of the array slice in the texture source of the copy operation.
    ///
    /// Provide `0` in this member if the texture type is not an array.
    pub sourceSlice: NSUInteger,
    /// The origin in the destination texture to copy into, in tiles.
    ///
    /// The X, Y and Z coordinates of the tiles relative to the origin match the same
    /// coordinates in the source region.
    ///
    /// When ``destinationLevel`` is equal to the destination texture's ``MTLTexture/firstMipmapInTail``,
    /// set `destinationOrigin.y` to `0`.
    pub destinationOrigin: MTLOrigin,
    /// The index of the mipmap level in the destination texture.
    ///
    /// Provide a value between `0` and the destination texture's ``MTLTexture/firstMipmapInTail``.
    ///
    /// When ``sourceLevel`` is equal to the source texture's ``MTLTexture/firstMipmapInTail``,
    /// set ``destinationLevel`` to the destination texture's ``MTLTexture/firstMipmapInTail``.
    pub destinationLevel: NSUInteger,
    /// The index of the array slice in the destination texture to copy into.
    ///
    /// Provide `0` in this member if the texture type is not an array.
    pub destinationSlice: NSUInteger,
}

#[cfg(feature = "MTLTypes")]
unsafe impl Encode for MTL4CopySparseTextureMappingOperation {
    const ENCODING: Encoding = Encoding::Struct(
        "?",
        &[
            <MTLRegion>::ENCODING,
            <NSUInteger>::ENCODING,
            <NSUInteger>::ENCODING,
            <MTLOrigin>::ENCODING,
            <NSUInteger>::ENCODING,
            <NSUInteger>::ENCODING,
        ],
    );
}

#[cfg(feature = "MTLTypes")]
unsafe impl RefEncode for MTL4CopySparseTextureMappingOperation {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

/// Groups together arguments for an operation to update a sparse buffer mapping.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4updatesparsebuffermappingoperation?language=objc)
#[cfg(feature = "MTLResourceStateCommandEncoder")]
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct MTL4UpdateSparseBufferMappingOperation {
    /// The mode of the mapping operation to perform.
    ///
    /// When mode is ``MTLSparseTextureMappingMode/MTLSparseTextureMappingModeMap``,
    /// Metal walks the tiles in the range in buffer offset order, assigning the
    /// next tile from the heap in increasing order, starting at ``heapOffset``.
    ///
    /// When mode is ``MTLSparseTextureMappingMode/MTLSparseTextureMappingModeUnmap``,
    /// Metal unmaps the tiles in the range, and ignores the value of member ``heapOffset``.
    pub mode: MTLSparseTextureMappingMode,
    /// The range in the buffer, in tiles.
    pub bufferRange: NSRange,
    /// The starting offset in the heap, in tiles.
    pub heapOffset: NSUInteger,
}

#[cfg(feature = "MTLResourceStateCommandEncoder")]
unsafe impl Encode for MTL4UpdateSparseBufferMappingOperation {
    const ENCODING: Encoding = Encoding::Struct(
        "?",
        &[
            <MTLSparseTextureMappingMode>::ENCODING,
            <NSRange>::ENCODING,
            <NSUInteger>::ENCODING,
        ],
    );
}

#[cfg(feature = "MTLResourceStateCommandEncoder")]
unsafe impl RefEncode for MTL4UpdateSparseBufferMappingOperation {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

/// Groups together arguments for an operation to copy a sparse buffer mapping.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4copysparsebuffermappingoperation?language=objc)
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct MTL4CopySparseBufferMappingOperation {
    /// The range in the source buffer, in tiles.
    ///
    /// The tiles remain mapped in the source buffer.
    pub sourceRange: NSRange,
    /// The origin in the destination buffer, in tiles.
    pub destinationOffset: NSUInteger,
}

unsafe impl Encode for MTL4CopySparseBufferMappingOperation {
    const ENCODING: Encoding =
        Encoding::Struct("?", &[<NSRange>::ENCODING, <NSUInteger>::ENCODING]);
}

unsafe impl RefEncode for MTL4CopySparseBufferMappingOperation {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

extern_protocol!(
    /// An abstraction representing a command queue that you use commit and synchronize command buffers and to
    /// perform other GPU operations.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4commandqueue?language=objc)
    pub unsafe trait MTL4CommandQueue: NSObjectProtocol + Send + Sync {
        #[cfg(feature = "MTLDevice")]
        /// Returns the GPU device that the command queue belongs to.
        #[unsafe(method(device))]
        #[unsafe(method_family = none)]
        fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>;

        /// Obtains this queue's optional label for debugging purposes.
        #[unsafe(method(label))]
        #[unsafe(method_family = none)]
        fn label(&self) -> Option<Retained<NSString>>;

        #[cfg(feature = "MTL4CommandBuffer")]
        /// Enqueues an array of command buffers for execution.
        ///
        /// The order in which you sort the command buffers in the array is meaningful, especially when it contains suspending/resuming
        /// render passes. A suspending/resuming render pass is a render pass you create by calling
        /// ``MTL4CommandBuffer/renderCommandEncoderWithDescriptor:options:``,
        /// and provide `MTL4RenderEncoderOptionSuspending` or `MTL4RenderEncoderOptionResuming` for the `options` parameter.
        ///
        /// If your command buffers contain suspend/resume render passes, ensure that the first command buffer only suspends,
        /// and the last one only resumes. Additionally, make sure that all intermediate command buffers are both suspending
        /// and resuming.
        ///
        /// - Parameters:
        /// - commandBuffers: an array of ``MTL4CommandBuffer``.
        /// - count: the number of ``MTL4CommandBuffer`` instances in the `commandBuffers` array.
        ///
        /// # Safety
        ///
        /// - `command_buffers` must be a valid pointer.
        /// - `count` might not be bounds-checked.
        #[unsafe(method(commit:count:))]
        #[unsafe(method_family = none)]
        unsafe fn commit_count(
            &self,
            command_buffers: NonNull<NonNull<ProtocolObject<dyn MTL4CommandBuffer>>>,
            count: NSUInteger,
        );

        #[cfg(feature = "MTL4CommandBuffer")]
        /// Enqueues an array of command buffer instances for execution with a set of options.
        ///
        /// Provide an ``MTL4CommitOptions`` instance to configure the commit operation.
        ///
        /// The order in which you sort the command buffers in the array is meaningful, especially when it contains suspending/resuming
        /// render passes. A suspending/resuming render pass is a render pass you create by calling
        /// ``MTL4CommandBuffer/renderCommandEncoderWithDescriptor:options:``,
        /// and provide `MTL4RenderEncoderOptionSuspending` or `MTL4RenderEncoderOptionResuming` for the `options` parameter.
        ///
        /// If your command buffers contain suspend/resume render passes, ensure that the first command buffer only suspends,
        /// and the last one only resumes. Additionally, make sure that all intermediate command buffers are both suspending
        /// and resuming.
        ///
        /// When you commit work from multiple threads, modifying and reusing the same options instance,
        /// you are responsible for externally synchronizing access to it.
        ///
        /// - Parameters:
        /// - commandBuffers: an array of ``MTL4CommandBuffer``.
        /// - count: the number of ``MTL4CommandBuffer`` instances in the `commandBuffers` array.
        /// - options: an instance of ``MTL4CommitOptions`` that configures the commit operation.
        ///
        /// # Safety
        ///
        /// - `command_buffers` must be a valid pointer.
        /// - `count` might not be bounds-checked.
        #[unsafe(method(commit:count:options:))]
        #[unsafe(method_family = none)]
        unsafe fn commit_count_options(
            &self,
            command_buffers: NonNull<NonNull<ProtocolObject<dyn MTL4CommandBuffer>>>,
            count: NSUInteger,
            options: &MTL4CommitOptions,
        );

        #[cfg(feature = "MTLEvent")]
        /// Schedules an operation to signal a GPU event with a specific value after all GPU work prior to this point is complete.
        ///
        /// - Parameters:
        /// - event: ``MTLEvent`` to signal.
        /// - value: the value to signal the ``MTLEvent`` with.
        #[unsafe(method(signalEvent:value:))]
        #[unsafe(method_family = none)]
        fn signalEvent_value(&self, event: &ProtocolObject<dyn MTLEvent>, value: u64);

        #[cfg(feature = "MTLEvent")]
        /// Schedules an operation to wait for a GPU event of a specific value before continuing to execute any future GPU work.
        ///
        /// - Parameters:
        /// - event: ``MTLEvent`` to wait on.
        /// - value: the specific value to wait for.
        #[unsafe(method(waitForEvent:value:))]
        #[unsafe(method_family = none)]
        fn waitForEvent_value(&self, event: &ProtocolObject<dyn MTLEvent>, value: u64);

        #[cfg(feature = "MTLDrawable")]
        /// Schedules a signal operation on the command queue to indicate when rendering to a Metal drawable is complete.
        ///
        /// Signaling when rendering to a ``MTLDrawable`` instance is complete indicates that it's safe to present it to the
        /// display.
        ///
        /// You are responsible for calling this method after committing all command buffers that contain commands targeting
        /// this drawable, and before calling ``MTLDrawable/present``, ``MTLDrawable/presentAtTime:``, or
        /// ``MTLDrawable/presentAfterMinimumDuration:``.
        ///
        /// - Note: This method doesn't trigger the presentation of the drawable, and fails if you call it after any of the
        /// present methods, or if you call it multiple times.
        ///
        /// Metal doesn't guarantee that command buffers you commit to the command queue after calling this method execute
        /// before presentation.
        ///
        /// - Parameters:
        /// - drawable: ``MTLDrawable`` instance to signal.
        #[unsafe(method(signalDrawable:))]
        #[unsafe(method_family = none)]
        fn signalDrawable(&self, drawable: &ProtocolObject<dyn MTLDrawable>);

        #[cfg(feature = "MTLDrawable")]
        /// Schedules a wait operation on the command queue to ensure the display is no longer using a specific Metal drawable.
        ///
        /// Use this method to ensure the display is no longer using a ``MTLDrawable`` instance before executing any subsequent
        /// commands.
        ///
        /// This method returns immediately and doesn't perform any synchronization on the current thread. You are responsible
        /// for calling this method before committing any command buffers containing commands that target this drawable.
        ///
        /// Call this method multiple times if you commit your command buffers to multiple command queues.
        ///
        /// - Parameters:
        /// - drawable: ``MTLDrawable`` instance to signal.
        #[unsafe(method(waitForDrawable:))]
        #[unsafe(method_family = none)]
        fn waitForDrawable(&self, drawable: &ProtocolObject<dyn MTLDrawable>);

        #[cfg(feature = "MTLResidencySet")]
        /// Marks a residency set as part of this command queue.
        ///
        /// Ensures that Metal makes the residency set resident during the execution of all command buffers you commit to this
        /// command queue.
        ///
        /// Each command queue supports up to 32 unique residency set instances.
        ///
        /// - Parameter residencySet: ``MTLResidencySet`` to add to the command queue.
        #[unsafe(method(addResidencySet:))]
        #[unsafe(method_family = none)]
        fn addResidencySet(&self, residency_set: &ProtocolObject<dyn MTLResidencySet>);

        #[cfg(feature = "MTLResidencySet")]
        /// Marks an array of residency sets as part of this command queue.
        ///
        /// Ensures that Metal makes the residency set resident during the execution of all command buffers you commit to this
        /// command queue.
        ///
        /// Each command queue supports up to 32 unique residency set instances.
        ///
        /// - Parameters:
        /// - residencySets: Array of ``MTLResidencySet`` instances to add to the command queue.
        /// - count: Number of ``MTLResidencySet`` instances in the array.
        ///
        /// # Safety
        ///
        /// - `residency_sets` must be a valid pointer.
        /// - `count` might not be bounds-checked.
        #[unsafe(method(addResidencySets:count:))]
        #[unsafe(method_family = none)]
        unsafe fn addResidencySets_count(
            &self,
            residency_sets: NonNull<NonNull<ProtocolObject<dyn MTLResidencySet>>>,
            count: NSUInteger,
        );

        #[cfg(feature = "MTLResidencySet")]
        /// Removes a residency set from the command queue.
        ///
        /// After calling this method ensures only the remaining residency sets remain resident during the execution of the
        /// command buffers you commit this command queue.
        ///
        /// - Parameter residencySet: ``MTLResidencySet`` instance to remove from the command queue.
        #[unsafe(method(removeResidencySet:))]
        #[unsafe(method_family = none)]
        fn removeResidencySet(&self, residency_set: &ProtocolObject<dyn MTLResidencySet>);

        #[cfg(feature = "MTLResidencySet")]
        /// Removes multiple residency sets from the command queue.
        ///
        /// After calling this method ensures only the remaining residency sets remain resident during the execution of the
        /// command buffers you commit this command queue.
        ///
        /// - Parameters:
        /// - residencySets: Array of ``MTLResidencySet`` instances to remove from the command queue.
        /// - count: Number of ``MTLResidencySet`` instances in the array.
        ///
        /// # Safety
        ///
        /// - `residency_sets` must be a valid pointer.
        /// - `count` might not be bounds-checked.
        #[unsafe(method(removeResidencySets:count:))]
        #[unsafe(method_family = none)]
        unsafe fn removeResidencySets_count(
            &self,
            residency_sets: NonNull<NonNull<ProtocolObject<dyn MTLResidencySet>>>,
            count: NSUInteger,
        );

        #[cfg(all(
            feature = "MTLAllocation",
            feature = "MTLHeap",
            feature = "MTLResource",
            feature = "MTLResourceStateCommandEncoder",
            feature = "MTLTexture",
            feature = "MTLTypes"
        ))]
        /// Updates multiple regions within a placement sparse texture to alias specific tiles of a Metal heap.
        ///
        /// You can provide a `nil` parameter to the `heap` argument only if when you perform unmap operations. Otherwise, you are
        /// responsible for ensuring the heap is non-nil and has a
        /// ``MTLHeapDescriptor/maxCompatiblePlacementSparsePageSize`` of at least the texture's
        /// ``MTLTextureDescriptor/placementSparsePageSize``.
        ///
        /// When performing a sparse mapping update, you are responsible for issuing a barrier against stage `MTLStageResourceState`.
        ///
        /// You can determine the sparse texture tier by calling `MTLTexture/sparseTextureTier`.
        ///
        /// - Parameters:
        /// - texture: A placement sparse ``MTLTexture``.
        /// - heap: ``MTLHeap`` you allocate with type ``MTLHeapType/MTLHeapTypePlacement``.
        /// - operations: An array of ``MTL4UpdateSparseTextureMappingOperation`` instances to perform.
        /// - count: Number of operations to perform.
        ///
        /// # Safety
        ///
        /// - `texture` may need to be synchronized.
        /// - `texture` may be unretained, you must ensure it is kept alive while in use.
        /// - `operations` must be a valid pointer.
        /// - `count` might not be bounds-checked.
        #[unsafe(method(updateTextureMappings:heap:operations:count:))]
        #[unsafe(method_family = none)]
        unsafe fn updateTextureMappings_heap_operations_count(
            &self,
            texture: &ProtocolObject<dyn MTLTexture>,
            heap: Option<&ProtocolObject<dyn MTLHeap>>,
            operations: NonNull<MTL4UpdateSparseTextureMappingOperation>,
            count: NSUInteger,
        );

        #[cfg(all(
            feature = "MTLAllocation",
            feature = "MTLResource",
            feature = "MTLTexture",
            feature = "MTLTypes"
        ))]
        /// Copies multiple regions within a source placement sparse texture to a destination placement sparse texture.
        ///
        /// You are responsible for ensuring the source and destination textures have the same
        /// ``MTLTextureDescriptor/placementSparsePageSize``.
        ///
        /// Additionally, you are responsible for ensuring that the source and destination textures don't use the same aliased tiles
        /// at the same time.
        ///
        /// - Note: If a sparse texture and a sparse buffer share the same backing tiles, these don't provide you
        /// you with meaningful views of the other resource’s data.
        ///
        /// - Parameters:
        /// - sourceTexture: The source placement sparse ``MTLTexture``.
        /// - destinationTexture: The destination placement sparse ``MTLTexture``.
        /// - operations: An array of ``MTL4CopySparseTextureMappingOperation`` instances to perform.
        /// - count: Number of operations to perform.
        ///
        /// # Safety
        ///
        /// - `source_texture` may need to be synchronized.
        /// - `source_texture` may be unretained, you must ensure it is kept alive while in use.
        /// - `destination_texture` may need to be synchronized.
        /// - `destination_texture` may be unretained, you must ensure it is kept alive while in use.
        /// - `operations` must be a valid pointer.
        /// - `count` might not be bounds-checked.
        #[unsafe(method(copyTextureMappingsFromTexture:toTexture:operations:count:))]
        #[unsafe(method_family = none)]
        unsafe fn copyTextureMappingsFromTexture_toTexture_operations_count(
            &self,
            source_texture: &ProtocolObject<dyn MTLTexture>,
            destination_texture: &ProtocolObject<dyn MTLTexture>,
            operations: NonNull<MTL4CopySparseTextureMappingOperation>,
            count: NSUInteger,
        );

        #[cfg(all(
            feature = "MTLAllocation",
            feature = "MTLBuffer",
            feature = "MTLHeap",
            feature = "MTLResource",
            feature = "MTLResourceStateCommandEncoder"
        ))]
        /// Updates multiple regions within a placement sparse buffer to alias specific tiles from a Metal heap.
        ///
        /// You can provide a `nil` parameter to the `heap` argument only when you perform unmap operations. Otherwise, you are
        /// responsible for ensuring parameter `heap` references an ``MTLHeap`` that has a ``MTLHeapDescriptor/maxCompatiblePlacementSparsePageSize``
        /// of at least the buffer's `placementSparsePageSize` you assign when creating the sparse buffer via
        /// ``MTLDevice/newBufferWithLength:options:placementSparsePageSize:``.
        ///
        /// - Parameters:
        /// - buffer: A placement sparse ``MTLBuffer``.
        /// - heap: An ``MTLHeap`` you allocate with type ``MTLHeapType/MTLHeapTypePlacement``.
        /// - operations: An array of ``MTL4UpdateSparseBufferMappingOperation`` instances to perform.
        /// - count: Number of operations to perform.
        ///
        /// # Safety
        ///
        /// - `buffer` may need to be synchronized.
        /// - `buffer` may be unretained, you must ensure it is kept alive while in use.
        /// - `buffer` contents should be of the correct type.
        /// - `operations` must be a valid pointer.
        /// - `count` might not be bounds-checked.
        #[unsafe(method(updateBufferMappings:heap:operations:count:))]
        #[unsafe(method_family = none)]
        unsafe fn updateBufferMappings_heap_operations_count(
            &self,
            buffer: &ProtocolObject<dyn MTLBuffer>,
            heap: Option<&ProtocolObject<dyn MTLHeap>>,
            operations: NonNull<MTL4UpdateSparseBufferMappingOperation>,
            count: NSUInteger,
        );

        #[cfg(all(
            feature = "MTLAllocation",
            feature = "MTLBuffer",
            feature = "MTLResource"
        ))]
        /// Copies multiple offsets within a source placement sparse buffer to a destination placement sparse buffer.
        ///
        /// You are responsible for ensuring the source destination sparse buffers have the same `placementSparsePageSize` when
        /// you create them via ``MTLDevice/newBufferWithLength:options:placementSparsePageSize:``.
        ///
        /// Additionally, you are responsible for ensuring both the source and destination sparse buffers don't use the same aliased
        /// tiles at the same time.
        ///
        /// - Note: If a sparse texture and a sparse buffer share the same backing tiles, these don't provide you
        /// with meaningful views of the other resource’s data.
        ///
        /// - Parameters:
        /// - sourceBuffer: The source placement sparse ``MTLBuffer``.
        /// - destinationBuffer: The destination placement sparse ``MTLBuffer``.
        /// - operations: An array of ``MTL4CopySparseBufferMappingOperation`` instances to perform.
        /// - count: Number of operations to perform.
        ///
        /// # Safety
        ///
        /// - `source_buffer` may need to be synchronized.
        /// - `source_buffer` may be unretained, you must ensure it is kept alive while in use.
        /// - `source_buffer` contents should be of the correct type.
        /// - `destination_buffer` may need to be synchronized.
        /// - `destination_buffer` may be unretained, you must ensure it is kept alive while in use.
        /// - `destination_buffer` contents should be of the correct type.
        /// - `operations` must be a valid pointer.
        /// - `count` might not be bounds-checked.
        #[unsafe(method(copyBufferMappingsFromBuffer:toBuffer:operations:count:))]
        #[unsafe(method_family = none)]
        unsafe fn copyBufferMappingsFromBuffer_toBuffer_operations_count(
            &self,
            source_buffer: &ProtocolObject<dyn MTLBuffer>,
            destination_buffer: &ProtocolObject<dyn MTLBuffer>,
            operations: NonNull<MTL4CopySparseBufferMappingOperation>,
            count: NSUInteger,
        );
    }
);