Protocol

MTLRenderCommandEncoder

An encoder that specifies graphics-rendering commands and executes graphics functions.

Overview

To perform a rendering pass with a render command encoder:

  1. Create a MTLRenderCommandEncoder object by calling the makeRenderCommandEncoder(descriptor:) 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 section.

Topics

Setting Graphics Rendering State

func setBlendColor(red: Float, green: Float, blue: Float, alpha: Float)

Specifies the constant blend color and alpha values.

Required.

func setCullMode(MTLCullMode)

Controls whether primitives are culled when front facing, back facing, or not culled at all.

Required.

func setDepthBias(Float, slopeScale: Float, clamp: Float)

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

Required.

func setDepthClipMode(MTLDepthClipMode)

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

Required.

func setDepthStencilState(MTLDepthStencilState?)

Sets the depth and stencil test state.

Required.

func setFrontFacing(MTLWinding)

Sets the winding order of front-facing primitives.

Required.

func setRenderPipelineState(MTLRenderPipelineState)

Sets the current render pipeline state object.

Required.

func setStencilReferenceValues(front: UInt32, back: UInt32)

Separately sets the front and back stencil reference values for stencil comparison tests.

Required.

func setStencilReferenceValue(UInt32)

Jointly sets the front and back stencil reference values for stencil comparison tests.

Required.

func setTriangleFillMode(MTLTriangleFillMode)

Sets how to rasterize triangle and triangle strip primitives.

Required.

func setVisibilityResultMode(MTLVisibilityResultMode, offset: Int)

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

Required.

func setViewport(MTLViewport)

Sets the viewport used for transformations and clipping.

Required.

func setViewports([MTLViewport])

Sets an array of viewports, one of which is used for transformations and clipping.

func setScissorRect(MTLScissorRect)

Sets the scissor rectangle for a fragment scissor test.

Required.

func setScissorRects([MTLScissorRect])

Sets an array of scissor rectangles, one of which is used for a fragment scissor test.

Specifying Resources for a Vertex Shader Function

func setVertexBuffer(MTLBuffer?, offset: Int, index: Int)

Sets a buffer for the vertex shader function at an index in the buffer argument table with an offset that specifies the start of the data.

Required.

func setVertexBuffers([MTLBuffer?], offsets: [Int], range: Range<Int>)

Sets an array of buffers for the vertex shader in a range of indices in the buffer argument table, with offsets for the start of each data set.

func setVertexBufferOffset(Int, index: Int)

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

Required.

func setVertexBytes(UnsafeRawPointer, length: Int, index: Int)

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

Required.

func setVertexSamplerState(MTLSamplerState?, index: Int)

Sets a sampler state for the vertex shader function at the index in the sampler state argument table.

Required.

func setVertexSamplerState(MTLSamplerState?, lodMinClamp: Float, lodMaxClamp: Float, index: Int)

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

Required.

func setVertexSamplerStates([MTLSamplerState?], range: Range<Int>)

Sets a sampler state for the vertex shader function in the range of indices in the sampler state argument table.

func setVertexSamplerStates([MTLSamplerState?], lodMinClamps: [Float], lodMaxClamps: [Float], range: Range<Int>)

Sets a sampler state for the vertex shader in the range of indices in the sampler state argument table, with clamp values for the level of detail.

func setVertexTexture(MTLTexture?, index: Int)

Sets a texture for the vertex shader function at the index in the texture argument table.

Required.

func setVertexTextures([MTLTexture?], range: Range<Int>)

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

Specifying Resources for a Fragment Shader Function

func setFragmentBuffer(MTLBuffer?, offset: Int, index: Int)

Sets a buffer for the fragment shader function at an index in the buffer argument table with an offset that specifies the start of the data.

Required.

func setFragmentBuffers([MTLBuffer?], offsets: [Int], range: Range<Int>)

Sets an array of buffers for the fragment shader function at a range of indices in the buffer argument table, with offsets for the start of each data set.

func setFragmentBufferOffset(Int, index: Int)

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

Required.

func setFragmentBytes(UnsafeRawPointer, length: Int, index: Int)

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

Required.

func setFragmentSamplerState(MTLSamplerState?, index: Int)

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

Required.

func setFragmentSamplerState(MTLSamplerState?, lodMinClamp: Float, lodMaxClamp: Float, index: Int)

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

Required.

func setFragmentSamplerStates([MTLSamplerState?], lodMinClamps: [Float], lodMaxClamps: [Float], range: Range<Int>)

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

func setFragmentSamplerStates([MTLSamplerState?], range: Range<Int>)

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

func setFragmentTexture(MTLTexture?, index: Int)

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

Required.

func setFragmentTextures([MTLTexture?], range: Range<Int>)

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

Specifying Resources for a Tile Shader Function

var tileHeight: Int

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

Required.

var tileWidth: Int

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

Required.

func setTileBuffer(MTLBuffer?, offset: Int, index: Int)

Sets a buffer for all tile shaders at an index in the buffer argument table with an offset that specifies the start of the data.

Required.

func setTileBuffers([MTLBuffer?], offsets: [Int], range: Range<Int>)

Sets an array of buffers for all tile shaders in a range of indices in the buffer argument table, with offsets for the start of each data set.

func setTileBufferOffset(Int, index: Int)

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

Required.

func setTileBytes(UnsafeRawPointer, length: Int, index: Int)

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

Required.

func setTileSamplerState(MTLSamplerState?, index: Int)

Sets a sampler state for all tile shaders at the index in the sampler state argument table.

Required.

func setTileSamplerState(MTLSamplerState?, lodMinClamp: Float, lodMaxClamp: Float, index: Int)

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

Required.

func setTileSamplerStates([MTLSamplerState?], range: Range<Int>)

Sets a sampler state for all tile shaders in the range of indices in the sampler state argument table.

func setTileSamplerStates([MTLSamplerState?], lodMinClamps: [Float], lodMaxClamps: [Float], range: Range<Int>)

Sets a sampler state for tall tile shaders in the range of indices in the sampler state argument table, specifying clamp values for the level of detail.

func setTileTexture(MTLTexture?, index: Int)

Sets a texture for all tile shaders at the index in the texture argument table.

Required.

func setTileTextures([MTLTexture?], range: Range<Int>)

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

Specifying Tessellation Factors

func setTessellationFactorBuffer(MTLBuffer?, offset: Int, instanceStride: Int)

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

Required.

func setTessellationFactorScale(Float)

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

Required.

Drawing Geometric Primitives

func drawPrimitives(type: MTLPrimitiveType, vertexStart: Int, vertexCount: Int, instanceCount: Int, baseInstance: Int)

Renders a number of instances of primitives using vertex data in contiguous array elements, starting from the base instance.

Required.

func drawPrimitives(type: MTLPrimitiveType, vertexStart: Int, vertexCount: Int, instanceCount: Int)

Renders a number of instances of primitives using vertex data in contiguous array elements.

Required.

func drawPrimitives(type: MTLPrimitiveType, vertexStart: Int, vertexCount: Int)

Renders one instance of primitives using vertex data in contiguous array elements.

Required.

func drawPrimitives(type: MTLPrimitiveType, indirectBuffer: MTLBuffer, indirectBufferOffset: Int)

Renders a number of instances of primitives using vertex data in contiguous array elements, starting from a base instance.

Required.

func drawIndexedPrimitives(type: MTLPrimitiveType, indexCount: Int, indexType: MTLIndexType, indexBuffer: MTLBuffer, indexBufferOffset: Int, instanceCount: Int, baseVertex: Int, baseInstance: Int)

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

Required.

func drawIndexedPrimitives(type: MTLPrimitiveType, indexType: MTLIndexType, indexBuffer: MTLBuffer, indexBufferOffset: Int, indirectBuffer: MTLBuffer, indirectBufferOffset: Int)

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

Required.

Executing a Tile Shader

func dispatchThreadsPerTile(MTLSize)

Encodes a dispatch call for a tile shading function to perform a midrender compute operation.

Required.

Enabling Texture Barriers

func textureBarrier()

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

Required.

Specifying a Store Action

func setColorStoreAction(MTLStoreAction, index: Int)

Specifies a known store action to replace the initial unknown value specified for a given color attachment.

Required.

func setColorStoreActionOptions(MTLStoreActionOptions, index: Int)

Specifies known store action options for a given color attachment.

Required.

func setDepthStoreAction(MTLStoreAction)

Specifies a known store action to replace the initial unknown value specified for a given depth attachment.

Required.

func setDepthStoreActionOptions(MTLStoreActionOptions)

Specifies known store action options for a given depth attachment.

Required.

func setStencilStoreAction(MTLStoreAction)

Specifies a known store action to replace the initial unknown value specified for a given stencil attachment.

Required.

func setStencilStoreActionOptions(MTLStoreActionOptions)

Specifies known store action options for a given stencil attachment.

Required.

Performing Fence Operations

func update(MTLFence, after: MTLRenderStages)

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

Required.

func wait(for: MTLFence, before: MTLRenderStages)

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

Required.

Specifying Resources for an Argument Buffer

func useResource(MTLResource, usage: MTLResourceUsage)

Specifies that a resource in an argument buffer can be safely used by a render pass.

Required.

func useResources([MTLResource], usage: MTLResourceUsage)

Specifies that an array of resources in an argument buffer can be safely used by a render pass.

func useHeap(MTLHeap)

Specifies that a heap containing resources in an argument buffer can be safely used by a render pass.

Required.

func useHeaps([MTLHeap])

Specifies that an array of heaps containing resources in an argument buffer can be safely used by a render pass.

Specifying Threadgroup Memory Length

func setThreadgroupMemoryLength(Int, offset: Int, index: Int)

Sets the size of the threadgroup memory argument at the given argument table index and offset.

Required.

Constants

enum MTLPrimitiveType

The geometric primitive type for drawing commands.

enum MTLIndexType

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

enum MTLVisibilityResultMode

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

enum MTLCullMode

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

enum MTLWinding

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

enum MTLDepthClipMode

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

enum MTLTriangleFillMode

The mode that determines how to rasterize triangle and triangle strip primitives.

struct MTLRenderStages

The render stage at which a fence is either updated or waited for.

Structures

struct MTLDrawIndexedPrimitivesIndirectArguments

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

struct MTLDrawPatchIndirectArguments

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

struct MTLDrawPrimitivesIndirectArguments

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

struct MTLQuadTessellationFactorsHalf

The per-patch tessellation factors for a quad patch.

struct MTLTriangleTessellationFactorsHalf

The per-patch tessellation factors for a triangle patch.

struct MTLScissorRect

A rectangle for the scissor fragment test.

struct MTLViewport

A 3D rectangular region for the viewport clipping.

Relationships

Inherits From

See Also

Encoders

protocol MTLBlitCommandEncoder

An encoder that specifies resource copy and resource synchronization commands.

protocol MTLComputeCommandEncoder

An encoder that specifies compute-processing commands and executes compute functions.

protocol MTLParallelRenderCommandEncoder

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