Protocol

MTLComputeCommandEncoder

An encoder that encodes your app's compute commands.

Declaration

protocol MTLComputeCommandEncoder

Overview

To create a MTLComputeCommandEncoder object, call the makeComputeCommandEncoder() method of the MTLCommandBuffer object in which you want to encode compute commands. Do not use standard allocation and initialization techniques to create a MTLComputeCommandEncoder object.

After you have created a MTLComputeCommandEncoder object, use it to encode the following data-parallel compute processing commands:

  1. Call the setComputePipelineState(_:) method with the MTLComputePipelineState object that contains the compute function that will be executed.

  2. Specify resources that hold the input data (or output destination) for the compute function. Set the location (index) of each resource in its corresponding argument table.

  3. Call the dispatchThreadgroups(_:threadsPerThreadgroup:) method to encode the compute function with a specified number of threadgroups for the grid and the number of threads per threadgroup.

  4. Call endEncoding() to finish encoding the compute commands onto the command buffer.

Topics

Specifying the Compute Pipeline State

func setComputePipelineState(MTLComputePipelineState)

Sets the compute function to be executed.

Required.

Specifying Resources for a Compute Function

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

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

Required.

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

Sets an array of buffers for the compute function in a range of indices in the buffer argument table, specifying corresponding offsets for each data set.

func setBufferOffset(Int, index: Int)

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

Required.

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

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

Required.

func setTexture(MTLTexture?, index: Int)

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

Required.

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

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

func setSamplerState(MTLSamplerState?, index: Int)

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

Required.

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

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

Required.

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

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

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

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

func setThreadgroupMemoryLength(Int, index: Int)

Sets the byte length of the threadgroup memory at an index in the threadgroup memory argument table.

Required.

Specifying Imageblock Size

func setImageblockWidth(Int, height: Int)

Sets the size, in pixels, of the imageblock.

Required.

Executing a Compute Function

func dispatchThreadgroups(MTLSize, threadsPerThreadgroup: MTLSize)

Encodes a dispatch call for a compute pass, using a grid aligned to threadgroup boundaries.

Required.

func dispatchThreads(MTLSize, threadsPerThreadgroup: MTLSize)

Encodes a dispatch call for a compute pass, using an arbitrarily-sized grid.

Required.

func dispatchThreadgroups(indirectBuffer: MTLBuffer, indirectBufferOffset: Int, threadsPerThreadgroup: MTLSize)

Encodes a dispatch call for a compute pass, using an indirect buffer that defines the size of a grid aligned to threadgroup boundaries.

Required.

Executing Concurrently or Serially

Define whether the encoder's commands should execute in parallel, or in succession.

Performing Fence Operations

func updateFence(MTLFence)

Updates the given fence to capture all GPU work enqueued by the command encoder up to this specific point.

Required.

func waitForFence(MTLFence)

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

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 compute pass.

Required.

func useResources([MTLResource], usage: MTLResourceUsage)

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

func useHeap(MTLHeap)

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

Required.

func useHeaps([MTLHeap])

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

Specifying Stage-In Region

func setStageInRegion(MTLRegion)

Sets the region of the stage-in attributes to apply to the compute kernel.

Required.

Structures

struct MTLDispatchThreadgroupsIndirectArguments

The data layout required for dispatching threadgroups via indirect buffer calls.

Relationships

Inherits From

See Also

Parallel Computation

Hello Compute

Demonstrates how to perform data-parallel computations using the GPU.

About Threads and Threadgroups

Learn how Metal organizes compute-processing workloads.

Calculating Threadgroup and Grid Sizes

Calculate the optimum sizes for threadgroups and grids when dispatching compute-processing workloads.

class MTLComputePipelineDescriptor

An object that configures new MTLComputePipelineState objects.

protocol MTLComputePipelineState

An object that contains the compute function and configuration state used in a compute pass.