Ray Queries

[Vecvec]

Connections
Works towards #1040

Description
This PR provides BLASes (bottom level acceleration structures), TLASes (top level acceleration structures), TLAS instances (which contain BLASes and data, like transforms, about them), TLAS packages (which contain vectors of TLAS instances).

Testing
Running tests & examples included in PR

This a updated version of #3631 and is inteanded to replace it.

Checklist

• Run cargo fmt.
• Run cargo clippy. If applicable, add:
  • n/a --target wasm32-unknown-unknown
  • n/a --target wasm32-unknown-emscripten
• Run cargo xtask test to run tests.
• Add change to CHANGELOG.md. See simple instructions inside file.
• More tests & examples.
• More docs

Later (follow-up PR)

• Acceleration structure compaction.
• Procedural geometry.
• as_hal methods

[JMS55]

I'm super excited for this!

What makes this PR a draft? What do you think is missing?

[Vecvec]

Examples, there is no case for no index buffer (but I'm working on it, hopefully done in a day or so).

[nical]

This looks very exciting. This is a pretty large PR and to my knowledge, none of the wgpu maintainers are ray tracing experts. So to facilitate the review process, while we try to ramp up our knowledge of the domain, could you summarize here the context (that is scattered in #1040 and other places)? In particular:

• The general ideas behind the design of the API compared to DX12/vulkan/metal:
  • What subset of the functionality does the design cover.
  • Tradeoffs (if any) compared to the underlying ray tracing APIs.
• The scope of this work (for example, only implementing a specific portion of the overall plan).
• Validation:
  • What are the important aspects of validation to be aware of for safety? For example preventing undefined behavior and out-of-bound memory accesses in shaders.
  • Any missing safety validation in this PR? Not saying the initial implementation should be bullet-proof enough to be a candidate for the WebGPU specification, but we should be aware of the shortcuts we take if any.
• Any other important things to know (For example tricky aspects of mapping to this or that API)?

[Vecvec]

To preface this, I came later to this (after most of the design was finalized), so I may not know all of the missing validation, tradeoffs, etc. I will be talking about the safe tlas building (blas building is always safe but there is a extra unsafe function to do unsafe tlas building which might (?) be faster)

To my knowledge the only missing pieces of validation are the vertex formats when creating a BLAS, metal (not yet implemented, but a consideration) only allows f32x3 (edit : finished), and tlas packages (which are only in wgpu) being able to have a different max instances from the max instances a tlas was created with (though I can't remember if it gets checked when building), this one is hard to validate, and later it might be a good idea to unify the tlases and tlas packages (especially if build acceleration structures unsafe gets removed).

The main tradeoffs are not exposing the scratch buffers because they are harder to validate (possibly) and could cause confusion (especially since most of that is lower level than wgpu provides, and also could be accidently be read back, giving garbage info and leaving the user confused) , which is why in an attempt to mitigate the allocation time blas building and tlas building are unified.

This implementation lacks compaction, which was in the initial API design, but needs another HAL function. Procedural geometry (naga needs to implement this, and if most people want to partially support this they will mainly use triangles). I believe there is a full wgpu API (though without ray-tracing pipelines)

Extra things to note: this is just for wgpu and wgpu-core, naga support (for ray queries) was added earlier. There is a ray-tracing pipeline that would be nice to have (it could allow a ray-tracer - e.g path-tracer - to be extended).

Edit: wgpu-hal support was also added earlier, but only for vulkan (so some things here still have to consider metal and dx12, though dx12 also was considered)

The naming is slightly confusing, this might be called ray-tracing, but something that uses this API to create something that simulates light bouncing around a scene might also be said to be ray-tracing (this does not do the second thing).

I think that is everything. Tell me if there are other questions about the API.

Edit # 2: mostly api is from #1040 (comment)

[Vecvec]

I've realised my previous comment requies quite some preexisting raytracing knowledge, so here are the API concepts:

• BLASes
  • A BLAS contains geometry in a device readable format, you can't interact directly with this, instead you have to build the BLAS with the buffers containing triangles or AABB.
• TLAS instances
  • A TLAS instance contains
    • A BLAS (or in native APIs it's handle)
    • A transformation matrix for the BLAS
    • Culling flags (if shader cull mask & instance.mask != 0 from vulkan this can be hit)
    • A custom index (this is data provided into the shader, unused elsewhere)
• TLASes
  • A TLAS contains TLAS instances in a device readable form, you cant interact directly with these either, instead you have to build the TLAS with TLAS instances
  • Note: most of the native APIs require the TLAS instances on a buffer. Wgpu's safe API however requires TLAS instances on the CPU, this is because native APIs have a handle to the BLAS in the TLAS instance, but this is almost impossible to validate. Having TLAS instances in a buffer is supported by build_acceleration_structures_unsafe_tlas and is why it is unsafe.
• TLAS packages
  • A TLAS package contains
    • A TLAS
    • TLAS Instances
  • Note: because TLASes build with their data in a buffer this does not exist in native APIs and is only used in safe building in wgpu

All metal, vulkan, and DXR use roughly these concepts (and they are based on one another).

[Vecvec]

I've noticed that a validation fix for spv (in trunk now see #5760) was duplicated in this PR, so I've removed that. (I think this was why gfx-rs/naga was requested for review)