<!--
{
  "documentType" : "article",
  "framework" : "Metal",
  "identifier" : "/documentation/Metal/ray-tracing-with-acceleration-structures",
  "metadataVersion" : "0.1.0",
  "role" : "collectionGroup",
  "title" : "Ray tracing with acceleration structures"
}
-->

# Ray tracing with acceleration structures

Build a representation of your scene’s geometry using triangles and bounding volumes to quickly trace rays through the scene.

## Discussion

Ray tracing can improve your content’s realism by more accurately modeling the behavior of light than traditional rendering. You can also use ray tracing to implement similar techniques that rely on line-of-sight, such as sound obstruction or visually based AI functions.

To apply ray tracing in your app:

1. Create acceleration structures that represent objects in a scene.
2. Define a ray’s behavior when it collides into parts of an acceleration structure by creating either intersectors or intersection queries.
3. Generate rays into the scene from a new or existing shader.

An *intersector* uses a table of your intersection functions that define the custom behavior for each intersection type. An *intersection query* returns to your calling function to handle the custom behavior for all intersection types.

Intersectors work with compute kernels on all GPUs, and with render shaders only on Apple silicon GPUs. Alternatively, your app can use intersection queries on non-Apple GPUs, or for porting code from other graphics APIs.

## Topics

### Ray tracing samples

[Accelerating ray tracing using Metal](/documentation/Metal/accelerating-ray-tracing-using-metal)

Implement ray-traced rendering using GPU-based parallel processing.

[Control the ray tracing process using intersection queries](/documentation/Metal/control-the-ray-tracing-process-using-intersection-queries)

Explicitly enumerate a ray’s intersections with acceleration structures by creating an intersection query object.

[Rendering reflections in real time using ray tracing](/documentation/Metal/rendering-reflections-in-real-time-using-ray-tracing)

Implement realistic real-time lighting by dynamically generating reflection maps
by encoding a ray-tracing compute pass.

[Rendering a curve primitive in a ray tracing scene](/documentation/Metal/rendering-a-curve-primitive-in-a-ray-tracing-scene)

Implement ray traced rendering using GPU-based parallel processing.

### Acceleration structures

[Improving ray-tracing data access using per-primitive data](/documentation/Metal/improving-ray-tracing-data-access-using-per-primitive-data)

Simplify data access and improve GPU utilization by storing custom primitive data directly in the acceleration structure.

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

A collection of model data for GPU-accelerated intersection of rays with the model.

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

Base class for Metal 4 acceleration structure descriptors.

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

A base class for classes that define the configuration for a new acceleration structure.

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

Descriptor for a primitive acceleration structure that directly references geometric shapes, such as triangles and
bounding boxes.

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

A description of an acceleration structure that contains geometry primitives.

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

Descriptor for an instance acceleration structure.

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

A description of an acceleration structure that derives from instances of primitive acceleration structures.

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

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

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

Options that affect how Metal builds an acceleration structure and the behavior
of that acceleration structure.

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

### Acceleration structures passes

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

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

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

### Geometry descriptors

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

Base class for all Metal 4 acceleration structure geometry descriptors.

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

A base class for descriptors that contain geometry data to convert into a ray-tracing acceleration structure.

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

Describes triangle geometry suitable for ray tracing.

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

A description of a list of triangle primitives to turn into an acceleration structure.

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

Describes curve geometry suitable for ray tracing.

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

A descriptor you configure with curve geometry for building acceleration structures.

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

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

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

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

Describes bounding-box geometry suitable for ray tracing.

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

A description of a list of bounding boxes to turn into an acceleration structure.

### Motion geometry descriptors

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

Describes motion triangle geometry, suitable for motion ray tracing.

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

A description of a list of triangle primitives, as motion keyframe data, to turn into an acceleration structure.

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

Describes motion curve geometry, suitable for motion ray tracing.

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

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

Describes motion bounding box geometry, suitable for motion ray tracing.

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

A description of a list of bounding boxes, as motion keyframe data, to turn into an acceleration structure.

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

Geometry data for a specific keyframe to use in a moving instance.

### Instance descriptors

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

A description of an instance in an instanced geometry acceleration structure.

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

A description of an instance in an instanced geometry acceleration structure, with the instance including a user identifier for the instance.

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

A description of an instance in an instanced geometry acceleration structure, with the instance including a user identifier and motion data for the instance.

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

Options for adjusting the behavior of an instanced acceleration structure.

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

Descriptor for an “indirect” instance acceleration structure that allows providing the instance count and
motion transform count indirectly, through buffer references.

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

A description of an acceleration structure that Metal derives from instances of primitive acceleration structures that the GPU can populate.

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

A description of an instance in an instanced geometry acceleration structure that the GPU can populate.

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

A description of an instance in an acceleration structure that the GPU can populate, with motion data for the instance.

### Intersection function tables

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

A table of intersection functions that Metal calls to perform ray-tracing intersection tests.

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

A specification of how to create an intersection function table.

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

A description of an intersection function that performs an intersection test.

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

Constants for specifying different types of custom intersection functions.

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

### Supporting types

[`MTLAxisAlignedBoundingBox`](/documentation/Metal/MTLAxisAlignedBoundingBox-swift.typealias)

The bounds for an axis-aligned bounding box.

[`MTLPackedFloat3`](/documentation/Metal/MTLPackedFloat3-swift.typealias)

}

[`MTLPackedFloat4x3`](/documentation/Metal/MTLPackedFloat4x3-swift.typealias)

A structure that contains the top three rows of a 4x4 matrix of 32-bit floating-point values, in column-major order.

[`MTLPackedFloat3Make(_:_:_:)`](/documentation/Metal/MTLPackedFloat3Make(_:_:_:))

Returns a new packed vector with three floating-point values.

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

[`MTL4BufferRangeMake(_:_:)`](/documentation/Metal/MTL4BufferRangeMake(_:_:))

### Supporting types

[`MTLAxisAlignedBoundingBox`](/documentation/Metal/MTLAxisAlignedBoundingBox-c.struct)

The bounds for an axis-aligned bounding box.

[`MTLPackedFloat3`](/documentation/Metal/MTLPackedFloat3-c.struct)

A structure that contains three 32-bit floating-point values with no additional padding.

[`MTLPackedFloat4x3`](/documentation/Metal/MTLPackedFloat4x3-c.struct)

A structure that contains the top three rows of a 4x4 matrix of 32-bit floating-point values, in column-major order.

[`MTLPackedFloat3Make(_:_:_:)`](/documentation/Metal/MTLPackedFloat3Make(_:_:_:))

Returns a new packed vector with three floating-point values.

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

[`MTL4BufferRangeMake(_:_:)`](/documentation/Metal/MTL4BufferRangeMake(_:_:))


---

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)