<!--
{
  "availability" : [
    "iOS: 26.0.0 -",
    "iPadOS: 26.0.0 -",
    "macCatalyst: 26.0.0 -",
    "macOS: 26.0.0 -",
    "tvOS: 26.0.0 -",
    "visionOS: 26.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Metal",
  "identifier" : "/documentation/Metal/MTL4ComputeCommandEncoder",
  "metadataVersion" : "0.1.0",
  "role" : "Protocol",
  "symbol" : {
    "kind" : "Protocol",
    "modules" : [
      "Metal"
    ],
    "preciseIdentifier" : "c:objc(pl)MTL4ComputeCommandEncoder"
  },
  "title" : "MTL4ComputeCommandEncoder"
}
-->

# MTL4ComputeCommandEncoder

Encodes computation dispatches, resource copying commands, and acceleration structure building commands for a single pass into a command buffer.

```
protocol MTL4ComputeCommandEncoder : MTL4CommandEncoder
```

## 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`](/documentation/Metal/MTLComputeCommandEncoder), [`MTLBlitCommandEncoder`](/documentation/Metal/MTLBlitCommandEncoder), and [`MTLAccelerationStructureCommandEncoder`](/documentation/Metal/MTLAccelerationStructureCommandEncoder),
and then encoding separate passes with them.

Create a compute encoder by calling a factory method of an [`MTL4CommandBuffer`](/documentation/Metal/MTL4CommandBuffer) instance,
such as [`makeComputeCommandEncoder()`](/documentation/Metal/MTL4CommandBuffer/makeComputeCommandEncoder()).

### Command stages

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

|Function                                                                                                                                                                                                                                |MTLStages                                                                    |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/dispatchThreads(threadsPerGrid:threadsPerThreadgroup:)``                                                                                                          |``doc://com.apple.metal/documentation/Metal/MTLStages/dispatch``             |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/dispatchThreads(indirectBuffer:)``                                                                                                                                |``doc://com.apple.metal/documentation/Metal/MTLStages/dispatch``             |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/dispatchThreadgroups(threadgroupsPerGrid:threadsPerThreadgroup:)``                                                                                                |``doc://com.apple.metal/documentation/Metal/MTLStages/dispatch``             |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/dispatchThreadgroups(indirectBuffer:threadsPerThreadgroup:)``                                                                                                     |``doc://com.apple.metal/documentation/Metal/MTLStages/dispatch``             |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceBuffer:sourceOffset:destinationBuffer:destinationOffset:size:)``                                                                                       |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:destinationTexture:destinationSlice:destinationLevel:destinationOrigin:options:)``|``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceTensor:sourceOrigin:sourceDimensions:destinationTensor:destinationOrigin:destinationDimensions:)``                                                     |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceTexture:destinationTexture:)``                                                                                                                         |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceTexture:sourceSlice:sourceLevel:destinationTexture:destinationSlice:destinationLevel:sliceCount:levelCount:)``                                         |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:destinationBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:)``|``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:destinationTexture:destinationSlice:destinationLevel:destinationOrigin:)``                     |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/copyCommands(sourceBuffer:sourceRange:destinationBuffer:destinationIndex:)``                                                                                      |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/fill(buffer:range:value:)``                                                                                                                                       |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/generateMipmaps(texture:)``                                                                                                                                       |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/optimizeCommands(buffer:range:)``                                                                                                                                 |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/optimizeContents(forCPUAccess:)``                                                                                                                                 |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/optimizeContents(forCPUAccess:slice:level:)``                                                                                                                     |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/optimizeContents(forGPUAccess:)``                                                                                                                                 |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/optimizeContents(forGPUAccess:slice:level:)``                                                                                                                     |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/resetCommands(buffer:range:)``                                                                                                                                    |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``                 |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/build(destinationAccelerationStructure:descriptor:scratchBuffer:)``                                                                                               |``doc://com.apple.metal/documentation/Metal/MTLStages/accelerationStructure``|
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceAccelerationStructure:destinationAccelerationStructure:)``                                                                                             |``doc://com.apple.metal/documentation/Metal/MTLStages/accelerationStructure``|
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/copyAndCompact(sourceAccelerationStructure:destinationAccelerationStructure:)``                                                                                   |``doc://com.apple.metal/documentation/Metal/MTLStages/accelerationStructure``|
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/refit(sourceAccelerationStructure:descriptor:destinationAccelerationStructure:scratchBuffer:options:)``                                                           |``doc://com.apple.metal/documentation/Metal/MTLStages/accelerationStructure``|
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/writeCompactedSize(sourceAccelerationStructure:destinationBuffer:)``                                                                                              |``doc://com.apple.metal/documentation/Metal/MTLStages/accelerationStructure``|
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/executeCommands(buffer:range:)``![](spacer)``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/executeCommandsInBuffer:withRange:``             |None                                                                         |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/executeCommands(buffer:indirectBuffer:)``                                                                                                                         |None                                                                         |
|``doc://com.apple.metal/documentation/Metal/MTL4ComputeCommandEncoder/writeTimestamp(granularity:counterHeap:index:)``                                                                                                                  |None                                                                         |

The [`executeCommands(buffer:range:)`](/documentation/Metal/MTL4ComputeCommandEncoder/executeCommands(buffer:range:)) and [`executeCommands(buffer:indirectBuffer:)`](/documentation/Metal/MTL4ComputeCommandEncoder/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`](/documentation/Metal/MTLIndirectCommandBuffer) applies to the same stages as when you encode the equivalent command directly.

For more information about stages and synchronization, see [`MTLStages`](/documentation/Metal/MTLStages) and [Resource synchronization](/documentation/Metal/resource-synchronization).

## Topics

### Configuring the pass

[`setComputePipelineState(_:)`](/documentation/Metal/MTL4ComputeCommandEncoder/setComputePipelineState(_:))

Configures this encoder with a compute pipeline state that applies to your subsequent dispatch commands.

[`setArgumentTable(_:)`](/documentation/Metal/MTL4ComputeCommandEncoder/setArgumentTable(_:))

Sets an argument table for the compute shader stage of this pipeline.

[`setThreadgroupMemoryLength(_:index:)`](/documentation/Metal/MTL4ComputeCommandEncoder/setThreadgroupMemoryLength(_:index:))

Configures the size of a threadgroup memory buffer for a threadgroup argument in the compute shader function.

[`setImageblockSize(width:height:)`](/documentation/Metal/MTL4ComputeCommandEncoder/setImageblockSize(width:height:))

Specifies the size, in pixels, of imageblock data in tile memory.

### Inspecting the pass

[`stages()`](/documentation/Metal/MTL4ComputeCommandEncoder/stages())

Queries a bitmask representing the shader stages on which commands currently present in this command encoder
operate.

### Running dispatch commands

Run compute kernels on the GPU.

[`dispatchThreads(threadsPerGrid:threadsPerThreadgroup:)`](/documentation/Metal/MTL4ComputeCommandEncoder/dispatchThreads(threadsPerGrid:threadsPerThreadgroup:))

Encodes a compute dispatch command using an arbitrarily-sized grid.

[`dispatchThreads(indirectBuffer:)`](/documentation/Metal/MTL4ComputeCommandEncoder/dispatchThreads(indirectBuffer:))

Encodes a compute dispatch command with an arbitrarily sized grid, using an indirect buffer for arguments.

[`dispatchThreadgroups(threadgroupsPerGrid:threadsPerThreadgroup:)`](/documentation/Metal/MTL4ComputeCommandEncoder/dispatchThreadgroups(threadgroupsPerGrid:threadsPerThreadgroup:))

Encodes a compute dispatch command with a grid that aligns to threadgroup boundaries.

[`dispatchThreadgroups(indirectBuffer:threadsPerThreadgroup:)`](/documentation/Metal/MTL4ComputeCommandEncoder/dispatchThreadgroups(indirectBuffer:threadsPerThreadgroup:))

Encodes a compute dispatch command with a grid that aligns to threadgroup boundaries, using an indirect buffer
for arguments.

### Encoding buffer copy commands

Copy data between buffers.

[`copy(sourceBuffer:sourceOffset:destinationBuffer:destinationOffset:size:)`](/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceBuffer:sourceOffset:destinationBuffer:destinationOffset:size:))

Encodes a command that copies data from a buffer instance into another.

### Encoding buffer-to-texture copy commands

Copy data from buffers to textures.

[`copy(sourceBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:destinationTexture:destinationSlice:destinationLevel:destinationOrigin:options:)`](/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:destinationTexture:destinationSlice:destinationLevel:destinationOrigin:options:))

Encodes a command to copy image data from a buffer into a texture with options for special texture formats.

[`copyFromBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:`](/documentation/Metal/MTL4ComputeCommandEncoder/copyFromBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:)

Encodes a command to copy image data from a buffer instance into a texture.

[`copyFromBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:options:`](/documentation/Metal/MTL4ComputeCommandEncoder/copyFromBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:options:)

Encodes a command to copy image data from a buffer into a texture with options for special texture formats.

### Encoding texture copy commands

Copy data between textures.

[`copy(sourceTensor:sourceOrigin:sourceDimensions:destinationTensor:destinationOrigin:destinationDimensions:)`](/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceTensor:sourceOrigin:sourceDimensions:destinationTensor:destinationOrigin:destinationDimensions:))

Encodes a command to copy data from a slice of the data plane of a tensor into a slice of the data plane of
another tensor.

[`copy(sourceTexture:destinationTexture:)`](/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceTexture:destinationTexture:))

Encodes a command that copies data from a texture to another.

[`copy(sourceTexture:sourceSlice:sourceLevel:destinationTexture:destinationSlice:destinationLevel:sliceCount:levelCount:)`](/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceTexture:sourceSlice:sourceLevel:destinationTexture:destinationSlice:destinationLevel:sliceCount:levelCount:))

Encodes a command that copies slices of a texture to slices of another texture.

[`copy(sourceTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:destinationTexture:destinationSlice:destinationLevel:destinationOrigin:)`](/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:destinationTexture:destinationSlice:destinationLevel:destinationOrigin:))

Encodes a command that copies image data from a slice of a texture into a slice of another texture.

### Encoding texture-to-buffer copy commands

Copy data from textures to buffers.

[`copy(sourceTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:destinationBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:)`](/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:destinationBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:))

Encodes a command that copies image data from a slice of a texture instance to a buffer, with
options for special texture formats.

[`copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:`](/documentation/Metal/MTL4ComputeCommandEncoder/copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:)

Encodes a command that copies image data from a slice of an [`MTLTexture`](/documentation/Metal/MTLTexture) instance to an [`MTLBuffer`](/documentation/Metal/MTLBuffer) instance.

[`copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:`](/documentation/Metal/MTL4ComputeCommandEncoder/copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:)

Encodes a command that copies image data from a slice of a texture instance to a buffer, with
options for special texture formats.

### Encoding indirect command buffer copy commands

Copy commands between indirect command buffers.

[`copyCommands(sourceBuffer:sourceRange:destinationBuffer:destinationIndex:)`](/documentation/Metal/MTL4ComputeCommandEncoder/copyCommands(sourceBuffer:sourceRange:destinationBuffer:destinationIndex:))

Encodes a command that copies commands from one indirect command buffer into another.

[`copyIndirectCommandBuffer:sourceRange:destination:destinationIndex:`](/documentation/Metal/MTL4ComputeCommandEncoder/copyIndirectCommandBuffer:sourceRange:destination:destinationIndex:)

Encodes a command that copies commands from an indirect command buffer into another.

### Encoding buffer fill commands

Fill buffers with repeating values.

[`fill(buffer:range:value:)`](/documentation/Metal/MTL4ComputeCommandEncoder/fill(buffer:range:value:))

Encodes a command that fills a buffer with a constant value for each byte.

[`fillBuffer:range:value:`](/documentation/Metal/MTL4ComputeCommandEncoder/fillBuffer:range:value:)

Encodes a command that fills a buffer with a constant value for each byte.

### Encoding mipmap generation commands

Generate mipmaps for textures.

[`generateMipmaps(texture:)`](/documentation/Metal/MTL4ComputeCommandEncoder/generateMipmaps(texture:))

Encodes a command that generates mipmaps for a texture instance from the base mipmap level up to the highest
mipmap level.

### Encoding optimization commands

Optimize resources and command buffers.

[`optimizeCommands(buffer:range:)`](/documentation/Metal/MTL4ComputeCommandEncoder/optimizeCommands(buffer:range:))

Encode a command to attempt to improve the performance of a range of commands within an indirect command buffer.

[`optimizeContents(forCPUAccess:)`](/documentation/Metal/MTL4ComputeCommandEncoder/optimizeContents(forCPUAccess:))

Encodes a command that modifies the contents of a texture to improve the performance of CPU accesses to
its contents.

[`optimizeContents(forCPUAccess:slice:level:)`](/documentation/Metal/MTL4ComputeCommandEncoder/optimizeContents(forCPUAccess:slice:level:))

Encodes a command that modifies the contents of a texture to improve the performance of CPU accesses
to its contents in a specific region.

[`optimizeContents(forGPUAccess:)`](/documentation/Metal/MTL4ComputeCommandEncoder/optimizeContents(forGPUAccess:))

Encodes a command that modifies the contents of a texture to improve the performance of GPU accesses
to its contents.

[`optimizeContents(forGPUAccess:slice:level:)`](/documentation/Metal/MTL4ComputeCommandEncoder/optimizeContents(forGPUAccess:slice:level:))

Encodes a command that modifies the contents of a texture instance to improve the performance of GPU accesses
to its contents in a specific region.

[`optimizeIndirectCommandBuffer:withRange:`](/documentation/Metal/MTL4ComputeCommandEncoder/optimizeIndirectCommandBuffer:withRange:)

Encode a command to attempt to improve the performance of a range of commands within an indirect command buffer.

### Encoding reset commands

[`resetCommands(buffer:range:)`](/documentation/Metal/MTL4ComputeCommandEncoder/resetCommands(buffer:range:))

Encodes a command that resets a range of commands in an indirect command buffer.

[`resetCommandsInBuffer:withRange:`](/documentation/Metal/MTL4ComputeCommandEncoder/resetCommandsInBuffer:withRange:)

Encodes a command that resets a range of commands in an indirect command buffer.

### Encoding acceleration structure build commands

Build acceleration structures for ray tracing.

[`build(destinationAccelerationStructure:descriptor:scratchBuffer:)`](/documentation/Metal/MTL4ComputeCommandEncoder/build(destinationAccelerationStructure:descriptor:scratchBuffer:))

Encodes an acceleration structure build into the command buffer.

### Encoding acceleration structure copy commands

Copy and compact acceleration structures.

[`copy(sourceAccelerationStructure:destinationAccelerationStructure:)`](/documentation/Metal/MTL4ComputeCommandEncoder/copy(sourceAccelerationStructure:destinationAccelerationStructure:))

Encodes an acceleration structure copy operation into the command buffer.

[`copyAndCompact(sourceAccelerationStructure:destinationAccelerationStructure:)`](/documentation/Metal/MTL4ComputeCommandEncoder/copyAndCompact(sourceAccelerationStructure:destinationAccelerationStructure:))

Encodes a command to copy and compact an acceleration structure.

[`writeCompactedSize(sourceAccelerationStructure:destinationBuffer:)`](/documentation/Metal/MTL4ComputeCommandEncoder/writeCompactedSize(sourceAccelerationStructure:destinationBuffer:))

Encodes a command to compute the size an acceleration structure can compact into, writing the result
into a buffer.

### Encoding acceleration structure refit commands

Update acceleration structures without rebuilding.

[`refit(sourceAccelerationStructure:descriptor:destinationAccelerationStructure:scratchBuffer:options:)`](/documentation/Metal/MTL4ComputeCommandEncoder/refit(sourceAccelerationStructure:descriptor:destinationAccelerationStructure:scratchBuffer:options:))

Encodes an acceleration structure refit operation into the command buffer, providing additional options.

[`refitAccelerationStructure:descriptor:destination:scratchBuffer:`](/documentation/Metal/MTL4ComputeCommandEncoder/refitAccelerationStructure:descriptor:destination:scratchBuffer:)

Encodes an acceleration structure refit into the command buffer.

### Encoding indirect command buffers

Encode a command that runs an indirect command buffer.

[`executeCommands(buffer:range:)`](/documentation/Metal/MTL4ComputeCommandEncoder/executeCommands(buffer:range:))

Encodes a command to execute commands from an indirect command buffer.

[`executeCommands(buffer:indirectBuffer:)`](/documentation/Metal/MTL4ComputeCommandEncoder/executeCommands(buffer:indirectBuffer:))

Encodes an instruction to execute commands from an indirect command buffer, using an indirect buffer for
arguments.

[`executeCommandsInBuffer:withRange:`](/documentation/Metal/MTL4ComputeCommandEncoder/executeCommandsInBuffer:withRange:)

Encodes a command to execute a series of commands from an indirect command buffer.

### Encoding performance measurement commands

Measure runtime performance with timestamps.

[`writeTimestamp(granularity:counterHeap:index:)`](/documentation/Metal/MTL4ComputeCommandEncoder/writeTimestamp(granularity:counterHeap:index:))

Writes a GPU timestamp into a heap.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)