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 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 and Tessellated Patches section.

Topics

Setting Graphics Rendering Behavior

func setRenderPipelineState(MTLRenderPipelineState)

Sets the current render pipeline state object.

Required.

func setTriangleFillMode(MTLTriangleFillMode)

Sets how to rasterize triangle and triangle strip primitives.

Required.

enum MTLTriangleFillMode

Specifies how to rasterize triangle and triangle strip primitives.

func setFrontFacing(MTLWinding)

Sets the winding order of front-facing primitives.

Required.

enum MTLWinding

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

func setCullMode(MTLCullMode)

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

Required.

enum MTLCullMode

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

Setting Depth and Stencil Behavior

func setDepthStencilState(MTLDepthStencilState?)

Sets the depth and stencil test state.

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.

enum MTLDepthClipMode

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

func setStencilReferenceValues(front: UInt32, back: UInt32)

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

Required.

func setStencilReferenceValue(UInt32)

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

Required.

Setting Viewport and Scissor Behavior

func setViewport(MTLViewport)

Sets the viewport used for transformations and clipping.

Required.

func setViewports([MTLViewport])

Sets an array of viewports.

struct MTLViewport

A 3D rectangular region for the viewport clipping.

func setScissorRect(MTLScissorRect)

Sets the scissor rectangle for a fragment scissor test.

Required.

struct MTLScissorRect

A rectangle for the scissor fragment test.

Setting Blend Behavior

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

Specifies the constant blend color and alpha values.

Required.

Setting Visibility Behavior

func setVisibilityResultMode(MTLVisibilityResultMode, offset: Int)

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

Required.

enum 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

func useResource(MTLResource, usage: MTLResourceUsage)

Adds an untracked resource to the render pass.

Required.

func useResources([MTLResource], usage: MTLResourceUsage)

Adds an array of untracked resources to the render pass.

func useHeap(MTLHeap)

Adds the resources in a heap to the render pass.

Required.

func useHeaps([MTLHeap])

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

Specifying Resources for a Vertex Function

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

Sets a buffer for the vertex function.

Required.

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

Sets an array of buffers for the vertex function.

func setVertexBufferOffset(Int, index: Int)

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

Required.

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

Sets a block of data for the vertex function.

Required.

func setVertexSamplerState(MTLSamplerState?, index: Int)

Sets a sampler for the vertex function.

Required.

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

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

Required.

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

Sets multiple samplers for the vertex function.

func setVertexTexture(MTLTexture?, index: Int)

Sets a texture for the vertex function.

Required.

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

Sets an array of textures for the vertex function.

Specifying Resources for a Fragment Function

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

Sets a buffer for the fragment function.

Required.

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

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

func setFragmentBufferOffset(Int, index: Int)

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

Required.

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

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

Required.

func setFragmentSamplerState(MTLSamplerState?, index: Int)

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

Required.

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

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.

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

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.

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 function at an index in the texture argument table.

Required.

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

Sets an array of textures for the fragment function 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 and Tessellated Patches

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

Encodes a command to render 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)

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

Required.

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

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

Required.

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

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.

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

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

Required.

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

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

Required.

enum MTLPrimitiveType

The geometric primitive type for drawing commands.

enum MTLIndexType

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

struct MTLQuadTessellationFactorsHalf

The per-patch tessellation factors for a quad patch.

struct MTLTriangleTessellationFactorsHalf

The per-patch tessellation factors for a triangle patch.

Drawing Geometric Primitives and Tessellated Patches Indirectly

Specifying Drawing and Dispatch Parameters Indirectly

Use indirect commands if your draw or dispatch call arguments are dynamically generated by the GPU.

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

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

Required.

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

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.

func drawPatches(numberOfPatchControlPoints: Int, patchIndexBuffer: MTLBuffer?, patchIndexBufferOffset: Int, indirectBuffer: MTLBuffer, indirectBufferOffset: Int)

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

Required.

struct MTLDrawIndexedPrimitivesIndirectArguments

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

struct MTLDrawPrimitivesIndirectArguments

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

struct MTLDrawPatchIndirectArguments

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

Specifying Resources for a Tile Function

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

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

Required.

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

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

Required.

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

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

func setTileBufferOffset(Int, index: Int)

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

Required.

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

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

Required.

func setTileSamplerState(MTLSamplerState?, index: Int)

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

Required.

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

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.

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

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

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

Sets a sampler state for the tile function in a 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 the tile function at an index in the texture argument table.

Required.

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

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

Executing a Tile Function

func setRenderPipelineState(MTLRenderPipelineState)

Sets the current render pipeline state object.

Required.

var tileWidth: Int

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

Required.

var tileHeight: Int

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

Required.

func dispatchThreadsPerTile(MTLSize)

Encodes a dispatch call to perform a midrender compute operation.

Required.

Synchronizing Command Execution for Untracked Resources

func updateFence(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 waitForFence(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.

func memoryBarrier(scope: MTLBarrierScope, after: MTLRenderStages, before: MTLRenderStages)

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

Required.

struct MTLRenderStages

The render stage at which a synchronization command is triggered.

struct MTLBarrierScope

Describes the types of resources that the a barrier operates on.

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.

Deprecated

Setting Render Pass State

func setColorStoreAction(MTLStoreAction, index: Int)

Specifies a store action for a color attachment.

Required.

func setColorStoreActionOptions(MTLStoreActionOptions, index: Int)

Specifies store action options for a color attachment.

Required.

func setDepthStoreAction(MTLStoreAction)

Specifies the depth store action for the depth attachment.

Required.

func setDepthStoreActionOptions(MTLStoreActionOptions)

Specifies store action options for the depth attachment.

Required.

func setStencilStoreAction(MTLStoreAction)

Specifies the stencil store action for the stencil attachment.

Required.

func setStencilStoreActionOptions(MTLStoreActionOptions)

Specifies store action options for the stencil attachment.

Required.

Relationships

Inherits From

See Also

Graphics

Hello Triangle

Demonstrates how to render a simple 2D triangle.

Basic Buffers

Demonstrates how to manage hundreds of vertices with a vertex buffer.

Basic Texturing

Demonstrates how to load image data and texture a quad.

protocol MTLParallelRenderCommandEncoder

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

Render Pass

A collection of commands that updates a set of render targets.

Render Pipeline

A specification for how graphics primitives should be rendered.

Vertex Data

Points that specify precise locations within the textures associated with graphics processing.

Presentation Objects

Various user interface elements you use to display your Metal content onscreen.