@woosh/meep-engine 3.38.0 → 3.40.0

package/src/shade/renderer/shader/chunk/light/sample/chunk_light_receiver_cosine.js

@@ -0,0 +1,25 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * How much a receiver at a point weighs light arriving from `direction` (unit, towards the light),
+ * for choosing which light to sample: the clamped cosine against the surface `normal`, so lights
+ * below a surface's horizon are never chosen — or 1 for every direction when `normal` is the zero
+ * vector, which is how a point with no surface says so: a scattering point inside a medium, which
+ * receives light from all around.
+ *
+ * The one place the light importance functions read the normal through.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_light_receiver_cosine = CodeChunk.from(
+    //language=WGSL
+    `
+fn light_receiver_cosine(normal: vec3<f32>, direction: vec3<f32>) -> f32 {
+    if (all(normal == vec3<f32>(0.0))) {
+        return 1.0;
+    }
+
+    return max(0.0, dot(normal, direction));
+}
+    `
+);

package/src/shade/renderer/shader/chunk/light/sample/chunk_select_light_importance.d.ts

@@ -7,12 +7,19 @@
  * shadow ray that follows. Lights returning 0 importance (out of range,
  * outside spot cone, etc.) are never selected.
  *
- * Iteration is per-thread, no workgroup memory: point/spot walk every
- * page in the table (no cap, suits clustered scenes); directional uses
+ * Iteration is per-thread, no workgroup memory: point/spot walk the pages
+ * their lights occupy — `GPULightCollection` packs them into rows
+ * [0, count), so the walk ends at the first missing or empty page and reads
+ * a page's bitmap only as far as its live count, never the table's page
+ * capacity (which it used to read whole, every call); directional uses
  * the 32-cap iteration mask. The path tracer's main shader is
  * register-pressure-sensitive, so workgroup-shared iteration would cost
  * occupancy.
  *
+ * `normal` is the receiving surface's; the zero vector is a point with no surface, inside a
+ * medium, which weighs every light by its unshadowed irradiance alone (see
+ * `light_receiver_cosine`).
+ *
  * The returned pdf is the true discrete selection probability w_i / sum_w,
  * so the Monte Carlo estimator divides by (selection.pdf * record.pdf)
  * rather than by the uniform 1/N approximation.

package/src/shade/renderer/shader/chunk/light/sample/chunk_select_light_importance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_select_light_importance.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/light/sample/chunk_select_light_importance.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4CAFU,SAAS,CA+IZ;0BA3KmB,gCAAgC"}
+{"version":3,"file":"chunk_select_light_importance.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/light/sample/chunk_select_light_importance.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,4CAFU,SAAS,CA+JZ;0BAlMmB,gCAAgC"}

package/src/shade/renderer/shader/chunk/light/sample/chunk_select_light_importance.js

@@ -16,12 +16,19 @@ import { LIGHT_SELECTION_STRUCT, LIGHT_SELECTION_TYPE } from "./LIGHT_SELECTION_
  * shadow ray that follows. Lights returning 0 importance (out of range,
  * outside spot cone, etc.) are never selected.
  *
- * Iteration is per-thread, no workgroup memory: point/spot walk every
- * page in the table (no cap, suits clustered scenes); directional uses
+ * Iteration is per-thread, no workgroup memory: point/spot walk the pages
+ * their lights occupy — `GPULightCollection` packs them into rows
+ * [0, count), so the walk ends at the first missing or empty page and reads
+ * a page's bitmap only as far as its live count, never the table's page
+ * capacity (which it used to read whole, every call); directional uses
  * the 32-cap iteration mask. The path tracer's main shader is
  * register-pressure-sensitive, so workgroup-shared iteration would cost
  * occupancy.
  *
+ * `normal` is the receiving surface's; the zero vector is a point with no surface, inside a
+ * medium, which weighs every light by its unshadowed irradiance alone (see
+ * `light_receiver_cosine`).
+ *
  * The returned pdf is the true discrete selection probability w_i / sum_w,
  * so the Monte Carlo estimator divides by (selection.pdf * record.pdf)
  * rather than by the uniform 1/N approximation.
@@ -43,8 +50,12 @@ fn select_light_importance(position: vec3<f32>, normal: vec3<f32>, random: f32)
 
     for (var p = 0u; p < POINT_LIGHTS_PAGE_LIMIT; p = p + 1u) {
         let page_addr = point_lights_page_address(&light_data, p);
-        if (page_addr == ~0u) { continue; }
-        for (var w = 0u; w < POINT_LIGHTS_OCCUPANCY_BITMAP_WORDS; w = w + 1u) {
+        // packed into rows [0, count): the first missing or empty page ends the table, and a
+        // page's live rows are its first slots
+        if (page_addr == ~0u) { break; }
+        let live = light_data[page_addr];
+        if (live == 0u) { break; }
+        for (var w = 0u; w * 32u < live; w = w + 1u) {
             var bits = point_lights_page_bitmap_word(&light_data, page_addr, w);
             while (bits != 0u) {
                 let bit = countTrailingZeros(bits);
@@ -56,8 +67,12 @@ fn select_light_importance(position: vec3<f32>, normal: vec3<f32>, random: f32)
     }
     for (var p = 0u; p < SPOT_LIGHTS_PAGE_LIMIT; p = p + 1u) {
         let page_addr = spot_lights_page_address(&light_data, p);
-        if (page_addr == ~0u) { continue; }
-        for (var w = 0u; w < SPOT_LIGHTS_OCCUPANCY_BITMAP_WORDS; w = w + 1u) {
+        // packed into rows [0, count): the first missing or empty page ends the table, and a
+        // page's live rows are its first slots
+        if (page_addr == ~0u) { break; }
+        let live = light_data[page_addr];
+        if (live == 0u) { break; }
+        for (var w = 0u; w * 32u < live; w = w + 1u) {
             var bits = spot_lights_page_bitmap_word(&light_data, page_addr, w);
             while (bits != 0u) {
                 let bit = countTrailingZeros(bits);
@@ -88,8 +103,12 @@ fn select_light_importance(position: vec3<f32>, normal: vec3<f32>, random: f32)
 
     for (var p = 0u; p < POINT_LIGHTS_PAGE_LIMIT; p = p + 1u) {
         let page_addr = point_lights_page_address(&light_data, p);
-        if (page_addr == ~0u) { continue; }
-        for (var w = 0u; w < POINT_LIGHTS_OCCUPANCY_BITMAP_WORDS; w = w + 1u) {
+        // packed into rows [0, count): the first missing or empty page ends the table, and a
+        // page's live rows are its first slots
+        if (page_addr == ~0u) { break; }
+        let live = light_data[page_addr];
+        if (live == 0u) { break; }
+        for (var w = 0u; w * 32u < live; w = w + 1u) {
             var bits = point_lights_page_bitmap_word(&light_data, page_addr, w);
             while (bits != 0u) {
                 let bit = countTrailingZeros(bits);
@@ -113,8 +132,12 @@ fn select_light_importance(position: vec3<f32>, normal: vec3<f32>, random: f32)
     }
     for (var p = 0u; p < SPOT_LIGHTS_PAGE_LIMIT; p = p + 1u) {
         let page_addr = spot_lights_page_address(&light_data, p);
-        if (page_addr == ~0u) { continue; }
-        for (var w = 0u; w < SPOT_LIGHTS_OCCUPANCY_BITMAP_WORDS; w = w + 1u) {
+        // packed into rows [0, count): the first missing or empty page ends the table, and a
+        // page's live rows are its first slots
+        if (page_addr == ~0u) { break; }
+        let live = light_data[page_addr];
+        if (live == 0u) { break; }
+        for (var w = 0u; w * 32u < live; w = w + 1u) {
             var bits = spot_lights_page_bitmap_word(&light_data, page_addr, w);
             while (bits != 0u) {
                 let bit = countTrailingZeros(bits);

package/src/shade/renderer/shader/chunk/screen_space/chunk_screen_importance.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How far in from each edge of the screen the importance falls off, as a fraction of the screen's
+ * height (the horizontal falloff is the same distance in pixels).
+ * @type {number}
+ */
+export const SCREEN_IMPORTANCE_BORDER_FRACTION: number;
+/**
+ * Steps a pixel's importance is quantized to when it is summed with atomics: a pixel of full
+ * importance adds this much.
+ * @type {number}
+ */
+export const SCREEN_IMPORTANCE_STEPS: number;
+/**
+ * How much a pixel matters by where it is on screen: 1 over most of it, falling to 0 at the edges —
+ * the automatic exposure's metering mask, after
+ * https://www.unrealengine.com/en-US/tech-blog/how-epic-games-is-handling-auto-exposure-in-4-25 —
+ * shared by every pass that weighs pixels by their place on screen.
+ *
+ * - `screen_importance(uv, vertical_aspect, border_fraction)` — the mask, in [0, 1]; `vertical_aspect`
+ *   is the screen's height over its width, `border_fraction` the falloff's width
+ * - `screen_importance_weight(uv, vertical_aspect)` — the mask at
+ *   {@link SCREEN_IMPORTANCE_BORDER_FRACTION} as an integer for an atomic sum:
+ *   {@link SCREEN_IMPORTANCE_STEPS} at full importance, and never below 1, so that a pixel at the very
+ *   edge still counts
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_importance: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_screen_importance.d.ts.map

package/src/shade/renderer/shader/chunk/screen_space/chunk_screen_importance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_screen_importance.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/screen_space/chunk_screen_importance.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,gDAFU,MAAM,CAEsC;AAEtD;;;;GAIG;AACH,sCAFU,MAAM,CAE0B;AAE1C;;;;;;;;;;;;;;GAcG;AACH,sCAFU,SAAS,CAwBjB;0BArDwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/screen_space/chunk_screen_importance.js

@@ -0,0 +1,54 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * How far in from each edge of the screen the importance falls off, as a fraction of the screen's
+ * height (the horizontal falloff is the same distance in pixels).
+ * @type {number}
+ */
+export const SCREEN_IMPORTANCE_BORDER_FRACTION = 0.13;
+
+/**
+ * Steps a pixel's importance is quantized to when it is summed with atomics: a pixel of full
+ * importance adds this much.
+ * @type {number}
+ */
+export const SCREEN_IMPORTANCE_STEPS = 64;
+
+/**
+ * How much a pixel matters by where it is on screen: 1 over most of it, falling to 0 at the edges —
+ * the automatic exposure's metering mask, after
+ * https://www.unrealengine.com/en-US/tech-blog/how-epic-games-is-handling-auto-exposure-in-4-25 —
+ * shared by every pass that weighs pixels by their place on screen.
+ *
+ * - `screen_importance(uv, vertical_aspect, border_fraction)` — the mask, in [0, 1]; `vertical_aspect`
+ *   is the screen's height over its width, `border_fraction` the falloff's width
+ * - `screen_importance_weight(uv, vertical_aspect)` — the mask at
+ *   {@link SCREEN_IMPORTANCE_BORDER_FRACTION} as an integer for an atomic sum:
+ *   {@link SCREEN_IMPORTANCE_STEPS} at full importance, and never below 1, so that a pixel at the very
+ *   edge still counts
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_importance = CodeChunk.from(
+    //language=WGSL
+    `
+fn screen_importance(
+    uv: vec2<f32>,
+    vertical_aspect: f32,
+    border_fraction: f32
+) -> f32{
+
+    let fov = border_fraction * vec2(vertical_aspect, 1.0);
+
+    let border   = smoothstep(vec2(0.0, 0.0), fov, uv) * (1.0 - smoothstep(vec2(1.0, 1.0) - fov, vec2(1.0, 1.0), uv));
+
+    return border.x * border.y;
+}
+
+fn screen_importance_weight(uv: vec2<f32>, vertical_aspect: f32) -> u32 {
+    let importance = screen_importance(uv, vertical_aspect, ${SCREEN_IMPORTANCE_BORDER_FRACTION});
+
+    return max(1u, u32(importance * ${SCREEN_IMPORTANCE_STEPS}));
+}
+    `
+);

package/src/shade/renderer/shader/chunk/screen_space/chunk_screen_space_newton_ray.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_screen_space_newton_ray.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/screen_space/chunk_screen_space_newton_ray.js"],"names":[],"mappings":"AAWA,0FAA0F;AAC1F,sDAwFkF;0BApGxD,6BAA6B"}
+{"version":3,"file":"chunk_screen_space_newton_ray.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/screen_space/chunk_screen_space_newton_ray.js"],"names":[],"mappings":"AAWA,0FAA0F;AAC1F,sDA0HkF;0BAtIxD,6BAA6B"}

package/src/shade/renderer/shader/chunk/screen_space/chunk_screen_space_newton_ray.js

@@ -29,41 +29,76 @@ fn screen_space_ray_projectable(p: vec3<f32>, projection: mat4x4<f32>) -> bool {
     return clip.w > 1e-6 && all(abs(clip) < vec4<f32>(1e30));
 }
 
-// Reconstruct the receiver at the subpixel lookup on its local tangent plane.
-// A texel-center position is a different surface point: projecting its nearest
-// point on the ray can exceed one pixel at grazing angles even for an exact hit.
-fn screen_space_ray_validate(
-    ray: Ray, uv: vec2<f32>, depth: texture_2d<f32>, normals: texture_2d<u32>,
-    projection: mat4x4<f32>, inverse_projection: mat4x4<f32>, world_to_view: mat4x4<f32>,
-    distance_tolerance: f32,
-) -> ScreenSpaceRayHit {
-    var hit = ScreenSpaceRayHit(uv, 0.0, 1e20, 0u, 1u);
-    if (!screen_space_ray_in_bounds(uv)) { return hit; }
+// The receiver sampled at one lookup: its device depth and its local tangent plane.
+struct ScreenSpaceRayReceiver {
+    depth: f32,
+    plane: vec4<f32>,
+}
+
+// One G-buffer fetch. Depth is stored at the texel center; .zw is the geometric
+// face normal, while .xy includes material normal mapping.
+fn screen_space_ray_load_receiver(
+    uv: vec2<f32>, depth: texture_2d<f32>, normals: texture_2d<u32>,
+    inverse_projection: mat4x4<f32>, world_to_view: mat4x4<f32>,
+) -> ScreenSpaceRayReceiver {
     let size = textureDimensions(depth, 0);
     let coord = vec2<i32>(uv * vec2<f32>(size));
     let d = textureLoad(depth, coord, 0).r;
-    if (is_background(d)) { hit.status = 2u; return hit; }
     let center = (vec2<f32>(coord) + 0.5) / vec2<f32>(size);
-    let center_position = inv_project_position(vec3<f32>(center, d), inverse_projection);
-    let normal = (world_to_view * vec4f(decode_g_buffer_normal(textureLoad(normals, coord, 0).zw), 0.0)).xyz;
-    let lookup_ray = inv_project_position(vec3f(uv, d), inverse_projection);
-    let denominator = dot(normal, lookup_ray);
-    if (!(abs(denominator) > 1e-6)) { hit.status = 3u; return hit; }
-    let scale = dot(normal, center_position) / denominator;
-    if (!(scale > 0.0)) { hit.status = 3u; return hit; }
-    let p = lookup_ray * scale;
+    let position = inv_project_position(vec3<f32>(center, d), inverse_projection);
+    let normal = (world_to_view * vec4<f32>(decode_g_buffer_normal(textureLoad(normals, coord, 0).zw), 0.0)).xyz;
+    return ScreenSpaceRayReceiver(d, plane_from_normal_and_point(normal, position));
+}
+
+// Reconstruct the receiver at the subpixel lookup on its local tangent plane, where the
+// lookup's camera ray meets it. A texel-center position is a different surface point:
+// projecting its nearest point on the ray can exceed one pixel at grazing angles even for
+// an exact hit. w is the scale along the camera ray. Where it is not positive the plane
+// has no intersection in front of the eye, and xyz is the depth sample under the lookup.
+fn screen_space_ray_lookup_position(
+    uv: vec2<f32>, receiver: ScreenSpaceRayReceiver, inverse_projection: mat4x4<f32>,
+) -> vec4<f32> {
+    let lookup_ray = inv_project_position(vec3f(uv, receiver.depth), inverse_projection);
+    let denominator = dot(receiver.plane.xyz, lookup_ray);
+    if (!(abs(denominator) > 1e-6)) { return vec4<f32>(lookup_ray, 0.0); }
+    let scale = -receiver.plane.w / denominator;
+    return vec4<f32>(select(lookup_ray, lookup_ray * scale, scale > 0.0), scale);
+}
+
+fn screen_space_ray_accept(
+    ray: Ray, uv: vec2<f32>, receiver: ScreenSpaceRayReceiver, size: vec2<f32>,
+    projection: mat4x4<f32>, inverse_projection: mat4x4<f32>, distance_tolerance: f32,
+) -> ScreenSpaceRayHit {
+    var hit = ScreenSpaceRayHit(uv, 0.0, 1e20, 0u, 1u);
+    let lookup = screen_space_ray_lookup_position(uv, receiver, inverse_projection);
+    if (!(lookup.w > 0.0)) { hit.status = 3u; return hit; }
+    let p = lookup.xyz;
     let travel = dot(p - ray.origin, ray.direction);
     hit.distance = travel;
     if (!(travel > 1e-4 && travel <= ray.tmax)) { hit.status = 4u; return hit; }
     let nearest = ray_nearest_point(ray, p);
     if (!screen_space_ray_projectable(nearest, projection)) { return hit; }
-    let pixel_error = length((project_position(nearest, projection).xy - uv) * vec2<f32>(size));
+    let pixel_error = length((project_position(nearest, projection).xy - uv) * size);
     hit.residual = distance(p, nearest);
     hit.status = 5u;
     if (pixel_error <= 1.0 && hit.residual <= distance_tolerance) { hit.status = 0u; }
     return hit;
 }
 
+fn screen_space_ray_validate(
+    ray: Ray, uv: vec2<f32>, depth: texture_2d<f32>, normals: texture_2d<u32>,
+    projection: mat4x4<f32>, inverse_projection: mat4x4<f32>, world_to_view: mat4x4<f32>,
+    distance_tolerance: f32,
+) -> ScreenSpaceRayHit {
+    if (!screen_space_ray_in_bounds(uv)) { return ScreenSpaceRayHit(uv, 0.0, 1e20, 0u, 1u); }
+    let receiver = screen_space_ray_load_receiver(uv, depth, normals, inverse_projection, world_to_view);
+    if (is_background(receiver.depth)) { return ScreenSpaceRayHit(uv, 0.0, 1e20, 0u, 2u); }
+    return screen_space_ray_accept(ray, uv, receiver, vec2<f32>(textureDimensions(depth, 0)),
+        projection, inverse_projection, distance_tolerance);
+}
+
+// One G-buffer fetch per lookup, as in the paper: the plane that rejects lookup n
+// is also the tangent plane of update n+1. max_updates updates read max_updates+1 texels.
 fn screen_space_newton_ray(
     ray: Ray, seed_uv: vec2<f32>, depth: texture_2d<f32>, normals: texture_2d<u32>,
     projection: mat4x4<f32>, inverse_projection: mat4x4<f32>, world_to_view: mat4x4<f32>,
@@ -71,28 +106,27 @@ fn screen_space_newton_ray(
 ) -> ScreenSpaceRayHit {
     var uv = seed_uv;
     var hit = ScreenSpaceRayHit(uv, 0.0, 1e20, 0u, 5u);
-    let size = textureDimensions(depth, 0);
-    for (var i = 0u; i < min(max_updates, 16u); i++) {
+    let size = vec2<f32>(textureDimensions(depth, 0));
+    let updates = min(max_updates, 16u);
+    if (updates == 0u) { return hit; }
+    for (var i = 0u; i <= updates; i++) {
+        let iterations = max(i, 1u);
+        if (!screen_space_ray_in_bounds(uv)) { return ScreenSpaceRayHit(uv, 0.0, 1e20, iterations, 1u); }
+        let receiver = screen_space_ray_load_receiver(uv, depth, normals, inverse_projection, world_to_view);
+        if (is_background(receiver.depth)) { return ScreenSpaceRayHit(uv, 0.0, 1e20, iterations, 2u); }
+        // The seed is the undisplaced background, not an update; only updated lookups are accepted.
+        if (i > 0u) {
+            hit = screen_space_ray_accept(ray, uv, receiver, size, projection, inverse_projection, distance_tolerance);
+            hit.iterations = i;
+            if (hit.status == 0u || hit.status == 1u || i == updates) { return hit; }
+        }
         hit.iterations = i + 1u;
-        if (!screen_space_ray_in_bounds(uv)) { hit.status = 1u; return hit; }
-        let coord = vec2<i32>(uv * vec2<f32>(size));
-        let d = textureLoad(depth, coord, 0).r;
-        if (is_background(d)) { hit.status = 2u; return hit; }
-        let center = (vec2<f32>(coord) + 0.5) / vec2<f32>(size);
-        let receiver = inv_project_position(vec3<f32>(center, d), inverse_projection);
-        // .zw is the geometric face normal; .xy includes material normal mapping.
-        let world_normal = decode_g_buffer_normal(textureLoad(normals, coord, 0).zw);
-        let normal = (world_to_view * vec4<f32>(world_normal, 0.0)).xyz;
-        if (!(abs(dot(ray.direction, normal)) > 1e-4)) { hit.status = 3u; return hit; }
-        let plane = plane_from_normal_and_point(normal, receiver);
-        let travel = plane_ray_raycast(ray.origin, ray.direction, plane);
+        if (!(abs(dot(ray.direction, receiver.plane.xyz)) > 1e-4)) { hit.status = 3u; return hit; }
+        let travel = plane_ray_raycast(ray.origin, ray.direction, receiver.plane);
         if (!(travel > 1e-4 && travel <= ray.tmax)) { hit.status = 4u; return hit; }
         let next = ray_at(ray.origin, ray.direction, travel);
         if (!screen_space_ray_projectable(next, projection)) { hit.status = 1u; return hit; }
         uv = project_position(next, projection).xy;
-        hit = screen_space_ray_validate(ray, uv, depth, normals, projection, inverse_projection, world_to_view, distance_tolerance);
-        hit.iterations = i + 1u;
-        if (hit.status == 0u || hit.status == 1u || hit.status == 2u) { return hit; }
     }
     return hit;
 }

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_band_of_index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The band `l` a band-major coefficient index belongs to — the inverse of `sh_index(m, l)` up to `m`,
+ * which is then `index - l * (l + 1)`.
+ *
+ * `floor(sqrt(index))`, corrected by one either way: `f32` square roots of perfect squares are exact,
+ * but the correction keeps the answer integer-exact rather than trusting rounding near a square — for
+ * every index below 65535², past which `(l + 1)²` wraps in `u32`. The ten bands the engine generates
+ * stop at index 99.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_band_of_index: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sh_band_of_index.d.ts.map

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_band_of_index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sh_band_of_index.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_band_of_index.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,qCAFU,SAAS,CAkBhB;0BA7BuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_band_of_index.js

@@ -0,0 +1,30 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * The band `l` a band-major coefficient index belongs to — the inverse of `sh_index(m, l)` up to `m`,
+ * which is then `index - l * (l + 1)`.
+ *
+ * `floor(sqrt(index))`, corrected by one either way: `f32` square roots of perfect squares are exact,
+ * but the correction keeps the answer integer-exact rather than trusting rounding near a square — for
+ * every index below 65535², past which `(l + 1)²` wraps in `u32`. The ten bands the engine generates
+ * stop at index 99.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_band_of_index = CodeChunk.from(
+    //language=WGSL
+    `
+fn sh_band_of_index(index: u32) -> u32 {
+    var l = u32(sqrt(f32(index)));
+
+    if ((l + 1u) * (l + 1u) <= index) {
+        l += 1u;
+    }
+
+    if (l * l > index) {
+        l -= 1u;
+    }
+
+    return l;
+}
+`);

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_basis_function.d.ts

@@ -0,0 +1,19 @@
+/**
+ * One real spherical harmonic `Y(l, m)` at a unit direction, for any band — the general form of the
+ * fixed-order `sh2_basis_at`/`sh3_basis_at` and of the generated `sh{N}_basis_at` chunks, in the same
+ * convention: all-positive (no Condon-Shortley phase), zonal axis +Z, `m` signed as in `sh_index(m, l)`
+ * (negative `m` is the `sin`/`y` family).
+ *
+ * Fully normalized associated Legendre recurrence plus `(x + iy)^|m|` for the azimuth, so there is no
+ * trigonometry and no factorial: `|m|` steps to the sectoral term, then `l - |m|` steps up the band.
+ * The work is `O(l)`; at the ten bands the SH-exponential encoder uses that is at most nineteen steps.
+ * Meant for kernels that run once (projection, fitting), where one function serving every order beats
+ * a chunk per order. Per-pixel reconstruction should use the unrolled `sh{N}_*` chunks instead.
+ *
+ * CPU twin: `core/geom/3d/sphere/harmonics/sh_basis_at.js`, which documents the recurrence.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_basis_function: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sh_basis_function.d.ts.map

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_basis_function.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sh_basis_function.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_basis_function.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,sCAFU,SAAS,CAwDhB;0BAxEuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_basis_function.js

@@ -0,0 +1,73 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * One real spherical harmonic `Y(l, m)` at a unit direction, for any band — the general form of the
+ * fixed-order `sh2_basis_at`/`sh3_basis_at` and of the generated `sh{N}_basis_at` chunks, in the same
+ * convention: all-positive (no Condon-Shortley phase), zonal axis +Z, `m` signed as in `sh_index(m, l)`
+ * (negative `m` is the `sin`/`y` family).
+ *
+ * Fully normalized associated Legendre recurrence plus `(x + iy)^|m|` for the azimuth, so there is no
+ * trigonometry and no factorial: `|m|` steps to the sectoral term, then `l - |m|` steps up the band.
+ * The work is `O(l)`; at the ten bands the SH-exponential encoder uses that is at most nineteen steps.
+ * Meant for kernels that run once (projection, fitting), where one function serving every order beats
+ * a chunk per order. Per-pixel reconstruction should use the unrolled `sh{N}_*` chunks instead.
+ *
+ * CPU twin: `core/geom/3d/sphere/harmonics/sh_basis_at.js`, which documents the recurrence.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_basis_function = CodeChunk.from(
+    //language=WGSL
+    `
+fn sh_basis_function(m: i32, l: i32, direction: vec3<f32>) -> f32 {
+    let order = u32(abs(m));
+    let band = u32(l);
+
+    let x = direction.x;
+    let y = direction.y;
+    let z = direction.z;
+
+    // (x + iy)^|m| = c + i s, and Q(|m|, |m|) / sqrt(2|m| + 1)
+    var c = 1.0;
+    var s = 0.0;
+    var sectoral = 0.28209479177387814; // 1 / sqrt(4 pi)
+
+    for (var k = 1u; k <= order; k++) {
+        let c_next = x * c - y * s;
+        s = x * s + y * c;
+        c = c_next;
+
+        sectoral *= sqrt(f32(2u * k - 1u) / f32(2u * k));
+    }
+
+    var q_previous = 0.0;
+    var q = sectoral * sqrt(f32(2u * order + 1u));
+
+    if (band > order) {
+        q_previous = q;
+        q = sqrt(f32(2u * order + 3u)) * z * q;
+    }
+
+    let mm = f32(order * order);
+
+    for (var k = order + 2u; k <= band; k++) {
+        let kk = f32(k * k);
+        let k1 = f32((k - 1u) * (k - 1u));
+
+        let a = sqrt((4.0 * kk - 1.0) / (kk - mm));
+        let b = sqrt((k1 - mm) / (4.0 * k1 - 1.0));
+
+        let q_next = a * (z * q - b * q_previous);
+
+        q_previous = q;
+        q = q_next;
+    }
+
+    if (m == 0) {
+        return q;
+    }
+
+    // sqrt(2), the real basis' factor on every m != 0 term
+    return 1.4142135623730951 * q * select(s, c, m > 0);
+}
+`);

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_vmf_window.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Band `l`'s attenuation under convolution with a von Mises-Fisher lobe of concentration `kappa`:
+ * `exp(-l(l+1) / (2 kappa))`. Band 0 is never attenuated.
+ *
+ * The large-kappa form of the vMF's zonal coefficients — Ref-NeRF's integrated directional encoding
+ * (Verbin et al., CVPR 2022, [VHM*22]), which Silvennoinen, Sloan, Iwanicki and Nowrouzezahrai use to
+ * encode roughness continuously in "Spherical Harmonic Exponentials for Efficient Glossy Reflections"
+ * (HPG 2025, https://doi.org/10.1111/cgf.70219), with `kappa = 1 / alpha`.
+ *
+ * The generated `sh{N}_color_evaluate_vmf` chunks fold the same factor into their unrolled bands;
+ * this is the one-band form for kernels that walk coefficients by index.
+ *
+ * CPU twin: `core/geom/3d/sphere/harmonics/sh_vmf_window.js`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_vmf_window: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sh_vmf_window.d.ts.map

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_vmf_window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sh_vmf_window.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_vmf_window.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,kCAFU,SAAS,CAQhB;0BAxBuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_vmf_window.js

@@ -0,0 +1,25 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * Band `l`'s attenuation under convolution with a von Mises-Fisher lobe of concentration `kappa`:
+ * `exp(-l(l+1) / (2 kappa))`. Band 0 is never attenuated.
+ *
+ * The large-kappa form of the vMF's zonal coefficients — Ref-NeRF's integrated directional encoding
+ * (Verbin et al., CVPR 2022, [VHM*22]), which Silvennoinen, Sloan, Iwanicki and Nowrouzezahrai use to
+ * encode roughness continuously in "Spherical Harmonic Exponentials for Efficient Glossy Reflections"
+ * (HPG 2025, https://doi.org/10.1111/cgf.70219), with `kappa = 1 / alpha`.
+ *
+ * The generated `sh{N}_color_evaluate_vmf` chunks fold the same factor into their unrolled bands;
+ * this is the one-band form for kernels that walk coefficients by index.
+ *
+ * CPU twin: `core/geom/3d/sphere/harmonics/sh_vmf_window.js`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_vmf_window = CodeChunk.from(
+    //language=WGSL
+    `
+fn sh_vmf_window(l: f32, kappa: f32) -> f32 {
+    return exp(-l * (l + 1.0) / (2.0 * kappa));
+}
+`);

package/src/shade/renderer/shader/chunk/spherical_harmonics/exponential/SH_EXP_P4Q2_PROBE_STRUCT.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A spherical-harmonic-exponential reflection probe in the configuration of Silvennoinen et al.'s
+ * results (HPG 2025, https://doi.org/10.1111/cgf.70219): P to degree 4, Q to degree 2 — five and three
+ * bands. What `SHExpEncoder` writes with `SH_EXP_P4Q2_SETTINGS` (see `sh_exp_probe_vec4_count` for the
+ * layout), 560 bytes:
+ *
+ * - `header`: `(alpha_min, alpha_max, 5, 3)` — the GGX alpha range the probe was fitted over and its band counts;
+ * - `p`: log-radiance coefficients of the reflection term, RGB, band-major;
+ * - `q`: those of the half-reflection term; `q[0]` is always zero, its band 0 being folded into `p[0]`.
+ *
+ * 33 of the 35 slots carry information, three floats each; `vec3` arrays stride 16 bytes in WGSL.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SH_EXP_P4Q2_PROBE_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../../type/WebGPUStruct.js";
+//# sourceMappingURL=SH_EXP_P4Q2_PROBE_STRUCT.d.ts.map

package/src/shade/renderer/shader/chunk/spherical_harmonics/exponential/SH_EXP_P4Q2_PROBE_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SH_EXP_P4Q2_PROBE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/spherical_harmonics/exponential/SH_EXP_P4Q2_PROBE_STRUCT.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,uCAFU,YAAY,CAMD;6BApBQ,+BAA+B"}

package/src/shade/renderer/shader/chunk/spherical_harmonics/exponential/SH_EXP_P4Q2_PROBE_STRUCT.js

@@ -0,0 +1,23 @@
+import { vec3f, vec4f } from "../../../type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../type/WebGPUStruct.js";
+
+/**
+ * A spherical-harmonic-exponential reflection probe in the configuration of Silvennoinen et al.'s
+ * results (HPG 2025, https://doi.org/10.1111/cgf.70219): P to degree 4, Q to degree 2 — five and three
+ * bands. What `SHExpEncoder` writes with `SH_EXP_P4Q2_SETTINGS` (see `sh_exp_probe_vec4_count` for the
+ * layout), 560 bytes:
+ *
+ * - `header`: `(alpha_min, alpha_max, 5, 3)` — the GGX alpha range the probe was fitted over and its band counts;
+ * - `p`: log-radiance coefficients of the reflection term, RGB, band-major;
+ * - `q`: those of the half-reflection term; `q[0]` is always zero, its band 0 being folded into `p[0]`.
+ *
+ * 33 of the 35 slots carry information, three floats each; `vec3` arrays stride 16 bytes in WGSL.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SH_EXP_P4Q2_PROBE_STRUCT = WebGPUStruct.from({
+    header: vec4f,
+    p: WebGPUArray.from(vec3f, 25),
+    q: WebGPUArray.from(vec3f, 9),
+}, "SHExpProbeP4Q2");