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

# MTLAccelerationStructureCommandEncoder

Encodes commands that build and refit acceleration structures for a single pass.

```
protocol MTLAccelerationStructureCommandEncoder : MTLCommandEncoder
```

## Overview

Create an acceleration structure encoder by calling one of the factory methods on an [`MTLCommandBuffer`](/documentation/Metal/MTLCommandBuffer) instance,
such as [`makeAccelerationStructureCommandEncoder()`](/documentation/Metal/MTLCommandBuffer/makeAccelerationStructureCommandEncoder()).

### Command stages

Most 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/MTLAccelerationStructureCommandEncoder/build(accelerationStructure:descriptor:scratchBuffer:scratchBufferOffset:)``                                               |``doc://com.apple.metal/documentation/Metal/MTLStages/accelerationStructure``|
|``doc://com.apple.metal/documentation/Metal/MTLAccelerationStructureCommandEncoder/copy(sourceAccelerationStructure:destinationAccelerationStructure:)``                                                      |``doc://com.apple.metal/documentation/Metal/MTLStages/accelerationStructure``|
|``doc://com.apple.metal/documentation/Metal/MTLAccelerationStructureCommandEncoder/writeCompactedSize(accelerationStructure:buffer:offset:)``                                                                 |``doc://com.apple.metal/documentation/Metal/MTLStages/accelerationStructure``|
|``doc://com.apple.metal/documentation/Metal/MTLAccelerationStructureCommandEncoder/writeCompactedSize(accelerationStructure:buffer:offset:sizeDataType:)``                                                    |``doc://com.apple.metal/documentation/Metal/MTLStages/accelerationStructure``|
|``doc://com.apple.metal/documentation/Metal/MTLAccelerationStructureCommandEncoder/copyAndCompact(sourceAccelerationStructure:destinationAccelerationStructure:)``                                            |``doc://com.apple.metal/documentation/Metal/MTLStages/accelerationStructure``|
|``doc://com.apple.metal/documentation/Metal/MTLAccelerationStructureCommandEncoder/refit(sourceAccelerationStructure:descriptor:destinationAccelerationStructure:scratchBuffer:scratchBufferOffset:)``        |``doc://com.apple.metal/documentation/Metal/MTLStages/accelerationStructure``|
|``doc://com.apple.metal/documentation/Metal/MTLAccelerationStructureCommandEncoder/refit(sourceAccelerationStructure:descriptor:destinationAccelerationStructure:scratchBuffer:scratchBufferOffset:options:)``|``doc://com.apple.metal/documentation/Metal/MTLStages/accelerationStructure``|
|``doc://com.apple.metal/documentation/Metal/MTLAccelerationStructureCommandEncoder/sampleCounters(sampleBuffer:sampleIndex:barrier:)``                                                                        |None                                                                         |

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

## Topics

### Building an acceleration structure

Construct acceleration structures from geometry data, such as for ray tracing.

[`build(accelerationStructure:descriptor:scratchBuffer:scratchBufferOffset:)`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/build(accelerationStructure:descriptor:scratchBuffer:scratchBufferOffset:))

Encodes a command to build a new acceleration structure.

### Copying an acceleration structure

Duplicate and compact acceleration structures.

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

Encodes a command to copy the data from one acceleration structure to another.

[`writeCompactedSize(accelerationStructure:buffer:offset:)`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/writeCompactedSize(accelerationStructure:buffer:offset:))

Encodes a command to calculate the compacted size of an acceleration structure.

[`writeCompactedSize(accelerationStructure:buffer:offset:sizeDataType:)`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/writeCompactedSize(accelerationStructure:buffer:offset:sizeDataType:))

Encodes a command to calculate the compacted size of an acceleration structure, taking into account the size of the output data.

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

Encodes a command to compact an acceleration structure’s data and copy it into a different acceleration structure.

### Refitting an acceleration structure

Adjust acceleration structures with geometry updates.

[`refit(sourceAccelerationStructure:descriptor:destinationAccelerationStructure:scratchBuffer:scratchBufferOffset:)`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/refit(sourceAccelerationStructure:descriptor:destinationAccelerationStructure:scratchBuffer:scratchBufferOffset:))

Updates an acceleration structure with new geometry or instance data.

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

Updates an acceleration structure with new geometry or instance data, with options that control the refitting process.

### Preventing resource access conflicts

Address hazards for untracked resources with fences.

[`updateFence(_:)`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/updateFence(_:))

Encodes a command that instructs the GPU to update a fence after the acceleration structure pass completes.

[`waitForFence(_:)`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/waitForFence(_:))

Encodes a command that instructs the GPU to pause the acceleration structure pass until another pass updates a fence.

### Making indirect resources resident

Move data for resources without direct bindings into GPU-accessible memory — such as resources the pass accesses through an argument buffer.

[`useHeap(_:)`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/useHeap(_:))

Makes the resources contained in the specified heap available to the acceleration structure pass.

[`useHeaps(_:)`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/useHeaps(_:))

Makes the resources contained in the specified heaps available to the acceleration structure pass.

[`useHeaps:count:`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/useHeaps:count:)

Specifies that an array of heaps containing resources in an argument buffer can be safely used by the acceleration structure pass.

[`useResource(_:usage:)`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/useResource(_:usage:))

Makes a resource available to the acceleration structure pass.

[`useResources(_:usage:)`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/useResources(_:usage:))

Makes multiple resources available to the acceleration structure pass.

[`useResources:count:usage:`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/useResources:count:usage:)

Specifies that an array of resources in an argument buffer can be safely used by the acceleration structure pass.

[`MTLResourceUsage`](/documentation/Metal/MTLResourceUsage)

Options that describe how a graphics or compute function uses an argument buffer’s resource.

### Sampling counters

Capture runtime data from GPU hardware counters.

[`sampleCounters(sampleBuffer:sampleIndex:barrier:)`](/documentation/Metal/MTLAccelerationStructureCommandEncoder/sampleCounters(sampleBuffer:sampleIndex:barrier:))

Encodes a command to sample hardware counters at this point in the acceleration structure pass and store the samples into a counter sample buffer.


---

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)