Crafter.Graphics/examples/Sponza/README.md

# Sponza example

Loads the Sponza atrium as a `.cmesh` + one albedo `.ctex` and renders
it via ray tracing on both Vulkan (native) and WebGPU (wasm). Same
`main.cpp`, `#ifdef CRAFTER_GRAPHICS_WINDOW_DOM` selects the backend.

## What this example proves

- `.cmesh` and `.ctex` decompression round-trip on both backends
  (GPU via `VK_EXT_memory_decompression` on Vulkan, CPU via
  `Compression::DecompressCPU` on WebGPU).
- A single texture binding flowing from `Image2D<RGBA8>` through the
  RT pipeline's closest-hit on both backends. The closest-hit samples
  at the barycentric attribs as UVs — proof-of-binding, not visually
  accurate. Per-vertex UV interpolation is the next step.

The closest-hit reads its texture and its sampler through **spec
constants** (`textures[albedoSlot]`, `samplers[samplerSlot]`), not a
runtime index. That is deliberate — see below.

On Vulkan the texture and the sampler are separate descriptors: a sampled
image in the resource heap and a sampler in the sampler heap, joined where
the closest-hit samples them,
`texture(sampler2D(textures[albedoSlot], samplers[samplerSlot]), uv)`.
The descriptor heap has no combined image samplers, and glslang rejects a
`descriptor_heap` `sampler2D` (#164).

## Native RT limitation: dynamic `descriptor_heap` indexing in hit shaders

Fixed in NVIDIA `615.78.08`: `tests/HeapDynamicIndexHit` selects buffers and
textures with a runtime index in a closest-hit, including different
descriptors in neighbouring lanes of a wave. This example still uses the
spec-constant pattern below, which also runs on the older drivers.

On NVIDIA driver `610.43.02` (Vulkan 1.4), indexing a
`layout(descriptor_heap)` array with a **runtime (non-constant)** index
inside a ray-tracing **hit** shader aborts the device with
`VK_ERROR_DEVICE_LOST` (an instruction-pointer / `READ_INVALID`
device-fault) with validation off. GPU-Assisted Validation masks it —
the scene runs fine under GPU-AV — which is why a validated run doesn't
catch it. It is a **driver-side fault**, the same family as the
descriptor-heap AS-read fault (#7 / #15) and the RT recursion / compute
TLAS-push issues (#21 / #22), but here for plain **SSBO and
sampled-image** descriptors read with a non-constant heap index
(issue #23).

### What was isolated (NVIDIA RTX 4090, driver `610.43.02`)

Driving a native bindless RT scene headlessly and bisecting the
closest-hit:

- A closest-hit that reads only `lightHeap[lightSlot]` where `lightSlot`
  is a **spec constant** survives indefinitely. ✅ (This example's
  `textures[albedoSlot]` and `samplers[samplerSlot]` are exactly this
  case.)
- Reading `indexHeap[assetIndexStart + gl_InstanceCustomIndexEXT]` /
  `vertexHeap[...]` — a heap index offset by a **runtime** value —
  device-losts on the first geometry hit. ❌
- Reading a **texture** dynamically,
  `textureHeap[assetColorStart + gl_InstanceCustomIndexEXT]`, also
  device-losts. ❌ So it is SSBO *and* sampled-image descriptors.
- `nonuniformEXT()` on the dynamic index does **not** help.
- The identical dynamic-heap-index pattern works fine in **fragment**
  shaders (the UI renderer indexes `uiTextures[]` / `ui*Heap[]` by
  per-item runtime slots), so this is **RT-stage-specific**, not a
  general `descriptor_heap` problem.
- Reading a spec-constant-indexed SSBO in **raygen** works; only the
  *dynamic* index in the hit stage faults.

### Why there is no transparent engine workaround

The AS-read fault (#15) is worked around transparently because an
acceleration structure can be reached two ways: through a descriptor, or
through its **device address** via
`OpConvertUToAccelerationStructureKHR` (which reads no descriptor). There
is exactly one TLAS, so the engine rewrites the heap AS read into an
address load and feeds the address in as push data.

Neither half of that applies here:

- **Sampled images have no device-address path.** A texture *must* be
  reached through a descriptor; there is no `OpConvertUToImage`. A
  dynamic heap texture index cannot be rewritten into anything that
  avoids dynamic descriptor selection.
- **There are many buffers, dynamically selected.** SSBOs *can* be
  reached by address (`buffer_reference` / `OpConvertUToPtr`), but a
  per-mesh array selected by `gl_InstanceCustomIndexEXT` would need the
  engine to maintain and bind an address-table buffer and a SPIR-V
  rewrite far larger than the single-TLAS AS case — and it would still
  leave the texture half broken.

So the engine cannot paper over this the way it does the AS read. The
fix is on the **consumer** side: avoid dynamically selecting a
*descriptor* in a hit shader.

### Recommended pattern

The fault is dynamic selection of a **descriptor**. Indexing *within* a
single bound resource — an element offset into one SSBO, a layer into
one array texture — is ordinary memory / layer addressing and is
**unaffected**. So bind one resource and index inside it, rather than
indexing the heap:

- **Geometry** — pack all meshes' vertices/indices into a single SSBO
  bound at a **spec-constant** slot and index it by a runtime element
  offset, or reach each mesh's buffer via `buffer_reference` (a device
  address loaded from one bound table). Either way the *descriptor* is
  constant; only the offset/address is dynamic.

  ```glsl
  // ❌ faults in a hit shader on NVIDIA: dynamic descriptor selection
  layout(descriptor_heap) buffer Verts { Vertex v[]; } vertexHeap[];
  Vertex vtx = vertexHeap[assetVertexStart + gl_InstanceCustomIndexEXT].v[i];

  // ✅ one descriptor (spec-constant slot), dynamic element offset
  layout(constant_id = 0) const uint16_t vertexSlot = 0us;
  layout(descriptor_heap) buffer Verts { Vertex v[]; } vertexHeap[];
  uint base = assetVertexStart[gl_InstanceCustomIndexEXT]; // from a bound SSBO
  Vertex vtx = vertexHeap[vertexSlot].v[base + i];
  ```

- **Materials / textures** — put them in one `texture2DArray` (or a small
  number of arrays bucketed by format/size) bound at a spec-constant
  slot and index by **layer**:

  ```glsl
  // ✅ one array texture (spec-constant slots), dynamic layer index
  layout(constant_id = 1) const uint16_t materialArraySlot = 0us;
  layout(constant_id = 2) const uint16_t samplerSlot = 0us;
  layout(descriptor_heap) uniform texture2DArray materials[];
  layout(descriptor_heap) uniform sampler        samplers[];
  uint layer = materialLayer[gl_InstanceCustomIndexEXT]; // from a bound SSBO
  vec3 albedo = texture(sampler2DArray(materials[materialArraySlot], samplers[samplerSlot]),
                        vec3(uv, layer)).rgb;
  ```

This is precisely what the WebGPU path already does — bucketed texture
arrays plus a single geometry buffer — so it is a proven, cross-backend
pattern, and it sidesteps the NVIDIA RT fault on the native path.


## Asset fetch

`project.cpp` calls `Crafter::GitFetch(...)` on
[https://github.com/jimmiebergmann/Sponza](https://github.com/jimmiebergmann/Sponza)
(pinned to commit `222338979d32f4f4818466291bdbc29f192b86ba`). The
clone lands in the per-user crafter-build cache; first build pulls
~280 MB once, subsequent builds reuse it.

`cfg.assets` then picks two files out of that clone:

| Source                                  | Compressed output       |
|-----------------------------------------|-------------------------|
| `sponza.obj`                            | `sponza.cmesh`          |
| `textures/sponza_arch_diff.tga`         | `sponza_arch_diff.ctex` |

Both land flat in the example's bin directory.

## Building

```
crafter build                          # native Vulkan
crafter build --target=wasm32-wasip1   # WebGPU / wasm
```

## License & attribution

Sponza geometry, materials, and textures are licensed under
[CC BY 3.0](https://creativecommons.org/licenses/by/3.0/).

- **Original model:** Frank Meinl, Crytek (2010).
- **OBJ packaging / cleanup:** Morgan McGuire, McGuire Computer
  Graphics Archive — https://casual-effects.com/data.
- **GitHub mirror used here:** Jimmie Bergmann's roof-material fixup —
  https://github.com/jimmiebergmann/Sponza.

When redistributing builds of this example that bundle the compressed
Sponza outputs (`*.cmesh`, `*.ctex`), the CC BY 3.0 attribution
requirement applies. Quoting the original credit somewhere visible to
end users (about-screen, credits page, etc.) is enough.

The Crafter.Graphics library code itself is LGPL-3.0; the two
licenses are compatible for data + code distribution.