feat(gpu): add two-pass raymarching infrastructure

Add RayMarchResult struct and functions for deferred SDF rendering:
- rayMarchWithID() tracks object ID and distance_max
- reconstructPosition(), normalWithID(), shadowWithStoredDistance()
- Pass 1: store geometry data, Pass 2: reuse for shading

Add WGSL style rule: prefer return values over pointers for small structs (≤16 bytes).

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

1 files changed, 84 insertions, 2 deletions

diff --git a/common/shaders/render/raymarching.wgsl b/common/shaders/render/raymarching.wgsl
index 5a86840..3adec8d 100644
--- a/common/shaders/render/raymarching.wgsl
+++ b/common/shaders/render/raymarching.wgsl
@@ -1,6 +1,13 @@
 // Common functions for Signed Distance Field (SDF) raymarching.
-// These functions require the user to define a `df(vec3<f32>) -> f32` function
-// which represents the scene's distance field.
+//
+// Required user-defined functions:
+//   - df(vec3<f32>) -> f32
+//       Distance field for single-pass rendering (rayMarch, normal, shadow)
+//   - dfWithID(vec3<f32>) -> RayMarchResult
+//       Distance field with object ID for two-pass rendering (rayMarchWithID, normalWithID, shadowWithStoredDistance)
+//
+// Provided constants:
+//   TOLERANCE, MAX_RAY_LENGTH, MAX_RAY_MARCHES, NORM_OFF
 
 const TOLERANCE: f32 = 0.0005;
 const MAX_RAY_LENGTH: f32 = 20.0;
@@ -57,3 +64,78 @@ fn shadow(lp: vec3<f32>, ld: vec3<f32>, mint: f32, maxt: f32) -> f32 {
   let sd = 1.0 - exp(-smul * max(t / maxt - soff, 0.0));
   return sd;
 }
+
+// ============================================================================
+// Two-Pass Raymarching Support
+// ============================================================================
+// Design note: RayMarchResult is passed/returned by value (not pointer).
+// At 12 bytes (3×f32), return value optimization makes this efficient.
+// See doc/CODING_STYLE.md for rationale.
+
+struct RayMarchResult {
+    distance: f32,      // Distance to surface (MAX_RAY_LENGTH if miss)
+    distance_max: f32,  // Total distance marched (for fog/AO)
+    object_id: f32,     // Object identifier (0.0 = background)
+}
+
+// Raymarch with object ID tracking.
+fn rayMarchWithID(ro: vec3<f32>, rd: vec3<f32>, init: RayMarchResult) -> RayMarchResult {
+  var t = init.distance;
+  var result = init;
+
+  for (var i = 0; i < MAX_RAY_MARCHES; i++) {
+    if (t > MAX_RAY_LENGTH) {
+      result.distance = MAX_RAY_LENGTH;
+      result.distance_max = MAX_RAY_LENGTH;
+      break;
+    }
+    let sample = dfWithID(ro + rd * t);
+    if (sample.distance < TOLERANCE) {
+      result.distance = t;
+      result.distance_max = t;
+      result.object_id = sample.object_id;
+      break;
+    }
+    t += sample.distance;
+  }
+
+  return result;
+}
+
+// Reconstruct world position from stored result.
+fn reconstructPosition(ray_origin: vec3<f32>, ray_dir: vec3<f32>, result: RayMarchResult) -> vec3<f32> {
+  return ray_origin + ray_dir * result.distance;
+}
+
+// Normal calculation using dfWithID.
+fn normalWithID(pos: vec3<f32>) -> vec3<f32> {
+  let eps = vec2<f32>(NORM_OFF, 0.0);
+  var nor: vec3<f32>;
+  nor.x = dfWithID(pos + eps.xyy).distance - dfWithID(pos - eps.xyy).distance;
+  nor.y = dfWithID(pos + eps.yxy).distance - dfWithID(pos - eps.yxy).distance;
+  nor.z = dfWithID(pos + eps.yyx).distance - dfWithID(pos - eps.yyx).distance;
+  return normalize(nor);
+}
+
+// Shadow using stored intersection distance.
+fn shadowWithStoredDistance(lp: vec3<f32>, ld: vec3<f32>, stored_dist: f32) -> f32 {
+  let ds = 1.0 - 0.4;
+  var t = 0.01;
+  var nd = 1e6;
+  let soff = 0.05;
+  let smul = 1.5;
+  let MAX_SHD_MARCHES = 20;
+
+  for (var i = 0; i < MAX_SHD_MARCHES; i++) {
+    let p = lp + ld * t;
+    let d = dfWithID(p).distance;
+    if (d < TOLERANCE || t >= stored_dist) {
+      let sd = 1.0 - exp(-smul * max(t / stored_dist - soff, 0.0));
+      return select(mix(sd, 1.0, smoothstep(0.0, 0.025, nd)), sd, t >= stored_dist);
+    }
+    nd = min(nd, d);
+    t += ds * d;
+  }
+  let sd = 1.0 - exp(-smul * max(t / stored_dist - soff, 0.0));
+  return sd;
+}