objc2_metal/generated/

MTL4CommandBuffer.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
use objc2::__framework_prelude::*;
use objc2_foundation::*;

use crate::*;

extern_class!(
    /// Options to configure a command buffer before encoding work into it.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4commandbufferoptions?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct MTL4CommandBufferOptions;
);

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

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

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

impl MTL4CommandBufferOptions {
    extern_methods!(
        #[cfg(feature = "MTLLogState")]
        /// Contains information related to shader logging.
        ///
        /// To enable shader logging, call ``MTL4CommandBuffer/beginCommandBufferWithAllocator:options:`` with an instance
        /// of ``MTL4CommandBufferOptions`` that contains a non-`nil` ``MTLLogState`` instance in this property.
        ///
        /// Shader functions log messages until the command buffer ends.
        #[unsafe(method(logState))]
        #[unsafe(method_family = none)]
        pub fn logState(&self) -> Option<Retained<ProtocolObject<dyn MTLLogState>>>;

        #[cfg(feature = "MTLLogState")]
        /// Setter for [`logState`][Self::logState].
        #[unsafe(method(setLogState:))]
        #[unsafe(method_family = none)]
        pub fn setLogState(&self, log_state: Option<&ProtocolObject<dyn MTLLogState>>);
    );
}

/// Methods declared on superclass `NSObject`.
impl MTL4CommandBufferOptions {
    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 MTL4CommandBufferOptions {
    #[inline]
    fn default_retained() -> Retained<Self> {
        Self::new()
    }
}

extern_protocol!(
    /// Records a sequence of GPU commands.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4commandbuffer?language=objc)
    pub unsafe trait MTL4CommandBuffer: NSObjectProtocol {
        #[cfg(feature = "MTLDevice")]
        /// Returns the GPU device that this command buffer belongs to.
        #[unsafe(method(device))]
        #[unsafe(method_family = none)]
        fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>;

        /// Assigns an optional label with this command buffer.
        #[unsafe(method(label))]
        #[unsafe(method_family = none)]
        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)]
        fn setLabel(&self, label: Option<&NSString>);

        #[cfg(feature = "MTL4CommandAllocator")]
        /// Prepares a command buffer for encoding.
        ///
        /// Attaches the command buffer to the specified ``MTL4CommandAllocator`` and declares that the
        /// application is ready to encode commands into the command buffer.
        ///
        /// Command allocators only service a single command buffer at a time. If you need to issue multiple
        /// calls to this method simultaneously, for example, in a multi-threaded command encoding scenario,
        /// create multiple instances of ``MTLCommandAllocator`` and use one for each call.
        ///
        /// You can safely reuse command allocators after ending the command buffer using it by calling
        /// ``endCommandBuffer``.
        ///
        /// After calling this method, any prior calls to ``useResidencySet:`` and ``useResidencySets:count:``
        /// on this command buffer instance no longer apply. Make sure to call these methods again to signal
        /// your residency requirements to Metal.
        ///
        /// - Parameter allocator: ``MTL4CommandAllocator`` to attach to.
        #[unsafe(method(beginCommandBufferWithAllocator:))]
        #[unsafe(method_family = none)]
        fn beginCommandBufferWithAllocator(
            &self,
            allocator: &ProtocolObject<dyn MTL4CommandAllocator>,
        );

        #[cfg(feature = "MTL4CommandAllocator")]
        /// Prepares a command buffer for encoding with additional options.
        ///
        /// Attaches the command buffer to the specified ``MTL4CommandAllocator`` and declares that the
        /// application is ready to encode commands into the command buffer.
        ///
        /// Command allocators only service a single command buffer at a time. If you need to issue multiple
        /// calls to this method simultaneously, for example, in a multi-threaded command encoding scenario,
        /// create multiple instances of ``MTLCommandAllocator`` and use one for each call.
        ///
        /// You can safely reuse command allocators after ending the command buffer using it by calling
        /// ``endCommandBuffer``.
        ///
        /// After calling this method, any prior calls to ``useResidencySet:`` and ``useResidencySets:count:``
        /// on this command buffer instance no longer apply. Make sure to call these methods again to signal
        /// your residency requirements to Metal.
        ///
        /// The options you provide configure the command buffer only until the command buffer ends, in the
        /// next call to ``endCommandBuffer``.
        ///
        /// - Parameters:
        /// - allocator: ``MTL4CommandAllocator`` to attach to.
        /// - options: ``MTL4CommandBufferOptions`` to configure the command buffer.
        #[unsafe(method(beginCommandBufferWithAllocator:options:))]
        #[unsafe(method_family = none)]
        fn beginCommandBufferWithAllocator_options(
            &self,
            allocator: &ProtocolObject<dyn MTL4CommandAllocator>,
            options: &MTL4CommandBufferOptions,
        );

        /// Closes a command buffer to prepare it for submission to a command queue.
        ///
        /// Explicitly ending the command buffer allows you to reuse the ``MTL4CommandAllocator`` to start servicing other
        /// command buffers. It is an error to call ``commit`` on a command buffer previously recording before calling this
        /// method.
        #[unsafe(method(endCommandBuffer))]
        #[unsafe(method_family = none)]
        fn endCommandBuffer(&self);

        #[cfg(all(
            feature = "MTL4CommandEncoder",
            feature = "MTL4RenderCommandEncoder",
            feature = "MTL4RenderPass"
        ))]
        /// Creates a render command encoder from a render pass descriptor.
        ///
        /// - Parameters:
        /// - descriptor: Descriptor for the render pass.
        /// - Returns: The created ``MTL4RenderCommandEncoder`` instance, or `nil` if the function failed.
        #[unsafe(method(renderCommandEncoderWithDescriptor:))]
        #[unsafe(method_family = none)]
        fn renderCommandEncoderWithDescriptor(
            &self,
            descriptor: &MTL4RenderPassDescriptor,
        ) -> Option<Retained<ProtocolObject<dyn MTL4RenderCommandEncoder>>>;

        #[cfg(all(
            feature = "MTL4CommandEncoder",
            feature = "MTL4RenderCommandEncoder",
            feature = "MTL4RenderPass"
        ))]
        /// Creates a render command encoder from a render pass descriptor with additional options.
        ///
        /// This method creates a render command encoder to encode a render pass, whilst providing you the option to define
        /// some render pass characteristics via an instance of ``MTL4RenderEncoderOptions``.
        ///
        /// Use these options to configure suspending/resuming render command encoders, which allow you to encode render passes
        /// from multiple threads simultaneously.
        ///
        /// - Parameters:
        /// - descriptor: Descriptor for the render pass.
        /// - options: ``MTL4RenderEncoderOptions`` instance that provide render pass options.
        /// - Returns: The created ``MTL4RenderCommandEncoder`` instance, or `nil` if the function fails.
        #[unsafe(method(renderCommandEncoderWithDescriptor:options:))]
        #[unsafe(method_family = none)]
        fn renderCommandEncoderWithDescriptor_options(
            &self,
            descriptor: &MTL4RenderPassDescriptor,
            options: MTL4RenderEncoderOptions,
        ) -> Option<Retained<ProtocolObject<dyn MTL4RenderCommandEncoder>>>;

        #[cfg(all(feature = "MTL4CommandEncoder", feature = "MTL4ComputeCommandEncoder"))]
        /// Creates a compute command encoder.
        ///
        /// - Returns: The created ``MTL4ComputeCommandEncoder`` instance, or `nil` if the function fails.
        #[unsafe(method(computeCommandEncoder))]
        #[unsafe(method_family = none)]
        fn computeCommandEncoder(
            &self,
        ) -> Option<Retained<ProtocolObject<dyn MTL4ComputeCommandEncoder>>>;

        #[cfg(all(
            feature = "MTL4CommandEncoder",
            feature = "MTL4MachineLearningCommandEncoder"
        ))]
        /// Creates a machine learning command encoder.
        ///
        /// - Returns: The created ``MTL4MachineLearningCommandEncoder`` instance , or `nil` if the function fails.
        #[unsafe(method(machineLearningCommandEncoder))]
        #[unsafe(method_family = none)]
        fn machineLearningCommandEncoder(
            &self,
        ) -> Option<Retained<ProtocolObject<dyn MTL4MachineLearningCommandEncoder>>>;

        #[cfg(feature = "MTLResidencySet")]
        /// Marks a residency set as part of the command buffer's execution.
        ///
        /// Ensures that Metal makes resident the resources that residency set contains during execution of this command buffer.
        ///
        /// - Parameter residencySet: ``MTLResidencySet`` instance to mark resident.
        #[unsafe(method(useResidencySet:))]
        #[unsafe(method_family = none)]
        fn useResidencySet(&self, residency_set: &ProtocolObject<dyn MTLResidencySet>);

        #[cfg(feature = "MTLResidencySet")]
        /// Marks an array of residency sets as part of the command buffer's execution.
        ///
        /// Ensures that Metal makes resident the resources that residency sets contain during execution of this command buffer.
        ///
        /// - Parameters:
        /// - residencySets: Array of ``MTLResidencySet`` instances to mark resident.
        /// - count: Number of ``MTLResidencySet`` instances in the array.
        ///
        /// # Safety
        ///
        /// - `residency_sets` must be a valid pointer.
        /// - `count` might not be bounds-checked.
        #[unsafe(method(useResidencySets:count:))]
        #[unsafe(method_family = none)]
        unsafe fn useResidencySets_count(
            &self,
            residency_sets: NonNull<NonNull<ProtocolObject<dyn MTLResidencySet>>>,
            count: NSUInteger,
        );

        /// Pushes a string onto a stack of debug groups for this command buffer.
        ///
        /// - Parameter string: The string to push.
        #[unsafe(method(pushDebugGroup:))]
        #[unsafe(method_family = none)]
        fn pushDebugGroup(&self, string: &NSString);

        /// Pops the latest string from the stack of debug groups for this command buffer.
        #[unsafe(method(popDebugGroup))]
        #[unsafe(method_family = none)]
        fn popDebugGroup(&self);

        #[cfg(feature = "MTL4Counters")]
        /// Writes a GPU timestamp into the given counter heap.
        ///
        /// This method captures a timestamp after work prior to this command in the command buffer is complete.
        /// Work after this call may or may not have started.
        ///
        /// You are responsible for ensuring the `counterHeap` is of type ``MTL4CounterHeapType/MTL4CounterHeapTypeTimestamp``.
        ///
        /// - Parameters:
        /// - counterHeap: ``MTL4CounterHeap`` to write the timestamp into.
        /// - index: The index within the ``MTL4CounterHeap`` that Metal writes the timestamp to.
        ///
        /// # Safety
        ///
        /// `index` might not be bounds-checked.
        #[unsafe(method(writeTimestampIntoHeap:atIndex:))]
        #[unsafe(method_family = none)]
        unsafe fn writeTimestampIntoHeap_atIndex(
            &self,
            counter_heap: &ProtocolObject<dyn MTL4CounterHeap>,
            index: NSUInteger,
        );

        #[cfg(all(
            feature = "MTL4BufferRange",
            feature = "MTL4Counters",
            feature = "MTLFence",
            feature = "MTLGPUAddress"
        ))]
        /// Encodes a command that resolves an opaque counter heap into a buffer.
        ///
        /// The command this method encodes converts the data within `counterHeap` into a common format
        /// and stores it into the `bufferRange` parameter.
        ///
        /// The command places each entry in the counter heap within `range` sequentially, starting at `alignedOffset`.
        /// Each entry needs to be a fixed size that you can query by calling the
        /// ``MTLDevice/sizeOfCounterHeapEntry:`` method.
        ///
        /// This command runs during the `MTLStageBlit` stage of the GPU timeline. Barrier against this stage
        /// to ensure the data is present in the resolve buffer parameter before you access it.
        ///
        /// - Note: Your app needs ensure the GPU places data in the heap before you resolve it by
        /// synchronizing this stage with other GPU operations.
        ///
        /// Similarly, your app needs to synchronize any GPU accesses to `bufferRange` after
        /// the command completes with barrier.
        ///
        /// If your app needs to access `bufferRange` from the CPU, signal an ``MTLSharedEvent``
        /// to notify the CPU when it's ready.
        /// Alternatively, you can resolve the heap's data from the CPU by calling
        /// the heap's ``MTL4CounterHeap/resolveCounterRange:`` method.
        ///
        /// - Parameters:
        /// - counterHeap: A heap the command resolves.
        /// - range: A range of index values within the heap the command resolves.
        /// - bufferRange: The buffer the command saves the data it resolves into.
        /// - fenceToWait: A fence the GPU waits for before starting, if applicable; otherwise `nil`.
        /// - fenceToUpdate: A fence the system updates after the command finishes resolving the data; otherwise `nil`.
        ///
        /// # Safety
        ///
        /// - `range` might not be bounds-checked.
        /// - `bufferRange` might not be bounds-checked.
        #[unsafe(method(resolveCounterHeap:withRange:intoBuffer:waitFence:updateFence:))]
        #[unsafe(method_family = none)]
        unsafe fn resolveCounterHeap_withRange_intoBuffer_waitFence_updateFence(
            &self,
            counter_heap: &ProtocolObject<dyn MTL4CounterHeap>,
            range: NSRange,
            buffer_range: MTL4BufferRange,
            fence_to_wait: Option<&ProtocolObject<dyn MTLFence>>,
            fence_to_update: Option<&ProtocolObject<dyn MTLFence>>,
        );
    }
);