@woosh/meep-engine 2.164.0 → 2.165.1

package/src/engine/graphics/sh3/lpg/light_probe_grid_obtain_storage_cached.js

@@ -0,0 +1,84 @@
+import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
+import { AABB3 } from "../../../../core/geom/3d/aabb/AABB3.js";
+import { number_pretty_print } from "../../../../core/primitives/numbers/number_pretty_print.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { ShadedGeometry } from "../../ecs/mesh-v2/ShadedGeometry.js";
+import { build_light_probe_grid_for_scene } from "./build_light_probe_grid_for_scene.js";
+import { LightProbeGrid } from "./LightProbeGrid.js";
+import { LightProbeGridSerializationAdapter } from "./serialization/LightProbeGridSerializationAdapter.js";
+
+/**
+ *
+ * @param {Engine} engine
+ * @param {string} path
+ * @param {LightProbeGrid} [grid]
+ * @param {number} [spacing] only used when building, if loading this parameter is ignored
+ * @return {Promise<LightProbeGrid>}
+ */
+export async function light_probe_grid_obtain_storage_cached({
+                                                                 engine,
+                                                                 path,
+                                                                 grid = new LightProbeGrid(),
+                                                                 spacing = 1
+                                                             }) {
+
+    grid.clear();
+
+    const key = `lpg:${path}`;
+
+    const adapter = new LightProbeGridSerializationAdapter();
+
+    if (await engine.storage.promiseContains(key)) {
+        const data = await engine.storage.promiseLoadBinary(key);
+
+        console.log(`LPG data size ${number_pretty_print(data.byteLength)} bytes`);
+
+        const buffer = BinaryBuffer.fromArrayBuffer(data);
+
+        adapter.deserialize(buffer, grid);
+
+        return grid;
+    }
+
+
+    const ecd = engine.entityManager.dataset;
+
+    // build bounding box for the scene
+    const mesh_bounds = new AABB3();
+    mesh_bounds.setNegativelyInfiniteBounds();
+
+    ecd.traverseEntities([ShadedGeometry, Transform],
+        /**
+         *
+         * @param {ShadedGeometry} sg
+         * @param transform
+         * @param entity
+         */
+        (sg, transform, entity) => {
+
+            const box = new AABB3();
+
+            sg.getBoundingBox(box);
+
+            mesh_bounds.union(box);
+
+        });
+
+    await build_light_probe_grid_for_scene({
+        grid,
+        engine,
+        ecd,
+        bounds: mesh_bounds,
+        spacing
+    });
+
+    const buffer = new BinaryBuffer();
+
+    adapter.serialize(buffer, grid);
+
+    buffer.trim();
+
+    engine.storage.promiseStoreBinary(key, buffer.data)
+
+    return grid;
+}

package/src/engine/graphics/sh3/lpg/light_probe_grid_textures.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Create the half-float luminance volume of a {@link LightProbeGrid}. Each texel holds the 4 SH2 Y coefficients in RGBA.
+ * @param {number} resolution_x
+ * @param {number} resolution_y
+ * @param {number} resolution_z
+ * @returns {DataTexture3D}
+ */
+export function make_light_probe_grid_luma_texture(resolution_x: number, resolution_y: number, resolution_z: number): DataTexture3D;
+/**
+ * Create an 8-bit chrominance volume (one of Co / Cg) of a {@link LightProbeGrid}. Each texel holds the 4 SH2
+ * coefficients of that chroma channel in RGBA.
+ * @param {number} resolution_x
+ * @param {number} resolution_y
+ * @param {number} resolution_z
+ * @returns {DataTexture3D}
+ */
+export function make_light_probe_grid_chroma_texture(resolution_x: number, resolution_y: number, resolution_z: number): DataTexture3D;
+/**
+ * Write probe data of a grid into the YCoCg textures created by {@link make_light_probe_grid_luma_texture} and
+ * {@link make_light_probe_grid_chroma_texture}. Texture dimensions must match the grid resolution.
+ * @param {LightProbeGrid} grid
+ * @param {DataTexture3D} texture_y luminance, half-float
+ * @param {DataTexture3D} texture_co chroma-orange, 8-bit
+ * @param {DataTexture3D} texture_cg chroma-green, 8-bit
+ */
+export function light_probe_grid_write_textures(grid: LightProbeGrid, texture_y: DataTexture3D, texture_co: DataTexture3D, texture_cg: DataTexture3D): void;
+export const LPG_CHROMA_SCALE: 0.25;
+import { DataTexture3D } from "three";
+//# sourceMappingURL=light_probe_grid_textures.d.ts.map

package/src/engine/graphics/sh3/lpg/light_probe_grid_textures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"light_probe_grid_textures.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lpg/light_probe_grid_textures.js"],"names":[],"mappings":"AA+BA;;;;;;GAMG;AACH,iEALW,MAAM,gBACN,MAAM,gBACN,MAAM,GACJ,aAAa,CA+BzB;AAED;;;;;;;GAOG;AACH,mEALW,MAAM,gBACN,MAAM,gBACN,MAAM,GACJ,aAAa,CA+BzB;AAUD;;;;;;;GAOG;AACH,iFAJW,aAAa,cACb,aAAa,cACb,aAAa,QAqCvB;AAtID,oCAAqC;8BAlB9B,OAAO"}

package/src/engine/graphics/sh3/lpg/light_probe_grid_textures.js

@@ -0,0 +1,160 @@
+import {
+    ClampToEdgeWrapping,
+    DataTexture3D,
+    HalfFloatType,
+    LinearFilter,
+    RGBAFormat,
+    UnsignedByteType
+} from "three";
+import { to_half_float_uint16 } from "../../../../core/binary/to_half_float_uint16.js";
+import { clamp } from "../../../../core/math/clamp.js";
+import { rgb_to_ycocg } from "../../../../core/color/YCoCg/rgb_to_ycocg.js";
+
+/*
+    YCoCg irradiance storage, after "Cross-Platform GI in Metro Exodus" (4A Games).
+    Luminance (Y) carries the HDR range and most of the perceptible detail, so it keeps half-float precision.
+    Chrominance (Co, Cg) is perceptually low-frequency and is dropped to 8-bit UNORM.
+
+    The 8-bit chroma is stored via a global affine map `stored = chroma * LPG_CHROMA_SCALE + 0.5` (decoded on the GPU
+    as `(stored - 0.5) / LPG_CHROMA_SCALE`). Because YCoCg is linear and this map is a global scale+bias, hardware
+    trilinear filtering of the three textures followed by reconstruction is exactly equivalent to filtering the
+    original RGB — the encoding does not disturb filtering.
+
+    Representable chroma range is +/- 0.5 / LPG_CHROMA_SCALE; chroma beyond it clips (a colored, very saturated probe
+    desaturates) while luminance, and therefore brightness, is preserved.
+*/
+export const LPG_CHROMA_SCALE = 0.25;
+
+const LPG_CHROMA_BIAS = 0.5;
+
+const __ycocg = new Float32Array(3);
+
+/**
+ * Create the half-float luminance volume of a {@link LightProbeGrid}. Each texel holds the 4 SH2 Y coefficients in RGBA.
+ * @param {number} resolution_x
+ * @param {number} resolution_y
+ * @param {number} resolution_z
+ * @returns {DataTexture3D}
+ */
+export function make_light_probe_grid_luma_texture(resolution_x, resolution_y, resolution_z) {
+
+    const texture = new DataTexture3D(
+        new Uint16Array(resolution_x * resolution_y * resolution_z * 4),
+        resolution_x,
+        resolution_y,
+        resolution_z
+    );
+
+    texture.name = "Light Probe Grid SH2 Y";
+
+    texture.flipY = false;
+    texture.generateMipmaps = false;
+    texture.magFilter = LinearFilter;
+    texture.minFilter = LinearFilter;
+
+    texture.wrapS = ClampToEdgeWrapping;
+    texture.wrapT = ClampToEdgeWrapping;
+    texture.wrapR = ClampToEdgeWrapping;
+
+    texture.type = HalfFloatType;
+    texture.format = RGBAFormat;
+    texture.internalFormat = "RGBA16F";
+
+    texture.unpackAlignment = 4;
+
+    texture.needsUpdate = true;
+
+    return texture;
+}
+
+/**
+ * Create an 8-bit chrominance volume (one of Co / Cg) of a {@link LightProbeGrid}. Each texel holds the 4 SH2
+ * coefficients of that chroma channel in RGBA.
+ * @param {number} resolution_x
+ * @param {number} resolution_y
+ * @param {number} resolution_z
+ * @returns {DataTexture3D}
+ */
+export function make_light_probe_grid_chroma_texture(resolution_x, resolution_y, resolution_z) {
+
+    const texture = new DataTexture3D(
+        new Uint8Array(resolution_x * resolution_y * resolution_z * 4),
+        resolution_x,
+        resolution_y,
+        resolution_z
+    );
+
+    texture.name = "Light Probe Grid SH2 chroma";
+
+    texture.flipY = false;
+    texture.generateMipmaps = false;
+    texture.magFilter = LinearFilter;
+    texture.minFilter = LinearFilter;
+
+    texture.wrapS = ClampToEdgeWrapping;
+    texture.wrapT = ClampToEdgeWrapping;
+    texture.wrapR = ClampToEdgeWrapping;
+
+    texture.type = UnsignedByteType;
+    texture.format = RGBAFormat;
+    texture.internalFormat = "RGBA8";
+
+    texture.unpackAlignment = 4;
+
+    texture.needsUpdate = true;
+
+    return texture;
+}
+
+/**
+ * @param {number} chroma
+ * @returns {number} 8-bit UNORM byte
+ */
+function encode_chroma_byte(chroma) {
+    return clamp(Math.round((chroma * LPG_CHROMA_SCALE + LPG_CHROMA_BIAS) * 255), 0, 255);
+}
+
+/**
+ * Write probe data of a grid into the YCoCg textures created by {@link make_light_probe_grid_luma_texture} and
+ * {@link make_light_probe_grid_chroma_texture}. Texture dimensions must match the grid resolution.
+ * @param {LightProbeGrid} grid
+ * @param {DataTexture3D} texture_y luminance, half-float
+ * @param {DataTexture3D} texture_co chroma-orange, 8-bit
+ * @param {DataTexture3D} texture_cg chroma-green, 8-bit
+ */
+export function light_probe_grid_write_textures(grid, texture_y, texture_co, texture_cg) {
+
+    const harmonics = grid.harmonics;
+    const count = grid.count;
+
+    const data_y = texture_y.image.data;
+    const data_co = texture_co.image.data;
+    const data_cg = texture_cg.image.data;
+
+    for (let i = 0; i < count; i++) {
+
+        const source_offset = i * 12;
+        const target_offset = i * 4;
+
+        for (let coefficient = 0; coefficient < 4; coefficient++) {
+
+            const source_address = source_offset + coefficient * 3;
+            const target_address = target_offset + coefficient;
+
+            rgb_to_ycocg(
+                __ycocg, 0,
+                harmonics[source_address],
+                harmonics[source_address + 1],
+                harmonics[source_address + 2]
+            );
+
+            data_y[target_address] = to_half_float_uint16(__ycocg[0]);
+            data_co[target_address] = encode_chroma_byte(__ycocg[1]);
+            data_cg[target_address] = encode_chroma_byte(__ycocg[2]);
+        }
+    }
+
+    texture_y.needsUpdate = true;
+    texture_co.needsUpdate = true;
+    texture_cg.needsUpdate = true;
+}

package/src/engine/graphics/sh3/lpg/material/LightProbeGridMaterialTransformer.d.ts

@@ -0,0 +1,23 @@
+export class LightProbeGridMaterialTransformer extends AbstractMaterialTransformer {
+    /**
+     *
+     * @param {LightProbeGrid} grid
+     * @param {number|ProbeResolutionStage} stage Vertex sampling is faster but less accurate, fragment is more expensive and precise
+     */
+    constructor({ grid, stage, }: LightProbeGrid);
+    /**
+     *
+     * @param {number} v
+     */
+    set intensity(arg: number);
+    /**
+     *
+     * @return {number}
+     */
+    get intensity(): number;
+    update(): void;
+    transform(source: any): any;
+    #private;
+}
+import { AbstractMaterialTransformer } from "../../../material/manager/AbstractMaterialTransformer.js";
+//# sourceMappingURL=LightProbeGridMaterialTransformer.d.ts.map

package/src/engine/graphics/sh3/lpg/material/LightProbeGridMaterialTransformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LightProbeGridMaterialTransformer.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/sh3/lpg/material/LightProbeGridMaterialTransformer.js"],"names":[],"mappings":"AAgBA;IA2FI;;;;OAIG;IACH,8CAYC;IAzBD;;;OAGG;IACH,2BAEC;IAdD;;;OAGG;IACH,wBAEC;IAiED,eA0CC;IAED,4BAoBC;;CACJ;4CAhO2C,0DAA0D"}

package/src/engine/graphics/sh3/lpg/material/LightProbeGridMaterialTransformer.js

@@ -0,0 +1,228 @@
+import { Vector3 } from "three";
+import { assert } from "../../../../../core/assert.js";
+import { composeCompile } from "../../../material/composeCompile.js";
+import { AbstractMaterialTransformer } from "../../../material/manager/AbstractMaterialTransformer.js";
+import { isLitMaterial } from "../../../render/forward_plus/plugin/isLitMaterial.js";
+import { ProbeResolutionStage } from "../../gi/material/ProbeResolutionStage.js";
+import {
+    light_probe_grid_write_textures,
+    make_light_probe_grid_chroma_texture,
+    make_light_probe_grid_luma_texture
+} from "../light_probe_grid_textures.js";
+import { space_fragment_transform_shader } from "./space_fragment/space_fragment_transform_shader.js";
+import { space_vertex_transform_shader } from "./space_vertex/space_vertex_transform_shader.js";
+
+const PROPERTY_TRANSFORMER_MARKER = '@light-probe-grid-material-transformer';
+
+export class LightProbeGridMaterialTransformer extends AbstractMaterialTransformer {
+
+    /**
+     *
+     * @type {LightProbeGrid}
+     */
+    #grid;
+
+    /**
+     *
+     * @type {ProbeResolutionStage|number}
+     */
+    #sampling_stage = ProbeResolutionStage.Fragment;
+
+    #textures = {
+        sh_y: make_light_probe_grid_luma_texture(1, 1, 1),
+        sh_co: make_light_probe_grid_chroma_texture(1, 1, 1),
+        sh_cg: make_light_probe_grid_chroma_texture(1, 1, 1)
+    };
+
+    #uniforms = {
+        lpg_t_sh_y: {
+            type: "t",
+            value: this.#textures.sh_y
+        },
+        lpg_t_sh_co: {
+            type: "t",
+            value: this.#textures.sh_co
+        },
+        lpg_t_sh_cg: {
+            type: "t",
+            value: this.#textures.sh_cg
+        },
+        lpg_v3_bounds_min: {
+            value: new Vector3()
+        },
+        lpg_v3_bounds_max: {
+            value: new Vector3()
+        },
+        lpg_v3_uvw_scale: {
+            value: new Vector3()
+        },
+        lpg_v3_uvw_offset: {
+            value: new Vector3()
+        },
+        lpg_f_intensity: {
+            value: 1
+        }
+    };
+
+    /**
+     *
+     * @type {number}
+     */
+    #uniform_version = -1;
+
+    /**
+     *
+     * @param {{uniforms, glslVersion, defines, vertexShader, fragmentShader}} shader
+     */
+    #onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, this.#uniforms);
+
+        switch (this.#sampling_stage) {
+            case ProbeResolutionStage.Vertex:
+                space_vertex_transform_shader(shader);
+                break;
+            case ProbeResolutionStage.Fragment:
+                space_fragment_transform_shader(shader);
+                break;
+            default:
+                throw new Error(`Unsupported resolution space ${this.#sampling_stage}`);
+        }
+    };
+
+    /**
+     *
+     * @return {number}
+     */
+    get intensity() {
+        return this.#uniforms.lpg_f_intensity.value;
+    }
+
+    /**
+     *
+     * @param {number} v
+     */
+    set intensity(v) {
+        this.#uniforms.lpg_f_intensity.value = v;
+    }
+
+    /**
+     *
+     * @param {LightProbeGrid} grid
+     * @param {number|ProbeResolutionStage} stage Vertex sampling is faster but less accurate, fragment is more expensive and precise
+     */
+    constructor({
+                    grid,
+                    stage = ProbeResolutionStage.Vertex,
+                }) {
+
+        super();
+
+        assert.defined(grid, 'grid');
+        assert.enum(stage, ProbeResolutionStage, 'stage');
+
+        this.#grid = grid;
+        this.#sampling_stage = stage;
+    }
+
+    /**
+     * Re-create channel textures when the grid resolution changes.
+     * Uniform objects are shared by reference with every compiled shader, so re-assigning their values is
+     * picked up by all transformed materials.
+     * @param {number} resolution_x
+     * @param {number} resolution_y
+     * @param {number} resolution_z
+     */
+    #ensure_texture_dimensions(resolution_x, resolution_y, resolution_z) {
+        const textures = this.#textures;
+
+        const image = textures.sh_y.image;
+
+        if (
+            image.width === resolution_x
+            && image.height === resolution_y
+            && image.depth === resolution_z
+        ) {
+            return;
+        }
+
+        textures.sh_y.dispose();
+        textures.sh_co.dispose();
+        textures.sh_cg.dispose();
+
+        textures.sh_y = make_light_probe_grid_luma_texture(resolution_x, resolution_y, resolution_z);
+        textures.sh_co = make_light_probe_grid_chroma_texture(resolution_x, resolution_y, resolution_z);
+        textures.sh_cg = make_light_probe_grid_chroma_texture(resolution_x, resolution_y, resolution_z);
+
+        const uniforms = this.#uniforms;
+
+        uniforms.lpg_t_sh_y.value = textures.sh_y;
+        uniforms.lpg_t_sh_co.value = textures.sh_co;
+        uniforms.lpg_t_sh_cg.value = textures.sh_cg;
+    }
+
+    update() {
+        const grid = this.#grid;
+
+        if (this.#uniform_version === grid.version) {
+            // up to date
+            return;
+        }
+
+        if (grid.count === 0) {
+            // nothing baked yet
+            return;
+        }
+
+        const resolution_x = grid.resolution_x;
+        const resolution_y = grid.resolution_y;
+        const resolution_z = grid.resolution_z;
+
+        this.#ensure_texture_dimensions(resolution_x, resolution_y, resolution_z);
+
+        const textures = this.#textures;
+
+        light_probe_grid_write_textures(grid, textures.sh_y, textures.sh_co, textures.sh_cg);
+
+        const uniforms = this.#uniforms;
+
+        const bounds = grid.bounds;
+
+        uniforms.lpg_v3_bounds_min.value.set(bounds.x0, bounds.y0, bounds.z0);
+        uniforms.lpg_v3_bounds_max.value.set(bounds.x1, bounds.y1, bounds.z1);
+
+        uniforms.lpg_v3_uvw_scale.value.set(
+            (resolution_x - 1) / resolution_x,
+            (resolution_y - 1) / resolution_y,
+            (resolution_z - 1) / resolution_z
+        );
+        uniforms.lpg_v3_uvw_offset.value.set(
+            0.5 / resolution_x,
+            0.5 / resolution_y,
+            0.5 / resolution_z
+        );
+
+        this.#uniform_version = grid.version;
+    }
+
+    transform(source) {
+        if (source.hasOwnProperty(PROPERTY_TRANSFORMER_MARKER)) {
+            // already transformed
+
+            if (source[PROPERTY_TRANSFORMER_MARKER] !== this) {
+                throw new Error('The material is already transformed, but is associated with a different transformer instance');
+            } else {
+                return source;
+            }
+
+        }
+
+        if (isLitMaterial(source)) {
+
+            source.onBeforeCompile = composeCompile(source.onBeforeCompile, this.#onBeforeCompile);
+
+            source[PROPERTY_TRANSFORMER_MARKER] = this;
+        }
+
+        return source;
+    }
+}

package/src/engine/graphics/sh3/lpg/material/chunk_lpg_get_irradiance_at.d.ts

@@ -0,0 +1,2 @@
+export const chunk_lpg_get_irradiance_at: "\n#ifndef LPG_CHUNK_GET_IRRADIANCE_AT\n#define LPG_CHUNK_GET_IRRADIANCE_AT\n\nvec3 lpg_get_irradiance_at(in vec3 normal, in vec3 shCoefficients[4]) {\n    // normal is assumed to have unit length\n\n    // band 0\n    vec3 result = shCoefficients[0] * 0.8862269254527579;\n\n    // band 1\n    result += shCoefficients[1] * 1.0233267079464885 * normal.y;\n    result += shCoefficients[2] * 1.0233267079464885 * normal.z;\n    result += shCoefficients[3] * 1.0233267079464885 * normal.x;\n\n    return result;\n}\n\n#endif\n";
+//# sourceMappingURL=chunk_lpg_get_irradiance_at.d.ts.map

package/src/engine/graphics/sh3/lpg/material/chunk_lpg_get_irradiance_at.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_lpg_get_irradiance_at.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/sh3/lpg/material/chunk_lpg_get_irradiance_at.js"],"names":[],"mappings":"AAIA,wjBAmBC"}

package/src/engine/graphics/sh3/lpg/material/chunk_lpg_get_irradiance_at.js

@@ -0,0 +1,24 @@
+
+// source: https://graphics.stanford.edu/papers/envmap/envmap.pdf
+// first two bands of chunk_lpv_get_irradiance_at, constants include the cosine-lobe convolution
+//language=GLSL
+export const chunk_lpg_get_irradiance_at = `
+#ifndef LPG_CHUNK_GET_IRRADIANCE_AT
+#define LPG_CHUNK_GET_IRRADIANCE_AT
+
+vec3 lpg_get_irradiance_at(in vec3 normal, in vec3 shCoefficients[4]) {
+    // normal is assumed to have unit length
+
+    // band 0
+    vec3 result = shCoefficients[0] * 0.8862269254527579;
+
+    // band 1
+    result += shCoefficients[1] * 1.0233267079464885 * normal.y;
+    result += shCoefficients[2] * 1.0233267079464885 * normal.z;
+    result += shCoefficients[3] * 1.0233267079464885 * normal.x;
+
+    return result;
+}
+
+#endif
+`

package/src/engine/graphics/sh3/lpg/material/common.d.ts

@@ -0,0 +1,3 @@
+declare const _default: string;
+export default _default;
+//# sourceMappingURL=common.d.ts.map

package/src/engine/graphics/sh3/lpg/material/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/sh3/lpg/material/common.js"],"names":[],"mappings":""}

package/src/engine/graphics/sh3/lpg/material/common.js

@@ -0,0 +1,73 @@
+import { chunk_lpg_get_irradiance_at } from "./chunk_lpg_get_irradiance_at.js";
+import { LPG_CHROMA_SCALE } from "../light_probe_grid_textures.js";
+
+// decode multiplier for the 8-bit chroma textures (see light_probe_grid_textures.js)
+const LPG_CHROMA_DECODE = 1 / LPG_CHROMA_SCALE;
+
+// language=GLSL
+export default `
+#ifndef LPG_SHADER_CHUNK_COMMON
+#define LPG_SHADER_CHUNK_COMMON
+
+precision highp sampler3D;
+
+uniform sampler3D lpg_t_sh_y;
+uniform sampler3D lpg_t_sh_co;
+uniform sampler3D lpg_t_sh_cg;
+
+uniform vec3 lpg_v3_bounds_min;
+uniform vec3 lpg_v3_bounds_max;
+
+/*
+    Probes sit on the bounds faces, texels do not: the first and the last probe layer of an axis with N layers map
+    to texel centers 0.5/N and 1 - 0.5/N. uvw = normalized * (N-1)/N + 0.5/N re-aligns hardware trilinear filtering
+    with the probe lattice; scale and offset are precomputed per-axis on the CPU.
+*/
+uniform vec3 lpg_v3_uvw_scale;
+uniform vec3 lpg_v3_uvw_offset;
+
+/*
+    Irradiance is stored as YCoCg (Metro Exodus): half-float luminance + two 8-bit chroma volumes. The chroma
+    encoding stored = chroma * LPG_CHROMA_SCALE + 0.5 is a global scale+bias, so hardware trilinear filtering of all
+    three volumes stays exactly equivalent to filtering RGB; we simply decode after the fetch.
+*/
+const float lpg_chroma_decode = ${LPG_CHROMA_DECODE.toFixed(8)};
+
+${ chunk_lpg_get_irradiance_at }
+
+vec3 lpg_compute_uvw(in vec3 position) {
+    vec3 normalized = (position - lpg_v3_bounds_min) / (lpg_v3_bounds_max - lpg_v3_bounds_min);
+
+    return normalized * lpg_v3_uvw_scale + lpg_v3_uvw_offset;
+}
+
+vec3[4] lpg_fetch_sh(in vec3 position) {
+    vec3 uvw = lpg_compute_uvw(position);
+
+    // positions outside the bounds clamp to the nearest edge probe
+    vec4 y = texture(lpg_t_sh_y, uvw);
+    vec4 co = (texture(lpg_t_sh_co, uvw) - 0.5) * lpg_chroma_decode;
+    vec4 cg = (texture(lpg_t_sh_cg, uvw) - 0.5) * lpg_chroma_decode;
+
+    // reconstruct RGB per coefficient: R = Y + Co - Cg, G = Y + Cg, B = Y - Co - Cg
+    vec4 r = y + co - cg;
+    vec4 g = y + cg;
+    vec4 b = y - co - cg;
+
+    return vec3[4](
+        vec3(r.x, g.x, b.x),
+        vec3(r.y, g.y, b.y),
+        vec3(r.z, g.z, b.z),
+        vec3(r.w, g.w, b.w)
+    );
+}
+
+vec3 lpg_sample_irradiance(in vec3 position, in vec3 normal) {
+
+    vec3[4] sh = lpg_fetch_sh(position);
+
+    return lpg_get_irradiance_at(normal, sh);
+}
+
+#endif
+`

package/src/engine/graphics/sh3/lpg/material/space_fragment/build_fragment_shader.d.ts

@@ -0,0 +1,6 @@
+/**
+ *
+ * @param {string} source
+ */
+export function build_fragment_shader(source: string): string;
+//# sourceMappingURL=build_fragment_shader.d.ts.map

package/src/engine/graphics/sh3/lpg/material/space_fragment/build_fragment_shader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build_fragment_shader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/sh3/lpg/material/space_fragment/build_fragment_shader.js"],"names":[],"mappings":"AA0BA;;;GAGG;AACH,8CAFW,MAAM,UAahB"}