Source code
Revision control
Copy as Markdown
Other Tools
//! 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::*;
/// Custom render pass options you specify at encoder creation time.
///
/// Use these options to implement parallel encoding of render passes across multiple CPU threads by providing these
/// values to the `options` parameter of ``MTL4CommandBuffer/renderCommandEncoderWithDescriptor:options:`` and
/// observing these requirements:
///
/// 1. Commit all command encoders together in an array you provide to ``MTL4CommandQueue/commit:count:`` or ``MTL4CommandQueue/commit:count:options:``
/// 2. The first command buffer in the array contains a render pass that you start with option ``MTL4RenderEncoderOptionSuspending``
/// 3. The last command buffer in the array contains the same render pass that you start with option ``MTL4RenderEncoderOptionResuming``
/// 4. All intermediate command buffers between the first and last in the array contain the same render pass that you
/// start with both ``MTL4RenderEncoderOptionResuming`` and ``MTL4RenderEncoderOptionSuspending`` options.
/// 5. The sequence of render passes, in submission order, doesn't intermix with compute, blit, acceleration structure
/// or machine learning encoding.
/// 6. A command buffer shouldn't contain a render pass that you start with option ``MTL4RenderEncoderOptionSuspending`` if
/// it already contains a render pass that you start with option ``MTL4RenderEncoderOptionResuming``.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4renderencoderoptions?language=objc)
// NS_OPTIONS
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct MTL4RenderEncoderOptions(pub NSUInteger);
bitflags::bitflags! {
impl MTL4RenderEncoderOptions: NSUInteger {
/// Declares that this render pass doesn't suspend nor resume.
#[doc(alias = "MTL4RenderEncoderOptionNone")]
const None = 0;
/// Configures the render pass as *suspending*.
///
/// Pass this option to ``MTL4CommandBuffer/renderCommandEncoderWithDescriptor:options:`` to specify that Metal can
/// stitch the work a render command encoder encodes with a subsequent "resuming" render command encoder.
#[doc(alias = "MTL4RenderEncoderOptionSuspending")]
const Suspending = 1<<0;
/// Configures the render pass to as *resuming*.
///
/// Pass this option to ``MTL4CommandBuffer/renderCommandEncoderWithDescriptor:options:`` to specify that Metal can
/// stitch the work a render command encoder encodes with a prior "suspending" render command encoder.
#[doc(alias = "MTL4RenderEncoderOptionResuming")]
const Resuming = 1<<1;
}
}
unsafe impl Encode for MTL4RenderEncoderOptions {
const ENCODING: Encoding = NSUInteger::ENCODING;
}
unsafe impl RefEncode for MTL4RenderEncoderOptions {
const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}
extern_protocol!(
/// Encodes a render pass into a command buffer, including all its draw calls and configuration.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/metal/mtl4rendercommandencoder?language=objc)
#[cfg(feature = "MTL4CommandEncoder")]
pub unsafe trait MTL4RenderCommandEncoder: MTL4CommandEncoder {
/// Sets the width of a tile for this render pass.
#[unsafe(method(tileWidth))]
#[unsafe(method_family = none)]
fn tileWidth(&self) -> NSUInteger;
/// Sets the height of a tile for this render pass.
#[unsafe(method(tileHeight))]
#[unsafe(method_family = none)]
fn tileHeight(&self) -> NSUInteger;
#[cfg(feature = "MTLRenderPipeline")]
/// Sets the mapping from logical shader color output to physical render pass color attachments.
///
/// Use this method to define how the physical color attachments you specify via ``MTL4RenderPassDescriptor/colorAttachments``
/// map to the logical color output the fragment shader writes to.
///
/// To use this feature, make sure to set ``MTL4RenderPassDescriptor/supportColorAttachmentMapping`` to
/// <doc
/// ://com.apple.documentation/documentation/swift/true>.
///
/// - Parameter mapping: Mapping from logical shader outputs to physical outputs.
#[unsafe(method(setColorAttachmentMap:))]
#[unsafe(method_family = none)]
fn setColorAttachmentMap(&self, mapping: Option<&MTLLogicalToPhysicalColorAttachmentMap>);
#[cfg(all(feature = "MTLAllocation", feature = "MTLRenderPipeline"))]
/// Configures this encoder with a render pipeline state that applies to your subsequent draw commands.
///
/// - Parameter pipelineState: a non-`nil` ``MTLRenderPipelineState`` instance.
#[unsafe(method(setRenderPipelineState:))]
#[unsafe(method_family = none)]
fn setRenderPipelineState(
&self,
pipeline_state: &ProtocolObject<dyn MTLRenderPipelineState>,
);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Sets the viewport which that transforms vertices from normalized device coordinates to window coordinates.
///
/// Metal clips fragments that lie outside this viewport, and optionally clamps fragments outside of z-near/z-far range
/// depending on the value you assign to ``setDepthClipMode:``.
///
/// - Parameter viewport: ``MTLViewport`` to set.
#[unsafe(method(setViewport:))]
#[unsafe(method_family = none)]
fn setViewport(&self, viewport: MTLViewport);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Sets an array of viewports to transform vertices from normalized device coordinates to window coordinates.
///
/// Metal clips fragments that lie outside of the viewport, and optionally clamps fragments outside of z-near/z-far range,
/// depending on the value you assign to ``setDepthClipMode:``.
///
/// Metal selects the viewport to use from the `[[ viewport_array_index ]]` attribute you specify in the pipeline
/// state's vertex shader function in the Metal Shading Language.
///
/// - Parameters:
/// - viewports: Array of ``MTLViewport`` instances.
/// - count: Number of ``MTLViewport`` instances in the array.
///
/// # Safety
///
/// - `viewports` must be a valid pointer.
/// - `count` might not be bounds-checked.
#[unsafe(method(setViewports:count:))]
#[unsafe(method_family = none)]
unsafe fn setViewports_count(&self, viewports: NonNull<MTLViewport>, count: NSUInteger);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Sets the vertex amplification count and its view mapping for each amplification ID.
///
/// Each view mapping element describes how to route the corresponding amplification ID to a specific viewport and
/// render target array index by using offsets from the base array index provided by the `[[ render_target_array_index ]]`
/// and/or `[[ viewport_array_index ]]` output attributes in the vertex shader. This allows Metal to route each amplified
/// vertex to a different `[[ render_target_array_index ]]` and `[[ viewport_array_index ]]`, even though you can't
/// directly amplify these attributes.
///
/// - Parameters:
/// - count: The number of outputs to create. The maximum value is `2`.
/// - viewMappings: Array of ``MTLVertexAmplificationViewMapping`` instances. Each instance provides
/// per-output offsets to a specific render target and viewport.
///
/// # Safety
///
/// - `count` might not be bounds-checked.
/// - `view_mappings` must be a valid pointer or null.
#[unsafe(method(setVertexAmplificationCount:viewMappings:))]
#[unsafe(method_family = none)]
unsafe fn setVertexAmplificationCount_viewMappings(
&self,
count: NSUInteger,
view_mappings: *const MTLVertexAmplificationViewMapping,
);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Controls whether Metal culls front facing primitives, back facing primitives, or culls no primitives at all.
///
/// - Parameter cullMode: ``MTLCullMode`` to set.
#[unsafe(method(setCullMode:))]
#[unsafe(method_family = none)]
fn setCullMode(&self, cull_mode: MTLCullMode);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Controls the behavior for fragments outside of the near or far planes.
///
/// - Parameter depthClipMode: ``MTLDepthClipMode`` to set.
#[unsafe(method(setDepthClipMode:))]
#[unsafe(method_family = none)]
fn setDepthClipMode(&self, depth_clip_mode: MTLDepthClipMode);
/// Configures the adjustments a render pass applies to depth values from fragment shader functions
/// by a scaling factor and bias.
///
/// - Parameters:
/// - depthBias: A constant bias the render pipeline applies to all fragments.
/// - slopeScale: A bias coefficient that scales with the depth of the primitive relative to the camera.
/// - clamp: A value that limits the bias value the render pipeline can apply to a fragment.
/// Pass a positive or negative value to limit the largest magnitude of a positive
/// or negative bias, respectively. Set this value to `0` to disable bias clamping.
#[unsafe(method(setDepthBias:slopeScale:clamp:))]
#[unsafe(method_family = none)]
fn setDepthBias_slopeScale_clamp(
&self,
depth_bias: c_float,
slope_scale: c_float,
clamp: c_float,
);
/// Configures the minimum and maximum bounds for depth bounds testing.
///
/// The render command encoder disables depth bounds testing by default.
/// The render command encoder also disables depth bounds testing when all of the following properties equal a specific value:
/// - The `minBound` property is equal to `0.0f`.
/// - The `maxBound` property is equal to `1.0f`.
/// Both `minBound` and `maxBound` need to be within `[0.0f, 1.0f]`, and `minBound` needs to be less than or equal to `maxBound`.
/// - Parameters:
/// - minBound: A minimum bound for depth testing, which discards fragments with a stored depth that is less than `minBound`.
/// - maxBound: A maximum bound for depth testing, which discards fragments with a stored depth that is greater than `maxBound`.
#[unsafe(method(setDepthTestMinBound:maxBound:))]
#[unsafe(method_family = none)]
fn setDepthTestMinBound_maxBound(&self, min_bound: c_float, max_bound: c_float);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Sets a scissor rectangle to discard fragments outside a specific area.
///
/// Metal performs a scissor test and discards all fragments outside of the scissor rect.
///
/// - Parameter rect: ``MTLScissorRect`` rectangle to specify. This rectangle needs to lie completely
/// within the current render attachment.
#[unsafe(method(setScissorRect:))]
#[unsafe(method_family = none)]
fn setScissorRect(&self, rect: MTLScissorRect);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Sets an array of scissor rectangles for a fragment scissor test.
///
/// Metal uses the specific scissor rectangle corresponding to the index you specify via the `[[ viewport_array_index ]]`
/// output attribute of the vertex shader function in the Metal Shading Language, discarding all fragments outside of
/// the scissor rect.
///
/// - Parameters:
/// - scissorRects: Array of ``MTLScissorRect`` structures.
/// - count: Number of ``MTLScissorRect`` structures in the array.
///
/// # Safety
///
/// - `scissor_rects` must be a valid pointer.
/// - `count` might not be bounds-checked.
#[unsafe(method(setScissorRects:count:))]
#[unsafe(method_family = none)]
unsafe fn setScissorRects_count(
&self,
scissor_rects: NonNull<MTLScissorRect>,
count: NSUInteger,
);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Configures how subsequent draw commands rasterize triangle and triangle strip primitives.
///
/// - Parameter fillMode:``MTLTriangleFillMode`` the render pass applies to draw commands that
/// rasterize triangles or triangle strips.
#[unsafe(method(setTriangleFillMode:))]
#[unsafe(method_family = none)]
fn setTriangleFillMode(&self, fill_mode: MTLTriangleFillMode);
/// Configures each pixel component value, including alpha, for the render pipeline’s constant blend color.
///
/// - Parameters:
/// - red: A value for the red component for the blend color constant.
/// - green: A value for the green component for the blend color constant.
/// - blue: A value for the blue component for the blend color constant.
/// - alpha: A value for the alpha component for the blend color constant.
#[unsafe(method(setBlendColorRed:green:blue:alpha:))]
#[unsafe(method_family = none)]
fn setBlendColorRed_green_blue_alpha(
&self,
red: c_float,
green: c_float,
blue: c_float,
alpha: c_float,
);
#[cfg(feature = "MTLDepthStencil")]
/// Configures this encoder with a depth stencil state that applies to your subsequent draw commands.
///
/// - Parameter depthStencilState: the ``MTLDepthStencilState`` instance to set.
#[unsafe(method(setDepthStencilState:))]
#[unsafe(method_family = none)]
fn setDepthStencilState(
&self,
depth_stencil_state: Option<&ProtocolObject<dyn MTLDepthStencilState>>,
);
/// Configures this encoder with a reference value for stencil testing.
///
/// The render pipeline applies this reference value to both front-facing and back-facing primitives.
///
/// - Parameter referenceValue: A stencil test comparison value.
#[unsafe(method(setStencilReferenceValue:))]
#[unsafe(method_family = none)]
fn setStencilReferenceValue(&self, reference_value: u32);
/// Configures the encoder with different stencil test reference values for front-facing and back-facing primitives.
///
/// The render pipeline applies `frontReferenceValue` to front-facing primitives and `backReferenceValue` to
/// back-facing primitives.
///
/// - Parameters:
/// - frontReferenceValue: A stencil test comparison value the render pipeline applies
/// to front-facing primitives.
/// - backReferenceValue: A stencil test comparison value the render pipeline applies
/// to back-facing primitives.
#[unsafe(method(setStencilFrontReferenceValue:backReferenceValue:))]
#[unsafe(method_family = none)]
fn setStencilFrontReferenceValue_backReferenceValue(
&self,
front_reference_value: u32,
back_reference_value: u32,
);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Configures a visibility test for Metal to run, and the destination for any results it generates.
///
/// You use the `mode` parameter to enable or disable the visibility test, and determine if it produces a boolean
/// response for passing fragments, or if it counts the number of fragments.
///
/// - Parameters:
/// - mode: A ``MTLVisibilityResultMode`` that configures which visibility test results
/// the render pass saves to a buffer, or disables visibility testing.
/// - offset: A location, in bytes, relative to the start of
/// ``MTL4RenderPassDescriptor/visibilityResultBuffer`` The GPU stores
/// the result of a visibility test at `offset`, which needs to be a multiple of `8`.
///
/// # Safety
///
/// `offset` might not be bounds-checked.
#[unsafe(method(setVisibilityResultMode:offset:))]
#[unsafe(method_family = none)]
unsafe fn setVisibilityResultMode_offset(
&self,
mode: MTLVisibilityResultMode,
offset: NSUInteger,
);
#[cfg(feature = "MTLRenderPass")]
/// Configures the store action for a color attachment.
///
/// - Parameters:
/// - storeAction: A store action for the color attachment that
/// can’t be ``MTLStoreAction/MTLStoreActionUnknown``.
/// - colorAttachmentIndex: The index of a color attachment.
///
/// # Safety
///
/// `colorAttachmentIndex` might not be bounds-checked.
#[unsafe(method(setColorStoreAction:atIndex:))]
#[unsafe(method_family = none)]
unsafe fn setColorStoreAction_atIndex(
&self,
store_action: MTLStoreAction,
color_attachment_index: NSUInteger,
);
#[cfg(feature = "MTLRenderPass")]
/// Configures the store action for the depth attachment.
///
/// - Parameter storeAction: A store action for the depth attachment that
/// can’t be ``MTLStoreAction/MTLStoreActionUnknown``.
#[unsafe(method(setDepthStoreAction:))]
#[unsafe(method_family = none)]
fn setDepthStoreAction(&self, store_action: MTLStoreAction);
#[cfg(feature = "MTLRenderPass")]
/// Configures the store action for the stencil attachment.
///
/// - Parameter storeAction: A store action for the stencil attachment that
/// can’t be ``MTLStoreAction/MTLStoreActionUnknown``.
#[unsafe(method(setStencilStoreAction:))]
#[unsafe(method_family = none)]
fn setStencilStoreAction(&self, store_action: MTLStoreAction);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Encodes a draw command that renders an instance of a geometric primitive.
///
/// This command assigns each vertex a unique `vertex_id` value that increases from `vertexStart` through
/// `(vertexStart + vertexCount - 1)`.
///
/// Your vertex shader function can use this value to uniquely identify each vertex.
///
/// - Parameters:
/// - primitiveType: A ``MTLPrimitiveType`` representing how the command interprets vertex argument data.
/// - vertexStart: The lowest value the command passes to your vertex shader function’s parameter with the
/// `[[vertex_id]]` attribute.
/// - vertexCount: An integer that represents the number of vertices of `primitiveType` the command draws.
///
/// # Safety
///
/// `vertexCount` might not be bounds-checked.
#[unsafe(method(drawPrimitives:vertexStart:vertexCount:))]
#[unsafe(method_family = none)]
unsafe fn drawPrimitives_vertexStart_vertexCount(
&self,
primitive_type: MTLPrimitiveType,
vertex_start: NSUInteger,
vertex_count: NSUInteger,
);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Encodes a draw command that renders multiple instances of a geometric primitive.
///
/// The command assigns each vertex a unique `vertex_id` value within its drawing instance
/// that increases from `vertexStart` through `(vertexStart + vertexCount - 1)`.
///
/// Additionally, the command assigns each drawing instance a unique `instance_id` value that increases
/// from `0` through `(instanceCount - 1)`.
///
/// Your vertex shader can use the `vertex_id` value to uniquely identify each vertex in each drawing instance, and the
/// `instance_id` value to identify which instance that vertex belongs to.
///
/// - Parameters:
/// - primitiveType: A ``MTLPrimitiveType`` represents how the command interprets vertex argument data.
/// - vertexStart: The lowest value the command passes to your vertex shader function’s parameter with
/// the `vertex_id` attribute.
/// - vertexCount: An integer that represents the number of vertices of `primitiveType` the command draws.
/// - instanceCount: An integer that represents the number of times the command draws `primitiveType` primitives
/// with `vertexCount` vertices.
///
/// # Safety
///
/// - `vertexCount` might not be bounds-checked.
/// - `instanceCount` might not be bounds-checked.
#[unsafe(method(drawPrimitives:vertexStart:vertexCount:instanceCount:))]
#[unsafe(method_family = none)]
unsafe fn drawPrimitives_vertexStart_vertexCount_instanceCount(
&self,
primitive_type: MTLPrimitiveType,
vertex_start: NSUInteger,
vertex_count: NSUInteger,
instance_count: NSUInteger,
);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Encodes a draw command that renders multiple instances of a geometric primitive,
/// starting with a custom instance identification number.
///
/// The command assigns each vertex a unique `vertex_id` value within its drawing instance
/// that increases from `vertexStart` through `(vertexStart + vertexCount - 1)`.
///
/// Additionally, the command assigns each drawing instance a unique `instance_id` value that increases
/// from `baseInstance` through `(baseInstance + instanceCount - 1)`.
///
/// Your vertex shader can use the `vertex_id` value to uniquely identify each vertex in each drawing instance, and the
/// `instance_id` value to identify which instance that vertex belongs to.
///
/// - Parameters:
/// - primitiveType: A ``MTLPrimitiveType`` representing how the command interprets vertex argument data.
/// - vertexStart: The lowest value the command passes to your vertex shader function’s parameter with
/// the `vertex_id` attribute.
/// - vertexCount: An integer that represents the number of vertices of `primitiveType` the command draws.
/// - instanceCount: An integer that represents the number of times the command draws `primitiveType`
/// with `vertexCount` vertices.
/// - baseInstance: The lowest value the command passes to your vertex shader function’s parameter with
/// the `instance_id` attribute.
///
/// # Safety
///
/// - `vertexCount` might not be bounds-checked.
/// - `instanceCount` might not be bounds-checked.
#[unsafe(method(drawPrimitives:vertexStart:vertexCount:instanceCount:baseInstance:))]
#[unsafe(method_family = none)]
unsafe fn drawPrimitives_vertexStart_vertexCount_instanceCount_baseInstance(
&self,
primitive_type: MTLPrimitiveType,
vertex_start: NSUInteger,
vertex_count: NSUInteger,
instance_count: NSUInteger,
base_instance: NSUInteger,
);
#[cfg(all(
feature = "MTLArgument",
feature = "MTLGPUAddress",
feature = "MTLRenderCommandEncoder"
))]
/// Encodes a draw command that renders an instance of a geometric primitive with indexed vertices.
///
/// Use this method to perform indexed drawing, where an index buffer determines how Metal assembles primitives.
///
/// Metal imposes some restrictions on the index buffer's address, which needs to be 2- or 4-byte aligned, and its length
/// in bytes, which needs to be a multiple of 2 or 4, depending on whether the format of the index is
/// ``MTLIndexType/MTLIndexTypeUInt16`` or ``MTLIndexType/MTLIndexTypeUInt32``.
///
/// Use an instance of ``MTLResidencySet`` to mark residency of the index buffer the `indexBuffer` parameter references.
///
/// - Parameters:
/// - primitiveType: A ``MTLPrimitiveType`` representing how the command interprets vertex argument data.
/// - indexCount: An integer that represents the number of vertices the command reads from `indexBuffer`.
/// - indexType: A ``MTLIndexType`` instance that represents the index format.
/// - indexBuffer: GPUAddress of a ``MTLBuffer`` instance that contains `indexCount` indices of `indexType` format.
/// You are responsible for ensuring this address is aligned to 2 bytes if the `indexType` format is
/// ``MTLIndexType/MTLIndexTypeUInt16``, and aligned to 4 bytes if the format is
/// ``MTLIndexType/MTLIndexTypeUInt32``.
/// - indexBufferLength: An integer that represents the length of `indexBuffer`, in bytes. You are responsible for
/// ensuring this this size is a multiple of 2 if the `indexType` format is ``MTLIndexType/MTLIndexTypeUInt16``,
/// and a multiple of 4 if the format is ``MTLIndexType/MTLIndexTypeUInt32``.
/// If this draw call causes Metal to read indices at or beyond the `indexBufferLength`, Metal
/// continues to execute them assigning a value of `0` to the `vertex_id` attribute.
///
/// # Safety
///
/// - `indexCount` might not be bounds-checked.
/// - `indexBuffer` might not be bounds-checked.
/// - `indexBufferLength` might not be bounds-checked.
#[unsafe(method(drawIndexedPrimitives:indexCount:indexType:indexBuffer:indexBufferLength:))]
#[unsafe(method_family = none)]
unsafe fn drawIndexedPrimitives_indexCount_indexType_indexBuffer_indexBufferLength(
&self,
primitive_type: MTLPrimitiveType,
index_count: NSUInteger,
index_type: MTLIndexType,
index_buffer: MTLGPUAddress,
index_buffer_length: NSUInteger,
);
#[cfg(all(
feature = "MTLArgument",
feature = "MTLGPUAddress",
feature = "MTLRenderCommandEncoder"
))]
/// Encodes a draw command that renders multiple instances of a geometric primitive with indexed vertices.
///
/// Use this method to perform instanced indexed drawing, where an index buffer determines how Metal assembles primitives.
///
/// The command assigns each drawing instance a unique `instance_id` value that increases
/// from `0` through `(instanceCount - 1)`. Your shader can use this value to identify which
/// instance the vertex belongs to.
///
/// Metal imposes some restrictions on the index buffer's address, which needs to be 2- or 4-byte aligned, and its length
/// in bytes, which needs to be a multiple of 2 or 4, depending on whether the format of the index is
/// ``MTLIndexType/MTLIndexTypeUInt16`` or ``MTLIndexType/MTLIndexTypeUInt32``.
///
/// Use an instance of ``MTLResidencySet`` to mark residency of the index buffer the `indexBuffer` parameter references.
///
/// - Parameters:
/// - primitiveType: A ``MTLPrimitiveType`` representing how the command interprets vertex argument data.
/// - indexCount: An integer that represents the number of vertices the command reads from `indexBuffer`.
/// - indexType: A ``MTLIndexType`` instance that represents the index format.
/// - indexBuffer: GPUAddress of a ``MTLBuffer`` instance that contains `indexCount` indices of `indexType` format.
/// You are responsible for ensuring this address is aligned to 2 bytes if the `indexType` format is
/// ``MTLIndexType/MTLIndexTypeUInt16``, and aligned to 4 bytes if the format is
/// ``MTLIndexType/MTLIndexTypeUInt32``.
/// - indexBufferLength: An integer that represents the length of `indexBuffer`, in bytes. You are responsible for
/// ensuring this this size is a multiple of 2 if the `indexType` format is ``MTLIndexType/MTLIndexTypeUInt16``,
/// and a multiple of 4 if the format is ``MTLIndexType/MTLIndexTypeUInt32``.
/// Metal disregards this value and assigns `0` to the `vertex_id` attribute for all primitives that
/// require loading indices at a byte offset of `indexBufferLength` or greater.
/// - instanceCount: An integer that represents the number of times the command draws `primitiveType` with `indexCount`
/// vertices.
///
/// # Safety
///
/// - `indexCount` might not be bounds-checked.
/// - `indexBuffer` might not be bounds-checked.
/// - `indexBufferLength` might not be bounds-checked.
/// - `instanceCount` might not be bounds-checked.
#[unsafe(method(drawIndexedPrimitives:indexCount:indexType:indexBuffer:indexBufferLength:instanceCount:))]
#[unsafe(method_family = none)]
unsafe fn drawIndexedPrimitives_indexCount_indexType_indexBuffer_indexBufferLength_instanceCount(
&self,
primitive_type: MTLPrimitiveType,
index_count: NSUInteger,
index_type: MTLIndexType,
index_buffer: MTLGPUAddress,
index_buffer_length: NSUInteger,
instance_count: NSUInteger,
);
#[cfg(all(
feature = "MTLArgument",
feature = "MTLGPUAddress",
feature = "MTLRenderCommandEncoder"
))]
/// Encodes a draw command that renders multiple instances of a geometric primitive with indexed vertices,
/// starting with a custom vertex and instance.
///
/// Use this method to perform instanced indexed drawing, where an index buffer determines how Metal assembles primitives
/// whilst customizing the base vertex and base instance value Metal passes to the vertex shader function.
///
/// The command assigns each drawing instance a unique `instance_id` value that increases
/// from `baseInstance` through `(baseInstance + instanceCount - 1)`. Your shader can use this value
/// to identify which instance the vertex belongs to.
///
/// Metal imposes some restrictions on the index buffer's address, which needs to be 2- or 4-byte aligned, and its length
/// in bytes, which needs to be a multiple of 2 or 4, depending on whether the format of the index is
/// ``MTLIndexType/MTLIndexTypeUInt16`` or ``MTLIndexType/MTLIndexTypeUInt32``.
///
/// Use an instance of ``MTLResidencySet`` to mark residency of the index buffer the `indexBuffer` parameter references.
///
/// - Parameters:
/// - primitiveType: A ``MTLPrimitiveType`` representing how the command interprets vertex argument data.
/// - indexCount: An integer that represents the number of vertices the command reads from `indexBuffer`.
/// - indexType: A ``MTLIndexType`` instance that represents the index format.
/// - indexBuffer: GPUAddress of a ``MTLBuffer`` instance that contains `indexCount` indices of `indexType` format.
/// You are responsible for ensuring this address is aligned to 2 bytes if the `indexType` format is
/// ``MTLIndexType/MTLIndexTypeUInt16``, and aligned to 4 bytes if the format is
/// ``MTLIndexType/MTLIndexTypeUInt32``.
/// - indexBufferLength: An integer that represents the length of `indexBuffer`, in bytes. You are responsible for
/// ensuring this this size is a multiple of 2 if the `indexType` format is ``MTLIndexType/MTLIndexTypeUInt16``,
/// and a multiple of 4 if the format is ``MTLIndexType/MTLIndexTypeUInt32``.
/// If this draw call causes Metal to read indices at or beyond the `indexBufferLength`, Metal
/// continues to execute them assigning a value of `0` to the `vertex_id` attribute.
/// - instanceCount: An integer that represents the number of times the command draws `primitiveType` with `indexCount`
/// vertices.
/// - baseVertex: The lowest value the command passes to your vertex shader functions’s parameter with the `vertex_id`
/// attribute. Metal disregards this value and assigns `0` to the `vertex_id` attribute for all
/// primitives that require loading indices at a byte offset of `indexBufferLength` or greater.
/// - baseInstance: The lowest value the command passes to your vertex shader’s parameter with the `instance_id` attribute.
///
/// # Safety
///
/// - `indexCount` might not be bounds-checked.
/// - `indexBuffer` might not be bounds-checked.
/// - `indexBufferLength` might not be bounds-checked.
/// - `instanceCount` might not be bounds-checked.
#[unsafe(method(drawIndexedPrimitives:indexCount:indexType:indexBuffer:indexBufferLength:instanceCount:baseVertex:baseInstance:))]
#[unsafe(method_family = none)]
unsafe fn drawIndexedPrimitives_indexCount_indexType_indexBuffer_indexBufferLength_instanceCount_baseVertex_baseInstance(
&self,
primitive_type: MTLPrimitiveType,
index_count: NSUInteger,
index_type: MTLIndexType,
index_buffer: MTLGPUAddress,
index_buffer_length: NSUInteger,
instance_count: NSUInteger,
base_vertex: NSInteger,
base_instance: NSUInteger,
);
#[cfg(all(feature = "MTLGPUAddress", feature = "MTLRenderCommandEncoder"))]
/// Encodes a draw command that renders multiple instances of a geometric primitive with indirect arguments.
///
/// When you use this function, Metal reads the parameters to the draw command from an ``MTLBuffer`` instance,
/// allowing you to implement a GPU-driven workflow where a compute pipeline state determines the draw arguments.
///
/// You are responsible for ensuring that the address of the indirect buffer you provide to this method has 4-byte
/// alignment.
///
/// Because this is a non-indexed draw call, Metal interprets the contents of the indirect buffer to match the
/// layout of struct ``MTLDrawPrimitivesIndirectArguments``.
///
/// Use an instance of ``MTLResidencySet`` to mark residency of the indirect buffer that the `indirectBuffer` parameter
/// references.
///
/// - Parameters:
/// - primitiveType: A ``MTLPrimitiveType`` representing how the command interprets vertex argument data.
/// - indirectBuffer: GPUAddress of a ``MTLBuffer`` instance with data that matches the layout of the
/// ``MTLDrawPrimitivesIndirectArguments`` structure. You are responsible for ensuring that the
/// alignment of this address is 4 bytes.
#[unsafe(method(drawPrimitives:indirectBuffer:))]
#[unsafe(method_family = none)]
fn drawPrimitives_indirectBuffer(
&self,
primitive_type: MTLPrimitiveType,
indirect_buffer: MTLGPUAddress,
);
#[cfg(all(
feature = "MTLArgument",
feature = "MTLGPUAddress",
feature = "MTLRenderCommandEncoder"
))]
/// Encodes a draw command that renders multiple instances of a geometric primitive with indexed vertices
/// and indirect arguments.
///
/// When you use this function, Metal reads the parameters to the draw command from an ``MTLBuffer`` instance,
/// allowing you to implement a GPU-driven workflow where a compute pipeline state determines the draw arguments.
///
/// Because this is an indexed draw call, Metal interprets the contents of the indirect buffer to match the
/// layout of struct ``MTLDrawIndexedPrimitivesIndirectArguments``, which includes `indexStart` and `indexCount`
/// members, denoting a range within the index buffer you provide in the `indexBuffer` parameter.
///
/// The range of indices within the `indexBuffer` form the primitives Metal draws.
///
/// Metal imposes some restrictions on the index buffer's address, which needs to be 2- or 4-byte aligned, and its length
/// in bytes, which needs to be a multiple of 2 or 4, depending on whether the format of the index is
/// ``MTLIndexType/MTLIndexTypeUInt16`` or ``MTLIndexType/MTLIndexTypeUInt32``.
///
/// Similarly, you are responsible for ensuring the indirect buffer's address has 4-byte alignment.
///
/// Use an instance of ``MTLResidencySet`` to mark residency of the indirect buffer that the `indirectBuffer` parameter
/// references, and of the index buffer the `indexBuffer` parameter references.
///
/// - Parameters:
/// - primitiveType: A ``MTLPrimitiveType`` representing how the command interprets vertex argument data.
/// - indexType: A ``MTLIndexType`` instance that represents the index format.
/// - indexBuffer: GPUAddress of a ``MTLBuffer`` instance that contains `indexCount` indices of `indexType` format.
/// You are responsible for ensuring this address is aligned to 2 bytes if the `indexType` format is
/// ``MTLIndexType/MTLIndexTypeUInt16``, and aligned to 4 bytes if the format is
/// ``MTLIndexType/MTLIndexTypeUInt32``.
/// - indexBufferLength: An integer that represents the length of `indexBuffer`, in bytes. You are responsible for
/// ensuring this this size is a multiple of 2 if the `indexType` format is ``MTLIndexType/MTLIndexTypeUInt16``,
/// and a multiple of 4 if the format is ``MTLIndexType/MTLIndexTypeUInt32``.
/// If this draw call causes Metal to read indices at or beyond the `indexBufferLength`, Metal
/// continues to execute them assigning a value of `0` to the `vertex_id` attribute.
/// - indirectBuffer: GPUAddress of an ``MTLBuffer`` instance with data that matches the layout of the
/// ``MTLDrawIndexedPrimitivesIndirectArguments`` structure. This address requires 4-byte alignment.
///
/// # Safety
///
/// - `indexBuffer` might not be bounds-checked.
/// - `indexBufferLength` might not be bounds-checked.
#[unsafe(method(drawIndexedPrimitives:indexType:indexBuffer:indexBufferLength:indirectBuffer:))]
#[unsafe(method_family = none)]
unsafe fn drawIndexedPrimitives_indexType_indexBuffer_indexBufferLength_indirectBuffer(
&self,
primitive_type: MTLPrimitiveType,
index_type: MTLIndexType,
index_buffer: MTLGPUAddress,
index_buffer_length: NSUInteger,
indirect_buffer: MTLGPUAddress,
);
#[cfg(all(
feature = "MTLAllocation",
feature = "MTLIndirectCommandBuffer",
feature = "MTLResource"
))]
/// Encodes a command that runs a range of commands from an indirect command buffer.
///
/// - Parameters:
/// - indirectCommandBuffer: A ``MTLIndirectCommandBuffer`` instance containing other commands that the current command runs.
/// - executionRange: A span of integers that represent the command entries in the buffer that the current command runs.
///
/// # Safety
///
/// - `indirect_command_buffer` may need to be synchronized.
/// - `indirect_command_buffer` may be unretained, you must ensure it is kept alive while in use.
/// - `executionRange` might not be bounds-checked.
#[unsafe(method(executeCommandsInBuffer:withRange:))]
#[unsafe(method_family = none)]
unsafe fn executeCommandsInBuffer_withRange(
&self,
indirect_command_buffer: &ProtocolObject<dyn MTLIndirectCommandBuffer>,
execution_range: NSRange,
);
#[cfg(all(
feature = "MTLAllocation",
feature = "MTLGPUAddress",
feature = "MTLIndirectCommandBuffer",
feature = "MTLResource"
))]
/// Encodes a command that runs an indirect range of commands from an indirect command buffer.
///
/// Use this method to indicate to Metal the span of indices in the command buffer to execute indirectly via an
/// ``MTLBuffer`` instance you provide in the `indirectRangeBuffer` parameter. This allows you to calculate the
/// span of commands Metal executes in the GPU timeline, enabling GPU-driven workflows.
///
/// Metal requires that the contents of this buffer match the layout of struct ``MTLIndirectCommandBufferExecutionRange``,
/// which specifies a location and a length within the indirect command buffer. You are responsible for ensuring the
/// address of this buffer has 4-byte alignment.
///
/// Use an instance of ``MTLResidencySet`` to mark residency of the indirect buffer that the `indirectRangeBuffer`
/// parameter references.
///
/// - Parameters:
/// - indirectCommandBuffer: A ``MTLIndirectCommandBuffer`` instance that contains other commands
/// the current command runs.
/// - indirectRangeBuffer: GPUAddress of a ``MTLBuffer`` instance with data that matches the layout of the
/// ``MTLIndirectCommandBufferExecutionRange`` structure. This address requires 4-byte alignment.
///
/// # Safety
///
/// - `indirect_command_buffer` may need to be synchronized.
/// - `indirect_command_buffer` may be unretained, you must ensure it is kept alive while in use.
/// - `indirectRangeBuffer` might not be bounds-checked.
#[unsafe(method(executeCommandsInBuffer:indirectBuffer:))]
#[unsafe(method_family = none)]
unsafe fn executeCommandsInBuffer_indirectBuffer(
&self,
indirect_command_buffer: &ProtocolObject<dyn MTLIndirectCommandBuffer>,
indirect_range_buffer: MTLGPUAddress,
);
/// Configures the size of a threadgroup memory buffer for a threadgroup argument in the object shader function.
///
/// - Parameters:
/// - length: The size of the threadgroup memory, in bytes.
/// - index: An integer that corresponds to the index of the argument you annotate with attribute `[[threadgroup(index)]]`
/// in the shader function.
///
/// # Safety
///
/// `index` might not be bounds-checked.
#[unsafe(method(setObjectThreadgroupMemoryLength:atIndex:))]
#[unsafe(method_family = none)]
unsafe fn setObjectThreadgroupMemoryLength_atIndex(
&self,
length: NSUInteger,
index: NSUInteger,
);
#[cfg(feature = "MTLTypes")]
/// Encodes a draw command that invokes a mesh shader and, optionally, an object shader with a grid of threadgroups.
///
/// - Parameters:
/// - threadgroupsPerGrid: A ``MTLSize`` instance that represents the number of threadgroups for each grid dimension.
/// - threadsPerObjectThreadgroup: A ``MTLSize`` instance that represents the number of threads in an object
/// shader threadgroup, if applicable.
/// - threadsPerMeshThreadgroup: A ``MTLSize`` instance that represents the number of threads in a mesh shader
/// threadgroup.
#[unsafe(method(drawMeshThreadgroups:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:))]
#[unsafe(method_family = none)]
fn drawMeshThreadgroups_threadsPerObjectThreadgroup_threadsPerMeshThreadgroup(
&self,
threadgroups_per_grid: MTLSize,
threads_per_object_threadgroup: MTLSize,
threads_per_mesh_threadgroup: MTLSize,
);
#[cfg(feature = "MTLTypes")]
/// Encodes a draw command that invokes a mesh shader and, optionally, an object shader with a grid of threads.
///
/// - Parameters:
/// - threadsPerGrid: A ``MTLSize`` instance that represents the number of threads for each grid dimension.
/// For mesh shaders, the command rounds the value down to the nearest multiple of
/// `threadsPerMeshThreadgroup` for each dimension. For object shaders, the value doesn’t
/// need to be a multiple of `threadsPerObjectThreadgroup`.
/// - threadsPerObjectThreadgroup: A ``MTLSize`` instance that represents the number of threads in an object
/// shader threadgroup, if applicable.
/// - threadsPerMeshThreadgroup: A ``MTLSize`` instance that represents the number of threads in a mesh shader
/// threadgroup.
#[unsafe(method(drawMeshThreads:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:))]
#[unsafe(method_family = none)]
fn drawMeshThreads_threadsPerObjectThreadgroup_threadsPerMeshThreadgroup(
&self,
threads_per_grid: MTLSize,
threads_per_object_threadgroup: MTLSize,
threads_per_mesh_threadgroup: MTLSize,
);
#[cfg(all(feature = "MTLGPUAddress", feature = "MTLTypes"))]
/// Encodes a draw command that invokes a mesh shader and, optionally, an object shader with indirect arguments.
///
/// This method enables you to determine the number of threadgroups per grid indirectly, in the GPU timeline.
/// Metal expects this buffer's contents to match the layout of structure ``MTLDispatchThreadgroupsIndirectArguments``.
/// You are responsible for ensuring the address of this buffer has 4-byte alignment.
///
/// Use an instance of ``MTLResidencySet`` to mark residency of the indirect buffer that the `indirectBuffer` parameter
/// references.
///
/// - Parameters:
/// - indirectBuffer: GPUAddress of an ``MTLBuffer`` instance with data that matches the layout of the
/// ``MTLDispatchThreadgroupsIndirectArguments`` structure. This address requires 4-byte alignment.
/// - threadsPerObjectThreadgroup: A ``MTLSize`` instance that represents the number of threads in an object
/// shader threadgroup, if applicable.
/// - threadsPerMeshThreadgroup: A ``MTLSize`` instance that represents the number of threads in a mesh shader
/// threadgroup.
#[unsafe(method(drawMeshThreadgroupsWithIndirectBuffer:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:))]
#[unsafe(method_family = none)]
fn drawMeshThreadgroupsWithIndirectBuffer_threadsPerObjectThreadgroup_threadsPerMeshThreadgroup(
&self,
indirect_buffer: MTLGPUAddress,
threads_per_object_threadgroup: MTLSize,
threads_per_mesh_threadgroup: MTLSize,
);
#[cfg(feature = "MTLTypes")]
/// Encodes a command that invokes a tile shader function from the encoder’s current tile render pipeline state.
///
/// - Parameter threadsPerTile: A ``MTLSize`` instance that represents the number of threads the render pass uses per tile.
/// Set the size’s ``MTLSize/width`` and ``MTLSize/height`` properties to values that are less
/// than or equal to ``tileWidth`` and ``tileHeight``, respectively. Some GPU families
/// only support square tile dispatches and require the same value for width and height.
/// Set ``MTLSize/depth`` to `1`.
#[unsafe(method(dispatchThreadsPerTile:))]
#[unsafe(method_family = none)]
fn dispatchThreadsPerTile(&self, threads_per_tile: MTLSize);
/// Configures the size of a threadgroup memory buffer for a threadgroup argument in the fragment and tile shader functions.
///
/// - Parameters:
/// - length: The size of the threadgroup memory, in bytes.
/// - offset: An integer that represents the location, in bytes, from the start of the threadgroup memory buffer
/// at `index` where the threadgroup memory begins.
/// - index: An integer that corresponds to the index of the argument you annotate with attribute `[[threadgroup(index)]]`
/// in the shader function.
///
/// # Safety
///
/// - `offset` might not be bounds-checked.
/// - `index` might not be bounds-checked.
#[unsafe(method(setThreadgroupMemoryLength:offset:atIndex:))]
#[unsafe(method_family = none)]
unsafe fn setThreadgroupMemoryLength_offset_atIndex(
&self,
length: NSUInteger,
offset: NSUInteger,
index: NSUInteger,
);
#[cfg(all(feature = "MTL4ArgumentTable", feature = "MTLRenderCommandEncoder"))]
/// Associates an argument table with a set of render stages.
///
/// Metal takes a snapshot of the resources in the argument table when you encode a draw, dispatch, or execute command.
/// This snapshot becomes available to the `stages` you specify to this method.
///
/// - Parameters:
/// - argumentTable: ``MTL4ArgumentTable`` to set.
/// - stages: A ``MTLRenderStages`` bitmask that specifies the shader stages with visibility over the table.
#[unsafe(method(setArgumentTable:atStages:))]
#[unsafe(method_family = none)]
fn setArgumentTable_atStages(
&self,
argument_table: &ProtocolObject<dyn MTL4ArgumentTable>,
stages: MTLRenderStages,
);
#[cfg(feature = "MTLRenderCommandEncoder")]
/// Configures the vertex winding order that determines which face of a geometric primitive is the front one.
///
/// - Parameter frontFacingWinding: A ``MTLWinding`` value that determines which side of a primitive the render pipeline
/// interprets as front facing.
#[unsafe(method(setFrontFacingWinding:))]
#[unsafe(method_family = none)]
fn setFrontFacingWinding(&self, front_facing_winding: MTLWinding);
#[cfg(all(feature = "MTL4Counters", feature = "MTLRenderCommandEncoder"))]
/// Writes a GPU timestamp into the given ``MTL4CounterHeap`` at `index` after `stage` completes.
///
/// This command only guarantees all draws prior to this command are complete when Metal writes the timestamp into
/// the counter heap you provide in the `counterHeap` parameter. The timestamp may also include subsequent operations.
///
/// If you call this method before any draw calls, Metal writes a timestamp before the stage you specify in the
/// `stage` parameter begins.
///
/// - Parameters:
/// - granularity: a ``MTL4TimestampGranularity`` hint.
/// - stage: ``MTLRenderStages`` that need to complete before Metal writes the timestamp. This may also include later
/// stages that are related, for example ``MTLRenderStages/MTLRenderStageMesh`` may include
/// ``MTLRenderStages/MTLRenderStageVertex``.
/// - counterHeap: ``MTL4CounterHeap`` into which Metal writes timestamps.
/// - index: The index value into which Metal writes this timestamp.
///
/// # Safety
///
/// `index` might not be bounds-checked.
#[unsafe(method(writeTimestampWithGranularity:afterStage:intoHeap:atIndex:))]
#[unsafe(method_family = none)]
unsafe fn writeTimestampWithGranularity_afterStage_intoHeap_atIndex(
&self,
granularity: MTL4TimestampGranularity,
stage: MTLRenderStages,
counter_heap: &ProtocolObject<dyn MTL4CounterHeap>,
index: NSUInteger,
);
}
);