@woosh/meep-engine 2.169.1 → 2.169.2

package/src/engine/graphics/sh3/lpv/depth/chunk_probe_depth_sampling.d.ts

@@ -0,0 +1,38 @@
+/**
+ * GLSL source for sampling the octahedral probe-depth atlas.
+ *
+ * WHY THIS EXISTS
+ *
+ * The production GI sampler (`sh3/gi/material/common.js`) and the probe-depth
+ * debug visualiser (`sh3/lpv/depth/octahedral/v2/`) each carried their own
+ * transcription of this library — `sign_not_zero`, `quadBlendWieghts`,
+ * `VecToSphereOct`, `SampleBlended`, `lpv_bilinear_lerp`, `lpv_sample_bilinear`,
+ * `wrapOctahedralTexelCoordinates`, `lpv_probe_getDepthBilinear`,
+ * `lpv_probe_getDepthTriangular` and `lpv_probe_getPosition`. The
+ * misspelling `quadBlendWieghts` was faithfully reproduced in both, which is
+ * how we know one was pasted from the other.
+ *
+ * The whole point of the visualiser is to show what the production sampler
+ * sees. A forked copy can silently show something else, so the visualiser stops
+ * being evidence. One definition, two consumers.
+ *
+ * HOST REQUIREMENTS
+ *
+ * This chunk declares the three probe uniforms it reads
+ * (`lpv_t_probe_positions`, `lpv_t_probe_depth`,
+ * `lpv_u_probe_depth_resolution`) so a host only has to interpolate it and bind
+ * them. It must be interpolated ABOVE any code that calls into it — GLSL
+ * requires declaration before use.
+ *
+ * NOT INCLUDED — `sh3/lpv/depth/octahedral/shader/visualize.frag.glsl`
+ *
+ * That older visualiser declares a `VecToSphereOct` that folds on
+ * `direction.z < 0.0` and returns `.xy`, where this one folds on `v.y < 0.0`
+ * and returns `.xz`. Those are different octahedral mappings, not two spellings
+ * of one — switching it to this chunk would change what that visualiser draws.
+ * It is deliberately left alone; see the note at the top of that file.
+ *
+ * @type {string}
+ */
+export const GLSL_LPV_PROBE_DEPTH_SAMPLING: string;
+//# sourceMappingURL=chunk_probe_depth_sampling.d.ts.map

package/src/engine/graphics/sh3/lpv/depth/chunk_probe_depth_sampling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_probe_depth_sampling.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/sh3/lpv/depth/chunk_probe_depth_sampling.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,4CAFU,MAAM,CAsOd"}

package/src/engine/graphics/sh3/lpv/depth/chunk_probe_depth_sampling.js

@@ -0,0 +1,265 @@
+/**
+ * GLSL source for sampling the octahedral probe-depth atlas.
+ *
+ * WHY THIS EXISTS
+ *
+ * The production GI sampler (`sh3/gi/material/common.js`) and the probe-depth
+ * debug visualiser (`sh3/lpv/depth/octahedral/v2/`) each carried their own
+ * transcription of this library — `sign_not_zero`, `quadBlendWieghts`,
+ * `VecToSphereOct`, `SampleBlended`, `lpv_bilinear_lerp`, `lpv_sample_bilinear`,
+ * `wrapOctahedralTexelCoordinates`, `lpv_probe_getDepthBilinear`,
+ * `lpv_probe_getDepthTriangular` and `lpv_probe_getPosition`. The
+ * misspelling `quadBlendWieghts` was faithfully reproduced in both, which is
+ * how we know one was pasted from the other.
+ *
+ * The whole point of the visualiser is to show what the production sampler
+ * sees. A forked copy can silently show something else, so the visualiser stops
+ * being evidence. One definition, two consumers.
+ *
+ * HOST REQUIREMENTS
+ *
+ * This chunk declares the three probe uniforms it reads
+ * (`lpv_t_probe_positions`, `lpv_t_probe_depth`,
+ * `lpv_u_probe_depth_resolution`) so a host only has to interpolate it and bind
+ * them. It must be interpolated ABOVE any code that calls into it — GLSL
+ * requires declaration before use.
+ *
+ * NOT INCLUDED — `sh3/lpv/depth/octahedral/shader/visualize.frag.glsl`
+ *
+ * That older visualiser declares a `VecToSphereOct` that folds on
+ * `direction.z < 0.0` and returns `.xy`, where this one folds on `v.y < 0.0`
+ * and returns `.xz`. Those are different octahedral mappings, not two spellings
+ * of one — switching it to this chunk would change what that visualiser draws.
+ * It is deliberately left alone; see the note at the top of that file.
+ *
+ * @type {string}
+ */
+export const GLSL_LPV_PROBE_DEPTH_SAMPLING = `
+#ifndef LPV_SHADER_CHUNK_PROBE_DEPTH_SAMPLING
+#define LPV_SHADER_CHUNK_PROBE_DEPTH_SAMPLING
+
+uniform sampler2D lpv_t_probe_positions;
+
+uniform sampler2D lpv_t_probe_depth;
+uniform uint lpv_u_probe_depth_resolution;
+
+ivec2 lpv_index_to_256_coordinate(uint index) {
+
+    uint pixel_x = index % 256u;
+    uint pixel_y = index / 256u;
+
+    return ivec2(int(pixel_x), int(pixel_y));
+}
+
+float sign_not_zero(float x) {
+    return x >= 0.0 ? 1.0 : -1.0;
+}
+
+vec2 sign_not_zero(vec2 x) {
+    return vec2(
+        sign_not_zero(x.x),
+        sign_not_zero(x.y)
+    );
+}
+
+vec3 sign_not_zero(vec3 x) {
+    return vec3(
+        sign_not_zero(x.x),
+        sign_not_zero(x.y),
+        sign_not_zero(x.z)
+    );
+}
+
+vec4 quadBlendWieghts(vec2 coords)
+{
+    vec4 res;
+/* 0 0 0
+    0 0 0
+    1 0 0 */
+    res.x = min(1.0f - coords.x, 1.0f - coords.y);
+/* 1 0 0
+    0 0 0
+    0 0 1 */
+    res.y = abs(coords.x - coords.y);
+/* 0 0 1
+    0 0 0
+    0 0 0 */
+    res.z = min(coords.x, coords.y);
+/* 0 0 0
+    0 0 1
+    0 1 1 */
+    res.w = ceil(coords.x - coords.y);
+    //res.xyz /= (res.x + res.y + res.z);
+    return res;
+}
+
+vec2 VecToSphereOct(vec3 v)
+{
+    float l1norm = abs(v.x) + abs(v.y) + abs(v.z);
+
+    vec2 result = v.xz / l1norm;
+
+    if (v.y < 0.0) {
+        result = (1.0 - abs(result.yx)) * sign_not_zero(result.xy);
+    }
+
+    return result;
+}
+
+float SampleBlended(sampler2D tex, vec2 uv0, vec2 uv1, vec2 uv2, vec4 weights) {
+
+    float samp0 = textureLod(tex, uv0, 0.0).r;
+    float samp1 = textureLod(tex, uv1, 0.0).r;
+    float samp2 = textureLod(tex, uv2, 0.0).r;
+
+    return samp0 * weights.x + samp1 * weights.y + samp2 * weights.z;
+}
+
+vec2 lpv_probe_getDepthTriangular(uint probe_index, vec3 direction) {
+    // get offset
+    uint depth_tile_resolution = lpv_u_probe_depth_resolution;
+    uvec2 atlas_size = uvec2(4096u);
+
+    uint tiles_per_row = atlas_size.x / depth_tile_resolution;
+
+    uint tile_x = probe_index % tiles_per_row;
+    uint tile_y = probe_index / tiles_per_row;
+
+    vec2 tile_offset = vec2(
+        tile_x * depth_tile_resolution,
+        tile_y * depth_tile_resolution
+    );
+
+    // convert direction to UV
+    vec2 octahedral_uv = clamp(VecToSphereOct(direction) * 0.5 + 0.5, 0.0, 1.0);
+    vec2 grid = octahedral_uv * vec2(depth_tile_resolution - 1u);
+
+    vec2 gridFrac = fract(grid);
+    vec2 gridFloor = floor(grid);
+
+    vec4 weights = quadBlendWieghts(gridFrac);
+
+    //3 nearest frames
+    vec2 frame0 = gridFloor;
+    vec2 frame1 = gridFloor + mix(vec2(0, 1), vec2(1, 0), weights.w);
+    vec2 frame2 = gridFloor + vec2(1.0, 1.0);
+
+    // move frames to atlas space
+    frame0 += tile_offset;
+    frame1 += tile_offset;
+    frame2 += tile_offset;
+
+    vec2 samp0 = texelFetch(lpv_t_probe_depth, ivec2(frame0), 0).rg;
+    vec2 samp1 = texelFetch(lpv_t_probe_depth, ivec2(frame1), 0).rg;
+    vec2 samp2 = texelFetch(lpv_t_probe_depth, ivec2(frame2), 0).rg;
+
+    vec2 d0 = samp0 * weights.x;
+    vec2 d1 = samp1 * weights.y;
+    vec2 d2 = samp2 * weights.z;
+
+    return (d0 + d1 + d2);
+}
+
+float lpv_bilinear_lerp(float v00, float v01, float v10, float v11, vec2 fraction) {
+
+    float x0 = mix(v00, v01, fraction.x);
+    float x1 = mix(v10, v11, fraction.x);
+
+    return mix(x0, x1, fraction.y);
+}
+
+vec2 lpv_bilinear_lerp(vec2 v00, vec2 v01, vec2 v10, vec2 v11, vec2 fraction) {
+
+    vec2 x0 = mix(v00, v01, fraction.x);
+    vec2 x1 = mix(v10, v11, fraction.x);
+
+    return mix(x0, x1, fraction.y);
+}
+
+vec2 lpv_sample_bilinear(sampler2D tex, ivec2 texel_position, vec2 fraction) {
+
+    float texel_00 = texelFetch(tex, texel_position, 0).r;
+    float texel_01 = texelFetch(tex, texel_position + ivec2(1, 0), 0).r;
+    float texel_10 = texelFetch(tex, texel_position + ivec2(0, 1), 0).r;
+    float texel_11 = texelFetch(tex, texel_position + ivec2(1, 1), 0).r;
+
+    return vec2(
+        lpv_bilinear_lerp(
+            texel_00, texel_01,
+            texel_10, texel_11,
+            fraction
+        ),
+        lpv_bilinear_lerp(
+            texel_00 * texel_00, texel_01 * texel_01,
+            texel_10 * texel_10, texel_11 * texel_11,
+            fraction
+        )
+    );
+}
+
+ivec2 wrapOctahedralTexelCoordinates(const in ivec2 texel, const in int texture_size) {
+    ivec2 wrapped = ((texel % texture_size) + texture_size) % texture_size;
+
+    int fx = (abs(texel.x / texture_size) + int(texel.x < 0));
+    int fy = (abs(texel.y / texture_size) + int(texel.y < 0));
+
+    if (((fx ^ fy) & 1) != 0) {
+        return (texture_size - (wrapped + ivec2(1)));
+        return wrapped;
+    } else {
+        return wrapped;
+    }
+}
+
+vec2 lpv_probe_getDepthBilinear(uint probe_index, vec3 direction) {
+    // get offset
+    int depth_tile_resolution = int(lpv_u_probe_depth_resolution);
+    ivec2 tile_resolution = ivec2(depth_tile_resolution);
+    const ivec2 atlas_size = ivec2(4096);
+
+    int tiles_per_row = atlas_size.x / depth_tile_resolution;
+
+    int tile_x = int(probe_index) % tiles_per_row;
+    int tile_y = int(probe_index) / tiles_per_row;
+
+    ivec2 tile_offset = ivec2(
+        tile_x * depth_tile_resolution,
+        tile_y * depth_tile_resolution
+    );
+
+    // convert direction to UV
+    vec2 octahedral_uv = clamp(VecToSphereOct(direction) * 0.5 + 0.5, 0.0, 1.0);
+    vec2 grid = octahedral_uv * vec2(depth_tile_resolution) - 0.5;
+
+    vec2 gridFrac = fract(grid);
+
+    ivec2 texel_position = ivec2(floor(grid));
+
+    ivec2 tile_p_00;
+    ivec2 tile_p_01;
+    ivec2 tile_p_10;
+    ivec2 tile_p_11;
+
+    tile_p_00 = wrapOctahedralTexelCoordinates(texel_position, depth_tile_resolution);
+    tile_p_01 = wrapOctahedralTexelCoordinates(texel_position + ivec2(1, 0), depth_tile_resolution);
+    tile_p_10 = wrapOctahedralTexelCoordinates(texel_position + ivec2(0, 1), depth_tile_resolution);
+    tile_p_11 = wrapOctahedralTexelCoordinates(texel_position + ivec2(1, 1), depth_tile_resolution);
+
+    vec2 texel_00 = texelFetch(lpv_t_probe_depth, tile_offset + tile_p_00, 0).rg;
+    vec2 texel_01 = texelFetch(lpv_t_probe_depth, tile_offset + tile_p_01, 0).rg;
+    vec2 texel_10 = texelFetch(lpv_t_probe_depth, tile_offset + tile_p_10, 0).rg;
+    vec2 texel_11 = texelFetch(lpv_t_probe_depth, tile_offset + tile_p_11, 0).rg;
+
+    return lpv_bilinear_lerp(
+        texel_00, texel_01,
+        texel_10, texel_11,
+        gridFrac
+    );
+}
+
+vec3 lpv_probe_getPosition(uint probe_index) {
+    return texelFetch(lpv_t_probe_positions, lpv_index_to_256_coordinate(probe_index), 0).rgb;
+}
+
+#endif
+`;

package/src/engine/graphics/sh3/lpv/depth/octahedral/shader/visualize.frag.glsl

@@ -1,3 +1,14 @@
+// DIVERGENCE WARNING — this shader does NOT use the shared probe-depth chunk.
+//
+// The `VecToSphereOct` below folds on `direction.z < 0.0` and returns `.xy`.
+// The production sampler and `sh3/lpv/depth/chunk_probe_depth_sampling.js` fold
+// on `v.y < 0.0` and return `.xz`. Those are two different octahedral mappings,
+// so this visualiser does not necessarily show what the GI path reads — and
+// switching it over to the shared chunk WOULD change what it draws. Whichever
+// convention is correct, it has to be decided and A/B'd deliberately; it was
+// left alone during the 2026-08-07 duplication pass rather than silently
+// unified. `quadBlendWieghts` and `SampleBlended` below are byte-identical to
+// the shared chunk and only stay here because the rest of the file cannot use it.
 vec3 inverseTransformDirection(in vec3 normal, in mat4 matrix) {
     // matrix is assumed to be orthogonal
     return normalize((vec4(normal, 0.0) * matrix).xyz);

package/src/engine/graphics/sh3/lpv/depth/octahedral/v2/VLPDepthMapVisualisation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VLPDepthMapVisualisation.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/engine/graphics/sh3/lpv/depth/octahedral/v2/VLPDepthMapVisualisation.js"],"names":[],"mappings":"AA8EA;IAYI;;;;OAIG;IACH,oCAFa,wBAAwB,CAQpC;IAfD,qBAEC;IAeD,gBA4CC;;CAEJ;mBAzIkB,iCAAiC"}
+{"version":3,"file":"VLPDepthMapVisualisation.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/engine/graphics/sh3/lpv/depth/octahedral/v2/VLPDepthMapVisualisation.js"],"names":[],"mappings":"AAkFA;IAYI;;;;OAIG;IACH,oCAFa,wBAAwB,CAQpC;IAfD,qBAEC;IAeD,gBA4CC;;CAEJ;mBA7IkB,iCAAiC"}

package/src/engine/graphics/sh3/lpv/depth/octahedral/v2/VLPDepthMapVisualisation.js

@@ -19,6 +19,7 @@ import { geometry_copy } from "../../../../../geometry/instancing/geometry_copy.
 import { AttributeDataTexture } from "../../../../../texture/AttributeDataTexture.js";
 import { makeOctahedralDepthAtlas } from "../../../../gi/material/makeOctahedralDepthAtlas.js";
 import { octahedral_depth_to_atlas, vector_buffer_to_attribute_texture } from "../../../probe_volume_to_textures.js";
+import { GLSL_LPV_PROBE_DEPTH_SAMPLING } from "../../chunk_probe_depth_sampling.js";
 import fragment from './visualise.frag.glsl'
 import vertex from './visualise.vert.glsl'
 
@@ -41,7 +42,10 @@ function makeMaterial(lpv) {
     octahedral_depth_to_atlas(lpv, depth_atlas.image.data, depth_atlas.image.width);
 
     const material = new ShaderMaterial({
-        fragmentShader: [fragment].join('\n'),
+        // The probe-depth sampling library has to be prepended, not pasted into
+        // the .glsl file: this visualiser exists to show what the production GI
+        // sampler sees, and it can only do that if both compile the same source.
+        fragmentShader: [GLSL_LPV_PROBE_DEPTH_SAMPLING, fragment].join('\n'),
         vertexShader: vertex,
         lights: false,
         uniforms: {