@woosh/meep-engine 3.67.0 → 3.69.0

package/src/shade/renderer/animation/animation_curve_write_keys.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Write a curve's keys into `out` at float index `at`, laid out as `ANIMATION_CURVE_KEYFRAME_STRUCT`, the
+ * form `chunk_animation_curve_evaluate_keys` reads them in.
+ *
+ * @param {Float32Array} out
+ * @param {number} at float index
+ * @param {import("../../../engine/animation/curve/AnimationCurve.js").AnimationCurve} curve
+ * @returns {number} the float index after the curve's keys
+ */
+export function animation_curve_write_keys(out: Float32Array, at: number, curve: import("../../../engine/animation/curve/AnimationCurve.js").AnimationCurve): number;
+/**
+ * Floats of one keyframe in an `ANIMATION_CURVE_KEYFRAME_STRUCT` array: time, value, in tangent, out
+ * tangent.
+ *
+ * @type {number}
+ */
+export const ANIMATION_CURVE_KEYFRAME_FLOATS: number;
+//# sourceMappingURL=animation_curve_write_keys.d.ts.map

package/src/shade/renderer/animation/animation_curve_write_keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation_curve_write_keys.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/animation_curve_write_keys.js"],"names":[],"mappings":"AAQA;;;;;;;;GAQG;AACH,gDALW,YAAY,MACZ,MAAM,SACN,OAAO,mDAAmD,EAAE,cAAc,GACxE,MAAM,CAkBlB;AAjCD;;;;;GAKG;AACH,8CAFU,MAAM,CAEiC"}

package/src/shade/renderer/animation/animation_curve_write_keys.js

@@ -0,0 +1,34 @@
+/**
+ * Floats of one keyframe in an `ANIMATION_CURVE_KEYFRAME_STRUCT` array: time, value, in tangent, out
+ * tangent.
+ *
+ * @type {number}
+ */
+export const ANIMATION_CURVE_KEYFRAME_FLOATS = 4;
+
+/**
+ * Write a curve's keys into `out` at float index `at`, laid out as `ANIMATION_CURVE_KEYFRAME_STRUCT`, the
+ * form `chunk_animation_curve_evaluate_keys` reads them in.
+ *
+ * @param {Float32Array} out
+ * @param {number} at float index
+ * @param {import("../../../engine/animation/curve/AnimationCurve.js").AnimationCurve} curve
+ * @returns {number} the float index after the curve's keys
+ */
+export function animation_curve_write_keys(out, at, curve) {
+    const keys = curve.keys;
+    const count = keys.length;
+
+    for (let i = 0; i < count; i++) {
+        const key = keys[i];
+
+        out[at] = key.time;
+        out[at + 1] = key.value;
+        out[at + 2] = key.inTangent;
+        out[at + 3] = key.outTangent;
+
+        at += ANIMATION_CURVE_KEYFRAME_FLOATS;
+    }
+
+    return at;
+}

package/src/shade/renderer/atmosphere/ATMOSPHERE_PARAMETERS_STRUCT.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Packed GPU uniform representation of {@link SceneAtmosphere} in GPU atmosphere units
+ * ($\text{km}$ and $\text{km}^{-1}$, scaled via `ATMOSPHERE_UNIT_METERS`).
+ *
+ * @see "A Scalable and Production Ready Sky and Atmosphere Rendering Technique", Hillaire (2020)
+ * @type {WebGPUStruct}
+ */
+export const ATMOSPHERE_PARAMETERS_STRUCT: WebGPUStruct;
+/**
+ * Deeply frozen default Earth uniform payload matching {@link ATMOSPHERE_PARAMETERS_STRUCT}.
+ */
+export const ATMOSPHERE_EARTH_UNIFORM: Readonly<Record<string, any>>;
+/**
+ * Parameterised Hillaire (2020) atmosphere medium, geometry, and LUT coordinate helpers operating
+ * on {@link ATMOSPHERE_PARAMETERS_STRUCT}.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_atmosphere_parameters: CodeChunk;
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=ATMOSPHERE_PARAMETERS_STRUCT.d.ts.map

package/src/shade/renderer/atmosphere/ATMOSPHERE_PARAMETERS_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ATMOSPHERE_PARAMETERS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/ATMOSPHERE_PARAMETERS_STRUCT.js"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,2CAFU,YAAY,CAmBK;AAE3B;;GAEG;AACH,qEAQK;AAEL;;;;;GAKG;AACH,0CAFU,SAAS,CA4GjB;6BA5J2B,gCAAgC;0BAFnC,iCAAiC"}

package/src/shade/renderer/atmosphere/ATMOSPHERE_PARAMETERS_STRUCT.js

@@ -0,0 +1,160 @@
+import { chunk_atmosphere_ray_bounds } from "../shader/chunk/atmosphere/chunk_atmosphere_ray_bounds.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { f32, vec3f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+import { ATMOSPHERE_ALTITUDE_CUTOFF } from "./ATMOSPHERE_ALTITUDE_CUTOFF.js";
+import { ATMOSPHERE_UNIT_SCALE_DECLARATION } from "./ATMOSPHERE_UNIT_SCALE.js";
+import { SceneAtmosphere } from "./SceneAtmosphere.js";
+
+/**
+ * Packed GPU uniform representation of {@link SceneAtmosphere} in GPU atmosphere units
+ * ($\text{km}$ and $\text{km}^{-1}$, scaled via `ATMOSPHERE_UNIT_METERS`).
+ *
+ * @see "A Scalable and Production Ready Sky and Atmosphere Rendering Technique", Hillaire (2020)
+ * @type {WebGPUStruct}
+ */
+export const ATMOSPHERE_PARAMETERS_STRUCT = WebGPUStruct.from({
+    planet_radius: f32,
+    atmosphere_height: f32,
+    rayleigh_scale_height: f32,
+    mie_scale_height: f32,
+
+    rayleigh_scattering: vec3f,
+    mie_phase_g: f32,
+
+    mie_scattering: vec3f,
+    ozone_center_height: f32,
+
+    mie_absorption: vec3f,
+    ozone_half_width: f32,
+
+    ozone_absorption: vec3f,
+    ground_albedo: vec3f,
+}, "AtmosphereParameters");
+
+/**
+ * Deeply frozen default Earth uniform payload matching {@link ATMOSPHERE_PARAMETERS_STRUCT}.
+ */
+export const ATMOSPHERE_EARTH_UNIFORM = (() => {
+    const raw = new SceneAtmosphere().write_uniform();
+    raw.rayleigh_scattering = Object.freeze([...raw.rayleigh_scattering]);
+    raw.mie_scattering = Object.freeze([...raw.mie_scattering]);
+    raw.mie_absorption = Object.freeze([...raw.mie_absorption]);
+    raw.ozone_absorption = Object.freeze([...raw.ozone_absorption]);
+    raw.ground_albedo = Object.freeze([...raw.ground_albedo]);
+    return Object.freeze(raw);
+})();
+
+/**
+ * Parameterised Hillaire (2020) atmosphere medium, geometry, and LUT coordinate helpers operating
+ * on {@link ATMOSPHERE_PARAMETERS_STRUCT}.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_atmosphere_parameters = CodeChunk.from(
+    //language=WGSL
+    `
+fn atmosphere_earth_parameters() -> ${ATMOSPHERE_PARAMETERS_STRUCT.wgsl_ref} {
+    var atm: ${ATMOSPHERE_PARAMETERS_STRUCT.wgsl_ref};
+    atm.planet_radius = 6378000.0 * METERS_TO_ATMOSPHERE_UNITS;
+    atm.atmosphere_height = 100000.0 * METERS_TO_ATMOSPHERE_UNITS;
+    atm.rayleigh_scale_height = 8000.0 * METERS_TO_ATMOSPHERE_UNITS;
+    atm.mie_scale_height = 1200.0 * METERS_TO_ATMOSPHERE_UNITS;
+    atm.rayleigh_scattering = vec3<f32>(5.802e-6, 13.558e-6, 33.100e-6) * INVERSE_METERS_TO_ATMOSPHERE_UNITS;
+    atm.mie_phase_g = 0.8;
+    atm.mie_scattering = vec3<f32>(3.996e-6, 3.996e-6, 3.996e-6) * INVERSE_METERS_TO_ATMOSPHERE_UNITS;
+    atm.ozone_center_height = 25000.0 * METERS_TO_ATMOSPHERE_UNITS;
+    atm.mie_absorption = vec3<f32>(0.444e-6, 0.444e-6, 0.444e-6) * INVERSE_METERS_TO_ATMOSPHERE_UNITS;
+    atm.ozone_half_width = 15000.0 * METERS_TO_ATMOSPHERE_UNITS;
+    atm.ozone_absorption = vec3<f32>(0.650e-6, 1.881e-6, 0.085e-6) * INVERSE_METERS_TO_ATMOSPHERE_UNITS;
+    atm.ground_albedo = vec3<f32>(0.3, 0.3, 0.3);
+    return atm;
+}
+
+fn atmosphere_planet_center_for(atm: ${ATMOSPHERE_PARAMETERS_STRUCT.wgsl_ref}) -> vec3<f32> {
+    return vec3<f32>(0.0, -atm.planet_radius, 0.0);
+}
+
+// Converts a world-space position (in metres) into planet-centre-relative GPU atmosphere units (km).
+fn atmosphere_position_relative_for(atm: ${ATMOSPHERE_PARAMETERS_STRUCT.wgsl_ref}, pos_ws: vec3<f32>) -> vec3<f32> {
+    return pos_ws * METERS_TO_ATMOSPHERE_UNITS - atmosphere_planet_center_for(atm);
+}
+
+// Planet-centre-relative observer position (in km) clamped away from the ground and top-of-atmosphere boundaries.
+fn atmosphere_clamped_observer_relative(
+    atm: ${ATMOSPHERE_PARAMETERS_STRUCT.wgsl_ref},
+    world_pos: vec3<f32>
+) -> vec3<f32> {
+    let rel = atmosphere_position_relative_for(atm, world_pos);
+    let r_raw = length(rel);
+    let up = select(vec3<f32>(0.0, 1.0, 0.0), rel / r_raw, r_raw > 0.0);
+    let cutoff = ${ATMOSPHERE_ALTITUDE_CUTOFF.toFixed(1)} * METERS_TO_ATMOSPHERE_UNITS;
+    let min_r = atm.planet_radius + cutoff;
+    let max_r = max(min_r, atm.planet_radius + atm.atmosphere_height - cutoff);
+    return up * clamp(r_raw, min_r, max_r);
+}
+
+fn atmosphere_density_for(atm: ${ATMOSPHERE_PARAMETERS_STRUCT.wgsl_ref}, h: f32) -> vec3<f32> {
+    let clamped_h = max(h, 0.0);
+    let rayleigh = exp(-clamped_h / max(atm.rayleigh_scale_height, MIN_ATMOSPHERE_LENGTH_UNITS));
+    let mie = exp(-clamped_h / max(atm.mie_scale_height, MIN_ATMOSPHERE_LENGTH_UNITS));
+    let ozone = max(0.0, 1.0 - abs(h - atm.ozone_center_height) / max(atm.ozone_half_width, MIN_ATMOSPHERE_LENGTH_UNITS));
+    return vec3<f32>(rayleigh, mie, ozone);
+}
+
+fn atmosphere_extinction_for(atm: ${ATMOSPHERE_PARAMETERS_STRUCT.wgsl_ref}, density: vec3<f32>) -> vec3<f32> {
+    let rayleigh = density.x * atm.rayleigh_scattering;
+    let mie = density.y * (atm.mie_scattering + atm.mie_absorption);
+    let ozone = density.z * atm.ozone_absorption;
+    return rayleigh + mie + ozone;
+}
+
+fn atmosphere_ray_bounds_for(
+    atm: ${ATMOSPHERE_PARAMETERS_STRUCT.wgsl_ref},
+    origin_rel: vec3<f32>,
+    ray_direction: vec3<f32>
+) -> AtmosphereRayBounds {
+    let b = dot(origin_rel, ray_direction);
+    let r = length(origin_rel);
+    let b2 = b * b;
+
+    let ground_r = atm.planet_radius;
+    let top_r = atm.planet_radius + atm.atmosphere_height;
+
+    // Difference-of-squares factoring (r - R)(r + R) avoids catastrophic f32 cancellation when
+    // altitude (r - ground_r) is metres above a 6,378 km planet radius.
+    let atmosphere_distance = -b + sqrt(max(b2 - (r - top_r) * (r + top_r), 0.0));
+
+    let ground_discriminant = b2 - (r - ground_r) * (r + ground_r);
+    let hits_ground = (b < 0.0) && (ground_discriminant >= 0.0);
+    let ground_distance = select(
+        -1.0,
+        max(-b - sqrt(max(ground_discriminant, 0.0)), 0.0),
+        hits_ground
+    );
+
+    var result: AtmosphereRayBounds;
+    result.t_max = select(atmosphere_distance, ground_distance, hits_ground);
+    result.ground_distance = ground_distance;
+    result.hits_ground = hits_ground;
+    return result;
+}
+
+fn sky_lut_uv_for(
+    atm: ${ATMOSPHERE_PARAMETERS_STRUCT.wgsl_ref},
+    height: f32,
+    sun_cos_zenith_angle: f32,
+    resolution: vec2<f32>
+) -> vec2<f32> {
+    let unit = vec2<f32>(
+        saturate(0.5 + 0.5 * sun_cos_zenith_angle),
+        saturate(height / max(atm.atmosphere_height, MIN_ATMOSPHERE_LENGTH_UNITS))
+    );
+    return (unit * (resolution - 1.0) + 0.5) / resolution;
+}
+    `, [
+        ATMOSPHERE_UNIT_SCALE_DECLARATION,
+        ATMOSPHERE_PARAMETERS_STRUCT.declaration_chunk,
+        chunk_atmosphere_ray_bounds,
+    ]
+);

package/src/shade/renderer/atmosphere/ATMOSPHERE_UNIT_SCALE.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Length of one GPU-side atmosphere spatial unit in world-space metres ($1\text{ km} = 10^3\text{ m}$),
+ * matching Hillaire (2020). Keeping GPU atmosphere geometry and extinction in kilometres and
+ * $\text{km}^{-1}$ keeps planetary squares inside 32-bit integer range, radii and sea-level
+ * scattering coefficients inside normal `f16`, and upper-atmosphere extinction three orders of
+ * magnitude further above division-by-zero epsilon floors while `SceneAtmosphere` remains authored
+ * in world-space metres and $\text{m}^{-1}$ on the CPU.
+ *
+ * @see "A Scalable and Production Ready Sky and Atmosphere Rendering Technique", Hillaire (2020)
+ * @type {number}
+ */
+export const ATMOSPHERE_UNIT_METERS: number;
+/**
+ * Multiplicative factor converting world-space lengths and positions ($\text{m}$) into GPU
+ * atmosphere units ($\text{km}$): `x_atm = x_meters * METERS_TO_ATMOSPHERE_UNITS`.
+ *
+ * @type {number}
+ */
+export const METERS_TO_ATMOSPHERE_UNITS: number;
+/**
+ * Multiplicative factor converting world-space scattering/extinction/absorption coefficients
+ * ($\text{m}^{-1}$) into inverse GPU atmosphere units ($\text{km}^{-1}$):
+ * `sigma_atm = sigma_per_meter * INVERSE_METERS_TO_ATMOSPHERE_UNITS`, preserving dimensionless
+ * optical depth $\sigma_{\text{atm}} \cdot d_{\text{atm}} = \sigma_m \cdot d_m$.
+ *
+ * @type {number}
+ */
+export const INVERSE_METERS_TO_ATMOSPHERE_UNITS: number;
+/**
+ * Positive lower bound (`1 mm` expressed in GPU atmosphere units) applied to radii and scale
+ * heights so zero or negative inputs cannot divide by zero.
+ *
+ * @type {number}
+ */
+export const MIN_ATMOSPHERE_LENGTH_UNITS: number;
+/**
+ * WGSL compile-time constants mirroring {@link ATMOSPHERE_UNIT_METERS},
+ * {@link METERS_TO_ATMOSPHERE_UNITS}, {@link INVERSE_METERS_TO_ATMOSPHERE_UNITS}, and
+ * {@link MIN_ATMOSPHERE_LENGTH_UNITS}.
+ *
+ * @type {CodeChunk}
+ */
+export const ATMOSPHERE_UNIT_SCALE_DECLARATION: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=ATMOSPHERE_UNIT_SCALE.d.ts.map

package/src/shade/renderer/atmosphere/ATMOSPHERE_UNIT_SCALE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ATMOSPHERE_UNIT_SCALE.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/ATMOSPHERE_UNIT_SCALE.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,qCAFU,MAAM,CAE4B;AAE5C;;;;;GAKG;AACH,yCAFU,MAAM,CAEqD;AAErE;;;;;;;GAOG;AACH,iDAFU,MAAM,CAEyD;AAEzE;;;;;GAKG;AACH,0CAFU,MAAM,CAE6D;AAE7E;;;;;;GAMG;AACH,gDAFU,SAAS,CAUjB;0BAxDwB,iCAAiC"}

package/src/shade/renderer/atmosphere/ATMOSPHERE_UNIT_SCALE.js

@@ -0,0 +1,57 @@
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+
+/**
+ * Length of one GPU-side atmosphere spatial unit in world-space metres ($1\text{ km} = 10^3\text{ m}$),
+ * matching Hillaire (2020). Keeping GPU atmosphere geometry and extinction in kilometres and
+ * $\text{km}^{-1}$ keeps planetary squares inside 32-bit integer range, radii and sea-level
+ * scattering coefficients inside normal `f16`, and upper-atmosphere extinction three orders of
+ * magnitude further above division-by-zero epsilon floors while `SceneAtmosphere` remains authored
+ * in world-space metres and $\text{m}^{-1}$ on the CPU.
+ *
+ * @see "A Scalable and Production Ready Sky and Atmosphere Rendering Technique", Hillaire (2020)
+ * @type {number}
+ */
+export const ATMOSPHERE_UNIT_METERS = 1_000;
+
+/**
+ * Multiplicative factor converting world-space lengths and positions ($\text{m}$) into GPU
+ * atmosphere units ($\text{km}$): `x_atm = x_meters * METERS_TO_ATMOSPHERE_UNITS`.
+ *
+ * @type {number}
+ */
+export const METERS_TO_ATMOSPHERE_UNITS = 1 / ATMOSPHERE_UNIT_METERS;
+
+/**
+ * Multiplicative factor converting world-space scattering/extinction/absorption coefficients
+ * ($\text{m}^{-1}$) into inverse GPU atmosphere units ($\text{km}^{-1}$):
+ * `sigma_atm = sigma_per_meter * INVERSE_METERS_TO_ATMOSPHERE_UNITS`, preserving dimensionless
+ * optical depth $\sigma_{\text{atm}} \cdot d_{\text{atm}} = \sigma_m \cdot d_m$.
+ *
+ * @type {number}
+ */
+export const INVERSE_METERS_TO_ATMOSPHERE_UNITS = ATMOSPHERE_UNIT_METERS;
+
+/**
+ * Positive lower bound (`1 mm` expressed in GPU atmosphere units) applied to radii and scale
+ * heights so zero or negative inputs cannot divide by zero.
+ *
+ * @type {number}
+ */
+export const MIN_ATMOSPHERE_LENGTH_UNITS = 1e-3 * METERS_TO_ATMOSPHERE_UNITS;
+
+/**
+ * WGSL compile-time constants mirroring {@link ATMOSPHERE_UNIT_METERS},
+ * {@link METERS_TO_ATMOSPHERE_UNITS}, {@link INVERSE_METERS_TO_ATMOSPHERE_UNITS}, and
+ * {@link MIN_ATMOSPHERE_LENGTH_UNITS}.
+ *
+ * @type {CodeChunk}
+ */
+export const ATMOSPHERE_UNIT_SCALE_DECLARATION = CodeChunk.from(
+    //language=WGSL
+    `
+const ATMOSPHERE_UNIT_METERS: f32 = ${ATMOSPHERE_UNIT_METERS.toFixed(1)};
+const METERS_TO_ATMOSPHERE_UNITS: f32 = 1.0 / ATMOSPHERE_UNIT_METERS;
+const INVERSE_METERS_TO_ATMOSPHERE_UNITS: f32 = ATMOSPHERE_UNIT_METERS;
+const MIN_ATMOSPHERE_LENGTH_UNITS: f32 = 1e-3 * METERS_TO_ATMOSPHERE_UNITS;
+    `
+);

package/src/shade/renderer/atmosphere/GPUSky.d.ts

@@ -1,26 +1,37 @@
 /**
+ * @typedef {import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  * @typedef {import("../GraphicsContext.js").GraphicsContext} GraphicsContext
  */
 export class GPUSky {
     /**
-     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry: PipelineEnquiry): void;
+    /**
      * @param {GraphicsContext} graphics
+     * @param {SceneAtmosphere} [atmosphere]
      */
-    constructor(graphics: GraphicsContext);
+    constructor(graphics: GraphicsContext, atmosphere?: SceneAtmosphere);
     /**
-     *
      * @returns {GPUTextureContext}
      */
     get lut_transmittance(): GPUTextureContext;
     /**
-     *
      * @returns {GPUTextureContext}
      */
     get lut_multiple_scattering(): GPUTextureContext;
     /**
-     * Whether the LUTs still hold nothing a reader could use: true until the first {@link update}.
-     * What reads {@link lut_transmittance} or {@link lut_multiple_scattering} has to see this false,
-     * as a texture nobody wrote reads as zero rather than failing.
+     * @returns {SceneAtmosphere}
+     */
+    get atmosphere(): SceneAtmosphere;
+    /**
+     * GPU uniform buffer holding {@link ATMOSPHERE_PARAMETERS_STRUCT}.
+     * @returns {GPUTypedBuffer}
+     */
+    get parameters_buffer(): GPUTypedBuffer;
+    /**
+     * Whether the LUTs have not yet been built or {@link SceneAtmosphere#version} has advanced
+     * since the last {@link update}.
      *
      * @returns {boolean}
      */
@@ -28,11 +39,15 @@ export class GPUSky {
     destroy(): void;
     debug(): void;
     /**
-     *
+     * Uploads any changed {@link SceneAtmosphere} parameters and rebuilds the transmittance and
+     * multiple-scattering LUTs when {@link needs_update} is true; a no-op on steady frames.
      */
     update(): void;
     #private;
 }
+export type PipelineEnquiry = import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
 export type GraphicsContext = import("../GraphicsContext.js").GraphicsContext;
 import { GPUTextureContext } from "../texture/GPUTextureContext.js";
+import { SceneAtmosphere } from "./SceneAtmosphere.js";
+import { GPUTypedBuffer } from "../buffer/GPUTypedBuffer.js";
 //# sourceMappingURL=GPUSky.d.ts.map

package/src/shade/renderer/atmosphere/GPUSky.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSky.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/GPUSky.js"],"names":[],"mappings":"AAUA;;GAEG;AAEH;IAkDI;;;OAGG;IACH,sBAFW,eAAe,EAqBzB;IA7DD;;;OAGG;IACH,2CAEC;IAOD;;;OAGG;IACH,iDAEC;IAQD;;;;;;OAMG;IACH,4BAEC;IA2BD,gBAGC;IAED,cAYC;IAED;;OAEG;IACH,eAiDC;;CAEJ;8BAvJY,OAAO,uBAAuB,EAAE,eAAe;kCAL1B,iCAAiC"}
+{"version":3,"file":"GPUSky.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/atmosphere/GPUSky.js"],"names":[],"mappings":"AAcA;;;GAGG;AAEH;IAEI;;OAEG;IACH,iCAFW,eAAe,QAKzB;IA+ED;;;OAGG;IACH,sBAHW,eAAe,eACf,eAAe,EAgCzB;IA9ED;;OAEG;IACH,2CAEC;IAOD;;OAEG;IACH,iDAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;OAGG;IACH,wCAEC;IAED;;;;;OAKG;IACH,4BAEC;IAsCD,gBAIC;IAED,cAOC;IAED;;;OAGG;IACH,eAwDC;;CAEJ;8BA5MY,OAAO,0CAA0C,EAAE,eAAe;8BAClE,OAAO,uBAAuB,EAAE,eAAe;kCAR1B,iCAAiC;gCAEnC,sBAAsB;+BANvB,6BAA6B"}

package/src/shade/renderer/atmosphere/GPUSky.js

@@ -1,31 +1,66 @@
+import { assert } from "../../../core/assert.js";
 import { FrameGraph } from "../../../engine/graphics/render/frame_graph/FrameGraph.js";
 import { TextureResourceDescriptor } from "../../device/graph/TextureResourceDescriptor.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { GPUTypedBuffer } from "../buffer/GPUTypedBuffer.js";
 import { graph_compute_pass } from "../shader/graph/compute/graph_compute_pass.js";
 import { graph_image_pass } from "../shader/graph/graph_image_pass.js";
 import { debug_draw_texture } from "../texture/debug_draw_texture.js";
 import { GPUTextureContext } from "../texture/GPUTextureContext.js";
+import { ATMOSPHERE_PARAMETERS_STRUCT } from "./ATMOSPHERE_PARAMETERS_STRUCT.js";
+import { SceneAtmosphere } from "./SceneAtmosphere.js";
 import { shader_multiscatter_lut } from "./shader_multiscatter_lut.js";
 import { shader_transmittance_lut } from "./shader_transmittance_lut.js";
 
 /**
+ * @typedef {import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  * @typedef {import("../GraphicsContext.js").GraphicsContext} GraphicsContext
  */
 
 export class GPUSky {
 
+    /**
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry) {
+        enquiry.render.push(shader_transmittance_lut.pipeline);
+        enquiry.compute.push(shader_multiscatter_lut.pipeline);
+    }
+
     /**
      * @type {GraphicsContext}
      */
     #graphics;
 
+    /**
+     * @type {SceneAtmosphere}
+     */
+    #atmosphere;
+
+    /**
+     * @type {GPUTypedBuffer}
+     */
+    #parameters_buffer;
+
+    /**
+     * Reusable POJO target for {@link SceneAtmosphere#write_uniform}.
+     * @type {Record<string, any>}
+     */
+    #uniform_scratch = {};
+
+    /**
+     * Last {@link SceneAtmosphere#version} committed into the LUTs and uniform buffer, or `-1`
+     * before the first {@link update}.
+     * @type {number}
+     */
+    #committed_version = -1;
+
     /**
      * @type {GPUTextureContext}
      */
     #lut_transmittance;
 
     /**
-     *
      * @returns {GPUTextureContext}
      */
     get lut_transmittance() {
@@ -38,7 +73,6 @@ export class GPUSky {
     #lut_multiple_scattering;
 
     /**
-     *
      * @returns {GPUTextureContext}
      */
     get lut_multiple_scattering() {
@@ -46,31 +80,52 @@ export class GPUSky {
     }
 
     /**
-     *
-     * @type {boolean}
+     * @returns {SceneAtmosphere}
+     */
+    get atmosphere() {
+        return this.#atmosphere;
+    }
+
+    /**
+     * GPU uniform buffer holding {@link ATMOSPHERE_PARAMETERS_STRUCT}.
+     * @returns {GPUTypedBuffer}
      */
-    #needs_update = true;
+    get parameters_buffer() {
+        return this.#parameters_buffer;
+    }
 
     /**
-     * Whether the LUTs still hold nothing a reader could use: true until the first {@link update}.
-     * What reads {@link lut_transmittance} or {@link lut_multiple_scattering} has to see this false,
-     * as a texture nobody wrote reads as zero rather than failing.
+     * Whether the LUTs have not yet been built or {@link SceneAtmosphere#version} has advanced
+     * since the last {@link update}.
      *
      * @returns {boolean}
      */
     get needs_update() {
-        return this.#needs_update;
+        return this.#committed_version !== this.#atmosphere.version;
     }
 
     /**
-     *
      * @param {GraphicsContext} graphics
+     * @param {SceneAtmosphere} [atmosphere]
      */
-    constructor(graphics) {
+    constructor(graphics, atmosphere = new SceneAtmosphere()) {
+        assert.defined(graphics, "graphics");
+        assert.defined(atmosphere, "atmosphere");
+        assert.equal(atmosphere.isSceneAtmosphere, true, "atmosphere.isSceneAtmosphere !== true");
+
         this.#graphics = graphics;
+        this.#atmosphere = atmosphere;
 
         const device = graphics.device;
 
+        this.#parameters_buffer = GPUTypedBuffer.create({
+            label: "Sky / Atmosphere Parameters",
+            device,
+            type: ATMOSPHERE_PARAMETERS_STRUCT,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            initial_value: atmosphere.write_uniform(this.#uniform_scratch),
+        });
+
         this.#lut_transmittance = new GPUTextureContext(device);
         this.#lut_transmittance.descriptor.label = "Sky / Transmittance LUT";
         this.#lut_transmittance.descriptor.format = "rgba16float";
@@ -83,37 +138,37 @@ export class GPUSky {
         // written by a compute shader, so STORAGE_BINDING rather than RENDER_ATTACHMENT
         this.#lut_multiple_scattering.descriptor.usage = GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC;
         this.#lut_multiple_scattering.resize(32, 32);
-
-
     }
 
     destroy() {
+        this.#parameters_buffer.destroy();
         this.#lut_transmittance.destroy();
         this.#lut_multiple_scattering.destroy();
     }
 
     debug() {
-
-
         let y = 50;
-        debug_draw_texture({ texture: this.#lut_transmittance, x: 50, y: y });
+        debug_draw_texture({ texture: this.#lut_transmittance, x: 50, y });
 
         y += this.#lut_transmittance.size[1] + 50;
 
-        debug_draw_texture({ texture: this.#lut_multiple_scattering, x: 50, y: y });
-
-        y += this.#lut_multiple_scattering.size[1] + 50;
-
+        debug_draw_texture({ texture: this.#lut_multiple_scattering, x: 50, y });
     }
 
     /**
-     *
+     * Uploads any changed {@link SceneAtmosphere} parameters and rebuilds the transmittance and
+     * multiple-scattering LUTs when {@link needs_update} is true; a no-op on steady frames.
      */
     update() {
-        if (!this.#needs_update) {
+        if (!this.needs_update) {
             return;
         }
 
+        this.#parameters_buffer.upload(
+            this.#atmosphere.write_uniform(this.#uniform_scratch),
+            this.#graphics.device.queue
+        );
+
         const graph = new FrameGraph("sky update");
 
         const command_ctx = ShadeGPUCommandContext.create(
@@ -121,43 +176,45 @@ export class GPUSky {
             "Renderer/main"
         );
 
-        const gr_transmittance = graph.import_resource("transmittance", TextureResourceDescriptor.fromTexture(this.#lut_transmittance.gpu_texture), this.#lut_transmittance);
-        const gr_multiscatter = graph.import_resource("multiscatter", TextureResourceDescriptor.fromTexture(this.#lut_multiple_scattering.gpu_texture), this.#lut_multiple_scattering);
+        const gr_transmittance = graph.import_resource(
+            "transmittance",
+            TextureResourceDescriptor.fromTexture(this.#lut_transmittance.gpu_texture),
+            this.#lut_transmittance
+        );
+        const gr_multiscatter = graph.import_resource(
+            "multiscatter",
+            TextureResourceDescriptor.fromTexture(this.#lut_multiple_scattering.gpu_texture),
+            this.#lut_multiple_scattering
+        );
 
-        // the handle the write produced, not the one imported: binding the pre-write version below
-        // is a superseded read, which is exactly what `validate()` rejects
         const [gr_transmittance_written] = graph_image_pass({
             graph,
             shader: shader_transmittance_lut,
             inputs: {
+                atmosphere: this.#parameters_buffer.buffer,
                 settings: {
                     steps: 40,
-                    // read off the texture rather than restated, so the two cannot disagree
                     resolution: [this.#lut_transmittance.width, this.#lut_transmittance.height],
                 }
             },
             output: [gr_transmittance]
         });
 
-
         graph_compute_pass({
             graph,
             shader: shader_multiscatter_lut,
-            // one workgroup per LUT texel, counted off the texture being written so the
-            // dispatch cannot cover a different area than the shader stores into
             group_count: [this.#lut_multiple_scattering.width, this.#lut_multiple_scattering.height, 1],
             bindings: {
+                atmosphere: this.#parameters_buffer.buffer,
                 tSkyLutTransmittance: gr_transmittance_written,
                 tSkyLutMultiscatterOut: gr_multiscatter
             }
         });
 
         command_ctx.encodeGraph(graph);
-
         command_ctx.finish();
 
-
-        this.#needs_update = false;
+        this.#committed_version = this.#atmosphere.version;
     }
 
-}
+}