Ray tracing

wgpu supports a ray-tracing API that mirrors what's emerging in the WebGPU community. It is experimental — the public API is marked 🧪EXPERIMENTAL🧪 in wgpu/src/lib.rs and may change without warning. Incorrect use can produce undefined behavior.

The full design rationale lives in docs/api-specs/ray_tracing.md. This page summarizes the implementation across the stack.

What's exposed

• BLAS (Bottom-Level Acceleration Structure) — a per-mesh BVH built from triangle lists or AABBs.
• TLAS (Top-Level Acceleration Structure) — an instance buffer over BLAS instances.
• @ray_query in shaders — kicks off ray traversal from any shader stage. Result is intersection details.
• Compute and fragment ray queries — WebGPU extension support; not full DXR/Vulkan KHR ray pipelines.

User-facing types in wgpu/src/api/:

• wgpu/src/api/blas.rs — Blas, BlasGeometries, BlasTriangleGeometry, BlasAabbGeometry, BlasBuildEntry.
• wgpu/src/api/tlas.rs — Tlas, TlasInstance, TlasPackage.
• Methods on CommandEncoder for building both structures and on RenderPipeline/ComputePipeline to declare bindings of acceleration structures.

The bitflag for the feature is Features::EXPERIMENTAL_RAY_QUERY plus the structure-building bit (Features::EXPERIMENTAL_RAY_TRACING_ACCELERATION_STRUCTURE).

Backend support

Backend	Status
Vulkan	KHR ray query extension. wgpu-hal/src/vulkan/ integrates VK_KHR_acceleration_structure, VK_KHR_ray_query.
Metal	MTLAccelerationStructure* types. wgpu-hal/src/metal/ uses objc2-metal's acceleration-structure features.
DX12	DXR via the windows crate. Requires Agility SDK and DXR-capable hardware.
GLES	Not supported.
WebGPU (browser)	Depends on the browser's WebGPU implementation.

Each backend's adapter.rs queries the runtime to discover whether the hardware supports the feature and reports Features::EXPERIMENTAL_RAY_QUERY accordingly.

Implementation map

Layer	Files
wgpu API	wgpu/src/api/blas.rs, wgpu/src/api/tlas.rs, ray-tracing methods on CommandEncoder and pipelines
wgpu-core	wgpu-core/src/ray_tracing.rs (18 KB), wgpu-core/src/command/ray_tracing.rs (52 KB), wgpu-core/src/device/ray_tracing.rs
wgpu-hal	per-backend acceleration-structure types and command-encoder methods; ray-query trait methods on Device
wgpu-types	wgpu-types/src/ray_tracing.rs (~8.5 KB) — common type definitions
naga	IR variant Type::AccelerationStructure, Type::RayQuery, plus per-backend emission of ray-query intrinsics

Examples

The examples/features/src/ tree has a substantial ray-tracing demo set:

• ray_traced_triangle/ — minimal "hello triangle" with ray queries.
• ray_cube_compute/, ray_cube_fragment/, ray_cube_normals/ — single-cube scenes from compute or fragment shaders.
• ray_aabb_compute/ — AABB geometry rather than triangles.
• ray_scene/ — a more complete scene with multiple BLAS instances.
• ray_shadows/ — shadow rays from a fragment shader.

These run on Vulkan, Metal, and DX12 where supported, and double as integration tests via cargo xtask test --bin wgpu-examples.

How it works at runtime

sequenceDiagram
    participant U as User code
    participant W as wgpu
    participant C as wgpu-core
    participant H as wgpu-hal
    U->>W: device.create_blas(...) / create_tlas(...)
    W->>C: ray_tracing creation
    C->>H: acceleration structure object
    U->>W: encoder.build_acceleration_structures(BLASes, TLASes)
    W->>C: command::ray_tracing::build_*
    C->>H: vkCmdBuildAccelerationStructuresKHR / accelStructCommandEncoder / D3D12 BuildRayTracingAccelerationStructure
    U->>W: render/compute pass with rayQuery in shader
    W->>C: pass commands
    C->>H: encoded as usual
    H->>Driver: dispatches; driver sees rayQuery intrinsic translated by naga

Naga support

Naga represents acceleration structures and ray queries as IR variants:

• naga::ir::Type::AccelerationStructure { vertex_return } (the recently-added vertex_return variant gates the RAY_HIT_VERTEX_POSITION capability).
• naga::ir::Type::RayQuery { vertex_return }.

Backends emit the right intrinsics:

• SPIR-V: OpTraceRayKHR-family instructions, ray-query opcodes, VK_KHR_ray_query capability.
• HLSL: RayQuery<RAY_FLAG_NONE> and friends.
• MSL: Metal's intersection_query<> types.

Capabilities::RAY_QUERY, Capabilities::RAY_HIT_VERTEX_POSITION, and (where applicable) Capabilities::EXT_RAY_TRACING_NV gate the feature in the validator.

Testing

• examples/features/src/ray_* doubles as test surface.
• tests/tests/wgpu-gpu/ includes ray-tracing tests, gated on the EXPERIMENTAL_RAY_QUERY feature.
• The CTS (gpuweb/cts) is starting to gain ray-tracing coverage as the spec stabilizes.

Caveats

• The API is experimental. Public types may change between releases.
• Coverage on each backend is uneven: GLES has no support; the Metal backend is closer to complete; Vulkan is the reference.
• Driver coverage is uneven too; many older/lower-end GPUs lack the underlying hardware.
• The docs/api-specs/ray_tracing.md document is the authoritative description of the API surface, not this page.