@woosh/meep-engine 3.38.0 → 3.40.0

package/src/shade/renderer/texture/virtual/VTPhysicalSlots.js

@@ -0,0 +1,245 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * The slot bookkeeping of a physical page cache — a square grid of `page_size + 2*border` slots
+ * over an atlas — with no texture behind it: which slots are taken, when each was last touched,
+ * which may never be evicted, and the mip each holds.
+ *
+ * {@link VTPhysicalCache} adds the layer textures and uploads on top of this. A cache whose pages
+ * are drawn rather than uploaded — the virtual shadow map's pool is a region of the shadow atlas —
+ * uses it on its own.
+ *
+ * Eviction metadata lives here as flat parallel arrays; the pick is a linear scan, which at the
+ * typical slot count (≤ ~1k) is cheaper than maintaining a heap.
+ */
+export class VTPhysicalSlots {
+
+    /**
+     * Payload texels per page side, without border.
+     * @type {number}
+     * @readonly
+     */
+    page_size;
+
+    /**
+     * Border texels on each side of the payload.
+     * @type {number}
+     * @readonly
+     */
+    border;
+
+    /**
+     * page_size + 2*border.
+     * @type {number}
+     * @readonly
+     */
+    slot_size;
+
+    /**
+     * Atlas side length in texels.
+     * @type {number}
+     * @readonly
+     */
+    atlas_size;
+
+    /**
+     * Slots along one atlas axis.
+     * @type {number}
+     * @readonly
+     */
+    slots_per_axis;
+
+    /**
+     * Total slot count.
+     * @type {number}
+     * @readonly
+     */
+    capacity;
+
+    /**
+     * Free slot indices, used as a stack.
+     * @type {number[]}
+     */
+    #free = [];
+
+    /**
+     * Per-slot: frame index of the last feedback touch.
+     * @type {Uint32Array}
+     */
+    #last_touch;
+
+    /**
+     * Per-slot: 1 when the slot must never be evicted (stack root pages).
+     * @type {Uint8Array}
+     */
+    #locked;
+
+    /**
+     * Per-slot: 1 when the slot is allocated.
+     * @type {Uint8Array}
+     */
+    #occupied;
+
+    /**
+     * Per-slot: virtual mip of the resident page — eviction tie-break only
+     * (prefer shedding fine pages, shrinking the resident quadtree from the
+     * leaves).
+     * @type {Uint8Array}
+     */
+    #mip;
+
+    /**
+     *
+     * @param {Object} options
+     * @param {number} [options.atlas_size]
+     * @param {number} [options.page_size]
+     * @param {number} [options.border]
+     */
+    constructor({
+                    atlas_size = 4096,
+                    page_size = 128,
+                    border = 4,
+                }) {
+        assert.isNonNegativeInteger(atlas_size, 'atlas_size');
+        assert.isNonNegativeInteger(page_size, 'page_size');
+        assert.isNonNegativeInteger(border, 'border');
+
+        this.page_size = page_size;
+        this.border = border;
+        this.slot_size = page_size + border * 2;
+        this.atlas_size = atlas_size;
+
+        this.slots_per_axis = Math.floor(atlas_size / this.slot_size);
+        this.capacity = this.slots_per_axis * this.slots_per_axis;
+
+        assert.greaterThan(this.capacity, 0, 'cache capacity');
+
+        this.#last_touch = new Uint32Array(this.capacity);
+        this.#locked = new Uint8Array(this.capacity);
+        this.#occupied = new Uint8Array(this.capacity);
+        this.#mip = new Uint8Array(this.capacity);
+
+        for (let i = this.capacity - 1; i >= 0; i--) {
+            this.#free.push(i);
+        }
+    }
+
+    /**
+     * Number of allocated slots.
+     * @returns {number}
+     */
+    get used() {
+        return this.capacity - this.#free.length;
+    }
+
+    /**
+     *
+     * @param {number} slot
+     * @returns {{x: number, y: number}} slot grid coordinates
+     */
+    slot_coords(slot) {
+        return {
+            x: slot % this.slots_per_axis,
+            y: (slot / this.slots_per_axis) | 0,
+        };
+    }
+
+    /**
+     *
+     * @param {number} slot
+     * @returns {boolean}
+     */
+    is_occupied(slot) {
+        return this.#occupied[slot] === 1;
+    }
+
+    /**
+     *
+     * @param {number} current_frame
+     * @param {boolean} [locked]
+     * @param {number} [mip] virtual mip of the incoming page
+     * @returns {number} slot index, or -1 when full
+     */
+    allocate(current_frame, locked = false, mip = 0) {
+        if (this.#free.length === 0) {
+            return -1;
+        }
+
+        const slot = this.#free.pop();
+
+        this.#occupied[slot] = 1;
+        this.#locked[slot] = locked ? 1 : 0;
+        this.#last_touch[slot] = current_frame;
+        this.#mip[slot] = mip;
+
+        return slot;
+    }
+
+    /**
+     *
+     * @param {number} slot
+     */
+    free(slot) {
+        assert.equal(this.#occupied[slot], 1, `slot ${slot} is not allocated`);
+
+        this.#occupied[slot] = 0;
+        this.#locked[slot] = 0;
+
+        this.#free.push(slot);
+    }
+
+    /**
+     *
+     * @param {number} slot
+     * @param {number} frame
+     */
+    touch(slot, frame) {
+        this.#last_touch[slot] = frame;
+    }
+
+    /**
+     *
+     * @param {number} slot
+     * @returns {number}
+     */
+    last_touch(slot) {
+        return this.#last_touch[slot];
+    }
+
+    /**
+     * Pick the least-recently-touched evictable slot.
+     *
+     * @param {number} current_frame
+     * @param {number} protect_window slots touched within this many frames
+     *      are not eligible — feedback readback runs a couple of frames
+     *      behind, so "recently touched" really means "probably on screen"
+     * @returns {number} slot index, or -1 when nothing is evictable
+     */
+    find_eviction_candidate(current_frame, protect_window) {
+        let best = -1;
+        let best_touch = 0xFFFFFFFF;
+        let best_mip = 0xFF;
+
+        for (let slot = 0; slot < this.capacity; slot++) {
+            if (this.#occupied[slot] === 0 || this.#locked[slot] === 1) {
+                continue;
+            }
+
+            const touch = this.#last_touch[slot];
+
+            if (current_frame - touch < protect_window) {
+                continue;
+            }
+
+            const mip = this.#mip[slot];
+
+            if (touch < best_touch || (touch === best_touch && mip < best_mip)) {
+                best_touch = touch;
+                best_mip = mip;
+                best = slot;
+            }
+        }
+
+        return best;
+    }
+}

package/src/shade/renderer/texture/virtual/build_chunk_vt_lookup.d.ts

@@ -9,7 +9,7 @@
  *   vt_stack_wrap_uv(uv, flags)            — repeat/clamp addressing
  *   vt_mip_level(info, ddx, ddy)           — analytic LOD in virtual-texel units
  *   vt_page_table_load(table, info, uv, m) — one textureLoad into the shared table
- *   vt_entry_unpack(word)                  — page table entry fields
+ *   vt_entry_unpack(word)                  — page table entry fields, from {@link chunk_vt_page_table_entry}
  *   vt_physical_uv(entry, info, uv)        — atlas UV for a wrapped virtual UV
  *
  * The mip formula must be byte-identical between feedback and sampling —

package/src/shade/renderer/texture/virtual/build_chunk_vt_lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build_chunk_vt_lookup.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/virtual/build_chunk_vt_lookup.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAL0B,SAAS,EAAxB,MAAM;IACS,MAAM,EAArB,MAAM;IACS,UAAU,EAAzB,MAAM;IACJ,SAAS,CA2HrB;0BArJyB,oCAAoC"}
+{"version":3,"file":"build_chunk_vt_lookup.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/virtual/build_chunk_vt_lookup.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAL0B,SAAS,EAAxB,MAAM;IACS,MAAM,EAArB,MAAM;IACS,UAAU,EAAzB,MAAM;IACJ,SAAS,CA2GrB;0BArIyB,oCAAoC"}

package/src/shade/renderer/texture/virtual/build_chunk_vt_lookup.js

@@ -1,5 +1,5 @@
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { VT_ENTRY_MIP_BITS, VT_ENTRY_PHYS_BITS } from "./VT_CONSTANTS.js";
+import { chunk_vt_page_table_entry } from "./chunk_vt_page_table_entry.js";
 import { VT_STACK_INFO_STRUCT } from "./VT_STACK_INFO_STRUCT.js";
 
 /**
@@ -13,7 +13,7 @@ import { VT_STACK_INFO_STRUCT } from "./VT_STACK_INFO_STRUCT.js";
  *   vt_stack_wrap_uv(uv, flags)            — repeat/clamp addressing
  *   vt_mip_level(info, ddx, ddy)           — analytic LOD in virtual-texel units
  *   vt_page_table_load(table, info, uv, m) — one textureLoad into the shared table
- *   vt_entry_unpack(word)                  — page table entry fields
+ *   vt_entry_unpack(word)                  — page table entry fields, from {@link chunk_vt_page_table_entry}
  *   vt_physical_uv(entry, info, uv)        — atlas UV for a wrapped virtual UV
  *
  * The mip formula must be byte-identical between feedback and sampling —
@@ -41,23 +41,6 @@ const VT_INV_ATLAS_SIZE: f32 = ${(1 / atlas_size).toExponential()};
 const VT_STACK_FLAG_WRAP_REPEAT: u32 = 1u;
 const VT_STACK_FLAG_UV_SET_1: u32 = 2u;
 
-struct VTPageTableEntry {
-    phys: vec2<u32>,
-    mip: u32,
-    valid: bool,
-}
-
-fn vt_entry_unpack(word: u32) -> VTPageTableEntry {
-    return VTPageTableEntry(
-        vec2<u32>(
-            word & ${(1 << VT_ENTRY_PHYS_BITS) - 1}u,
-            (word >> ${VT_ENTRY_PHYS_BITS}u) & ${(1 << VT_ENTRY_PHYS_BITS) - 1}u
-        ),
-        (word >> ${VT_ENTRY_PHYS_BITS * 2}u) & ${(1 << VT_ENTRY_MIP_BITS) - 1}u,
-        (word & ${1 << (VT_ENTRY_PHYS_BITS * 2 + VT_ENTRY_MIP_BITS)}u) != 0u
-    );
-}
-
 fn vt_stack_wrap_uv(uv: vec2<f32>, flags: u32) -> vec2<f32> {
     if ((flags & VT_STACK_FLAG_WRAP_REPEAT) != 0u) {
         return fract(uv);
@@ -145,6 +128,7 @@ fn vt_physical_uv(
 `,
         [
             VT_STACK_INFO_STRUCT.declaration_chunk,
+            chunk_vt_page_table_entry,
         ]
     );
 }

package/src/shade/renderer/texture/virtual/chunk_vt_page_table_entry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The page-table entry word as its fields — the WGSL side of {@link vt_entry_pack} /
+ * {@link vt_entry_unpack}: the physical slot holding a page, the mip of that page, and whether the
+ * entry points at anything.
+ *
+ * Independent of any cache geometry, so it is shared by every table that stores entries in this
+ * layout — the virtual texture page table, and the virtual shadow map's page rows.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_vt_page_table_entry: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vt_page_table_entry.d.ts.map

package/src/shade/renderer/texture/virtual/chunk_vt_page_table_entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vt_page_table_entry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/virtual/chunk_vt_page_table_entry.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,wCAFU,SAAS,CAsBjB;0BAjCwB,oCAAoC"}

package/src/shade/renderer/texture/virtual/chunk_vt_page_table_entry.js

@@ -0,0 +1,34 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { VT_ENTRY_MIP_BITS, VT_ENTRY_PHYS_BITS } from "./VT_CONSTANTS.js";
+
+/**
+ * The page-table entry word as its fields — the WGSL side of {@link vt_entry_pack} /
+ * {@link vt_entry_unpack}: the physical slot holding a page, the mip of that page, and whether the
+ * entry points at anything.
+ *
+ * Independent of any cache geometry, so it is shared by every table that stores entries in this
+ * layout — the virtual texture page table, and the virtual shadow map's page rows.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_vt_page_table_entry = CodeChunk.from(
+    //language=WGSL
+    `
+struct VTPageTableEntry {
+    phys: vec2<u32>,
+    mip: u32,
+    valid: bool,
+}
+
+fn vt_entry_unpack(word: u32) -> VTPageTableEntry {
+    return VTPageTableEntry(
+        vec2<u32>(
+            word & ${(1 << VT_ENTRY_PHYS_BITS) - 1}u,
+            (word >> ${VT_ENTRY_PHYS_BITS}u) & ${(1 << VT_ENTRY_PHYS_BITS) - 1}u
+        ),
+        (word >> ${VT_ENTRY_PHYS_BITS * 2}u) & ${(1 << VT_ENTRY_MIP_BITS) - 1}u,
+        (word & ${1 << (VT_ENTRY_PHYS_BITS * 2 + VT_ENTRY_MIP_BITS)}u) != 0u
+    );
+}
+`
+);

package/src/shade/renderer/volumetrics/GPUSceneVolumetrics.d.ts

@@ -1,24 +1,34 @@
 /**
  * @typedef {import("../GraphicsContext.js").GraphicsContext} GraphicsContext
  * @typedef {import("./SceneVolumetrics.js").SceneVolumetrics} SceneVolumetrics
+ * @typedef {import("../buffer/table/GPUTypedTable.js").GPUTypedTable} GPUTypedTable
  */
 /**
- * Represents participating media and volumetric lighting.
- * View-dependent.
+ * Keeps a scene's participating-media volumes in the scene database, as rows of its
+ * `participating_media_volumes` table: the froxel volumetrics read them there, and so do the ray
+ * passes, which already bind the scene database and have no storage binding to spare for a table
+ * of their own.
+ *
+ * The table is written whole whenever {@link SceneVolumetrics#version} moves — cleared and refilled
+ * in the scene's volume order — and not at all otherwise; the scene database's own update, later in
+ * the same frame, takes the rows to the GPU. The rows are dense from 0, which the passes' walk over
+ * `[0, participating_media_volumes_count)` relies on. A volume whose transform has no inverse —
+ * scaled to nothing on an axis — gets no row.
  */
 export class GPUSceneVolumetrics {
     /**
      *
-     * @param {GPUDevice} device
+     * @param {GPUTypedTable} table the scene database's `participating_media_volumes` table
      * @param {SceneVolumetrics} volumetrics
      */
-    constructor(device: GPUDevice, volumetrics: SceneVolumetrics);
+    constructor(table: import("../buffer/table/GPUTypedTable.js").GPUTypedTable<any>, volumetrics: SceneVolumetrics);
     /**
      * @type {SceneVolumetrics}
      */
     source: SceneVolumetrics;
-    get table(): GPUSingleTypeTable;
-    get metadata_buffer(): GPUTypedBuffer;
+    /**
+     * Nothing to release: the rows belong to the scene database.
+     */
     destroy(): void;
     /**
      *
@@ -30,6 +40,5 @@ export class GPUSceneVolumetrics {
 }
 export type GraphicsContext = import("../GraphicsContext.js").GraphicsContext;
 export type SceneVolumetrics = import("./SceneVolumetrics.js").SceneVolumetrics;
-import { GPUSingleTypeTable } from "../buffer/table/single/GPUSingleTypeTable.js";
-import { GPUTypedBuffer } from "../buffer/GPUTypedBuffer.js";
+export type GPUTypedTable = import("../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
 //# sourceMappingURL=GPUSceneVolumetrics.d.ts.map

package/src/shade/renderer/volumetrics/GPUSceneVolumetrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/GPUSceneVolumetrics.js"],"names":[],"mappings":"AAOA;;;GAGG;AAEH;;;GAGG;AACH;IAkCI;;;;OAIG;IACH,4CAFW,gBAAgB,EAkB1B;IArDD;;OAEG;IACH,QAFU,gBAAgB,CAEpB;IAWN,gCAEC;IAOD,sCAEC;IA8BD,gBAGC;IAED;;;;OAIG;IACH,YAHW,eAAe,gBACf,MAAM,QA+ChB;;CAEJ;8BA1HY,OAAO,uBAAuB,EAAE,eAAe;+BAC/C,OAAO,uBAAuB,EAAE,gBAAgB;mCAN1B,8CAA8C;+BADlD,6BAA6B"}
+{"version":3,"file":"GPUSceneVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/GPUSceneVolumetrics.js"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH;IAeI;;;;OAIG;IACH,+FAFW,gBAAgB,EAM1B;IAtBD;;OAEG;IACH,QAFU,gBAAgB,CAEpB;IAqBN;;OAEG;IACH,gBACC;IAED;;;;OAIG;IACH,YAHW,eAAe,gBACf,MAAM,QA4ChB;;CAEJ;8BAlGY,OAAO,uBAAuB,EAAE,eAAe;+BAC/C,OAAO,uBAAuB,EAAE,gBAAgB"}

package/src/shade/renderer/volumetrics/GPUSceneVolumetrics.js

@@ -1,18 +1,22 @@
 import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
-import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
-import { GPUTypedBuffer } from "../buffer/GPUTypedBuffer.js";
-import { GPUSingleTypeTable } from "../buffer/table/single/GPUSingleTypeTable.js";
-import { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "./PARTICIPATING_MEDIA_VOLUME_STRUCT.js";
-import { SCENE_VOLUMETRICS_METADATA_STRUCT } from "./SCENE_VOLUMETRICS_METADATA_STRUCT.js";
 
 /**
  * @typedef {import("../GraphicsContext.js").GraphicsContext} GraphicsContext
  * @typedef {import("./SceneVolumetrics.js").SceneVolumetrics} SceneVolumetrics
+ * @typedef {import("../buffer/table/GPUTypedTable.js").GPUTypedTable} GPUTypedTable
  */
 
 /**
- * Represents participating media and volumetric lighting.
- * View-dependent.
+ * Keeps a scene's participating-media volumes in the scene database, as rows of its
+ * `participating_media_volumes` table: the froxel volumetrics read them there, and so do the ray
+ * passes, which already bind the scene database and have no storage binding to spare for a table
+ * of their own.
+ *
+ * The table is written whole whenever {@link SceneVolumetrics#version} moves — cleared and refilled
+ * in the scene's volume order — and not at all otherwise; the scene database's own update, later in
+ * the same frame, takes the rows to the GPU. The rows are dense from 0, which the passes' walk over
+ * `[0, participating_media_volumes_count)` relies on. A volume whose transform has no inverse —
+ * scaled to nothing on an axis — gets no row.
  */
 export class GPUSceneVolumetrics {
 
@@ -21,59 +25,29 @@ export class GPUSceneVolumetrics {
      */
     source
 
-
     #version = -1;
 
     /**
-     *
-     * @type {GPUSingleTypeTable}
+     * The scene database's `participating_media_volumes` table; owned by the database.
+     * @type {GPUTypedTable}
      */
     #table;
 
-    get table() {
-        return this.#table;
-    }
-
-    /**
-     * @type {GPUTypedBuffer}
-     */
-    #metadata_buffer;
-
-    get metadata_buffer() {
-        return this.#metadata_buffer;
-    }
-
-    /**
-     * @type {GPUDevice}
-     */
-    #device;
-
     /**
      *
-     * @param {GPUDevice} device
+     * @param {GPUTypedTable} table the scene database's `participating_media_volumes` table
      * @param {SceneVolumetrics} volumetrics
      */
-    constructor(device, volumetrics) {
-        this.#device = device;
-
-        this.#table = new GPUSingleTypeTable({
-            device,
-            type: PARTICIPATING_MEDIA_VOLUME_STRUCT,
-        });
-
-        this.#metadata_buffer = GPUTypedBuffer.create({
-            label: "scene volumetrics metadata buffer",
-            device,
-            type: SCENE_VOLUMETRICS_METADATA_STRUCT,
-            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-        })
+    constructor(table, volumetrics) {
+        this.#table = table;
 
         this.source = volumetrics;
     }
 
+    /**
+     * Nothing to release: the rows belong to the scene database.
+     */
     destroy() {
-        this.#table.destroy();
-        this.#metadata_buffer.destroy();
     }
 
     /**
@@ -90,14 +64,24 @@ export class GPUSceneVolumetrics {
             return;
         }
 
-        const cmd = ShadeGPUCommandContext.create(gfx, 'volumetrics update');
+        const table = this.#table;
+
+        table.clear();
 
         const m4_transform_inverse = new Float32Array(16);
-        this.source.volumes.forEach((v,index) => {
 
-            m4_invert(m4_transform_inverse, v.transform.matrix);
+        const volumes = this.source.volumes;
+
+        for (let i = 0; i < volumes.length; i++) {
+            const v = volumes[i];
 
-            this.#table.set(index, {
+            if (!m4_invert(m4_transform_inverse, v.transform.matrix)) {
+                // scaled to nothing on an axis: it encloses nothing, and without an inverse every
+                // pass would place it wrong — an all-zero matrix puts the whole world inside it
+                continue;
+            }
+
+            table.add({
                 particle_spec: {
                     scattering: v.particle_spec.scattering,
                     extinction: v.particle_spec.extinction,
@@ -110,22 +94,9 @@ export class GPUSceneVolumetrics {
                 fade_distance: v.fade_distance,
                 density: v.density,
             });
-
-        })
-
-        this.#table.update(cmd);
-
-        this.#metadata_buffer.upload({
-            instance_count: this.source.volumes.length,
-        }, this.#device.queue);
-
-
-        cmd.finish();
-
-        // this.#table.debug_dump().then(console.warn); // DEBUG
+        }
 
         this.#version = this.source.version;
-
     }
 
-}
+}

package/src/shade/renderer/volumetrics/chunk_participating_media_volume_sample.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A participating-media volume at a point and along a ray, exactly: what the ray passes trace
+ * through, where the froxel volumetrics discretize.
+ *
+ * - `participating_media_volume_density_at` is the volume's particle density at a world position:
+ *   `density` times its edge fade, zero outside its box. The fade is the per-axis smoothstep over
+ *   `fade_distance` (in world units, unaffected by scale) that `compute_volume_fade_factor` evaluates
+ *   at a froxel's midpoint; here it is the field itself. Bounded above by `density`, so
+ *   `density * extinction` majorizes the volume anywhere in it.
+ * - `participating_media_volume_span` is where a ray is inside the box, as distances along it,
+ *   clipped to `[0, t_max]`; empty (`y <= x`) when it misses. The direction need not be unit
+ *   length, and the distances are in its units: the local direction is not renormalized.
+ *
+ * The coefficients at a point are `density_at * particle_spec.{scattering, extinction}`, scattered
+ * by Henyey-Greenstein with `particle_spec.g`, as the froxels scatter it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_participating_media_volume_sample: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_participating_media_volume_sample.d.ts.map

package/src/shade/renderer/volumetrics/chunk_participating_media_volume_sample.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_participating_media_volume_sample.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/chunk_participating_media_volume_sample.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;GAiBG;AACH,sDAFU,SAAS,CAgDjB;0BAnEwB,iCAAiC"}

package/src/shade/renderer/volumetrics/chunk_participating_media_volume_sample.js

@@ -0,0 +1,70 @@
+import { chunk_aabb3_slab_span } from "../shader/chunk/geometry/aabb3/chunk_aabb3_slab_span.js";
+import { chunk_mat4_extract_scale } from "../shader/chunk/geometry/mat4/chunk_mat4_extract_scale.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { PARTICIPATING_MEDIA_VOLUME_STRUCT } from "./PARTICIPATING_MEDIA_VOLUME_STRUCT.js";
+
+/**
+ * A participating-media volume at a point and along a ray, exactly: what the ray passes trace
+ * through, where the froxel volumetrics discretize.
+ *
+ * - `participating_media_volume_density_at` is the volume's particle density at a world position:
+ *   `density` times its edge fade, zero outside its box. The fade is the per-axis smoothstep over
+ *   `fade_distance` (in world units, unaffected by scale) that `compute_volume_fade_factor` evaluates
+ *   at a froxel's midpoint; here it is the field itself. Bounded above by `density`, so
+ *   `density * extinction` majorizes the volume anywhere in it.
+ * - `participating_media_volume_span` is where a ray is inside the box, as distances along it,
+ *   clipped to `[0, t_max]`; empty (`y <= x`) when it misses. The direction need not be unit
+ *   length, and the distances are in its units: the local direction is not renormalized.
+ *
+ * The coefficients at a point are `density_at * particle_spec.{scattering, extinction}`, scattered
+ * by Henyey-Greenstein with `particle_spec.g`, as the froxels scatter it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_participating_media_volume_sample = CodeChunk.from(
+    //language=WGSL
+    `
+fn participating_media_volume_density_at(volume: ${PARTICIPATING_MEDIA_VOLUME_STRUCT.wgsl_ref}, position: vec3<f32>) -> f32 {
+    let local = (volume.transform_inverse * vec4<f32>(position, 1.0)).xyz;
+    let to_edge_local = vec3<f32>(0.5) - abs(local);
+
+    if (any(to_edge_local < vec3<f32>(0.0))) {
+        return 0.0;
+    }
+
+    if (volume.fade_distance <= 0.001) {
+        return volume.density;
+    }
+
+    let to_edge_world = to_edge_local * mat4_extract_scale(volume.transform);
+    let fade = smoothstep(vec3<f32>(0.0), vec3<f32>(volume.fade_distance), to_edge_world);
+
+    return volume.density * fade.x * fade.y * fade.z;
+}
+
+fn participating_media_volume_span(
+    volume: ${PARTICIPATING_MEDIA_VOLUME_STRUCT.wgsl_ref},
+    origin: vec3<f32>,
+    direction: vec3<f32>,
+    t_max: f32,
+) -> vec2<f32> {
+    let local_origin = (volume.transform_inverse * vec4<f32>(origin, 1.0)).xyz;
+    let local_direction = (volume.transform_inverse * vec4<f32>(direction, 0.0)).xyz;
+    let inverse_direction = 1.0 / local_direction;
+
+    let x = aabb3_slab_span(-0.5 - local_origin.x, 0.5 - local_origin.x, inverse_direction.x);
+    let y = aabb3_slab_span(-0.5 - local_origin.y, 0.5 - local_origin.y, inverse_direction.y);
+    let z = aabb3_slab_span(-0.5 - local_origin.z, 0.5 - local_origin.z, inverse_direction.z);
+
+    let near = max(max(x.x, y.x), max(z.x, 0.0));
+    let far = min(min(x.y, y.y), min(z.y, t_max));
+
+    return vec2<f32>(near, far);
+}
+    `,
+    [
+        PARTICIPATING_MEDIA_VOLUME_STRUCT.declaration_chunk,
+        chunk_aabb3_slab_span,
+        chunk_mat4_extract_scale,
+    ]
+);