Crafter.Graphics/examples/RTVolume/README.md

# RTVolume

Ray tracing of **procedural (AABB) geometry** with an **any-hit** cut-out
on both backends — software WebGPU (issue #13) and native Vulkan hardware
RT (issue #33).

A 3×3×3 grid of unit boxes is registered as an AABB BLAS
(`Mesh::BuildProcedural` — `VK_GEOMETRY_TYPE_AABBS_KHR` on Vulkan, the
software AABB-leaf path on WebGPU). The hit group is procedural
(`RTShaderGroupType::ProceduralHitGroup` /
`VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR`) carrying:

- `intersection.wgsl` / `intersection.glsl` — analytic ray–sphere test that
  turns each box into a radius-1 sphere (runs once per box the ray enters);
- `anyhit.wgsl` / `anyhit.glsl` — ignores the intersection for half the
  cells of a spherical checkerboard, so the ray passes through and the
  background / spheres behind show through (the visible proof any-hit runs);
- `closesthit.wgsl` / `closesthit.glsl` — normal-based Lambert shading,
  tinted per instance.

The geometry is registered **non-opaque** and the instances clear their
force-opaque flag, which is what lets the any-hit shader run. Flip the
instance flag to `kRTGeometryInstanceForceOpaque` (or build the mesh with
`opaque = true`) to skip any-hit and see solid spheres.

WebGPU/DOM (free camera, WASD + mouse):

```
crafter-build --target=wasm32-wasip1 -r
```

Native Vulkan (fixed camera in raygen.glsl):

```
crafter-build -r
```
-												docs(webgpu-rt): add RTVolume example (procedural spheres + any-hit cut-out)

A 3x3x3 grid of AABB-geometry spheres rendered through an analytic
ray-sphere intersection shader, with an any-hit spherical-checkerboard
cut-out so the background shows through. Exercises both features end to
end on the WebGPU wavefront tracer.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

											
										
										
											2026-06-02 22:09:30 +00:00
+								# RTVolume
-												test(vulkan-rt): port RTVolume example to native Vulkan (#33)

Regression test for the procedural BLAS path: the same 3x3x3 grid of
unit-box AABBs runs through a PROCEDURAL_HIT_GROUP_KHR group whose GLSL
intersection shader (reportIntersectionEXT) turns each box into a
radius-1 sphere, the any-hit shader punches the spherical-checkerboard
cut-out (visible proof non-opaque geometry runs any-hit), and the
closest-hit shades per-instance tints — the WebGPU example behavior
reproduced natively. Fixed camera in raygen.glsl; the WebGPU/DOM path is
unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

											
										
										
											2026-06-13 00:17:37 +00:00
+								Ray tracing of **procedural (AABB) geometry** with an **any-hit** cut-out
 								on both backends — software WebGPU (issue #13) and native Vulkan hardware
 								RT (issue #33).
-												docs(webgpu-rt): add RTVolume example (procedural spheres + any-hit cut-out)

A 3x3x3 grid of AABB-geometry spheres rendered through an analytic
ray-sphere intersection shader, with an any-hit spherical-checkerboard
cut-out so the background shows through. Exercises both features end to
end on the WebGPU wavefront tracer.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

											
										
										
											2026-06-02 22:09:30 +00:00
 								A 3×3×3 grid of unit boxes is registered as an AABB BLAS
-												test(vulkan-rt): port RTVolume example to native Vulkan (#33)

Regression test for the procedural BLAS path: the same 3x3x3 grid of
unit-box AABBs runs through a PROCEDURAL_HIT_GROUP_KHR group whose GLSL
intersection shader (reportIntersectionEXT) turns each box into a
radius-1 sphere, the any-hit shader punches the spherical-checkerboard
cut-out (visible proof non-opaque geometry runs any-hit), and the
closest-hit shades per-instance tints — the WebGPU example behavior
reproduced natively. Fixed camera in raygen.glsl; the WebGPU/DOM path is
unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

											
										
										
											2026-06-13 00:17:37 +00:00
+								(`Mesh::BuildProcedural` — `VK_GEOMETRY_TYPE_AABBS_KHR` on Vulkan, the
 								software AABB-leaf path on WebGPU). The hit group is procedural
 								(`RTShaderGroupType::ProceduralHitGroup` /
 								`VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR`) carrying:
-												docs(webgpu-rt): add RTVolume example (procedural spheres + any-hit cut-out)

A 3x3x3 grid of AABB-geometry spheres rendered through an analytic
ray-sphere intersection shader, with an any-hit spherical-checkerboard
cut-out so the background shows through. Exercises both features end to
end on the WebGPU wavefront tracer.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

											
										
										
											2026-06-02 22:09:30 +00:00
-												test(vulkan-rt): port RTVolume example to native Vulkan (#33)

Regression test for the procedural BLAS path: the same 3x3x3 grid of
unit-box AABBs runs through a PROCEDURAL_HIT_GROUP_KHR group whose GLSL
intersection shader (reportIntersectionEXT) turns each box into a
radius-1 sphere, the any-hit shader punches the spherical-checkerboard
cut-out (visible proof non-opaque geometry runs any-hit), and the
closest-hit shades per-instance tints — the WebGPU example behavior
reproduced natively. Fixed camera in raygen.glsl; the WebGPU/DOM path is
unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

											
										
										
											2026-06-13 00:17:37 +00:00
+								- `intersection.wgsl` / `intersection.glsl` — analytic ray–sphere test that
 								  turns each box into a radius-1 sphere (runs once per box the ray enters);
 								- `anyhit.wgsl` / `anyhit.glsl` — ignores the intersection for half the
 								  cells of a spherical checkerboard, so the ray passes through and the
 								  background / spheres behind show through (the visible proof any-hit runs);
 								- `closesthit.wgsl` / `closesthit.glsl` — normal-based Lambert shading,
 								  tinted per instance.
-												docs(webgpu-rt): add RTVolume example (procedural spheres + any-hit cut-out)

A 3x3x3 grid of AABB-geometry spheres rendered through an analytic
ray-sphere intersection shader, with an any-hit spherical-checkerboard
cut-out so the background shows through. Exercises both features end to
end on the WebGPU wavefront tracer.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

											
										
										
											2026-06-02 22:09:30 +00:00
 								The geometry is registered **non-opaque** and the instances clear their
 								force-opaque flag, which is what lets the any-hit shader run. Flip the
 								instance flag to `kRTGeometryInstanceForceOpaque` (or build the mesh with
 								`opaque = true`) to skip any-hit and see solid spheres.
-												test(vulkan-rt): port RTVolume example to native Vulkan (#33)

Regression test for the procedural BLAS path: the same 3x3x3 grid of
unit-box AABBs runs through a PROCEDURAL_HIT_GROUP_KHR group whose GLSL
intersection shader (reportIntersectionEXT) turns each box into a
radius-1 sphere, the any-hit shader punches the spherical-checkerboard
cut-out (visible proof non-opaque geometry runs any-hit), and the
closest-hit shades per-instance tints — the WebGPU example behavior
reproduced natively. Fixed camera in raygen.glsl; the WebGPU/DOM path is
unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

											
										
										
											2026-06-13 00:17:37 +00:00
+								WebGPU/DOM (free camera, WASD + mouse):
-												docs(webgpu-rt): add RTVolume example (procedural spheres + any-hit cut-out)

A 3x3x3 grid of AABB-geometry spheres rendered through an analytic
ray-sphere intersection shader, with an any-hit spherical-checkerboard
cut-out so the background shows through. Exercises both features end to
end on the WebGPU wavefront tracer.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

											
										
										
											2026-06-02 22:09:30 +00:00
 								```
 								crafter-build --target=wasm32-wasip1 -r
 								```
-												test(vulkan-rt): port RTVolume example to native Vulkan (#33)

Regression test for the procedural BLAS path: the same 3x3x3 grid of
unit-box AABBs runs through a PROCEDURAL_HIT_GROUP_KHR group whose GLSL
intersection shader (reportIntersectionEXT) turns each box into a
radius-1 sphere, the any-hit shader punches the spherical-checkerboard
cut-out (visible proof non-opaque geometry runs any-hit), and the
closest-hit shades per-instance tints — the WebGPU example behavior
reproduced natively. Fixed camera in raygen.glsl; the WebGPU/DOM path is
unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

											
										
										
											2026-06-13 00:17:37 +00:00
 								Native Vulkan (fixed camera in raygen.glsl):
 								```
 								crafter-build -r
 								```