--- title: MTLRenderCommandEncoder framework: metal role: symbol role_heading: Protocol path: metal/mtlrendercommandencoder --- # MTLRenderCommandEncoder Encodes configuration and draw commands for a single render pass into a command buffer. ## Declaration ```swift protocol MTLRenderCommandEncoder : MTLCommandEncoder ``` ## Mentioned 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 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). tip: Avoid visual stutter by creating pipeline states at a noncritical time, such as during launch, because of the time it can take to make them. 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. note: MTLRenderStages and its values have the same functionality as MTLStages and its corresponding stage values. For more information about stages and synchronization, see MTLStages and Resource synchronization. ## Topics ### Configuration commands - [Render pass configuration](metal/render-pass-configuration.md) ### Resource preparation commands - [Mesh and object shader resource preparation commands](metal/mesh-and-object-shader-resource-preparation-commands.md) - [Vertex shader resource preparation commands](metal/vertex-shader-resource-preparation-commands.md) - [Fragment shader resource preparation commands](metal/fragment-shader-resource-preparation-commands.md) - [Tile shaders resource preparation commands](metal/tile-shaders-resource-preparation-commands.md) - [Argument buffer resource preparation commands](metal/argument-buffer-resource-preparation-commands.md) ### Drawing with vertices - [drawPrimitives(type:vertexStart:vertexCount:)](metal/mtlrendercommandencoder/drawprimitives(type:vertexstart:vertexcount:).md) - [drawPrimitives(type:vertexStart:vertexCount:instanceCount:)](metal/mtlrendercommandencoder/drawprimitives(type:vertexstart:vertexcount:instancecount:).md) - [drawPrimitives(type:vertexStart:vertexCount:instanceCount:baseInstance:)](metal/mtlrendercommandencoder/drawprimitives(type:vertexstart:vertexcount:instancecount:baseinstance:).md) - [drawPrimitives(type:indirectBuffer:indirectBufferOffset:)](metal/mtlrendercommandencoder/drawprimitives(type:indirectbuffer:indirectbufferoffset:).md) ### Drawing with indexed vertices - [drawIndexedPrimitives(type:indexCount:indexType:indexBuffer:indexBufferOffset:)](metal/mtlrendercommandencoder/drawindexedprimitives(type:indexcount:indextype:indexbuffer:indexbufferoffset:).md) - [drawIndexedPrimitives(type:indexCount:indexType:indexBuffer:indexBufferOffset:instanceCount:)](metal/mtlrendercommandencoder/drawindexedprimitives(type:indexcount:indextype:indexbuffer:indexbufferoffset:instancecount:).md) - [drawIndexedPrimitives(type:indexCount:indexType:indexBuffer:indexBufferOffset:instanceCount:baseVertex:baseInstance:)](metal/mtlrendercommandencoder/drawindexedprimitives(type:indexcount:indextype:indexbuffer:indexbufferoffset:instancecount:basevertex:baseinstance:).md) - [drawIndexedPrimitives(type:indexType:indexBuffer:indexBufferOffset:indirectBuffer:indirectBufferOffset:)](metal/mtlrendercommandencoder/drawindexedprimitives(type:indextype:indexbuffer:indexbufferoffset:indirectbuffer:indirectbufferoffset:).md) ### Drawing with meshes - [drawMeshThreads(_:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:)](metal/mtlrendercommandencoder/drawmeshthreads(_:threadsperobjectthreadgroup:threadspermeshthreadgroup:).md) - [drawMeshThreadgroups(_:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:)](metal/mtlrendercommandencoder/drawmeshthreadgroups(_:threadsperobjectthreadgroup:threadspermeshthreadgroup:).md) - [drawMeshThreadgroups(indirectBuffer:indirectBufferOffset:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:)](metal/mtlrendercommandencoder/drawmeshthreadgroups(indirectbuffer:indirectbufferoffset:threadsperobjectthreadgroup:threadspermeshthreadgroup:).md) ### Drawing with tessellation patches - [drawPatches(numberOfPatchControlPoints:patchStart:patchCount:patchIndexBuffer:patchIndexBufferOffset:instanceCount:baseInstance:)](metal/mtlrendercommandencoder/drawpatches(numberofpatchcontrolpoints:patchstart:patchcount:patchindexbuffer:patchindexbufferoffset:instancecount:baseinstance:).md) - [drawPatches(numberOfPatchControlPoints:patchIndexBuffer:patchIndexBufferOffset:indirectBuffer:indirectBufferOffset:)](metal/mtlrendercommandencoder/drawpatches(numberofpatchcontrolpoints:patchindexbuffer:patchindexbufferoffset:indirectbuffer:indirectbufferoffset:).md) ### Drawing with indexed tessellation patches - [drawIndexedPatches(numberOfPatchControlPoints:patchStart:patchCount:patchIndexBuffer:patchIndexBufferOffset:controlPointIndexBuffer:controlPointIndexBufferOffset:instanceCount:baseInstance:)](metal/mtlrendercommandencoder/drawindexedpatches(numberofpatchcontrolpoints:patchstart:patchcount:patchindexbuffer:patchindexbufferoffset:controlpointindexbuffer:controlpointindexbufferoffset:instancecount:baseinstance:).md) - [drawIndexedPatches(numberOfPatchControlPoints:patchIndexBuffer:patchIndexBufferOffset:controlPointIndexBuffer:controlPointIndexBufferOffset:indirectBuffer:indirectBufferOffset:)](metal/mtlrendercommandencoder/drawindexedpatches(numberofpatchcontrolpoints:patchindexbuffer:patchindexbufferoffset:controlpointindexbuffer:controlpointindexbufferoffset:indirectbuffer:indirectbufferoffset:).md) ### Drawing with tile shaders - [dispatchThreadsPerTile(_:)](metal/mtlrendercommandencoder/dispatchthreadspertile(_:).md) - [tileWidth](metal/mtlrendercommandencoder/tilewidth.md) - [tileHeight](metal/mtlrendercommandencoder/tileheight.md) ### Preventing resource access conflicts - [waitForFence(_:before:)](metal/mtlrendercommandencoder/waitforfence(_:before:).md) - [updateFence(_:after:)](metal/mtlrendercommandencoder/updatefence(_:after:).md) - [memoryBarrier(resources:after:before:)](metal/mtlrendercommandencoder/memorybarrier(resources:after:before:).md) - [memoryBarrier(scope:after:before:)](metal/mtlrendercommandencoder/memorybarrier(scope:after:before:).md) ### Running commands from indirect command buffers - [executeCommandsInBuffer(_:range:)](metal/mtlrendercommandencoder/executecommandsinbuffer(_:range:).md) - [executeCommandsInBuffer(_:indirectBuffer:offset:)](metal/mtlrendercommandencoder/executecommandsinbuffer(_:indirectbuffer:offset:).md) ### Sampling counters - [sampleCounters(sampleBuffer:sampleIndex:barrier:)](metal/mtlrendercommandencoder/samplecounters(samplebuffer:sampleindex:barrier:).md) ### Deprecated - [Deprecated symbols](metal/deprecated-symbols.md) ## Relationships ### Inherits From - [MTLCommandEncoder](metal/mtlcommandencoder.md) - [NSObjectProtocol](objectivec/nsobjectprotocol.md) ## See Also ### Encoding a render pass - [MTL4RenderCommandEncoder](metal/mtl4rendercommandencoder.md) - [MTL4RenderEncoderOptions](metal/mtl4renderencoderoptions.md) - [MTLTriangleFillMode](metal/mtltrianglefillmode.md) - [MTLWinding](metal/mtlwinding.md) - [MTLCullMode](metal/mtlcullmode.md) - [MTLPrimitiveType](metal/mtlprimitivetype.md) - [MTLIndexType](metal/mtlindextype.md) - [MTLDepthClipMode](metal/mtldepthclipmode.md) - [MTLVisibilityResultMode](metal/mtlvisibilityresultmode.md) - [MTLVisibilityResultType](metal/mtlvisibilityresulttype.md)