@woosh/meep-engine 2.163.1 → 2.163.3

package/src/engine/graphics/sh3/sky/hosek/make_environment_sky_hosek.js

@@ -0,0 +1,49 @@
+import {
+    DataTexture,
+    EquirectangularReflectionMapping,
+    FloatType,
+    LinearFilter,
+    RGBAFormat
+} from "three";
+import { render_hosek_sky_to_equirectangular } from "./render_hosek_sky_to_equirectangular.js";
+
+/**
+ * Build an environment map from the Hosek sky model as a single equirectangular
+ * {@link DataTexture} (three.js' native sky representation,
+ * EquirectangularReflectionMapping).
+ *
+ * This returns the raw (sharp) sky; prefiltering for IBL is done by
+ * `GraphicsEngine.set_environment_texture`, which PMREMs it. The texture can be
+ * used directly as `scene.background`.
+ *
+ * @param {object} options
+ * @param {number[]|Float32Array} options.sun direction towards the sun (engine frame, +Y up); need not be unit length
+ * @param {number} [options.resolution=256] width of the equirectangular map; height is resolution/2
+ * @param {number} [options.turbidity=2] atmospheric turbidity, 1..10
+ * @param {number} [options.overcast=0] 0 = clear, 1 = fully overcast
+ * @param {number[]|Float32Array} [options.albedo=[0,0,0]] linear ground albedo
+ * @returns {THREE.DataTexture}
+ */
+export function make_environment_sky_hosek(
+    {
+        sun,
+        resolution = 256,
+        turbidity = 2,
+        overcast = 0,
+        albedo = [0, 0, 0]
+    }
+) {
+    const width = Math.max(2, resolution | 0);
+    const height = Math.max(1, width >> 1);
+
+    const data = render_hosek_sky_to_equirectangular(sun, width, height, { turbidity, overcast, albedo });
+
+    const texture = new DataTexture(data, width, height, RGBAFormat, FloatType);
+    texture.mapping = EquirectangularReflectionMapping;
+    texture.magFilter = LinearFilter;
+    texture.minFilter = LinearFilter;
+    texture.generateMipmaps = false;
+    texture.needsUpdate = true;
+
+    return texture;
+}

package/src/engine/graphics/sh3/sky/hosek/render_hosek_sky_to_equirectangular.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Render the Hosek sky into an equirectangular RGBA float buffer.
+ *
+ * The layout matches three.js' `equirectUv` (so the result can be used directly
+ * as an EquirectangularReflectionMapping texture or fed to PMREMGenerator):
+ *   u = atan2(z, x) / (2pi) + 0.5
+ *   v = asin(y) / pi + 0.5
+ * with +Y up, matching the engine convention.
+ *
+ * @param {number[]|Float32Array} sun direction towards the sun (engine frame, +Y up); need not be unit length
+ * @param {number} width  number of horizontal (longitude) samples
+ * @param {number} height number of vertical (latitude) samples
+ * @param {object} [options]
+ * @param {number} [options.turbidity=2] atmospheric turbidity, 1..10
+ * @param {number} [options.overcast=0] 0 = clear, 1 = fully overcast
+ * @param {number[]|Float32Array} [options.albedo=[0,0,0]] linear ground albedo
+ * @param {Float32Array} [options.target] optional pre-allocated buffer of length width*height*4
+ * @returns {Float32Array} RGBA, row 0 = bottom (-Y), length width*height*4
+ */
+export function render_hosek_sky_to_equirectangular(sun: number[] | Float32Array, width: number, height: number, options?: {
+    turbidity?: number;
+    overcast?: number;
+    albedo?: number[] | Float32Array;
+    target?: Float32Array;
+}): Float32Array;
+//# sourceMappingURL=render_hosek_sky_to_equirectangular.d.ts.map

package/src/engine/graphics/sh3/sky/hosek/render_hosek_sky_to_equirectangular.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render_hosek_sky_to_equirectangular.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/sh3/sky/hosek/render_hosek_sky_to_equirectangular.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AACH,yDAVW,MAAM,EAAE,GAAC,YAAY,SACrB,MAAM,UACN,MAAM;IAEW,SAAS,GAA1B,MAAM;IACW,QAAQ,GAAzB,MAAM;IAC0B,MAAM,GAAtC,MAAM,EAAE,GAAC,YAAY;IACE,MAAM,GAA7B,YAAY;IACV,YAAY,CAgDxB"}

package/src/engine/graphics/sh3/sky/hosek/render_hosek_sky_to_equirectangular.js

@@ -0,0 +1,70 @@
+import { make_sky_hosek } from "../../path_tracer/make_sky_hosek.js";
+
+const TWO_PI = Math.PI * 2;
+
+/**
+ * Render the Hosek sky into an equirectangular RGBA float buffer.
+ *
+ * The layout matches three.js' `equirectUv` (so the result can be used directly
+ * as an EquirectangularReflectionMapping texture or fed to PMREMGenerator):
+ *   u = atan2(z, x) / (2pi) + 0.5
+ *   v = asin(y) / pi + 0.5
+ * with +Y up, matching the engine convention.
+ *
+ * @param {number[]|Float32Array} sun direction towards the sun (engine frame, +Y up); need not be unit length
+ * @param {number} width  number of horizontal (longitude) samples
+ * @param {number} height number of vertical (latitude) samples
+ * @param {object} [options]
+ * @param {number} [options.turbidity=2] atmospheric turbidity, 1..10
+ * @param {number} [options.overcast=0] 0 = clear, 1 = fully overcast
+ * @param {number[]|Float32Array} [options.albedo=[0,0,0]] linear ground albedo
+ * @param {Float32Array} [options.target] optional pre-allocated buffer of length width*height*4
+ * @returns {Float32Array} RGBA, row 0 = bottom (-Y), length width*height*4
+ */
+export function render_hosek_sky_to_equirectangular(sun, width, height, options = {}) {
+    const {
+        turbidity = 2,
+        overcast = 0,
+        albedo = [0, 0, 0],
+        target
+    } = options;
+
+    const sky = make_sky_hosek(sun, turbidity, overcast, albedo);
+
+    const data = target !== undefined ? target : new Float32Array(width * height * 4);
+
+    const direction = [0, 0, 0];
+
+    let p = 0;
+
+    for (let j = 0; j < height; j++) {
+        const v = (j + 0.5) / height;
+
+        // v = asin(y)/pi + 0.5  =>  y = sin((v - 0.5) * pi)
+        const latitude = (v - 0.5) * Math.PI;
+        const y = Math.sin(latitude);
+        const cos_latitude = Math.cos(latitude);
+
+        for (let i = 0; i < width; i++) {
+            const u = (i + 0.5) / width;
+
+            // u = atan2(z, x)/(2pi) + 0.5  =>  atan2(z, x) = (u - 0.5) * 2pi
+            const longitude = (u - 0.5) * TWO_PI;
+
+            direction[0] = cos_latitude * Math.cos(longitude);
+            direction[1] = y;
+            direction[2] = cos_latitude * Math.sin(longitude);
+
+            const offset = p * 4;
+
+            // writes linear RGB into data[offset .. offset + 2]
+            sky(data, offset, direction, 0);
+
+            data[offset + 3] = 1;
+
+            p++;
+        }
+    }
+
+    return data;
+}

package/src/engine/graphics/sh3/sky/hosek/setup_environment_sky_from_ecd.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Build a Hosek sky environment and apply it to a graphics scene, deriving the
+ * sun direction from the dataset's directional light.
+ *
+ * Delegates to {@link GraphicsEngine#set_environment_texture}, which PMREMs the
+ * equirectangular sky and assigns it as both the IBL source
+ * (`scene.environment`) and the skybox (`scene.background`).
+ *
+ * @param {GraphicsEngine} graphics
+ * @param {EntityComponentDataset} ecd source of the {@link DirectionalLight} that defines the sun
+ * @param {object} [options]
+ * @param {number} [options.resolution=256] width of the equirectangular map; height is resolution/2
+ * @param {number} [options.turbidity=2] atmospheric turbidity, 1..10
+ * @param {number} [options.overcast=0] 0 = clear, 1 = fully overcast
+ * @param {number[]|Float32Array} [options.albedo=[0,0,0]] linear ground albedo
+ * @returns {THREE.DataTexture} the equirectangular sky texture that was applied
+ */
+export function setup_environment_sky_from_ecd(graphics: GraphicsEngine, ecd: EntityComponentDataset, options?: {
+    resolution?: number;
+    turbidity?: number;
+    overcast?: number;
+    albedo?: number[] | Float32Array;
+}): THREE.DataTexture;
+//# sourceMappingURL=setup_environment_sky_from_ecd.d.ts.map

package/src/engine/graphics/sh3/sky/hosek/setup_environment_sky_from_ecd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup_environment_sky_from_ecd.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/sh3/sky/hosek/setup_environment_sky_from_ecd.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AACH;IAN4B,UAAU,GAA3B,MAAM;IACW,SAAS,GAA1B,MAAM;IACW,QAAQ,GAAzB,MAAM;IAC0B,MAAM,GAAtC,MAAM,EAAE,GAAC,YAAY;IACnB,MAAM,WAAW,CA+B7B"}

package/src/engine/graphics/sh3/sky/hosek/setup_environment_sky_from_ecd.js

@@ -0,0 +1,51 @@
+import { DirectionalLight } from "../../../render/forward_plus/model/DirectionalLight.js";
+import { EnvironmentTextureProjection } from "../../../texture/EnvironmentTextureProjection.js";
+import { make_environment_sky_hosek } from "./make_environment_sky_hosek.js";
+
+/**
+ * Build a Hosek sky environment and apply it to a graphics scene, deriving the
+ * sun direction from the dataset's directional light.
+ *
+ * Delegates to {@link GraphicsEngine#set_environment_texture}, which PMREMs the
+ * equirectangular sky and assigns it as both the IBL source
+ * (`scene.environment`) and the skybox (`scene.background`).
+ *
+ * @param {GraphicsEngine} graphics
+ * @param {EntityComponentDataset} ecd source of the {@link DirectionalLight} that defines the sun
+ * @param {object} [options]
+ * @param {number} [options.resolution=256] width of the equirectangular map; height is resolution/2
+ * @param {number} [options.turbidity=2] atmospheric turbidity, 1..10
+ * @param {number} [options.overcast=0] 0 = clear, 1 = fully overcast
+ * @param {number[]|Float32Array} [options.albedo=[0,0,0]] linear ground albedo
+ * @returns {THREE.DataTexture} the equirectangular sky texture that was applied
+ */
+export function setup_environment_sky_from_ecd(graphics, ecd, options = {}) {
+    const {
+        resolution = 256,
+        turbidity = 2,
+        overcast = 0,
+        albedo = [0, 0, 0]
+    } = options;
+
+    const { component: light } = ecd.getAnyComponent(DirectionalLight);
+
+    /**
+     * Direction *towards* the sun = negated light travel direction.
+     * Falls back to an overhead sun when the dataset has no directional light.
+     * @type {number[]}
+     */
+    let sun;
+
+    if (light !== null) {
+        const d = light.direction;
+        sun = [-d.x, -d.y, -d.z];
+    } else {
+        sun = [0, 1, 0];
+    }
+
+    const texture = make_environment_sky_hosek({ sun, resolution, turbidity, overcast, albedo });
+
+    graphics.set_environment_texture(texture, EnvironmentTextureProjection.Equirectangular);
+
+    return texture;
+}

package/src/engine/graphics/texture/EnvironmentTextureProjection.d.ts

@@ -0,0 +1,9 @@
+/**
+ * How an environment-map texture is projected onto the sphere.
+ */
+export type EnvironmentTextureProjection = number;
+export namespace EnvironmentTextureProjection {
+    let Equirectangular: number;
+    let Cube: number;
+}
+//# sourceMappingURL=EnvironmentTextureProjection.d.ts.map

package/src/engine/graphics/texture/EnvironmentTextureProjection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvironmentTextureProjection.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/texture/EnvironmentTextureProjection.js"],"names":[],"mappings":";;;2CAEU,MAAM"}

package/src/engine/graphics/texture/EnvironmentTextureProjection.js

@@ -0,0 +1,15 @@
+/**
+ * How an environment-map texture is projected onto the sphere.
+ * @enum {number}
+ */
+export const EnvironmentTextureProjection = {
+    /**
+     * Lat-long / equirectangular projection. This is the default and the
+     * representation three.js uses for sky textures.
+     */
+    Equirectangular: 0,
+    /**
+     * Cube map (six faces packed as a CubeTexture).
+     */
+    Cube: 1
+};

package/src/engine/graphics/texture/reflection/convolve_equirectangular_reflection.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Convolve an equirectangular radiance map for a single output direction,
+ * importance-sampling a cone around it with a spherical-gaussian GGX weight.
+ * This is the per-texel core of the prefilter (extracted for testing).
+ *
+ * @param {Sampler2D} input equirectangular radiance (the previous, sharper mip)
+ * @param {number} out_x output (reflection) direction, unit length, +Y up
+ * @param {number} out_y
+ * @param {number} out_z
+ * @param {number} roughness perceptual roughness for this convolution step
+ * @param {number} sample_count number of cone samples
+ * @param {number[]|Float32Array} result
+ * @param {number} [result_offset=0]
+ */
+export function convolve_equirectangular_reflection_direction(input: Sampler2D, out_x: number, out_y: number, out_z: number, roughness: number, sample_count: number, result: number[] | Float32Array, result_offset?: number): void;
+/**
+ * Convolve a whole equirectangular level into `output`.
+ *
+ * @param {Sampler2D} input source radiance (previous mip)
+ * @param {Sampler2D} output destination (this mip)
+ * @param {number} roughness convolution roughness for this step
+ * @param {number} sample_count
+ */
+export function convolve_equirectangular_reflection_level(input: Sampler2D, output: Sampler2D, roughness: number, sample_count: number): void;
+/**
+ * Build a prefiltered reflection mip chain from a base equirectangular radiance
+ * map. Mip 0 is the (sharp) base; each subsequent mip is half resolution and
+ * convolved from the previous one, so roughness increases with mip level. This
+ * is the CPU replacement for THREE's PMREMGenerator, decoupled from three.js.
+ *
+ * @param {Sampler2D} base equirectangular RGBA radiance (mip 0)
+ * @param {object} [options]
+ * @param {number} [options.sample_count=32] cone samples per texel (the sky is low frequency)
+ * @param {number} [options.mip_levels] number of levels; defaults to the full chain
+ * @param {number} [options.max_roughness=0.7] roughness reached at the last mip
+ * @returns {Sampler2D[]} mip chain, index 0 = base
+ */
+export function build_equirectangular_reflection_mip_chain(base: Sampler2D, options?: {
+    sample_count?: number;
+    mip_levels?: number;
+    max_roughness?: number;
+}): Sampler2D[];
+import { Sampler2D } from "../sampler/Sampler2D.js";
+//# sourceMappingURL=convolve_equirectangular_reflection.d.ts.map

package/src/engine/graphics/texture/reflection/convolve_equirectangular_reflection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convolve_equirectangular_reflection.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/reflection/convolve_equirectangular_reflection.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;GAaG;AACH,qEATW,SAAS,SACT,MAAM,SACN,MAAM,SACN,MAAM,aACN,MAAM,gBACN,MAAM,UACN,MAAM,EAAE,GAAC,YAAY,kBACrB,MAAM,QAiEhB;AAED;;;;;;;GAOG;AACH,iEALW,SAAS,UACT,SAAS,aACT,MAAM,gBACN,MAAM,QA6BhB;AAED;;;;;;;;;;;;GAYG;AACH,iEAPW,SAAS;IAEQ,YAAY,GAA7B,MAAM;IACW,UAAU,GAA3B,MAAM;IACW,aAAa,GAA9B,MAAM;IACJ,SAAS,EAAE,CAoCvB;0BArLyB,yBAAyB"}

package/src/engine/graphics/texture/reflection/convolve_equirectangular_reflection.js

@@ -0,0 +1,189 @@
+import { hammersley_sequence_2d } from "../../../../core/math/statistics/hammersley_sequence_2d.js";
+import { v3_orthonormal_matrix_from_normal } from "../../../../core/geom/vec3/v3_orthonormal_matrix_from_normal.js";
+import { v3_uniform_sample_cone } from "../../../../core/geom/vec3/v3_uniform_sample_cone.js";
+import { reflection_sample_weight } from "../../../../core/math/physics/brdf/reflection_sample_weight.js";
+import { cone_cosine_from_roughness } from "../../../../core/math/physics/brdf/cone_cosine_from_roughness.js";
+import { equirectangular_uv_to_direction } from "../../../../core/geom/3d/equirectangular/equirectangular_uv_to_direction.js";
+import { sampler2d_sample_equirectangular_direction } from "../sampler/sampler2d_sample_equirectangular_direction.js";
+import { Sampler2D } from "../sampler/Sampler2D.js";
+import {
+    equirectangular_reflection_lod_to_roughness,
+    roughness_from_relative_mip
+} from "./equirectangular_reflection_roughness.js";
+
+/**
+ * Below this we treat the surface as a perfect mirror.
+ * @type {number}
+ */
+const BSDF_ROUGHNESS_MINIMUM = 0.02;
+
+// scratch state (single-threaded, non-reentrant)
+const _basis = new Float32Array(9);
+const _rand = [0, 0];
+const _local = [0, 0, 0];
+const _radiance = [0, 0, 0, 0];
+
+/**
+ * Convolve an equirectangular radiance map for a single output direction,
+ * importance-sampling a cone around it with a spherical-gaussian GGX weight.
+ * This is the per-texel core of the prefilter (extracted for testing).
+ *
+ * @param {Sampler2D} input equirectangular radiance (the previous, sharper mip)
+ * @param {number} out_x output (reflection) direction, unit length, +Y up
+ * @param {number} out_y
+ * @param {number} out_z
+ * @param {number} roughness perceptual roughness for this convolution step
+ * @param {number} sample_count number of cone samples
+ * @param {number[]|Float32Array} result
+ * @param {number} [result_offset=0]
+ */
+export function convolve_equirectangular_reflection_direction(
+    input,
+    out_x, out_y, out_z,
+    roughness,
+    sample_count,
+    result,
+    result_offset = 0
+) {
+    const cone_cos = cone_cosine_from_roughness(roughness);
+
+    v3_orthonormal_matrix_from_normal(_basis, 0, out_x, out_y, out_z);
+
+    const t_x = _basis[0], t_y = _basis[1], t_z = _basis[2];
+    const b_x = _basis[3], b_y = _basis[4], b_z = _basis[5];
+    const n_x = _basis[6], n_y = _basis[7], n_z = _basis[8];
+
+    const itemSize = input.itemSize;
+
+    let weight_accum = 0;
+    let r0 = 0, r1 = 0, r2 = 0, r3 = 0;
+
+    for (let i = 0; i < sample_count; i++) {
+        hammersley_sequence_2d(_rand, 0, i, sample_count);
+
+        v3_uniform_sample_cone(_local, 0, _rand[0], _rand[1], cone_cos);
+
+        const lx = _local[0], ly = _local[1], lz = _local[2];
+
+        // world direction = lx * T + ly * B + lz * N
+        let in_x = lx * t_x + ly * b_x + lz * n_x;
+        let in_y = lx * t_y + ly * b_y + lz * n_y;
+        let in_z = lx * t_z + ly * b_z + lz * n_z;
+
+        const len = Math.sqrt(in_x * in_x + in_y * in_y + in_z * in_z);
+        if (len > 0) {
+            const inv_len = 1.0 / len;
+            in_x *= inv_len;
+            in_y *= inv_len;
+            in_z *= inv_len;
+        }
+
+        sampler2d_sample_equirectangular_direction(input, in_x, in_y, in_z, _radiance, 0);
+
+        const weight = reflection_sample_weight(out_x, out_y, out_z, in_x, in_y, in_z, roughness);
+
+        r0 += _radiance[0] * weight;
+        r1 += _radiance[1] * weight;
+        r2 += _radiance[2] * weight;
+        if (itemSize > 3) {
+            r3 += _radiance[3] * weight;
+        }
+
+        weight_accum += weight;
+    }
+
+    const inv = weight_accum === 0 ? 0 : 1.0 / weight_accum;
+
+    result[result_offset] = r0 * inv;
+    result[result_offset + 1] = r1 * inv;
+    result[result_offset + 2] = r2 * inv;
+    if (itemSize > 3) {
+        result[result_offset + 3] = r3 * inv;
+    }
+}
+
+/**
+ * Convolve a whole equirectangular level into `output`.
+ *
+ * @param {Sampler2D} input source radiance (previous mip)
+ * @param {Sampler2D} output destination (this mip)
+ * @param {number} roughness convolution roughness for this step
+ * @param {number} sample_count
+ */
+export function convolve_equirectangular_reflection_level(input, output, roughness, sample_count) {
+    const width = output.width;
+    const height = output.height;
+
+    const direction = [0, 0, 0];
+    const texel = new Float32Array(output.itemSize);
+
+    for (let j = 0; j < height; j++) {
+        const v = (j + 0.5) / height;
+
+        for (let i = 0; i < width; i++) {
+            const u = (i + 0.5) / width;
+
+            equirectangular_uv_to_direction(u, v, direction, 0);
+
+            convolve_equirectangular_reflection_direction(
+                input,
+                direction[0], direction[1], direction[2],
+                roughness,
+                sample_count,
+                texel,
+                0
+            );
+
+            output.write(i, j, texel);
+        }
+    }
+}
+
+/**
+ * Build a prefiltered reflection mip chain from a base equirectangular radiance
+ * map. Mip 0 is the (sharp) base; each subsequent mip is half resolution and
+ * convolved from the previous one, so roughness increases with mip level. This
+ * is the CPU replacement for THREE's PMREMGenerator, decoupled from three.js.
+ *
+ * @param {Sampler2D} base equirectangular RGBA radiance (mip 0)
+ * @param {object} [options]
+ * @param {number} [options.sample_count=32] cone samples per texel (the sky is low frequency)
+ * @param {number} [options.mip_levels] number of levels; defaults to the full chain
+ * @param {number} [options.max_roughness=0.7] roughness reached at the last mip
+ * @returns {Sampler2D[]} mip chain, index 0 = base
+ */
+export function build_equirectangular_reflection_mip_chain(base, options = {}) {
+    const {
+        sample_count = 32,
+        mip_levels,
+        max_roughness = 0.7
+    } = options;
+
+    const full_levels = Math.floor(Math.log2(Math.max(1, Math.min(base.width, base.height)))) + 1;
+    const levels = mip_levels !== undefined ? Math.min(mip_levels, full_levels) : full_levels;
+
+    const mips = [base];
+
+    for (let i = 1; i < levels; i++) {
+        const previous = mips[i - 1];
+
+        const width = Math.max(1, previous.width >> 1);
+        const height = Math.max(1, previous.height >> 1);
+
+        const level = Sampler2D.float32(base.itemSize, width, height);
+
+        const prev_roughness = equirectangular_reflection_lod_to_roughness(i - 1, levels, max_roughness);
+        const curr_roughness = equirectangular_reflection_lod_to_roughness(i, levels, max_roughness);
+
+        const step_roughness = Math.max(
+            BSDF_ROUGHNESS_MINIMUM,
+            roughness_from_relative_mip(prev_roughness, curr_roughness)
+        );
+
+        convolve_equirectangular_reflection_level(previous, level, step_roughness, sample_count);
+
+        mips.push(level);
+    }
+
+    return mips;
+}

package/src/engine/graphics/texture/reflection/equirectangular_reflection_roughness.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Roughness schedule for a prefiltered reflection mip chain, ported from the
+ * EEVEE "sphere probe" convolution (generalised to an arbitrary mip count).
+ */
+/**
+ * Map a mip level to the perceptual roughness it represents.
+ *
+ * @param {number} lod mip level, 0 = sharpest
+ * @param {number} mip_levels total number of mip levels
+ * @param {number} [max_roughness=0.7] roughness reached at the last mip
+ * @returns {number}
+ */
+export function equirectangular_reflection_lod_to_roughness(lod: number, mip_levels: number, max_roughness?: number): number;
+/**
+ * Given that the previous mip is already convolved to `prev_mip_roughness`,
+ * derive the additional roughness to apply when convolving it into the current
+ * mip, so the result matches `curr_mip_roughness`. Uses the gaussian
+ * convolution composition rule G(a) x G(b) = G(a+b).
+ *
+ * @param {number} prev_mip_roughness
+ * @param {number} curr_mip_roughness
+ * @returns {number}
+ */
+export function roughness_from_relative_mip(prev_mip_roughness: number, curr_mip_roughness: number): number;
+//# sourceMappingURL=equirectangular_reflection_roughness.d.ts.map

package/src/engine/graphics/texture/reflection/equirectangular_reflection_roughness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equirectangular_reflection_roughness.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/reflection/equirectangular_reflection_roughness.js"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,iEALW,MAAM,cACN,MAAM,kBACN,MAAM,GACJ,MAAM,CAiBlB;AAED;;;;;;;;;GASG;AACH,gEAJW,MAAM,sBACN,MAAM,GACJ,MAAM,CAYlB"}

package/src/engine/graphics/texture/reflection/equirectangular_reflection_roughness.js

@@ -0,0 +1,51 @@
+/**
+ * Roughness schedule for a prefiltered reflection mip chain, ported from the
+ * EEVEE "sphere probe" convolution (generalised to an arbitrary mip count).
+ */
+
+/**
+ * Map a mip level to the perceptual roughness it represents.
+ *
+ * @param {number} lod mip level, 0 = sharpest
+ * @param {number} mip_levels total number of mip levels
+ * @param {number} [max_roughness=0.7] roughness reached at the last mip
+ * @returns {number}
+ */
+export function equirectangular_reflection_lod_to_roughness(lod, mip_levels, max_roughness = 0.7) {
+    const mip_ratio = mip_levels > 1 ? lod / (mip_levels - 1) : 0;
+
+    const a = mip_ratio;
+    const b = 0.6; // factor of ratio
+    const c = 0.4; // factor of ratio_sqrt
+
+    const b2 = b * b;
+    const c2 = c * c;
+    const c4 = c2 * c2;
+
+    // inverse of the roughness->lod mapping (a quadratic)
+    const ratio = (-Math.sqrt(4.0 * a * b * c2 + c4) + 2.0 * a * b + c2) / (2.0 * b2);
+
+    return ratio * max_roughness;
+}
+
+/**
+ * Given that the previous mip is already convolved to `prev_mip_roughness`,
+ * derive the additional roughness to apply when convolving it into the current
+ * mip, so the result matches `curr_mip_roughness`. Uses the gaussian
+ * convolution composition rule G(a) x G(b) = G(a+b).
+ *
+ * @param {number} prev_mip_roughness
+ * @param {number} curr_mip_roughness
+ * @returns {number}
+ */
+export function roughness_from_relative_mip(prev_mip_roughness, curr_mip_roughness) {
+    // the exponent should be 2 but 3 is a bit less blurry than expected in practice
+    const exponent = 3.0;
+
+    const m_prev = Math.pow(prev_mip_roughness, exponent);
+    const m_curr = Math.pow(curr_mip_roughness, exponent);
+
+    const m_target = Math.max(0.0, m_curr - m_prev);
+
+    return Math.pow(m_target, 1.0 / exponent);
+}

package/src/engine/graphics/texture/sampler/sampler2d_sample_equirectangular_direction.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Bilinearly sample a Sampler2D that holds an equirectangular image, by world
+ * direction (+Y up). The longitude axis (U) wraps and the latitude axis (V) is
+ * clamped, so there is no seam at longitude +/-pi (unlike Sampler2D's own
+ * bilinear sampling, which clamps both axes).
+ *
+ * @param {Sampler2D} sampler equirectangular source
+ * @param {number} dir_x
+ * @param {number} dir_y
+ * @param {number} dir_z
+ * @param {number[]|Float32Array} result
+ * @param {number} [result_offset=0]
+ */
+export function sampler2d_sample_equirectangular_direction(sampler: Sampler2D, dir_x: number, dir_y: number, dir_z: number, result: number[] | Float32Array, result_offset?: number): void;
+//# sourceMappingURL=sampler2d_sample_equirectangular_direction.d.ts.map

package/src/engine/graphics/texture/sampler/sampler2d_sample_equirectangular_direction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler2d_sample_equirectangular_direction.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/sampler/sampler2d_sample_equirectangular_direction.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,sFANW,MAAM,SACN,MAAM,SACN,MAAM,UACN,MAAM,EAAE,GAAC,YAAY,kBACrB,MAAM,QA+ChB"}

package/src/engine/graphics/texture/sampler/sampler2d_sample_equirectangular_direction.js

@@ -0,0 +1,63 @@
+import { equirectangular_direction_to_uv } from "../../../../core/geom/3d/equirectangular/equirectangular_direction_to_uv.js";
+
+const _uv = [0, 0];
+
+/**
+ * Bilinearly sample a Sampler2D that holds an equirectangular image, by world
+ * direction (+Y up). The longitude axis (U) wraps and the latitude axis (V) is
+ * clamped, so there is no seam at longitude +/-pi (unlike Sampler2D's own
+ * bilinear sampling, which clamps both axes).
+ *
+ * @param {Sampler2D} sampler equirectangular source
+ * @param {number} dir_x
+ * @param {number} dir_y
+ * @param {number} dir_z
+ * @param {number[]|Float32Array} result
+ * @param {number} [result_offset=0]
+ */
+export function sampler2d_sample_equirectangular_direction(sampler, dir_x, dir_y, dir_z, result, result_offset = 0) {
+    equirectangular_direction_to_uv(dir_x, dir_y, dir_z, _uv, 0);
+
+    const width = sampler.width;
+    const height = sampler.height;
+    const itemSize = sampler.itemSize;
+    const data = sampler.data;
+
+    // texel-space coordinates with texel centers at integer + 0.5
+    const fx = _uv[0] * width - 0.5;
+    const fy = _uv[1] * height - 0.5;
+
+    const x0i = Math.floor(fx);
+    const y0i = Math.floor(fy);
+
+    const tx = fx - x0i;
+    const ty = fy - y0i;
+
+    // longitude wraps, latitude clamps
+    const x0 = ((x0i % width) + width) % width;
+    const x1 = ((x0i + 1) % width + width) % width;
+    const y0 = y0i < 0 ? 0 : (y0i >= height ? height - 1 : y0i);
+    const y1i = y0i + 1;
+    const y1 = y1i < 0 ? 0 : (y1i >= height ? height - 1 : y1i);
+
+    const w00 = (1 - tx) * (1 - ty);
+    const w10 = tx * (1 - ty);
+    const w01 = (1 - tx) * ty;
+    const w11 = tx * ty;
+
+    const row0 = y0 * width;
+    const row1 = y1 * width;
+
+    const o00 = (row0 + x0) * itemSize;
+    const o10 = (row0 + x1) * itemSize;
+    const o01 = (row1 + x0) * itemSize;
+    const o11 = (row1 + x1) * itemSize;
+
+    for (let c = 0; c < itemSize; c++) {
+        result[result_offset + c] =
+            data[o00 + c] * w00 +
+            data[o10 + c] * w10 +
+            data[o01 + c] * w01 +
+            data[o11 + c] * w11;
+    }
+}