Protocol

MTLRenderCommandEncoder

The object to use for encoding commands for a render pass.

Declaration

@protocol MTLRenderCommandEncoder

Overview

To perform a rendering pass with a render command encoder:

  1. Create a MTLRenderCommandEncoder object by calling the renderCommandEncoderWithDescriptor: method of the MTLCommandBuffer object in which you want to encode rendering commands. Do not use standard allocation and initialization techniques to create a MTLRenderCommandEncoder object. The render command encoder represents a single rendering pass into a specific attachment. Typically, you create a MTLRenderPassAttachmentDescriptor object once to describe the attachment and then use it repeatedly as the destination for rendering commands for as many rendering passes as needed.

  2. Call the setRenderPipelineState: method to specify a MTLRenderPipelineState that defines the state of the graphics rendering pipeline, including vertex and fragment functions. You usually create this MTLRenderPipelineState infrequently—for example, when your app is initialized. When you create a MTLRenderPipelineState, you have the option to obtain reflection data in MTLRenderPipelineReflection that reveals details of the vertex and fragment functions and their arguments. Only obtain reflection data if you need it.

  3. Specify resources for input to and output from the vertex and fragment functions. Set the location (index) of each resource in its corresponding argument table.

  4. Specify additional fixed-function state, such as viewport, scissor rectangle, depth test, and stencil test settings.

  5. Draw graphics primitives.

  6. Call the endEncoding method to terminate the render command encoder.

To render a number of instances of tessellated patches, call any method in the Drawing Tessellated Patches section. These methods can only be called if the vertex function is a post-tessellation vertex function; conversely, you cannot call any method in the Drawing Geometric Primitives and Tessellated Patches section.

Topics

Setting Graphics Rendering Behavior

- setRenderPipelineState:

Sets the current render pipeline state object.

Required.

- setTriangleFillMode:

Sets how to rasterize triangle and triangle strip primitives.

Required.

MTLTriangleFillMode

Specifies how to rasterize triangle and triangle strip primitives.

- setFrontFacingWinding:

Sets the winding order of front-facing primitives.

Required.

MTLWinding

The vertex winding rule that determines a front-facing primitive.

- setCullMode:

Specifies whether to cull primitives when front- or back-facing.

Required.

MTLCullMode

The mode that determines whether to perform culling and which type of primitive to cull.

Setting Depth and Stencil Behavior

- setDepthStencilState:

Sets the depth and stencil test state.

Required.

- setDepthBias:slopeScale:clamp:

Adjusts the depth values from fragment functions by a scaling factor and a scaling bias, clamping the bias to a maximum amount.

Required.

- setDepthClipMode:

Controls what is done with fragments outside of the near or far planes.

Required.

MTLDepthClipMode

The mode that determines how to deal with fragments outside of the near or far planes.

- setStencilFrontReferenceValue:backReferenceValue:

Sets the stencil reference values for front and back stencil comparison tests.

Required.

- setStencilReferenceValue:

Sets a stencil reference value for both front and back stencil comparison tests.

Required.

Setting Viewport and Scissor Behavior

Rendering to Multiple Viewports in a Draw Command

Select viewports and their corresponding scissor rectangles in your vertex shader.

- setViewport:

Sets the viewport used for transformations and clipping.

Required.

- setViewports:count:

Sets an array of viewports.

Required.

- setScissorRect:

Sets the scissor rectangle for a fragment scissor test.

Required.

- setScissorRects:count:

Sets an array of scissor rectangles.

Required.

MTLViewport

A 3D rectangular region for the viewport clipping.

MTLScissorRect

A rectangle for the scissor fragment test.

Setting Blend Behavior

- setBlendColorRed:green:blue:alpha:

Specifies the constant blend color and alpha values.

Required.

Setting Visibility Behavior

- setVisibilityResultMode:offset:

Controls how to monitor samples that pass the depth and stencil tests.

Required.

MTLVisibilityResultMode

The mode that determines whether samples pass the depth and stencil tests and whether to monitor the samples that pass.

Specifying Resource Usage for Argument Buffers

- useResource:usage:stages:

Adds an untracked resource to the render pass, specifying which render stages need it.

Required.

- useResources:count:usage:stages:

Adds an array of untracked resources to the render pass, specifying which stages need them.

Required.

- useHeap:stages:

Adds the resources in a heap to the render pass, specifying which render stages need them.

Required.

- useHeaps:count:stages:

Adds the resources in an array of heaps to the render pass, specifying which render stages need them.

Required.

- useResource:usage:

Adds an untracked resource to the render pass.

Required.

- useResources:count:usage:

Adds an array of untracked resources to the render pass.

Required.

- useHeap:

Adds the resources in a heap to the render pass.

Required.

- useHeaps:count:

Adds the resources in an array of heaps to the render pass.

Required.

MTLResourceUsage

The options that describe how a resource within an argument buffer will be used in a graphics or compute function.

Specifying Arguments for a Vertex Function

- setVertexBuffer:offset:atIndex:

Sets a buffer for the vertex function.

Required.

- setVertexBuffers:offsets:withRange:

Sets an array of buffers for the vertex function.

Required.

- setVertexBufferOffset:atIndex:

Sets where the data begins in a buffer already bound to the vertex shader.

Required.

- setVertexBytes:length:atIndex:

Sets a block of data for the vertex shader.

Required.

- setVertexSamplerState:atIndex:

Sets a sampler for the vertex function.

Required.

- setVertexSamplerState:lodMinClamp:lodMaxClamp:atIndex:

Sets a sampler for the vertex function, specifying clamp values for the level of detail.

Required.

- setVertexSamplerStates:withRange:

Sets multiple samplers for the vertex function.

Required.

- setVertexSamplerStates:lodMinClamps:lodMaxClamps:withRange:

Sets multiple samplers for the vertex function, specifying clamp values for the level of detail of each sampler.

Required.

- setVertexTexture:atIndex:

Sets a texture for the vertex function.

Required.

- setVertexTextures:withRange:

Sets an array of textures for the vertex function.

Required.

Specifying Arguments for a Fragment Function

- setFragmentBuffer:offset:atIndex:

Sets a buffer for the fragment function.

Required.

- setFragmentBuffers:offsets:withRange:

Sets an array of buffers for the fragment function in a range of indices in the buffer argument table.

Required.

- setFragmentBufferOffset:atIndex:

Sets where the data begins in a buffer already bound to the fragment shader.

Required.

- setFragmentBytes:length:atIndex:

Sets a block of data for the fragment shader.

Required.

- setFragmentSamplerState:atIndex:

Sets a sampler state for the fragment function at an index in the sampler state argument table.

Required.

- setFragmentSamplerStates:withRange:

Sets an array of sampler states for the fragment function in a range of indices in the sampler state argument table.

Required.

- setFragmentSamplerState:lodMinClamp:lodMaxClamp:atIndex:

Sets a sampler state for the fragment function at an index in the sampler state argument table, specifying clamp values for the minimum and maximum level of detail.

Required.

- setFragmentSamplerStates:lodMinClamps:lodMaxClamps:withRange:

Sets sampler states for the fragment function in a range of indices in the sampler state argument table, specifying clamp values for levels of detail.

Required.

- setFragmentTexture:atIndex:

Sets a texture for the fragment function at an index in the texture argument table.

Required.

- setFragmentTextures:withRange:

Sets an array of textures for the fragment function in a range of indices in the texture argument table.

Required.

Specifying Tessellation Factors

- setTessellationFactorBuffer:offset:instanceStride:

Sets the per-patch tessellation factors buffer for the tessellator.

Required.

- setTessellationFactorScale:

Sets the scale factor applied to the per-patch tessellation factors.

Required.

Configuring Vertex Amplification

- setVertexAmplificationCount:viewMappings:

Sets the number of output vertices for each input vertex, along with offsets into the layer and viewport lists.

Required.

MTLVertexAmplificationViewMapping

An offset applied to a render target index and viewport index.

Drawing Geometric Primitives and Tessellated Patches

- drawPrimitives:vertexStart:vertexCount:instanceCount:baseInstance:

Encodes a command to render a number of instances of primitives using vertex data in contiguous array elements, starting from the base instance.

Required.

- drawPrimitives:vertexStart:vertexCount:instanceCount:

Encodes a command to render a number of instances of primitives using vertex data in contiguous array elements.

Required.

- drawPrimitives:vertexStart:vertexCount:

Encodes a command to render one instance of primitives using vertex data in contiguous array elements.

Required.

- drawIndexedPrimitives:indexCount:indexType:indexBuffer:indexBufferOffset:instanceCount:baseVertex:baseInstance:

Encodes a command to render a number of instances of primitives using an index list specified in a buffer, starting from the base vertex of the base instance.

Required.

- drawIndexedPrimitives:indexCount:indexType:indexBuffer:indexBufferOffset:instanceCount:

Encodes a command to render a number of instances of primitives using an index list specified in a buffer.

Required.

- drawIndexedPrimitives:indexCount:indexType:indexBuffer:indexBufferOffset:

Encodes a command to render one instance of primitives using an index list specified in a buffer.

Required.

- drawPatches:patchStart:patchCount:patchIndexBuffer:patchIndexBufferOffset:instanceCount:baseInstance:

Encodes a command to render a number of instances of tessellated patches.

Required.

- drawIndexedPatches:patchStart:patchCount:patchIndexBuffer:patchIndexBufferOffset:controlPointIndexBuffer:controlPointIndexBufferOffset:instanceCount:baseInstance:

Encodes a command to render a number of instances of tessellated patches, using a control point index buffer.

Required.

MTLPrimitiveType

The geometric primitive type for drawing commands.

MTLIndexType

The index type for an index buffer that references vertices of geometric primitives.

MTLQuadTessellationFactorsHalf

The per-patch tessellation factors for a quad patch.

MTLTriangleTessellationFactorsHalf

The per-patch tessellation factors for a triangle patch.

Drawing Geometric Primitives and Tessellated Patches Indirectly

Specifying Drawing and Dispatch Arguments Indirectly

Use indirect commands if you don't know your draw or dispatch call arguments when you encode the command.

- drawPrimitives:indirectBuffer:indirectBufferOffset:

Encodes a command to render a number of instances of primitives using vertex data in contiguous array elements, starting from a base instance.

Required.

- drawIndexedPrimitives:indexType:indexBuffer:indexBufferOffset:indirectBuffer:indirectBufferOffset:

Encodes a command to render a number of instances of primitives using index data in contiguous array elements, starting from the base vertex of a base instance.

Required.

- drawPatches:patchIndexBuffer:patchIndexBufferOffset:indirectBuffer:indirectBufferOffset:

Encodes a command to render a number of instances of tessellated patches, using an indirect buffer.

Required.

- drawIndexedPatches:patchIndexBuffer:patchIndexBufferOffset:controlPointIndexBuffer:controlPointIndexBufferOffset:indirectBuffer:indirectBufferOffset:

Encodes a command to render a number of instances of tessellated patches, using a control point index buffer and an indirect buffer.

Required.

MTLDrawIndexedPrimitivesIndirectArguments

The data layout required for drawing indexed primitives via indirect buffer calls.

MTLDrawPrimitivesIndirectArguments

The data layout required for drawing primitives via indirect buffer calls.

MTLDrawPatchIndirectArguments

The data layout required for drawing patches via indirect buffer calls.

Sampling Rasterization Execution Data

- sampleCountersInBuffer:atSampleIndex:withBarrier:

Encodes a command to sample hardware counters at this point in the render pass and store the samples into a counter sample buffer.

Required.

Specifying Resources for a Tile Function

- setThreadgroupMemoryLength:offset:atIndex:

Sets the size of a threadgroup memory buffer for the tile function at an index in the argument table.

Required.

- setTileBuffer:offset:atIndex:

Sets a buffer for the tile function at an index in the buffer argument table.

Required.

- setTileBuffers:offsets:withRange:

Sets an array of buffers for the tile function in a range of indices in the buffer argument table.

Required.

- setTileBufferOffset:atIndex:

Sets an offset specifying the start of the data for a buffer already bound to the tile function.

Required.

- setTileBytes:length:atIndex:

Sets a block of data for the tile function at an index in the buffer argument table.

Required.

- setTileSamplerState:atIndex:

Sets a sampler state for the tile function at an index in the sampler state argument table.

Required.

- setTileSamplerState:lodMinClamp:lodMaxClamp:atIndex:

Sets a sampler state for the tile function at an index in the sampler state argument table, specifying clamp values for the level of detail.

Required.

- setTileSamplerStates:withRange:

Sets a sampler state for the tile function in a range of indices in the sampler state argument table, specifying clamp values for the minimum and maximum level of detail.

Required.

- setTileSamplerStates:lodMinClamps:lodMaxClamps:withRange:

Sets an array of sampler states for the tile function in a range of indices in the sampler state argument table, specifying clamp values for the minimum and maximum level of detail.

Required.

- setTileTexture:atIndex:

Sets a texture for the tile function at an index in the texture argument table.

Required.

- setTileTextures:withRange:

Sets an array of textures for the tile function in a range of indices in the texture argument table.

Required.

Executing a Tile Function

- setRenderPipelineState:

Sets the current render pipeline state object.

Required.

tileWidth

The width of the tile, in pixels, for this render pass.

Required.

tileHeight

The height of the tile, in pixels, for this render pass.

Required.

- dispatchThreadsPerTile:

Encodes a dispatch call to perform a midrender compute operation.

Required.

Executing Commands from Indirect Command Buffers

- executeCommandsInBuffer:withRange:

Encodes a command to execute commands in an indirect command buffer.

Required.

- executeCommandsInBuffer:indirectBuffer:indirectBufferOffset:

Encodes a command to execute commands in an indirect command buffer, specifying the range indirectly.

Required.

Synchronizing Command Execution for Untracked Resources

- updateFence:afterStages:

Updates the given fence to capture all GPU work enqueued by the command encoder up to the given render stage.

Required.

- waitForFence:beforeStages:

Prevents further GPU work to be enqueued by the command encoder until the given fence is reached for the given render stage.

Required.

- memoryBarrierWithScope:afterStages:beforeStages:

Encodes a barrier so that data written to memory by commands encoded before the barrier is available to commands encoded after the barrier.

Required.

MTLRenderStages

The render stages at which a synchronization command is triggered.

MTLBarrierScope

Describes the types of resources that a barrier operates on.

- textureBarrier

Ensures that any texture reads issued after the barrier can safely read from any rendering to those textures performed before the barrier.

Required.

Deprecated

Setting Render Pass State

- setColorStoreAction:atIndex:

Specifies a store action for a color attachment.

Required.

- setColorStoreActionOptions:atIndex:

Specifies store action options for a color attachment.

Required.

- setDepthStoreAction:

Specifies the depth store action for the depth attachment.

Required.

- setDepthStoreActionOptions:

Specifies store action options for the depth attachment.

Required.

- setStencilStoreAction:

Specifies the stencil store action for the stencil attachment.

Required.

- setStencilStoreActionOptions:

Specifies store action options for the stencil attachment.

Required.

Relationships

Inherits From

See Also

Rendering

Creating and Sampling Textures

Load image data into a texture and apply it to a quadrangle.

Calculating Primitive Visibility Using Depth Testing

Determine which pixels are visible in a scene by using a depth texture.

Generating Multiple Output Vertex Streams from One Input Stream

Render efficiently to multiple layers or viewports.

Render Pipelines

Specify how graphics primitives should be rendered.

MTLRenderPassDescriptor

A group of render targets that hold the results of a render pass.

MTLParallelRenderCommandEncoder

An object that splits up a single render pass so that it can be simultaneously encoded from multiple threads.

Model I/O

Specify precise locations within the textures associated with graphics processing.