MTL4ComputeCommandEncoder

Declaration

protocol MTL4ComputeCommandEncoder : MTL4CommandEncoder

Mentioned in

• Understanding the Metal 4 core API

Overview

Each Metal 4 compute encoder combines compute dispatch commands, blit commands, and acceleration structure commands into a single pass. The unified nature of this encoder type eliminates the overhead from creating separate encoders like MTLComputeCommandEncoder, MTLBlitCommandEncoder, and MTLAccelerationStructureCommandEncoder, and then encoding separate passes with them.

Create a compute encoder by calling a factory method of an MTL4CommandBuffer instance, such as makeComputeCommandEncoder().

Command stages

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

The executeCommands(buffer:range:) and executeCommands(buffer:indirectBuffer:) 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 pass

• setComputePipelineState(_:)
• setArgumentTable(_:)
• setThreadgroupMemoryLength(_:index:)
• setImageblockSize(width:height:)

Inspecting the pass

• stages()

Running dispatch commands

• dispatchThreads(threadsPerGrid:threadsPerThreadgroup:)
• dispatchThreads(indirectBuffer:)
• dispatchThreadgroups(threadgroupsPerGrid:threadsPerThreadgroup:)
• dispatchThreadgroups(indirectBuffer:threadsPerThreadgroup:)

Encoding buffer copy commands

• copy(sourceBuffer:sourceOffset:destinationBuffer:destinationOffset:size:)

Encoding buffer-to-texture copy commands

• copy(sourceBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:destinationTexture:destinationSlice:destinationLevel:destinationOrigin:options:)

Encoding texture copy commands

• copy(sourceTensor:sourceOrigin:sourceDimensions:destinationTensor:destinationOrigin:destinationDimensions:)
• copy(sourceTexture:destinationTexture:)
• copy(sourceTexture:sourceSlice:sourceLevel:destinationTexture:destinationSlice:destinationLevel:sliceCount:levelCount:)
• copy(sourceTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:destinationTexture:destinationSlice:destinationLevel:destinationOrigin:)

Encoding texture-to-buffer copy commands

• copy(sourceTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:destinationBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:)

Encoding indirect command buffer copy commands

• copyCommands(sourceBuffer:sourceRange:destinationBuffer:destinationIndex:)

Encoding buffer fill commands

• fill(buffer:range:value:)

Encoding mipmap generation commands

• generateMipmaps(texture:)

Encoding optimization commands

• optimizeCommands(buffer:range:)
• optimizeContents(forCPUAccess:)
• optimizeContents(forCPUAccess:slice:level:)
• optimizeContents(forGPUAccess:)
• optimizeContents(forGPUAccess:slice:level:)

Encoding reset commands

• resetCommands(buffer:range:)

Encoding acceleration structure build commands

• build(destinationAccelerationStructure:descriptor:scratchBuffer:)

Encoding acceleration structure copy commands

• copy(sourceAccelerationStructure:destinationAccelerationStructure:)
• copyAndCompact(sourceAccelerationStructure:destinationAccelerationStructure:)
• writeCompactedSize(sourceAccelerationStructure:destinationBuffer:)

Encoding acceleration structure refit commands

• refit(sourceAccelerationStructure:descriptor:destinationAccelerationStructure:scratchBuffer:options:)

Encoding indirect command buffers

• executeCommands(buffer:range:)
• executeCommands(buffer:indirectBuffer:)

Encoding performance measurement commands

• writeTimestamp(granularity:counterHeap:index:)

Relationships

Inherits From

• MTL4CommandEncoder
• NSObjectProtocol

See Also

Encoding a compute pass

• Creating threads and threadgroups
• Calculating threadgroup and grid sizes
• MTLComputeCommandEncoder