MTLRenderCommandEncoder
Encodes configuration and draw commands for a single render pass into a command buffer.
Declaration
protocol MTLRenderCommandEncoder : MTLCommandEncoderMentioned in
- Understanding the Metal 4 core API
- Improving CPU performance by using argument buffers
- Improving rendering performance with vertex amplification
- Sampling GPU data into counter sample buffers
- Setting up a command structure
- Simplifying GPU resource management with residency sets
- Tracking the resource residency of argument buffers
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
To create an MTLRenderCommandEncoder instance, call the makeRenderCommandEncoder(descriptor:) method of an MTLCommandBuffer instance, or the makeRenderCommandEncoder() method of an MTLParallelRenderCommandEncoder instance.
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 on the Render pass configuration page. For example, you may need to configure the pass’s viewport, its scissor rectangle, and the settings for depth and stencil tests.
Assign resources, such as buffers and textures, for the shaders that depend on them. For more information, see the shader-specific pages in the resource preparation section, such as Vertex shader resource preparation commands and Fragment shader resource preparation commands. If your shaders access resources through an argument buffer, make those resources resident in GPU memory by calling the methods on the Argument buffer resource preparation commands page.
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 executeCommandsInBuffer(_:range:) and executeCommandsInBuffer(_:indirectBuffer:offset:) 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
Configuration commands
Resource preparation commands
Mesh and object shader resource preparation commandsVertex shader resource preparation commandsFragment shader resource preparation commandsTile shaders resource preparation commandsArgument buffer resource preparation commands
Drawing with vertices
drawPrimitives(type:vertexStart:vertexCount:)drawPrimitives(type:vertexStart:vertexCount:instanceCount:)drawPrimitives(type:vertexStart:vertexCount:instanceCount:baseInstance:)drawPrimitives(type:indirectBuffer:indirectBufferOffset:)
Drawing with indexed vertices
drawIndexedPrimitives(type:indexCount:indexType:indexBuffer:indexBufferOffset:)drawIndexedPrimitives(type:indexCount:indexType:indexBuffer:indexBufferOffset:instanceCount:)drawIndexedPrimitives(type:indexCount:indexType:indexBuffer:indexBufferOffset:instanceCount:baseVertex:baseInstance:)drawIndexedPrimitives(type:indexType:indexBuffer:indexBufferOffset:indirectBuffer:indirectBufferOffset:)
Drawing with meshes
drawMeshThreads(_:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:)drawMeshThreadgroups(_:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:)drawMeshThreadgroups(indirectBuffer:indirectBufferOffset:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:)
Drawing with tessellation patches
drawPatches(numberOfPatchControlPoints:patchStart:patchCount:patchIndexBuffer:patchIndexBufferOffset:instanceCount:baseInstance:)drawPatches(numberOfPatchControlPoints:patchIndexBuffer:patchIndexBufferOffset:indirectBuffer:indirectBufferOffset:)
Drawing with indexed tessellation patches
drawIndexedPatches(numberOfPatchControlPoints:patchStart:patchCount:patchIndexBuffer:patchIndexBufferOffset:controlPointIndexBuffer:controlPointIndexBufferOffset:instanceCount:baseInstance:)drawIndexedPatches(numberOfPatchControlPoints:patchIndexBuffer:patchIndexBufferOffset:controlPointIndexBuffer:controlPointIndexBufferOffset:indirectBuffer:indirectBufferOffset:)
Drawing with tile shaders
Preventing resource access conflicts
waitForFence(_:before:)updateFence(_:after:)memoryBarrier(resources:after:before:)memoryBarrier(scope:after:before:)