MTLComputeCommandEncoder

Encodes computation dispatch commands for a single compute pass into a command buffer.

Declaration

protocol MTLComputeCommandEncoder : MTLCommandEncoder

Mentioned in

Overview

Create a compute encoder by calling one of the factory methods on an MTLCommandBuffer instance, such as makeComputeCommandEncoder(dispatchType:). You can encode multiple commands that each run a compute kernel as part of a single pass of the encoder with the following steps:

Configure an MTLComputePipelineState instance with a kernel, using a method such as makeComputePipelineState(function:). See the Creating compute pipeline states section of Pipeline state creation for all MTLDevice methods that create a new pipeline state for your command encoder.
Set the pipeline state with the setComputePipelineState(_:) method on your command encoder.
Set kernel arguments by binding buffers, textures, and other resources with methods such as setBuffer(_:offset:index:) and setTexture(_:index:).
Encode compute commands that call your kernel by either Dispatching kernel calls directly or Dispatching from indirect command buffers.
Call endEncoding() to finish encoding the kernel call of the compute pass.

Command stages

Most compute commands apply to one stage within a pass. The following table shows which stage applies to each command:

Function	MTLStages
Dispatchthreads(_:threadsperthreadgroup:)	Dispatch
Dispatchthreadgroups(_:threadsperthreadgroup:)	Dispatch
Dispatchthreadgroups(indirectbuffer:indirectbufferoffset:threadsperthreadgroup:)	Dispatch
Executecommandsinbuffer(_:range:)[Image]Executecommandsinbuffer:withrange:	None
Executecommandsinbuffer(_:indirectbuffer:offset:)[Image]Executecommandsinbuffer:indirectbuffer:indirectbufferoffset:	None
Samplecounters(samplebuffer:sampleindex:barrier:)	None

The executeCommandsInBuffer(_:range:) and executeCommandsInBuffer(_:indirectBuffer:offset:) commands don’t apply to any stage, which means you can’t use a barrier to wait for all commands in an indirect command buffer to complete. However, each command within the MTLIndirectCommandBuffer applies to the same stages as when you encode the equivalent command directly.

For more information about stages and synchronization, see MTLStages and Resource synchronization.

Topics

Configuring the pipeline state

Binding buffers

Binding raw bytes

Binding textures

Binding texture samplers

Binding function tables

Binding arguments for acceleration structures

Making indirect resources resident

Configuring tile memory

Configuring stage-in data

Dispatching kernel calls directly

Dispatching from indirect command buffers

Preventing resource access conflicts

Sampling counters

sampleCounters(sampleBuffer:sampleIndex:barrier:)