Protocol

MTLRenderCommandEncoder

The MTLRenderCommandEncoder protocol is used to define the interface for objects that encode graphics rendering state and commands into a command buffer. Your app does not define classes that implement this protocol.

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.

Symbols

Setting Graphics Rendering State

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

Specifies the constant blend color and alpha values.

func setCullMode(MTLCullMode)

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

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.

func setDepthClipMode(MTLDepthClipMode)

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

func setDepthStencilState(MTLDepthStencilState?)

Sets the depth and stencil test state.

func setFrontFacing(MTLWinding)

Sets the winding order of front-facing primitives.

func setRenderPipelineState(MTLRenderPipelineState)

Sets the current render pipeline state object.

func setScissorRect(MTLScissorRect)

Specifies a rectangle for a fragment scissor test. Fragments that lie outside the scissor rectangle are discarded.

func setStencilReferenceValues(front: UInt32, back: UInt32)

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

func setStencilReferenceValue(UInt32)

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

func setTriangleFillMode(MTLTriangleFillMode)

Sets how to rasterize triangle and triangle strip primitives.

func setViewport(MTLViewport)

Sets the viewport, which is used to transform vertices from normalized device coordinates to window coordinates.

func setVisibilityResultMode(MTLVisibilityResultMode, offset: Int)

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

Specifying Resources for a Vertex Shader Function

func setVertexBuffer(MTLBuffer?, offset: Int, at: 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.

func setVertexBuffers(UnsafePointer<MTLBuffer?>!, offsets: UnsafePointer<Int>!, with: NSRange)

Sets an array of buffers for the vertex shader function in a range of indices in the buffer argument table. This method also specifies corresponding offsets for the start of each data set.

func setVertexBufferOffset(Int, at: Int)

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

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

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

func setVertexSamplerState(MTLSamplerState?, at: Int)

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

func setVertexSamplerStates(UnsafePointer<MTLSamplerState?>?, with: NSRange)

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

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

Sets a sampler state for the vertex shader function at the index in the sampler state argument table. This method also specifies the clamp values for the minimum and maximum level of detail.

func setVertexSamplerStates(UnsafePointer<MTLSamplerState?>?, lodMinClamps: UnsafePointer<Float>?, lodMaxClamps: UnsafePointer<Float>?, with: NSRange)

Sets an array of sampler states for the vertex shader function in a range of indices in the sampler state argument table. This method also specifies the corresponding clamp values for the minimum and maximum levels of detail.

func setVertexTexture(MTLTexture?, at: Int)

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

func setVertexTextures(UnsafePointer<MTLTexture?>?, with: NSRange)

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, at: 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.

func setFragmentBuffers(UnsafePointer<MTLBuffer?>!, offsets: UnsafePointer<Int>!, with: NSRange)

Sets an array of buffers for the fragment shader function in a range of indices in the buffer argument table. This method also specifies corresponding offsets for the start of each data set.

func setFragmentBufferOffset(Int, at: Int)

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

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

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

func setFragmentSamplerState(MTLSamplerState?, at: Int)

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

func setFragmentSamplerStates(UnsafePointer<MTLSamplerState?>?, with: NSRange)

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

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

Sets a sampler state for the fragment shader function at the index in the sampler state argument table. This method also specifies the clamp values for the minimum and maximum level of detail.

func setFragmentSamplerStates(UnsafePointer<MTLSamplerState?>?, lodMinClamps: UnsafePointer<Float>?, lodMaxClamps: UnsafePointer<Float>?, with: NSRange)

Sets an array of sampler states for the fragment shader function in a range of indices in the sampler state argument table. This method also specifies the corresponding clamp values for the minimum and maximum levels of detail.

func setFragmentTexture(MTLTexture?, at: Int)

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

func setFragmentTextures(UnsafePointer<MTLTexture?>?, with: NSRange)

Sets an array of textures for the fragment shader 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.

func setTessellationFactorScale(Float)

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

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.

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

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

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

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

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.

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.

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.

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.

Specifying a Store Action

func setColorStoreAction(MTLStoreAction, at: Int)

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

func setDepthStoreAction(MTLStoreAction)

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

func setStencilStoreAction(MTLStoreAction)

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

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.

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.

Constants

MTLPrimitiveType

The geometric primitive type for drawing commands.

MTLIndexType

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

MTLVisibilityResultMode

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

MTLCullMode

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

MTLWinding

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

MTLDepthClipMode

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

MTLTriangleFillMode

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

MTLRenderStages

Relationships

Inherits From