WebGPU RT: port Sponza to wavefront (shadow ray in SHADE)

Restructure Sponza for the wavefront model: raygen emits the primary ray;
closesthit (in SHADE) gathers albedo/normal, accumulates ambient, and
emits a shadow ray carrying the pending direct term; miss adds the sky
(primary) or the direct term (shadow miss). resolve.wgsl applies the same
Reinhard+gamma the megakernel raygen did inline. User bindings moved to
group 3 (groups 0..2 reserved). RTPass maxDepth=2.

Renders the atrium correctly through the wavefront pipeline (textures,
two-sided shading, sun+ambient, shadows, tonemap).

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

examples/Sponza/closesthit.wgsl

@@ -1,35 +1,25 @@
-// Payload declared here so the WGSL assembler sees it before raygen
+// Sponza closest-hit (runs in SHADE). In the wavefront model the lighting
-// (the assembler concatenates closesthit/anyhit/miss BEFORE raygen).
+// + shadow trace that used to live in raygen happens here: gather surface
+// data, accumulate ambient, and emit a shadow ray toward the sun carrying
+// the pending direct contribution. The shadow ray's miss adds that
+// contribution (sun visible); its hit adds nothing (occluded), since
+// RT_FLAG_SKIP_CLOSEST_HIT suppresses closesthit on the shadow ray.
 //
-// WGSL forbids cycles in the function call graph, so closesthit_main
+// Payload declared here so the assembler sees it before wfPayload / SHADE.
-// CAN'T call traceRay (that would create closesthit → traceRay →
-// runClosestHit → closesthit). The lighting + shadow trace therefore
-// happens in raygen; closesthit's job is just to gather surface data
-// into the payload.
-//
-//   shadowRay = 0 (primary): closesthit fills albedo/worldPos/normal/hit.
-//   shadowRay = 1 (shadow):  closesthit is skipped (RT_FLAG_SKIP_CLOSEST_HIT),
-//                            miss flips color to white = "lit".
 struct Payload {
-    color:       vec3<f32>,
+    color:     vec3<f32>,   // shadow ray: pending albedo·sun·nDotL
-    shadowRay:   u32,
+    shadowRay: u32,         // 0 primary, 1 shadow
-    worldPos:    vec3<f32>,
-    hit:         u32,
-    worldNormal: vec3<f32>,
-    _pad:        f32,
 };
 
-// User-bound resources at group(2). Matches the UICustomBinding span the
+// User resources at @group(3) (0..2 are the wavefront pipeline's reserved
-// host hands to PipelineRTWebGPU::Init.
+// groups). binding 0 albedo array, 1 sampler, 2 camera (raygen only).
-//   binding 0 — albedo texture_2d_array, one layer per Sponza material
+@group(3) @binding(0) var albedos : texture_2d_array<f32>;
-//   binding 1 — sampler (linear clamp)
+@group(3) @binding(1) var samp    : sampler;
-//   binding 2 — camera storage buffer (read by raygen only)
+
-@group(2) @binding(0) var albedos : texture_2d_array<f32>;
+const SUN_DIR_TO_LIGHT: vec3<f32> = vec3<f32>(-0.35,  1.00, -0.20);
-@group(2) @binding(1) var samp    : sampler;
+const SUN_COLOR:        vec3<f32> = vec3<f32>( 1.10,  1.00,  0.85);
+const AMBIENT_COLOR:    vec3<f32> = vec3<f32>( 0.18,  0.20,  0.28);
 
-// VertexNormalTangentUVPacked is `packed` on the outer struct but each
-// inner `Vector<float, N, 4>` is SIMD-aligned to a 16-byte stride. So
-// each vertex is 12 u32 words: normal at 0..2, tangent at 4..6, uv at 8..9.
 const ATTRIB_STRIDE_U32:    u32 = 12u;
 const ATTRIB_NORMAL_OFFSET: u32 = 0u;
 const ATTRIB_UV_OFFSET:     u32 = 8u;
@@ -52,7 +42,6 @@ fn fetchNormal(meshRec: MeshRecord, vertexIdx: u32) -> vec3<f32> {
 }
 
 fn closesthit_main(ray: RayDesc, hit: HitInfo, payload: ptr<function, Payload>) {
-    // Resolve hit triangle → 3 vertex indices.
     let meshIdx = tlasEntries[hit.instanceId].blasMeshIdx;
     let meshRec = meshRecords[meshIdx];
     let baseIdx = meshRec.indexOffset + hit.primitiveId * 3u;
@@ -61,19 +50,14 @@ fn closesthit_main(ray: RayDesc, hit: HitInfo, payload: ptr<function, Payload>)
     let i2 = indices[baseIdx + 2u];
     let bary = vec3<f32>(1.0 - hit.attribs.x - hit.attribs.y, hit.attribs.x, hit.attribs.y);
 
-    // Albedo via barycentric UV interpolation.
     let uv0 = fetchUV(meshRec, i0);
     let uv1 = fetchUV(meshRec, i1);
     let uv2 = fetchUV(meshRec, i2);
     let uv  = uv0 * bary.x + uv1 * bary.y + uv2 * bary.z;
-    // OBJ V is bottom-up; sampler is top-down. fract for manual tiling.
     let uvTiled = vec2<f32>(fract(uv.x), fract(1.0 - uv.y));
     let layer   = i32(hit.customIndex);
     let albedo  = textureSampleLevel(albedos, samp, uvTiled, layer, 0.0).rgb;
 
-    // World-space smooth shading normal. Multiply through the
-    // object-to-world rotation so this stays correct if a future scene
-    // rotates instances (Sponza itself is all identities).
     let n0 = fetchNormal(meshRec, i0);
     let n1 = fetchNormal(meshRec, i1);
     let n2 = fetchNormal(meshRec, i2);
@@ -83,8 +67,23 @@ fn closesthit_main(ray: RayDesc, hit: HitInfo, payload: ptr<function, Payload>)
         dot(hit.objectToWorldR1.xyz, nObj),
         dot(hit.objectToWorldR2.xyz, nObj)));
 
-    (*payload).color       = albedo;
+    // Two-sided: flip the normal toward the camera (Sponza curtains have
-    (*payload).worldPos    = ray.origin + ray.direction * hit.t;
+    // inconsistent winding).
-    (*payload).worldNormal = nWorld;
+    let nFacing = select(-nWorld, nWorld, dot(nWorld, ray.direction) < 0.0);
-    (*payload).hit         = 1u;
+    let lightDir = normalize(SUN_DIR_TO_LIGHT);
+    let nDotL    = max(0.0, dot(nFacing, lightDir));
+    let worldPos = ray.origin + ray.direction * hit.t;
+
+    // Ambient is unconditional; direct light is gated behind the shadow ray.
+    rtAccumulate(albedo * AMBIENT_COLOR);
+
+    if (nDotL > 0.0) {
+        let shadowOrigin = worldPos + nFacing * 0.5;
+        var sp: Payload;
+        sp.color     = albedo * SUN_COLOR * nDotL;
+        sp.shadowRay = 1u;
+        rtEmitRay(shadowOrigin, 0.001, lightDir, 10000.0,
+                  RT_FLAG_SKIP_CLOSEST_HIT | RT_FLAG_TERMINATE_ON_FIRST_HIT,
+                  0xFFu, 0u, 0u, sp);
+    }
 }

examples/Sponza/main.cpp

@@ -253,10 +253,11 @@ int main() {
     DescriptorHeapWebGPU heap;
     heap.Initialize(/*images*/ 2, /*buffers*/ 2, /*samplers*/ 2);
 
-    std::array<WebGPUShader, 3> shaders {{
+    std::array<WebGPUShader, 4> shaders {{
         WebGPUShader(fs::path("raygen.wgsl"),     "raygen_main",     WebGPURTStage::Raygen),
         WebGPUShader(fs::path("miss.wgsl"),       "miss_main",       WebGPURTStage::Miss),
         WebGPUShader(fs::path("closesthit.wgsl"), "closesthit_main", WebGPURTStage::ClosestHit),
+        WebGPUShader(fs::path("resolve.wgsl"),    "resolve_main",    WebGPURTStage::Resolve),
     }};
     ShaderBindingTableWebGPU sbt;
     sbt.Init(shaders);
@@ -271,14 +272,15 @@ int main() {
         { .type = RTShaderGroupType::TrianglesHitGroup, .closestHitShader = 2 },
     }};
 
-    // Three user bindings at @group(2):
+    // Three user bindings at @group(3) (the wavefront pipeline reserves
+    // groups 0..2 for WfParams / data heaps / indirect args):
     //   binding 0 — albedo texture_2d_array (one layer per material)
     //   binding 1 — sampler (linear clamp)
     //   binding 2 — Camera storage buffer (host-driven, updated per frame)
     std::array<UICustomBinding, 3> bindings {{
-        { .group = 2, .binding = 0, .kind = UICustomBindingKind::SampledTextureArray, ._pad = 0, .pushOffset = 0 },
+        { .group = 3, .binding = 0, .kind = UICustomBindingKind::SampledTextureArray, ._pad = 0, .pushOffset = 0 },
-        { .group = 2, .binding = 1, .kind = UICustomBindingKind::Sampler,             ._pad = 0, .pushOffset = 0 },
+        { .group = 3, .binding = 1, .kind = UICustomBindingKind::Sampler,             ._pad = 0, .pushOffset = 0 },
-        { .group = 2, .binding = 2, .kind = UICustomBindingKind::Buffer,              ._pad = 0, .pushOffset = 0 },
+        { .group = 3, .binding = 2, .kind = UICustomBindingKind::Buffer,              ._pad = 0, .pushOffset = 0 },
     }};
 
     PipelineRTWebGPU pipeline;
@@ -367,6 +369,7 @@ int main() {
     RTPass rtPass(&pipeline);
     rtPass.handlesPtr   = userHandles.data();
     rtPass.handlesCount = static_cast<std::uint32_t>(userHandles.size());
+    rtPass.maxDepth     = 2;   // primary + shadow
     window.passes.push_back(&rtPass);
 
     // ── Free camera: WASD + mouse-delta look ───────────────────────────
@@ -375,9 +378,10 @@ int main() {
     // height, looking +X down the long axis (bbox: X[-1921..1800],
     // Y[-126..1429], Z[-1183..1105]). The user can fine-tune from there.
     struct CamState {
-        Vector<float, 3, 4> position{ -1500.0f, 200.0f, 0.0f };
+        // 3/4 view from a corner aimed at the atrium centre.
-        float yaw   = 0.0f;   // radians, around world +Y
+        Vector<float, 3, 4> position{ -1400.0f, 700.0f, -600.0f };
-        float pitch = 0.0f;   // radians, +pitch looks up
+        float yaw   = 0.405f;   // radians, around world +Y
+        float pitch = -0.317f;  // radians, +pitch looks up
     } cam;
 
     Input::Map inputMap;

examples/Sponza/miss.wgsl

@@ -1,16 +1,12 @@
+// Sponza miss (runs in SHADE). Primary miss → two-stop sky gradient.
+// Shadow miss → the sun is unoccluded, so add the pending direct term.
 fn miss_main(ray: RayDesc, payload: ptr<function, Payload>) {
     if ((*payload).shadowRay == 1u) {
-        // Shadow ray escaped to infinity — the sun is visible from the
+        rtAccumulate((*payload).color);
-        // origin, so the surface there should pick up full direct light.
-        // raygen reads color.x as the visibility coefficient.
-        (*payload).color = vec3<f32>(1.0);
         return;
     }
-
-    // Primary miss: cheap two-stop sky gradient. (*payload).hit stays 0
-    // so raygen knows to skip the lighting path and just use this color.
     let t = clamp(ray.direction.y * 0.5 + 0.5, 0.0, 1.0);
     let sky    = vec3<f32>(0.45, 0.65, 0.95);
     let zenith = vec3<f32>(0.95, 0.85, 0.65);
-    (*payload).color = mix(sky, zenith, t);
+    rtAccumulate(mix(sky, zenith, t));
 }

examples/Sponza/project.cpp

@@ -82,6 +82,7 @@ extern "C" Configuration CrafterBuildProject(std::span<const std::string_view> a
         cfg.files.emplace_back(fs::path("raygen.wgsl"));
         cfg.files.emplace_back(fs::path("closesthit.wgsl"));
         cfg.files.emplace_back(fs::path("miss.wgsl"));
+        cfg.files.emplace_back(fs::path("resolve.wgsl"));
         EnableWasiBrowserRuntime(cfg);
     } else {
         cfg.shaders.emplace_back(fs::path("raygen.glsl"),     std::string("main"), ShaderType::RayGen);

examples/Sponza/raygen.wgsl

@@ -1,12 +1,8 @@
-// WebGPU raygen. Camera state comes from the host every frame via a
+// Sponza raygen (runs in GENERATE). Emits the pixel's primary ray; all
-// storage buffer bound at @group(2) @binding(2); main.cpp drives that
+// shading + the shadow trace now happen in SHADE (closesthit/miss). Camera
-// from WASD + mouse-delta through Crafter::Input.
+// state comes from the host each frame via a storage buffer at
-//
+// @group(3) @binding(2) (groups 0..2 are reserved by the wavefront
-// The shading + shadow trace all happens here because WGSL forbids
+// pipeline). main.cpp drives it from WASD + mouse-delta.
-// recursive function call graphs — closesthit_main can't call traceRay
-// (that would loop closesthit → traceRay → runClosestHit → closesthit).
-// Raygen is the entry point and not called by anyone, so it can call
-// traceRay twice (once primary, once shadow) without forming a cycle.
 
 struct Camera {
     origin:  vec3<f32>,
@@ -18,92 +14,25 @@ struct Camera {
     forward: vec3<f32>,
     pad1:    f32,
 };
-@group(2) @binding(2) var<storage, read> camera : Camera;
+@group(3) @binding(2) var<storage, read> camera : Camera;
-
-// Sun coming through Sponza's open roof. Y is up; this points "down and
-// slightly along +X" so the light grazes the colonnades on one side.
-const SUN_DIR_TO_LIGHT: vec3<f32> = vec3<f32>(-0.35,  1.00, -0.20);
-const SUN_COLOR:        vec3<f32> = vec3<f32>( 1.10,  1.00,  0.85);
-const AMBIENT_COLOR:    vec3<f32> = vec3<f32>( 0.18,  0.20,  0.28);
 
 fn raygen_main(gid: vec3<u32>) {
-    if (gid.x >= hdr.surfaceW || gid.y >= hdr.surfaceH) { return; }
+    if (gid.x >= wfParams.surfaceW || gid.y >= wfParams.surfaceH) { return; }
 
     let pixel      = vec2<f32>(f32(gid.x), f32(gid.y));
-    let resolution = vec2<f32>(f32(hdr.surfaceW), f32(hdr.surfaceH));
+    let resolution = vec2<f32>(f32(wfParams.surfaceW), f32(wfParams.surfaceH));
     let uv         = (pixel + vec2<f32>(0.5)) / resolution;
     let ndc        = uv * 2.0 - vec2<f32>(1.0);
 
-    // Pinhole camera reconstructed from the host basis. ndc.x runs left-
-    // to-right across the screen → +right; ndc.y is top-down so we
-    // negate before applying +up.
     let direction = normalize(
         camera.right   * (ndc.x  * camera.aspect * camera.tanHalf) +
         camera.up      * (-ndc.y * camera.tanHalf) +
         camera.forward);
 
-    // ── Primary ray ────────────────────────────────────────────────────
     var payload: Payload;
     payload.color     = vec3<f32>(0.0);
     payload.shadowRay = 0u;
-    payload.hit       = 0u;
 
-    traceRay(
+    rtEmitPrimaryRay(camera.origin, 0.001, direction, 10000.0,
-        0u, 0u, 0xFFu,
+                     0u, 0xFFu, 0u, 0u, payload);
-        0u, 0u, 0u,
-        camera.origin, 0.001,
-        direction,     10000.0,
-        &payload);
-
-    var finalColor: vec3<f32>;
-    if (payload.hit == 1u) {
-        // Closesthit filled albedo/worldPos/worldNormal. Two-sided
-        // shading: flip the normal toward the camera if we hit the back
-        // face — Sponza's curtains in particular have inconsistent
-        // winding, and without this half the surface would go black.
-        let albedo = payload.color;
-        let nFacing = select(-payload.worldNormal,
-                              payload.worldNormal,
-                              dot(payload.worldNormal, direction) < 0.0);
-        let lightDir = normalize(SUN_DIR_TO_LIGHT);
-        let nDotL    = max(0.0, dot(nFacing, lightDir));
-
-        // ── Shadow ray ────────────────────────────────────────────────
-        // Only worth tracing if the surface faces the sun at all.
-        var visibility = 0.0;
-        if (nDotL > 0.0) {
-            // Normal-offset bias on Sponza's units (~3700 wide atrium)
-            // is hefty; 0.5 keeps the shadow ray clear of the originating
-            // triangle without producing visible "floating" shadows.
-            let shadowOrigin = payload.worldPos + nFacing * 0.5;
-
-            var shadowPayload: Payload;
-            shadowPayload.color     = vec3<f32>(0.0);  // default: blocked
-            shadowPayload.shadowRay = 1u;
-            shadowPayload.hit       = 0u;
-            traceRay(
-                0u,
-                RT_FLAG_SKIP_CLOSEST_HIT | RT_FLAG_TERMINATE_ON_FIRST_HIT,
-                0xFFu,
-                0u, 0u, 0u,
-                shadowOrigin, 0.001,
-                lightDir,     10000.0,
-                &shadowPayload);
-            visibility = shadowPayload.color.x;
-        }
-
-        let lit = AMBIENT_COLOR + SUN_COLOR * (nDotL * visibility);
-        finalColor = albedo * lit;
-    } else {
-        // Sky color was filled by miss_main.
-        finalColor = payload.color;
-    }
-
-    // Reinhard tonemap + gamma 2.2 so sun-lit albedos don't clip and
-    // shadow detail stays readable.
-    let mapped = finalColor / (finalColor + vec3<f32>(1.0));
-    let gamma  = pow(mapped, vec3<f32>(1.0 / 2.2));
-    textureStore(outImage,
-                 vec2<i32>(i32(gid.x), i32(gid.y)),
-                 vec4<f32>(gamma, 1.0));
 }

examples/Sponza/resolve.wgsl

@@ -0,0 +1,7 @@
+// Sponza RESOLVE-stage tonemap: Reinhard + gamma 2.2 over the linear
+// accumulator — matches the tonemap the megakernel raygen applied inline.
+fn resolve_main(coord: vec2<u32>, hdr: vec4<f32>) -> vec4<f32> {
+    let mapped = hdr.rgb / (hdr.rgb + vec3<f32>(1.0));
+    let g      = pow(mapped, vec3<f32>(1.0 / 2.2));
+    return vec4<f32>(g, 1.0);
+}