Protocol

MTLArgumentEncoder

An object used to encode data into an argument buffer.

Declaration

protocol MTLArgumentEncoder

Overview

A MTLArgumentEncoder object encodes buffers, textures, samplers, and inlined constant data into an argument buffer. The argument buffer itself is represented by a MTLBuffer object that you set as the encoding destination by calling the setArgumentBuffer(_:offset:) method.

The recommended way to declare an argument buffer is to define its structure in your Metal shading language code. The argument buffer can then be directly assigned to a specific buffer index of a function. To create an encoder for this type of argument buffer, call one of the following MTLFunction methods:

If you construct your shaders dynamically at runtime, you can still construct argument buffers as parameters for the shader. Define each argument separately and then add it to an array of MTLArgumentDescriptor objects. To create an encoder for this type of argument buffer, call the makeArgumentEncoder(arguments:) method of the MTLDevice class.

Topics

Creating an Argument Buffer

func setArgumentBuffer(MTLBuffer?, offset: Int)

Specifies the argument buffer that resources are encoded into.

Required.

func setArgumentBuffer(MTLBuffer?, startOffset: Int, arrayElement: Int)

Specifies the argument buffer that resources are encoded into.

Required.

var encodedLength: Int

The number of bytes required to store the encoded resources of an argument buffer.

Required.

Encoding Buffers

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

Encodes a reference to a buffer into the argument buffer.

Required.

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

Encodes references to an array of buffers into the argument buffer.

Encoding Textures

func setTexture(MTLTexture?, index: Int)

Encodes a reference to a texture into the argument buffer.

Required.

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

Encodes references to an array of textures into the argument buffer.

Encoding Samplers

func setSamplerState(MTLSamplerState?, index: Int)

Encodes a sampler into the argument buffer.

Required.

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

Encodes an array of samplers into the argument buffer.

Encoding Pipeline States

func setRenderPipelineState(MTLRenderPipelineState?, index: Int)

Encodes a reference to a render pipeline state into the argument buffer.

Required.

func setRenderPipelineStates([MTLRenderPipelineState?], range: Range<Int>)

Encodes references to an array of render pipeline states into the argument buffer.

func setComputePipelineState(MTLComputePipelineState?, at: Int)

Encodes a reference to a compute pipeline state into the argument buffer.

Required.

func setComputePipelineStates(UnsafePointer<MTLComputePipelineState?>, with: NSRange)

Encodes references to an array of compute pipeline states into the argument buffer.

Required.

Encoding Inlined Constant Data

func constantData(at: Int) -> UnsafeMutableRawPointer

Returns a pointer for an inlined constant data argument in the argument buffer.

Required.

Encoding Indirect Command Buffers

func setIndirectCommandBuffer(MTLIndirectCommandBuffer?, index: Int)

Encodes a reference to an indirect command buffer into the argument buffer.

Required.

func setIndirectCommandBuffers([MTLIndirectCommandBuffer?], range: Range<Int>)

Encodes an array of indirect command buffers into the argument buffer.

Creating a Nested Argument Encoder

func makeArgumentEncoderForBuffer(atIndex: Int) -> MTLArgumentEncoder?

Creates a new argument encoder for a nested argument buffer.

Required.

Querying Alignment

var alignment: Int

The alignment, in bytes, required for storing the encoded resources of an argument buffer.

Required.

Identifying the Argument Encoder

var label: String?

A string that identifies the argument buffer.

Required.

var device: MTLDevice

The device object that created the argument encoder.

Required.

Relationships

Inherits From

See Also

Argument Buffers

About Argument Buffers

Improve your app’s performance by grouping your resources into an argument buffer.

Basic Argument Buffers

Demonstrates how to manage groups of resources with an argument buffer.

Argument Buffers with Arrays and Resource Heaps

Demonstrates how to define an argument buffer with arrays and reduce CPU overhead by combining argument buffers with resource heaps.

Argument Buffers with GPU Encoding

Demonstrates how to encode an argument buffer with a compute pass and then access its arguments in a subsequent render pass.

Dynamic Terrain with Argument Buffers

Demonstrates how to use argument buffers to render a dynamic terrain in real time with a GPU-driven pipeline.

Indexing Argument Buffers

Assign resource indices within an argument buffer.

Tracking the Resource Residency of Argument Buffers

Optimize resource performance within an argument buffer.

class MTLArgumentDescriptor

A representation of an argument within an argument buffer.