objc2_metal_kit/generated/

MTKModel.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 objc2_metal::*;
#[cfg(feature = "objc2-model-io")]
use objc2_model_io::*;

use crate::*;

/// MTKModelErrors
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/metalkit/mtkmodelerror?language=objc)
// NS_TYPED_ENUM
pub type MTKModelError = NSString;

extern "C" {
    /// [Apple's documentation](https://developer.apple.com/documentation/metalkit/mtkmodelerrordomain?language=objc)
    pub static MTKModelErrorDomain: &'static MTKModelError;
}

extern "C" {
    /// [Apple's documentation](https://developer.apple.com/documentation/metalkit/mtkmodelerrorkey?language=objc)
    pub static MTKModelErrorKey: &'static MTKModelError;
}

extern_class!(
    /// Allocator passed to MDLAsset init method to load vertex and index data directly into Metal buffers.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/metalkit/mtkmeshbufferallocator?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct MTKMeshBufferAllocator;
);

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

impl MTKMeshBufferAllocator {
    extern_methods!(
        /// Must initialize with device
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        /// Initialize the allocator with a device to be used to create buffers.
        ///
        /// The designated initializer for this class.
        #[unsafe(method(initWithDevice:))]
        #[unsafe(method_family = init)]
        pub fn initWithDevice(
            this: Allocated<Self>,
            device: &ProtocolObject<dyn MTLDevice>,
        ) -> Retained<Self>;

        /// Device used to create buffers.
        #[unsafe(method(device))]
        #[unsafe(method_family = none)]
        pub fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>;
    );
}

/// Methods declared on superclass `NSObject`.
impl MTKMeshBufferAllocator {
    extern_methods!(
        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

extern_class!(
    /// Mesh buffer created by MTKMeshBufferAllocator when Model I/O needs to memory for vertex or index data backing.
    ///
    /// Memory backing these buffer are Metal buffers.  Model I/O will load index and vertex data from from a model asset directly in to the Metal buffer.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/metalkit/mtkmeshbuffer?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct MTKMeshBuffer;
);

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

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

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

impl MTKMeshBuffer {
    extern_methods!(
        /// Only an MTKMeshBufferAllocator object can initilize a MTKMeshBuffer object
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        /// Size in bytes of the buffer allocation.
        #[unsafe(method(length))]
        #[unsafe(method_family = none)]
        pub fn length(&self) -> NSUInteger;

        /// Allocator object used to create this buffer.
        ///
        /// This allcoator is stored so that it can be used by Model I/O for copy and relayout operations (such as when a new vertex descriptor is applied to a vertex buffer).
        #[unsafe(method(allocator))]
        #[unsafe(method_family = none)]
        pub fn allocator(&self) -> Retained<MTKMeshBufferAllocator>;

        #[cfg(feature = "objc2-model-io")]
        /// Zone from which this buffer was created (if it was created from a zone).
        ///
        /// A single MetalBuffer is allocated for each zone.  Each zone could have many MTKMeshBuffers, each with it's own offset.  If a MTKMeshBufferAllocator is used, Model I/O will attempt to load all vertex and index data of a single mesh into a single zone.  This allows the GPU to achieve a higher cache hit rate when drawing the mesh.  So although there maybe many MTKMeshBuffers for a model they will be backed with the same contigous MetalBuffer.
        #[unsafe(method(zone))]
        #[unsafe(method_family = none)]
        pub fn zone(&self) -> Option<Retained<ProtocolObject<dyn MDLMeshBufferZone>>>;

        /// Metal Buffer backing vertex/index data.
        ///
        /// Many MTKMeshBuffers may reference the same buffer, but each with it's own offset.  (i.e. Many MTKMeshBuffers may be suballocated from a single buffer)
        #[unsafe(method(buffer))]
        #[unsafe(method_family = none)]
        pub fn buffer(&self) -> Retained<ProtocolObject<dyn MTLBuffer>>;

        /// Byte offset of the data within the metal buffer.
        #[unsafe(method(offset))]
        #[unsafe(method_family = none)]
        pub fn offset(&self) -> NSUInteger;

        #[cfg(feature = "objc2-model-io")]
        /// the intended type of the buffer
        #[unsafe(method(type))]
        #[unsafe(method_family = none)]
        pub fn r#type(&self) -> MDLMeshBufferType;
    );
}

/// Methods declared on superclass `NSObject`.
impl MTKMeshBuffer {
    extern_methods!(
        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

extern_class!(
    /// A segment of a mesh and properties to render the segement.
    ///
    /// Container for data that can be rendered in a single draw call. 1:1 mapping to MDLSubmesh.  Each submesh contains an index Buffer with which the parents mesh data can be rendered.  Actual vertex data resides in the submesh's parent MTKMesh object.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/metalkit/mtksubmesh?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct MTKSubmesh;
);

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

impl MTKSubmesh {
    extern_methods!(
        /// Applicatiohs must not explicity allocate or initialize.  Must initialize as part of MTKMesh object.
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        /// Metal primitive type with which to draw this object.
        ///
        /// Value to use for primitiveType parameter in a [MTLRenderCommandEncoder drawIndexedPrimitives] call.
        #[unsafe(method(primitiveType))]
        #[unsafe(method_family = none)]
        pub fn primitiveType(&self) -> MTLPrimitiveType;

        /// Metal index type of data in indexBuffer.
        ///
        /// Value to use for indexType parameter in a [MTLRenderCommandEncoder drawIndexedPrimitives] call.
        #[unsafe(method(indexType))]
        #[unsafe(method_family = none)]
        pub fn indexType(&self) -> MTLIndexType;

        /// IndexBuffer (including indexCount) to render the object.
        ///
        /// The MTLBuffer to use for indexBuffer parameter in a [MTLRenderCommandEncoder drawIndexedPrimitives] call.
        #[unsafe(method(indexBuffer))]
        #[unsafe(method_family = none)]
        pub fn indexBuffer(&self) -> Retained<MTKMeshBuffer>;

        /// Number of indicies in indexBuffer.
        ///
        /// Value to use for indexCount parameter in a [MTLRenderCommandEncoder drawIndexedPrimitives] call.
        #[unsafe(method(indexCount))]
        #[unsafe(method_family = none)]
        pub fn indexCount(&self) -> NSUInteger;

        /// Parent MTKMesh object containing vertex data of this object.
        ///
        /// The buffer of this parent mesh should be set in the encoder before a drawIndexedPrimitives call is made.
        #[unsafe(method(mesh))]
        #[unsafe(method_family = none)]
        pub fn mesh(&self) -> Option<Retained<MTKMesh>>;

        /// Name from the original MDLSubmesh object.
        ///
        /// Although not directly used by this object, the application may use this to identify the submesh in the renderer/scene/world.
        #[unsafe(method(name))]
        #[unsafe(method_family = none)]
        pub fn name(&self) -> Retained<NSString>;

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

/// Methods declared on superclass `NSObject`.
impl MTKSubmesh {
    extern_methods!(
        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

extern_class!(
    /// Container for vertex data of a mesh and submeshes to render it.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/metalkit/mtkmesh?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct MTKMesh;
);

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

impl MTKMesh {
    extern_methods!(
        /// Cannot use default init.  Must initialize with mesh and metal device.
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        #[cfg(feature = "objc2-model-io")]
        /// Initialize the mesh and the mesh's submeshes.
        ///
        /// Parameter `mesh`: Model I/O Mesh from which to create this MetalKit mesh
        ///
        /// Parameter `device`: Metal device on which to create mesh resources
        ///
        /// Parameter `error`: Pointer to an NSError object set if an error occurred
        ///
        /// The designated initializer for this class.  This does NOT initialize any meshes that are children of the Model I/O mesh, only submeshes that are part of the given mesh.  An exception is raised if vertexBuffer objects in the given mesh and the indexBuffer of any submesh in this mesh have not been created with a MTKMeshBufferAllocator object.  If a submesh using MDLGeometryTypeQuads or MDLGeometryTypeTopology is used, that submesh will be copied, and recreated to use MDLGeometryTypeTriangles, before this routine creates the MTKSubmesh.
        #[unsafe(method(initWithMesh:device:error:_))]
        #[unsafe(method_family = init)]
        pub fn initWithMesh_device_error(
            this: Allocated<Self>,
            mesh: &MDLMesh,
            device: &ProtocolObject<dyn MTLDevice>,
        ) -> Result<Retained<Self>, Retained<NSError>>;

        #[cfg(feature = "objc2-model-io")]
        /// Initialize all meshes in a Model I/O asset.
        ///
        /// Parameter `asset`: Model I/O asset from which to create MetalKit meshes
        ///
        /// Parameter `device`: Metal device on which to create mesh resources
        ///
        /// Parameter `sourceMeshes`: Array built by this method containing MDLMesh objects corresponding the returned MTKMesh objects
        ///
        /// Parameter `error`: Pointer to an NSError object set if an error occurred
        ///
        /// Returns: MetalKit Meshes created from the Model I/O asset
        ///
        /// A convenience method to create MetalKit meshes from each mesh in a Model I/O asset.  resulting meshes are returned while the corresponding Model I/O meshes from which they were generated will appear in the sourceMeshes array.  All vertexBuffer objects in each MDLMesh object in the asset and the indexBuffer of each submesh within each of these meshes must have been created using a MTKMeshBufferAllocator object.  Thus
        #[unsafe(method(newMeshesFromAsset:device:sourceMeshes:error:_))]
        #[unsafe(method_family = new)]
        pub fn newMeshesFromAsset_device_sourceMeshes_error(
            asset: &MDLAsset,
            device: &ProtocolObject<dyn MTLDevice>,
            source_meshes: Option<&mut Option<Retained<NSArray<MDLMesh>>>>,
        ) -> Result<Retained<NSArray<MTKMesh>>, Retained<NSError>>;

        /// Array of buffers in which mesh vertex data resides.
        ///
        /// This is filled with mesh buffer objects using the layout described by the vertexDescriptor property.  Elements in this array can be [NSNull null] if the vertexDescriptor does not specify elements for buffer for the given index
        #[unsafe(method(vertexBuffers))]
        #[unsafe(method_family = none)]
        pub fn vertexBuffers(&self) -> Retained<NSArray<MTKMeshBuffer>>;

        #[cfg(feature = "objc2-model-io")]
        /// Model I/O vertex descriptor specifying the layout of data in vertexBuffers.
        ///
        /// This is not directly used by this object, but the application can use this information to determine rendering state or create a Metal vertex descriptor to build a RenderPipelineState object capable of interpreting data in 'vertexBuffers'.  Changing propties in the object will not result in the relayout data in vertex descriptor and thus will make the vertex descriptor no loger describe the layout of vertes data and verticies. (i.e. don't change properties in this vertexDescriptor)
        #[unsafe(method(vertexDescriptor))]
        #[unsafe(method_family = none)]
        pub fn vertexDescriptor(&self) -> Retained<MDLVertexDescriptor>;

        /// Submeshes containing index buffers to rendering mesh vertices.
        #[unsafe(method(submeshes))]
        #[unsafe(method_family = none)]
        pub fn submeshes(&self) -> Retained<NSArray<MTKSubmesh>>;

        /// Number of vertices in the vertexBuffers.
        #[unsafe(method(vertexCount))]
        #[unsafe(method_family = none)]
        pub fn vertexCount(&self) -> NSUInteger;

        /// Name of the mesh copies from the originating Model I/O mesh.
        ///
        /// Can be used by the app to identify the mesh in its scene/world/renderer etc.
        #[unsafe(method(name))]
        #[unsafe(method_family = none)]
        pub fn name(&self) -> Retained<NSString>;

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

/// Methods declared on superclass `NSObject`.
impl MTKMesh {
    extern_methods!(
        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

/// Partially converts a Metal vertex descriptor to a Model I/O vertex descriptor
///
/// This method can only set vertex format, offset, bufferIndex, and stride information in the produced Model I/O vertex descriptor.  It does not add any semantic information such at attributes names.  Names must be set in the returned Model I/O vertex descriptor before it can be applied to a a Model I/O mesh.
#[cfg(feature = "objc2-model-io")]
#[inline]
pub extern "C-unwind" fn MTKModelIOVertexDescriptorFromMetal(
    metal_descriptor: &MTLVertexDescriptor,
) -> Retained<MDLVertexDescriptor> {
    extern "C-unwind" {
        fn MTKModelIOVertexDescriptorFromMetal(
            metal_descriptor: &MTLVertexDescriptor,
        ) -> *mut MDLVertexDescriptor;
    }
    let ret = unsafe { MTKModelIOVertexDescriptorFromMetal(metal_descriptor) };
    unsafe { Retained::retain_autoreleased(ret) }
        .expect("function was marked as returning non-null, but actually returned NULL")
}

/// Partially converts a Metal vertex descriptor to a Model I/O vertex descriptor
///
/// This method can only set vertex format, offset, bufferIndex, and stride information in the produced Model I/O vertex descriptor.  It does not add any semantic information such at attributes names.  Names must be set in the returned Model I/O vertex descriptor before it can be applied to a a Model I/O mesh. If error is nonnull, and the conversion cannot be made, it will be set.
///
/// # Safety
///
/// `error` must be a valid pointer or null.
#[cfg(feature = "objc2-model-io")]
#[inline]
pub unsafe extern "C-unwind" fn MTKModelIOVertexDescriptorFromMetalWithError(
    metal_descriptor: &MTLVertexDescriptor,
    error: *mut *mut NSError,
) -> Retained<MDLVertexDescriptor> {
    extern "C-unwind" {
        fn MTKModelIOVertexDescriptorFromMetalWithError(
            metal_descriptor: &MTLVertexDescriptor,
            error: *mut *mut NSError,
        ) -> *mut MDLVertexDescriptor;
    }
    let ret = unsafe { MTKModelIOVertexDescriptorFromMetalWithError(metal_descriptor, error) };
    unsafe { Retained::retain_autoreleased(ret) }
        .expect("function was marked as returning non-null, but actually returned NULL")
}

/// Partially converts a Model I/O vertex descriptor to a Metal vertex descriptor
///
/// This method can only set vertex format, offset, bufferIndex, and stride information in the produced Metal vertex descriptor. It simply copies attributes 1 for 1. Thus attributes in the given Model I/O vertex descriptor must be arranged in the correct order for the resulting descriptor to properly map mesh data to vertex shader inputs.  Layout stepFunction and stepRates for the resulting MTLVertexDescriptor must also be set by application.
#[cfg(feature = "objc2-model-io")]
#[inline]
pub extern "C-unwind" fn MTKMetalVertexDescriptorFromModelIO(
    model_io_descriptor: &MDLVertexDescriptor,
) -> Option<Retained<MTLVertexDescriptor>> {
    extern "C-unwind" {
        fn MTKMetalVertexDescriptorFromModelIO(
            model_io_descriptor: &MDLVertexDescriptor,
        ) -> *mut MTLVertexDescriptor;
    }
    let ret = unsafe { MTKMetalVertexDescriptorFromModelIO(model_io_descriptor) };
    unsafe { Retained::retain_autoreleased(ret) }
}

/// Partially converts a Model I/O vertex descriptor to a Metal vertex descriptor
///
/// This method can only set vertex format, offset, bufferIndex, and stride information in the produced Metal vertex descriptor. It simply copies attributes 1 for 1. Thus attributes in the given Model I/O vertex descriptor must be arranged in the correct order for the resulting descriptor to properly map mesh data to vertex shader inputs.  Layout stepFunction and stepRates for the resulting MTLVertexDescriptor must also be set by application.  If error is nonnull, and the conversion cannot be made, it will be set.
///
/// # Safety
///
/// `error` must be a valid pointer or null.
#[cfg(feature = "objc2-model-io")]
#[inline]
pub unsafe extern "C-unwind" fn MTKMetalVertexDescriptorFromModelIOWithError(
    model_io_descriptor: &MDLVertexDescriptor,
    error: *mut *mut NSError,
) -> Option<Retained<MTLVertexDescriptor>> {
    extern "C-unwind" {
        fn MTKMetalVertexDescriptorFromModelIOWithError(
            model_io_descriptor: &MDLVertexDescriptor,
            error: *mut *mut NSError,
        ) -> *mut MTLVertexDescriptor;
    }
    let ret = unsafe { MTKMetalVertexDescriptorFromModelIOWithError(model_io_descriptor, error) };
    unsafe { Retained::retain_autoreleased(ret) }
}

/// Converts a Metal vertex format to a Model I/O vertex format
///
/// Returns: A Model I/O vertexformat correspoinding to the given Metal vertex format.  Returns MDLVertexFormatInvalid if no matching Model I/O vertex format exists.
#[cfg(feature = "objc2-model-io")]
#[inline]
pub extern "C-unwind" fn MTKModelIOVertexFormatFromMetal(
    vertex_format: MTLVertexFormat,
) -> MDLVertexFormat {
    extern "C-unwind" {
        fn MTKModelIOVertexFormatFromMetal(vertex_format: MTLVertexFormat) -> MDLVertexFormat;
    }
    unsafe { MTKModelIOVertexFormatFromMetal(vertex_format) }
}

/// Converts a Model I/O vertex format to a Metal vertex format
///
/// Returns: A Metal vertexformat correspoinding to the given Model I/O vertex format.  Returns MTLVertexFormatInvalid if no matching Metal vertex format exists.
#[cfg(feature = "objc2-model-io")]
#[inline]
pub extern "C-unwind" fn MTKMetalVertexFormatFromModelIO(
    vertex_format: MDLVertexFormat,
) -> MTLVertexFormat {
    extern "C-unwind" {
        fn MTKMetalVertexFormatFromModelIO(vertex_format: MDLVertexFormat) -> MTLVertexFormat;
    }
    unsafe { MTKMetalVertexFormatFromModelIO(vertex_format) }
}