MTL4RenderCommandEncoder
Encodes configuration and draw commands for a single render pass into a command buffer.
Declaration
protocol MTL4RenderCommandEncoder : MTL4CommandEncoderMentioned in
Overview
A render pass draws a scene, or a component within a scene, to its render attachments, the outputs of a render pass. You can render to those outputs with various approaches, including techniques that apply the following:
Primitive drawing
Mesh drawing
Ray tracing
Dispatching tile shaders
Create a render encoder by calling a factory method of an MTL4CommandBuffer instance, such as makeRenderCommandEncoder(descriptor:options:).
To configure the render pass for your first drawing commands, start with a pipeline state by passing an MTLRenderPipelineState instance to the encoder’s setRenderPipelineState(_:) method. You create the pipeline states your render pass needs, typically ahead of time, by calling one or more MTLDevice methods (see Pipeline state creation).
Configure other encoder settings by calling the methods in the configuration groups below, such as setViewport(_:) for the viewport, setScissorRect(_:) for the scissor rectangle, and setDepthStencilState(_:) for depth and stencil tests.
Bind resources by calling setArgumentTable(_:stages:) with an MTL4ArgumentTable instance. This table contains the buffers, textures, and other resources your shaders depend on.
Encode drawing commands after you configure the state and resources the commands depend on. The encoder maintains its current state and applies it to all subsequent draw commands. For drawing commands that need different states or resources, reconfigure the render pass appropriately and then encode those draw commands. Repeat the process for each batch of drawing commands that depend on the same render pass configuration and resources.
When you finish encoding the render pass’s commands, finalize it into the command buffer by calling the encoder’s endEncoding() method.
Command stages
Most render commands apply to one or more stages within a pass. The following table shows which stages apply to each command:
Draw commands don’t apply to fragment when the MTLRenderPipelineState for the draw disables rasterization. See isRasterizationEnabled.
Mesh draw commands don’t apply to object when the MTLRenderPipelineState for the draw doesn’t have an object shader.
The executeCommands(buffer:range:) and executeCommands(buffer:indirectBuffer:) commands don’t apply to any stage, which means you can’t use a barrier to wait for all commands in an indirect command buffer to complete. However, each command within the MTLIndirectCommandBuffer applies to the same stages as when you encode the equivalent command directly.
For more information about stages and synchronization, see MTLStages and Resource synchronization.
Topics
Configuring pipeline state
Configuring the actions for attachments
Configuring blend behavior
Configuring rendering behavior
Configuring depth and stencil behavior
setDepthStencilState(_:)setDepthBias(_:slopeScale:clamp:)setDepthClipMode(_:)setDepthTestBounds(_:)setStencilReferenceValue(_:)setStencilReferenceValue(front:back:)
Configuring viewport and scissor behavior
Configuring visibility testing
Configuring vertex amplification
Configuring persistent threadgroup memory
Binding argument tables
Drawing with vertices
drawPrimitives(primitiveType:vertexStart:vertexCount:)drawPrimitives(primitiveType:vertexStart:vertexCount:instanceCount:)drawPrimitives(primitiveType:vertexStart:vertexCount:instanceCount:baseInstance:)drawPrimitives(primitiveType:indirectBuffer:)
Drawing with indexed vertices
drawIndexedPrimitives(primitiveType:indexCount:indexType:indexBuffer:indexBufferLength:)drawIndexedPrimitives(primitiveType:indexCount:indexType:indexBuffer:indexBufferLength:instanceCount:)drawIndexedPrimitives(primitiveType:indexCount:indexType:indexBuffer:indexBufferLength:instanceCount:baseVertex:baseInstance:)drawIndexedPrimitives(primitiveType:indexType:indexBuffer:indexBufferLength:indirectBuffer:)
Drawing with meshes
drawMeshThreads(threadsPerGrid:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:)drawMeshThreadgroups(threadgroupsPerGrid:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:)drawMeshThreadgroups(indirectBuffer:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:)