--- title: MTL4RenderCommandEncoder framework: metal role: symbol role_heading: Protocol path: metal/mtl4rendercommandencoder --- # MTL4RenderCommandEncoder Encodes configuration and draw commands for a single render pass into a command buffer. ## Declaration ```swift protocol MTL4RenderCommandEncoder : MTL4CommandEncoder ``` ## Mentioned in Understanding the Metal 4 core API ## 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 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). 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 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 - [setRenderPipelineState(_:)](metal/mtl4rendercommandencoder/setrenderpipelinestate(_:).md) ### Configuring the actions for attachments - [setColorStoreAction(_:index:)](metal/mtl4rendercommandencoder/setcolorstoreaction(_:index:).md) - [setDepthStoreAction(_:)](metal/mtl4rendercommandencoder/setdepthstoreaction(_:).md) - [setStencilStoreAction(_:)](metal/mtl4rendercommandencoder/setstencilstoreaction(_:).md) ### Configuring blend behavior - [setBlendColor(red:green:blue:alpha:)](metal/mtl4rendercommandencoder/setblendcolor(red:green:blue:alpha:).md) - [setColorAttachmentMap(_:)](metal/mtl4rendercommandencoder/setcolorattachmentmap(_:).md) ### Configuring rendering behavior - [setTriangleFillMode(_:)](metal/mtl4rendercommandencoder/settrianglefillmode(_:).md) - [setFrontFacing(_:)](metal/mtl4rendercommandencoder/setfrontfacing(_:).md) - [setCullMode(_:)](metal/mtl4rendercommandencoder/setcullmode(_:).md) ### Configuring depth and stencil behavior - [setDepthStencilState(_:)](metal/mtl4rendercommandencoder/setdepthstencilstate(_:).md) - [setDepthBias(_:slopeScale:clamp:)](metal/mtl4rendercommandencoder/setdepthbias(_:slopescale:clamp:).md) - [setDepthClipMode(_:)](metal/mtl4rendercommandencoder/setdepthclipmode(_:).md) - [setDepthTestBounds(_:)](metal/mtl4rendercommandencoder/setdepthtestbounds(_:).md) - [setStencilReferenceValue(_:)](metal/mtl4rendercommandencoder/setstencilreferencevalue(_:).md) - [setStencilReferenceValue(front:back:)](metal/mtl4rendercommandencoder/setstencilreferencevalue(front:back:).md) ### Configuring viewport and scissor behavior - [setViewport(_:)](metal/mtl4rendercommandencoder/setviewport(_:).md) - [setViewports(_:)](metal/mtl4rendercommandencoder/setviewports(_:).md) - [setScissorRect(_:)](metal/mtl4rendercommandencoder/setscissorrect(_:).md) - [setScissorRects(_:)](metal/mtl4rendercommandencoder/setscissorrects(_:).md) ### Configuring visibility testing - [setVisibilityResultMode(_:offset:)](metal/mtl4rendercommandencoder/setvisibilityresultmode(_:offset:).md) ### Configuring vertex amplification - [setVertexAmplificationCount(_:)](metal/mtl4rendercommandencoder/setvertexamplificationcount(_:)-85tu1.md) - [setVertexAmplificationCount(_:)](metal/mtl4rendercommandencoder/setvertexamplificationcount(_:)-911ja.md) ### Configuring persistent threadgroup memory - [setObjectThreadgroupMemoryLength(_:index:)](metal/mtl4rendercommandencoder/setobjectthreadgroupmemorylength(_:index:).md) - [setThreadgroupMemoryLength(_:offset:index:)](metal/mtl4rendercommandencoder/setthreadgroupmemorylength(_:offset:index:).md) ### Binding argument tables - [setArgumentTable(_:stages:)](metal/mtl4rendercommandencoder/setargumenttable(_:stages:).md) ### Drawing with vertices - [drawPrimitives(primitiveType:vertexStart:vertexCount:)](metal/mtl4rendercommandencoder/drawprimitives(primitivetype:vertexstart:vertexcount:).md) - [drawPrimitives(primitiveType:vertexStart:vertexCount:instanceCount:)](metal/mtl4rendercommandencoder/drawprimitives(primitivetype:vertexstart:vertexcount:instancecount:).md) - [drawPrimitives(primitiveType:vertexStart:vertexCount:instanceCount:baseInstance:)](metal/mtl4rendercommandencoder/drawprimitives(primitivetype:vertexstart:vertexcount:instancecount:baseinstance:).md) - [drawPrimitives(primitiveType:indirectBuffer:)](metal/mtl4rendercommandencoder/drawprimitives(primitivetype:indirectbuffer:).md) ### Drawing with indexed vertices - [drawIndexedPrimitives(primitiveType:indexCount:indexType:indexBuffer:indexBufferLength:)](metal/mtl4rendercommandencoder/drawindexedprimitives(primitivetype:indexcount:indextype:indexbuffer:indexbufferlength:).md) - [drawIndexedPrimitives(primitiveType:indexCount:indexType:indexBuffer:indexBufferLength:instanceCount:)](metal/mtl4rendercommandencoder/drawindexedprimitives(primitivetype:indexcount:indextype:indexbuffer:indexbufferlength:instancecount:).md) - [drawIndexedPrimitives(primitiveType:indexCount:indexType:indexBuffer:indexBufferLength:instanceCount:baseVertex:baseInstance:)](metal/mtl4rendercommandencoder/drawindexedprimitives(primitivetype:indexcount:indextype:indexbuffer:indexbufferlength:instancecount:basevertex:baseinstance:).md) - [drawIndexedPrimitives(primitiveType:indexType:indexBuffer:indexBufferLength:indirectBuffer:)](metal/mtl4rendercommandencoder/drawindexedprimitives(primitivetype:indextype:indexbuffer:indexbufferlength:indirectbuffer:).md) ### Drawing with meshes - [drawMeshThreads(threadsPerGrid:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:)](metal/mtl4rendercommandencoder/drawmeshthreads(threadspergrid:threadsperobjectthreadgroup:threadspermeshthreadgroup:).md) - [drawMeshThreadgroups(threadgroupsPerGrid:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:)](metal/mtl4rendercommandencoder/drawmeshthreadgroups(threadgroupspergrid:threadsperobjectthreadgroup:threadspermeshthreadgroup:).md) - [drawMeshThreadgroups(indirectBuffer:threadsPerObjectThreadgroup:threadsPerMeshThreadgroup:)](metal/mtl4rendercommandencoder/drawmeshthreadgroups(indirectbuffer:threadsperobjectthreadgroup:threadspermeshthreadgroup:).md) ### Drawing with tile shaders - [dispatchThreadsPerTile(_:)](metal/mtl4rendercommandencoder/dispatchthreadspertile(_:).md) - [tileWidth](metal/mtl4rendercommandencoder/tilewidth.md) - [tileHeight](metal/mtl4rendercommandencoder/tileheight.md) ### Running commands from indirect command buffers - [executeCommands(buffer:range:)](metal/mtl4rendercommandencoder/executecommands(buffer:range:).md) - [executeCommands(buffer:indirectBuffer:)](metal/mtl4rendercommandencoder/executecommands(buffer:indirectbuffer:).md) ### Sampling counters - [writeTimestamp(granularity:after:counterHeap:index:)](metal/mtl4rendercommandencoder/writetimestamp(granularity:after:counterheap:index:).md) ## Relationships ### Inherits From - [MTL4CommandEncoder](metal/mtl4commandencoder.md) - [NSObjectProtocol](objectivec/nsobjectprotocol.md) ## See Also ### Encoding a render pass - [MTLRenderCommandEncoder](metal/mtlrendercommandencoder.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)