@woosh/meep-engine 3.38.0 → 3.40.0

package/src/shade/renderer/material/resident/GPUResidentMaterialContext.js

@@ -5,13 +5,15 @@ import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
 import { round_up } from "../../../../core/math/round_up.js";
 import { TextureViewDescriptor } from "../../../descriptor/texture/TextureViewDescriptor.js";
 import { ShadeGPUCommandContext } from "../../../device/ShadeGPUCommandContext.js";
+import { GPU_DATABASE_NULL } from "../../buffer/table/GPU_DATABASE_NULL.js";
+import { MEDIA_TABLE_CAPACITY, MEDIA_TABLE_STRUCT } from "../../medium/MEDIA_TABLE_STRUCT.js";
+import { MEDIUM_STRUCT } from "../../medium/MEDIUM_STRUCT.js";
 import { write_gpu_typed_buffer } from "../../shader/type/serde/write_gpu_typed_buffer.js";
 import { ColorSpace } from "../../texture/ColorSpace.js";
 import { PIXEL_TEXTURE_ORM } from "../PIXEL_TEXTURE_ORM.js";
 import { render_copy_texture } from "../../postprocess/gtao/render_copy_texture.js";
 import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
 import { sampler_descriptor_pack } from "../../texture/format/sampler_descriptor_pack.js";
-import { PIXEL_TEXTURE_NORMAL } from "../../texture/util/PIXEL_TEXTURE_NORMAL.js";
 import { WHITE_PIXEL_TEXTURE } from "../../texture/util/WHITE_PIXEL_TEXTURE.js";
 import { INDIRECT_MATERIAL_ARRAY_TYPE } from "./INDIRECT_MATERIAL_ARRAY_TYPE.js";
 import { INDIRECT_MATERIAL_STRUCT } from "./INDIRECT_MATERIAL_STRUCT.js";
@@ -22,11 +24,18 @@ import { INDIRECT_MATERIAL_STRUCT } from "./INDIRECT_MATERIAL_STRUCT.js";
  * @typedef {import("../../texture/ShadeTexture.js").ShadeTexture} ShadeTexture
  * @typedef {import("../ShadeMaterial.js").ShadeMaterial} ShadeMaterial
  * @typedef {import("../StandardShadeMaterial.js").StandardShadeMaterial} StandardShadeMaterial
+ * @typedef {import("../../medium/ParticipatingMedium.js").ParticipatingMedium} ParticipatingMedium
  */
 
 class MaterialInfo {
     id = 0
 
+    /**
+     * The {@link ShadeMaterial#version} the row was packed at; -1 before the first pack.
+     * @type {number}
+     */
+    version = -1
+
     /**
      * @type {StandardShadeMaterial}
      */
@@ -43,13 +52,40 @@ class MaterialInfo {
     texture_orm
 
     /**
-     * @type {TextureInfo}
+     * The material's normal map, or null for none — see {@link INDIRECT_MATERIAL_STRUCT}'s
+     * `texture_normal`.
+     * @type {TextureInfo|null}
      */
     texture_normal
     /**
      * @type {TextureInfo}
      */
     texture_emissive
+
+    /**
+     * Slot of the material's medium in the media table, or GPU_DATABASE_NULL for none.
+     * @type {number}
+     */
+    medium_slot = GPU_DATABASE_NULL
+}
+
+class MediumInfo {
+    /**
+     * Row of the media table this medium is written at.
+     * @type {number}
+     */
+    slot = 0
+
+    /**
+     * The {@link ParticipatingMedium#version} the row was written at; -1 until it first is.
+     * @type {number}
+     */
+    version = -1
+
+    /**
+     * @type {ParticipatingMedium}
+     */
+    source;
 }
 
 class TextureInfo {
@@ -61,6 +97,12 @@ class TextureInfo {
     source;
 }
 
+/**
+ * Byte offset of the media table's first record, after its count.
+ * @type {number}
+ */
+const MEDIA_TABLE_RECORDS_OFFSET = MEDIA_TABLE_STRUCT.fields.find(f => f.name === 'records').offset;
+
 /**
  * What a material that is not standard contributes to the ray passes: white, opaque, fully rough,
  * not metallic, not transmissive, not emissive — through the default textures its missing slots
@@ -161,10 +203,14 @@ export class GPUResidentMaterialContext {
     }
 
     /**
+     * One entry per material object, never one per equal value: a mesh row names its own
+     * material's id and the shaders read `materials[mesh.material]`, so a material that only
+     * equals another — a clone — still needs the row at its own id. Shared by `equals()`, that row
+     * was never written: zeroed, opacity 0, a surface rays passed through.
      *
-     * @type {HashMap<ShadeMaterial, MaterialInfo>}
+     * @type {Map<ShadeMaterial, MaterialInfo>}
      */
-    #material_cache = new HashMap();
+    #material_cache = new Map();
 
     /**
      *
@@ -196,6 +242,57 @@ export class GPUResidentMaterialContext {
      */
     #version_managed_materials = 0;
 
+    /**
+     * The media the resident materials fill their insides with, one row each, shared by every
+     * material that names the same medium. Rows are dense ({@link #media_slots}), unlike material
+     * rows, which sit at the material's own id. Like materials, a medium stays resident once seen.
+     *
+     * @type {Map<ParticipatingMedium, MediumInfo>}
+     */
+    #media = new Map();
+
+    /**
+     * @type {IdPool}
+     */
+    #media_slots = new IdPool();
+
+    /**
+     * Whether the table's count is the number of resident media.
+     * @type {boolean}
+     */
+    #media_count_written = false;
+
+    /**
+     * @type {number}
+     */
+    #media_limit = 0;
+
+    /**
+     * How many media the table can hold: what {@link MEDIA_TABLE_STRUCT} addresses, within the
+     * device's uniform binding size.
+     *
+     * @returns {number}
+     */
+    get media_limit() {
+        return this.#media_limit;
+    }
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #buffer_media;
+
+    /**
+     * The media table, {@link MEDIA_TABLE_STRUCT}: how many media are resident, then one
+     * {@link MEDIUM_STRUCT} per slot, the slot a material row names in its `medium` field. A uniform
+     * buffer, written in place as media change.
+     *
+     * @returns {GPUBuffer}
+     */
+    get buffer_media() {
+        return this.#buffer_media;
+    }
+
     /**
      *
      * @param {GPUDevice} device
@@ -227,6 +324,17 @@ export class GPUResidentMaterialContext {
             size: INDIRECT_MATERIAL_STRUCT.size * this.#material_limit,
         });
 
+        this.#media_limit = Math.min(
+            Math.floor((limits.maxUniformBufferBindingSize - MEDIA_TABLE_RECORDS_OFFSET) / MEDIUM_STRUCT.size),
+            MEDIA_TABLE_CAPACITY
+        );
+
+        this.#buffer_media = device.createBuffer({
+            label: 'Participating Media',
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            size: MEDIA_TABLE_STRUCT.size,
+        });
+
         this.#buffer_textures = new GPUTextureContext(device);
         const descriptor = this.#buffer_textures.descriptor;
 
@@ -241,36 +349,124 @@ export class GPUResidentMaterialContext {
 
 
     /**
+     * Pack a material's row from its current fields, and remember the version that was.
      *
-     * @param {StandardShadeMaterial} material
-     * @returns {MaterialInfo}
+     * @param {MaterialInfo} info
      */
-    #pack_material(material) {
-        const r = new MaterialInfo();
+    #pack_material(info) {
+        const material = info.source;
 
+        info.texture_albedo = this.obtain_texture(material.texture_albedo ?? WHITE_PIXEL_TEXTURE);
+        info.texture_orm = this.obtain_texture(material.texture_orm ?? PIXEL_TEXTURE_ORM);
+        // no default stands in for a missing normal map: the atlas cannot hold the flat texel
+        const texture_normal = material.texture_normal ?? null;
 
-        r.id = material.id;
+        info.texture_normal = texture_normal === null ? null : this.obtain_texture(texture_normal);
+        info.texture_emissive = this.obtain_texture(material.texture_emissive ?? WHITE_PIXEL_TEXTURE);
 
-        r.source = material;
+        const medium = material.isStandardShadeMaterial === true ? material.medium : null;
 
-        r.texture_albedo = this.obtain_texture(material.texture_albedo ?? WHITE_PIXEL_TEXTURE);
-        r.texture_orm = this.obtain_texture(material.texture_orm ?? PIXEL_TEXTURE_ORM);
-        r.texture_normal = this.obtain_texture(material.texture_normal ?? PIXEL_TEXTURE_NORMAL);
-        r.texture_emissive = this.obtain_texture(material.texture_emissive ?? WHITE_PIXEL_TEXTURE);
+        info.medium_slot = medium === null ? GPU_DATABASE_NULL : this.#obtain_medium(medium).slot;
 
+        info.version = material.version;
 
         this.#version++;
+    }
 
-        return r;
+    /**
+     * Give a medium its row, once. Its record is written by {@link #write_media}, which also
+     * rewrites it whenever its version moves.
+     *
+     * @param {ParticipatingMedium} medium
+     * @returns {MediumInfo}
+     */
+    #obtain_medium(medium) {
+        assert.equal(medium.isParticipatingMedium, true, 'medium.isParticipatingMedium !== true');
+
+        let info = this.#media.get(medium);
+
+        if (info === undefined) {
+            info = new MediumInfo();
+
+            info.slot = this.#media_slots.get();
+            info.source = medium;
+
+            assert.lessThan(
+                info.slot,
+                this.#media_limit,
+                `medium slot ${info.slot} exceeds the media limit (=${this.#media_limit})`
+            );
+
+            this.#media.set(medium, info);
+
+            this.#media_count_written = false;
+        }
+
+        return info;
     }
 
     /**
+     * Write every resident medium whose version has moved since its row was last written — new
+     * ones included. Media are few and shared, so this looks at each of them per update rather than
+     * hearing from the materials that name them: an edit to a medium changes no material.
+     */
+    #write_media() {
+        if (!this.#media_count_written) {
+            // slots are dense and never given back, so the count is how many there are
+            this.#device.queue.writeBuffer(this.#buffer_media, 0, new Uint32Array([this.#media.size]));
+
+            this.#media_count_written = true;
+        }
+
+        /** @type {ArrayBuffer|null} */
+        let bytes = null;
+
+        for (const info of this.#media.values()) {
+            const medium = info.source;
+
+            if (info.version === medium.version) {
+                continue;
+            }
+
+            if (bytes === null) {
+                bytes = new ArrayBuffer(MEDIUM_STRUCT.size);
+            }
+
+            write_gpu_typed_buffer(medium.to_gpu_record(), MEDIUM_STRUCT, bytes, 0);
+
+            this.#device.queue.writeBuffer(this.#buffer_media, MEDIA_TABLE_RECORDS_OFFSET + info.slot * MEDIUM_STRUCT.size, bytes);
+
+            info.version = medium.version;
+        }
+    }
+
+    /**
+     * Make a material resident, or repack it if its {@link ShadeMaterial#version} has moved since —
+     * the same contract {@link GPUMaterialManager} restages by. A hit used to be final, so a factor
+     * set after the first pack never reached the row. Every caller re-obtains what it needs before
+     * {@link update}: the scene's drawn list, and the manager's materials whenever its version
+     * moves, so the check rides on walks that already happen.
      *
      * @param {ShadeMaterial} material
      * @returns {MaterialInfo}
      */
     obtain_material(material) {
-        return this.#material_cache.getOrCompute(material, this.#pack_material, this);
+        let info = this.#material_cache.get(material);
+
+        if (info === undefined) {
+            info = new MaterialInfo();
+
+            info.id = material.id;
+            info.source = material;
+
+            this.#material_cache.set(material, info);
+
+            this.#pack_material(info);
+        } else if (info.version !== material.version) {
+            this.#pack_material(info);
+        }
+
+        return info;
     }
 
     /**
@@ -481,11 +677,11 @@ export class GPUResidentMaterialContext {
                 {
                     texture_albedo: info.texture_albedo.id,
                     texture_orm: info.texture_orm.id,
-                    texture_normal: info.texture_normal.id,
+                    texture_normal: info.texture_normal === null ? GPU_DATABASE_NULL : info.texture_normal.id,
                     texture_emissive: info.texture_emissive.id,
                     sampler_albedo: sampler_descriptor_pack(info.texture_albedo.source),
                     sampler_orm: sampler_descriptor_pack(info.texture_orm.source),
-                    sampler_normal: sampler_descriptor_pack(info.texture_normal.source),
+                    sampler_normal: info.texture_normal === null ? 0 : sampler_descriptor_pack(info.texture_normal.source),
                     sampler_emissive: sampler_descriptor_pack(info.texture_emissive.source),
                     color_albedo: surface.diffuse_color,
                     roughness_factor: surface.roughness_factor,
@@ -493,6 +689,7 @@ export class GPUResidentMaterialContext {
                     transmission_factor: surface.transmission_factor,
                     ior_factor: surface.ior_factor,
                     emissive_factor: surface.emissive_factor,
+                    medium: info.medium_slot,
                 },
                 INDIRECT_MATERIAL_STRUCT,
                 mapped_buffer_materials,
@@ -558,6 +755,8 @@ export class GPUResidentMaterialContext {
 
         this.#update_from_manager();
 
+        this.#write_media();
+
         if (this.#version === this.#version_commited) {
             return;
         }
@@ -568,6 +767,7 @@ export class GPUResidentMaterialContext {
 
     destroy() {
         this.#buffer_materials.destroy();
+        this.#buffer_media.destroy();
         this.#buffer_textures.destroy();
     }
 }

package/src/shade/renderer/material/resident/INDIRECT_MATERIAL_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"INDIRECT_MATERIAL_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/INDIRECT_MATERIAL_STRUCT.js"],"names":[],"mappings":"AAGA,oDA0B2B;6BA5BE,mCAAmC"}
+{"version":3,"file":"INDIRECT_MATERIAL_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/INDIRECT_MATERIAL_STRUCT.js"],"names":[],"mappings":"AAGA,oDAoC2B;6BAtCE,mCAAmC"}

package/src/shade/renderer/material/resident/INDIRECT_MATERIAL_STRUCT.js

@@ -4,6 +4,11 @@ import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 export const INDIRECT_MATERIAL_STRUCT = WebGPUStruct.from({
     texture_albedo: u32,
     texture_orm: u32,
+    /**
+     * Atlas slot of the material's normal map, or GPU_DATABASE_NULL for none, which shades with the
+     * geometric normal. Not a default texture, as the other slots have: the atlas is rgba8unorm, and
+     * the flat texel is 0.5, which 8 bits store as 128/255 — a normal leaning 0.32 degrees.
+     */
     texture_normal: u32,
     texture_emissive: u32,
 
@@ -27,4 +32,9 @@ export const INDIRECT_MATERIAL_STRUCT = WebGPUStruct.from({
      */
     ior_factor: f32,
     emissive_factor: vec3f,
+    /**
+     * Slot of the material's {@link StandardShadeMaterial.medium} in the resident media table, or
+     * GPU_DATABASE_NULL for none. Sits in what was the struct's tail padding.
+     */
+    medium: u32,
 }, "IndirectMaterialInfo");

package/src/shade/renderer/medium/MEDIA_TABLE_STRUCT.d.ts

@@ -0,0 +1,17 @@
+/**
+ * How many media the resident media table holds: what fits in the baseline 65536-byte uniform
+ * binding after the table's 16-byte header.
+ * @type {number}
+ */
+export const MEDIA_TABLE_CAPACITY: number;
+/**
+ * The resident media table as the ray passes bind it, as the uniform `media`: how many media are
+ * resident, and one {@link MEDIUM_STRUCT} per slot, the slot a material row names in its `medium`
+ * field. The count lets a pass skip everything media cost it — the probe for which media a path
+ * starts inside — in a scene that has none. Uniform rather than storage because every pass tracing
+ * with `render_trace_path` binds it, and the Brick4 probe bake already uses all ten storage buffers
+ * the engine requires.
+ */
+export const MEDIA_TABLE_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=MEDIA_TABLE_STRUCT.d.ts.map

package/src/shade/renderer/medium/MEDIA_TABLE_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MEDIA_TABLE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/medium/MEDIA_TABLE_STRUCT.js"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,mCAFU,MAAM,CAEkE;AAElF;;;;;;;GAOG;AACH,8CAG8B;6BArBD,gCAAgC"}

package/src/shade/renderer/medium/MEDIA_TABLE_STRUCT.js

@@ -0,0 +1,24 @@
+import { u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+import { MEDIUM_STRUCT } from "./MEDIUM_STRUCT.js";
+
+/**
+ * How many media the resident media table holds: what fits in the baseline 65536-byte uniform
+ * binding after the table's 16-byte header.
+ * @type {number}
+ */
+export const MEDIA_TABLE_CAPACITY = Math.floor((65536 - 16) / MEDIUM_STRUCT.size);
+
+/**
+ * The resident media table as the ray passes bind it, as the uniform `media`: how many media are
+ * resident, and one {@link MEDIUM_STRUCT} per slot, the slot a material row names in its `medium`
+ * field. The count lets a pass skip everything media cost it — the probe for which media a path
+ * starts inside — in a scene that has none. Uniform rather than storage because every pass tracing
+ * with `render_trace_path` binds it, and the Brick4 probe bake already uses all ten storage buffers
+ * the engine requires.
+ */
+export const MEDIA_TABLE_STRUCT = WebGPUStruct.from({
+    count: u32,
+    records: WebGPUArray.from(MEDIUM_STRUCT, MEDIA_TABLE_CAPACITY),
+}, "ParticipatingMediaTable");

package/src/shade/renderer/medium/MEDIUM_PHASE_LOBE_KIND.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What a GPU phase lobe's two parameters mean. Every phase function a medium can state reduces to
+ * one or more lobes of these two kinds.
+ */
+export type MEDIUM_PHASE_LOBE_KIND = number;
+/**
+ * What a GPU phase lobe's two parameters mean. Every phase function a medium can state reduces to
+ * one or more lobes of these two kinds.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const MEDIUM_PHASE_LOBE_KIND: Readonly<{
+    /**
+     * `phase_draine(mu, g = p0, alpha = p1)`: Henyey-Greenstein, Cornette-Shanks, Rayleigh, the
+     * molecular water phase and both lobes of Jendersie-d'Eon
+     */
+    Draine: 0;
+    /**
+     * `phase_fournier_forand_u(sin²(psi / 2), nu = p0, kappa = p1)`
+     */
+    FournierForand: 1;
+}>;
+//# sourceMappingURL=MEDIUM_PHASE_LOBE_KIND.d.ts.map

package/src/shade/renderer/medium/MEDIUM_PHASE_LOBE_KIND.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MEDIUM_PHASE_LOBE_KIND.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/medium/MEDIUM_PHASE_LOBE_KIND.js"],"names":[],"mappings":";;;;qCAKU,MAAM;AALhB;;;;;;GAMG;AACH;IACI;;;OAGG;;IAEH;;OAEG;;GAEJ"}

package/src/shade/renderer/medium/MEDIUM_PHASE_LOBE_KIND.js

@@ -0,0 +1,18 @@
+/**
+ * What a GPU phase lobe's two parameters mean. Every phase function a medium can state reduces to
+ * one or more lobes of these two kinds.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const MEDIUM_PHASE_LOBE_KIND = Object.freeze({
+    /**
+     * `phase_draine(mu, g = p0, alpha = p1)`: Henyey-Greenstein, Cornette-Shanks, Rayleigh, the
+     * molecular water phase and both lobes of Jendersie-d'Eon
+     */
+    Draine: 0,
+    /**
+     * `phase_fournier_forand_u(sin²(psi / 2), nu = p0, kappa = p1)`
+     */
+    FournierForand: 1,
+});

package/src/shade/renderer/medium/MEDIUM_STRUCT.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The most phase lobes one medium carries on the GPU, after expansion: water is two, a
+ * Jendersie-d'Eon droplet population is two, so four leaves room for one of each.
+ * @type {number}
+ */
+export const MEDIUM_PHASE_LOBE_LIMIT: number;
+/**
+ * One scattering component of a medium: its scattering coefficient and its phase function.
+ * `kind` is a {@link MEDIUM_PHASE_LOBE_KIND}, which says what `p0` and `p1` are.
+ */
+export const MEDIUM_PHASE_LOBE_STRUCT: WebGPUStruct;
+/**
+ * What light does inside a medium, as the GPU reads it: absorption, and the scattering lobes
+ * whose coefficients sum to the medium's scattering. Extinction is absorption plus the sum of the
+ * lobes' scattering; the phase function at a point is the lobes' phase functions weighted by their
+ * scattering, per channel.
+ */
+export const MEDIUM_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=MEDIUM_STRUCT.d.ts.map

package/src/shade/renderer/medium/MEDIUM_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MEDIUM_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/medium/MEDIUM_STRUCT.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,sCAFU,MAAM,CAEyB;AAEzC;;;GAGG;AACH,oDAQsB;AAEtB;;;;;GAKG;AACH,yCAW0B;6BAxCG,gCAAgC"}

package/src/shade/renderer/medium/MEDIUM_STRUCT.js

@@ -0,0 +1,43 @@
+import { f32, u32, vec3f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+
+/**
+ * The most phase lobes one medium carries on the GPU, after expansion: water is two, a
+ * Jendersie-d'Eon droplet population is two, so four leaves room for one of each.
+ * @type {number}
+ */
+export const MEDIUM_PHASE_LOBE_LIMIT = 4;
+
+/**
+ * One scattering component of a medium: its scattering coefficient and its phase function.
+ * `kind` is a {@link MEDIUM_PHASE_LOBE_KIND}, which says what `p0` and `p1` are.
+ */
+export const MEDIUM_PHASE_LOBE_STRUCT = WebGPUStruct.from({
+    /**
+     * scattering coefficient sigma_s of this lobe, RGB, 1/m
+     */
+    scattering: vec3f,
+    kind: u32,
+    p0: f32,
+    p1: f32,
+}, "MediumPhaseLobe");
+
+/**
+ * What light does inside a medium, as the GPU reads it: absorption, and the scattering lobes
+ * whose coefficients sum to the medium's scattering. Extinction is absorption plus the sum of the
+ * lobes' scattering; the phase function at a point is the lobes' phase functions weighted by their
+ * scattering, per channel.
+ */
+export const MEDIUM_STRUCT = WebGPUStruct.from({
+    /**
+     * absorption coefficient sigma_a, RGB, 1/m
+     */
+    absorption: vec3f,
+    /**
+     * where media bounded by refracting surfaces overlap, the higher priority is the medium
+     */
+    priority: u32,
+    lobe_count: u32,
+    lobes: WebGPUArray.from(MEDIUM_PHASE_LOBE_STRUCT, MEDIUM_PHASE_LOBE_LIMIT),
+}, "ParticipatingMedium");

package/src/shade/renderer/medium/ParticipatingMedium.d.ts

@@ -0,0 +1,111 @@
+/**
+ * One scattering component of a medium.
+ */
+export class ParticipatingMediumLobe {
+    /**
+     * @param {number[]} scattering RGB scattering coefficient, 1/m
+     * @param {MediumPhaseFunction} phase
+     */
+    constructor(scattering: number[], phase: MediumPhaseFunction);
+    /**
+     * RGB scattering coefficient, 1/m
+     * @type {number[]}
+     */
+    scattering: number[];
+    /**
+     * @type {MediumPhaseFunction}
+     */
+    phase: MediumPhaseFunction;
+}
+/**
+ * What light does inside a region: how much is absorbed and how much scattered per metre, per
+ * channel, and in which directions the scattered light goes. Water is pure water's absorption plus
+ * whatever is dissolved, scattered by the molecules themselves and by particles; glass is
+ * absorption alone; fog is droplets.
+ *
+ * Coefficients are RGB in 1/m, in the renderer's linear working colour space. Absorption is the
+ * whole medium's; scattering is declared one component at a time with its own phase function,
+ * because a medium's components scatter differently (water's molecules almost evenly, its
+ * particles almost all forward) and the phase function at a point is their mixture, weighted by
+ * each one's scattering:
+ *
+ *      water.absorption = [0.35, 0.067, 0.019];
+ *      water.add_lobe([0.0009, 0.0019, 0.0045], new PhaseWaterMolecular({ depolarization: 0.039 }));
+ *      water.add_lobe([0.05, 0.05, 0.05], new PhaseFournierForand({ backscatter_fraction: 0.0183 }));
+ *
+ * The index of refraction is not here: it belongs to the surface the medium is entered through.
+ */
+export class ParticipatingMedium {
+    /**
+     * Absorption coefficient sigma_a, RGB, 1/m.
+     * @type {number[]}
+     */
+    absorption: number[];
+    /**
+     * Where regions bounded by refracting surfaces overlap — water modelled into the wall of the
+     * glass holding it — the medium of higher priority is the one that fills the overlap.
+     * A non-negative integer.
+     * @type {number}
+     */
+    priority: number;
+    /** Authored coefficients changed; resident consumers can queue a write without polling. */
+    onChanged: Signal;
+    /**
+     * Bumped whenever something that reaches the GPU changes, so the resident media table knows to
+     * repack this medium — the contract {@link ShadeMaterial#version} has. {@link add_lobe} and
+     * {@link clear_lobes} bump it themselves; {@link absorption}, {@link priority} and a lobe's
+     * phase parameters are public fields, so after writing one of those, set {@link needsUpdate}.
+     *
+     * @returns {number}
+     */
+    get version(): number;
+    /**
+     * Mark the medium changed, so its GPU record is repacked.
+     *
+     * @param {boolean} value
+     */
+    set needsUpdate(value: boolean);
+    /**
+     * The scattering components, in the order they were added.
+     * @returns {ReadonlyArray<ParticipatingMediumLobe>}
+     */
+    get lobes(): readonly ParticipatingMediumLobe[];
+    /**
+     * How many lobes the GPU carries for this medium; at most {@link MEDIUM_PHASE_LOBE_LIMIT}.
+     * @returns {number}
+     */
+    get gpu_lobe_count(): number;
+    /**
+     * Add a scattering component.
+     *
+     * @param {number[]} scattering RGB scattering coefficient sigma_s of this component, 1/m
+     * @param {MediumPhaseFunction} phase
+     */
+    add_lobe(scattering: number[], phase: MediumPhaseFunction): void;
+    /**
+     * Remove every scattering component; the medium only absorbs afterwards.
+     */
+    clear_lobes(): void;
+    /**
+     * The value {@link MEDIUM_STRUCT} is written from: unused lobe slots are zero.
+     *
+     * @returns {{absorption: number[], priority: number, lobe_count: number, lobes: MediumPhaseLobeRecord[]}}
+     */
+    to_gpu_record(): {
+        absorption: number[];
+        priority: number;
+        lobe_count: number;
+        lobes: MediumPhaseLobeRecord[];
+    };
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isParticipatingMedium: boolean;
+    #private;
+}
+export type MediumPhaseFunction = import("./phase/MediumPhaseFunction.js").MediumPhaseFunction;
+export type MediumPhaseLobeRecord = import("./phase/MediumPhaseFunction.js").MediumPhaseLobeRecord;
+export type ShadeMaterial = import("../material/ShadeMaterial.js").ShadeMaterial;
+import Signal from "../../../core/events/signal/Signal.js";
+//# sourceMappingURL=ParticipatingMedium.d.ts.map

package/src/shade/renderer/medium/ParticipatingMedium.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticipatingMedium.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/medium/ParticipatingMedium.js"],"names":[],"mappings":"AAwBA;;GAEG;AACH;IACI;;;OAGG;IACH,wBAHW,MAAM,EAAE,SACR,mBAAmB,EAa7B;IAVG;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEU;IAE5B;;OAEG;IACH,OAFU,mBAAmB,CAEX;CAEzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH;IACI;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;;;OAKG;IACH,UAFU,MAAM,CAEH;IAYb,2FAA2F;IAC3F,kBAAyB;IAEzB;;;;;;;OAOG;IACH,sBAEC;IAED;;;;OAIG;IACH,gCAKC;IAED;;;OAGG;IACH,gDAEC;IAED;;;OAGG;IACH,6BAQC;IAED;;;;;OAKG;IACH,qBAHW,MAAM,EAAE,SACR,mBAAmB,QAgB7B;IAED;;OAEG;IACH,oBAKC;IAED;;;;OAIG;IACH,iBAFa;QAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,qBAAqB,EAAE,CAAA;KAAC,CA8BxG;IAGL;;;OAGG;IACH,gCAFU,OAAO,CAEkC;;CANlD;kCAvMY,OAAO,gCAAgC,EAAE,mBAAmB;oCAC5D,OAAO,gCAAgC,EAAE,qBAAqB;4BAC9D,OAAO,8BAA8B,EAAE,aAAa;mBAN9C,uCAAuC"}