@woosh/meep-engine 3.61.2 → 3.61.3

package/src/shade/renderer/gpu_primitive/hash_table/chunk_hash_table_atomic.js

@@ -0,0 +1,122 @@
+import { chunk_hash_lowbias32 } from "../../shader/chunk/random/chunk_hash_lowbias32.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_generate_next_linear_congruential_index } from "./chunk_generate_next_linear_congruential_index.js";
+import { HASH_TABLE_MISS, HASH_TABLE_PROBE_LIMIT } from "./cpu_build_hash_table.js";
+
+/**
+ * The encoded key of a record removed from a table the device keeps ({@link chunk_hash_table_atomic}):
+ * a probe passes over it as over another key's record, and an insert may take its place. No key
+ * encodes to it, keys staying below `0xFFFFFFFE`.
+ * @type {number}
+ */
+export const HASH_TABLE_REMOVED = 0xFFFFFFFF;
+
+/**
+ * The table `cpu_build_hash_table` lays out (`[element_count, table_size]`, then `table_size` records
+ * of `(key + 1, value)`, an empty record 0) kept on the device: inserted into and removed from by
+ * atomics, on `hash_table_get`'s probe sequence and limit. A key may hold several records, which find
+ * visits in turn; the caller tells them apart by what their values name. `element_count` counts the
+ * records held.
+ *
+ * ```wgsl
+ * fn hash_table_atomic_start(table, offset: u32, key: u32) -> vec2<u32>                           // a cursor at the key's first record
+ * fn hash_table_atomic_find(table, offset: u32, key: u32, cursor: ptr<function, vec2<u32>>) -> u32  // the key's next record, or HASH_TABLE_MISS
+ * fn hash_table_atomic_value(table, record: u32) -> u32
+ * fn hash_table_atomic_insert(table, offset: u32, key: u32, value: u32) -> bool                    // false: no record free within the probe limit
+ * fn hash_table_atomic_remove(table, offset: u32, record: u32)
+ * ```
+ *
+ * `table` is a `ptr<storage, array<atomic<u32>>, read_write>`, and a record is named by the word it
+ * starts at. Insert claims the first empty or removed record of the key's sequence by
+ * compare-exchange on its key and stores the value after it, so a find racing that insert in one
+ * dispatch may read the value before it lands: a caller whose inserts share a dispatch with its finds
+ * checks what a value names before trusting it. Inserts and removes of different records may share a
+ * dispatch. A find ends at the sequence's first empty record or at the probe limit.
+ *
+ * A table holds at least `HASH_TABLE_PROBE_LIMIT` records, a power of two, so that the probes of a
+ * key's sequence meet no record twice.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_hash_table_atomic = CodeChunk.from(
+    //language=WGSL
+    `
+const HASH_TABLE_MISS = ${HASH_TABLE_MISS}u;
+const HASH_TABLE_REMOVED = ${HASH_TABLE_REMOVED}u;
+const HASH_TABLE_PROBE_LIMIT = ${HASH_TABLE_PROBE_LIMIT}u;
+
+fn hash_table_atomic_start(table: ptr<storage, array<atomic<u32>>, read_write>, offset: u32, key: u32) -> vec2<u32> {
+    let mask = atomicLoad(&(*table)[offset + 1u]) - 1u;
+
+    // the record index, then the probes taken
+    return vec2<u32>(hash_lowbias32(key) & mask, 0u);
+}
+
+fn hash_table_atomic_find(table: ptr<storage, array<atomic<u32>>, read_write>, offset: u32, key: u32, cursor: ptr<function, vec2<u32>>) -> u32 {
+    let mask = atomicLoad(&(*table)[offset + 1u]) - 1u;
+    let encoded = key + 1u;
+
+    while ((*cursor).y < HASH_TABLE_PROBE_LIMIT) {
+        let record = offset + 2u + 2u * (*cursor).x;
+        let stored = atomicLoad(&(*table)[record]);
+
+        *cursor = vec2<u32>(generate_next_linear_congruential_index((*cursor).x, mask), (*cursor).y + 1u);
+
+        if (stored == 0u) {
+            // the key's sequence ends at its first empty record
+            (*cursor).y = HASH_TABLE_PROBE_LIMIT;
+
+            return HASH_TABLE_MISS;
+        }
+
+        if (stored == encoded) {
+            return record;
+        }
+    }
+
+    return HASH_TABLE_MISS;
+}
+
+fn hash_table_atomic_value(table: ptr<storage, array<atomic<u32>>, read_write>, record: u32) -> u32 {
+    return atomicLoad(&(*table)[record + 1u]);
+}
+
+fn hash_table_atomic_insert(table: ptr<storage, array<atomic<u32>>, read_write>, offset: u32, key: u32, value: u32) -> bool {
+    let mask = atomicLoad(&(*table)[offset + 1u]) - 1u;
+
+    var index = hash_lowbias32(key) & mask;
+
+    for (var probe = 0u; probe < HASH_TABLE_PROBE_LIMIT; probe++) {
+        let record = offset + 2u + 2u * index;
+        let stored = atomicLoad(&(*table)[record]);
+
+        if (stored == 0u || stored == HASH_TABLE_REMOVED) {
+            let claim = atomicCompareExchangeWeak(&(*table)[record], stored, key + 1u);
+
+            if (claim.exchanged) {
+                atomicStore(&(*table)[record + 1u], value);
+                atomicAdd(&(*table)[offset], 1u);
+
+                return true;
+            }
+
+            if (claim.old_value == stored) {
+                // a weak exchange may fail on a record that still holds what it read: the same record again
+                continue;
+            }
+        }
+
+        index = generate_next_linear_congruential_index(index, mask);
+    }
+
+    return false;
+}
+
+fn hash_table_atomic_remove(table: ptr<storage, array<atomic<u32>>, read_write>, offset: u32, record: u32) {
+    atomicStore(&(*table)[record], HASH_TABLE_REMOVED);
+    atomicSub(&(*table)[offset], 1u);
+}
+`, [
+        chunk_generate_next_linear_congruential_index,
+        chunk_hash_lowbias32,
+    ]);

package/src/shade/renderer/gpu_primitive/hash_table/chunk_hash_table_get.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_hash_table_get.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/hash_table/chunk_hash_table_get.js"],"names":[],"mappings":"AAcA;;;GAGG;AACH,mCAFU,SAAS,CAkDlB;0BAjEyB,oCAAoC"}
+{"version":3,"file":"chunk_hash_table_get.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/hash_table/chunk_hash_table_get.js"],"names":[],"mappings":"AAIA;;;GAGG;AACH,mCAFU,SAAS,CAkDlB;0BAvDyB,oCAAoC"}

package/src/shade/renderer/gpu_primitive/hash_table/chunk_hash_table_get.js

@@ -1,16 +1,6 @@
 import { chunk_hash_lowbias32 } from "../../shader/chunk/random/chunk_hash_lowbias32.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-
-const chunk_generate_next_linear_congruential_index = CodeChunk.from(
-    //language=WGSL
-    `
-fn generate_next_linear_congruential_index(index:u32, mask: u32) -> u32{
-    let index5 = index * 5;
-
-    return (index5 + 1) & mask;
-}
-    `
-)
+import { chunk_generate_next_linear_congruential_index } from "./chunk_generate_next_linear_congruential_index.js";
 
 /**
  * @see cpu_build_hash_table

package/src/shade/renderer/gpu_primitive/hash_table/cpu_build_hash_table.d.ts

@@ -40,6 +40,14 @@ export function cpu_hash_table_word_count(input_size: number): number;
  * @see cpu_build_hash_table to build at a given size
  */
 export function cpu_hash_table_create(table: Uint32Array, inputs: number[], input_size: number): boolean;
+/**
+ * Maximum number of slots visited per operation.
+ * Must match the WGSL twins ({@link chunk_hash_table_get}, `chunk_hash_table_atomic`): a lookup probes
+ * at most this many slots, so an insert that cannot place a record within the limit must report it —
+ * otherwise it would create an entry that lookups can never reach.
+ * @type {number}
+ */
+export const HASH_TABLE_PROBE_LIMIT: number;
 /**
  * Sentinel returned on lookup miss.
  * Must match the WGSL twin ({@link chunk_hash_table_get}).

package/src/shade/renderer/gpu_primitive/hash_table/cpu_build_hash_table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cpu_build_hash_table.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/hash_table/cpu_build_hash_table.js"],"names":[],"mappings":"AAoEA;;;;;;GAMG;AACH,0CALW,WAAW,UACX,MAAM,OACN,MAAM,GACJ,MAAM,CAsClB;AAED;;;;;;;;;GASG;AACH,6CARW,WAAW,iBACX,MAAM,cACN,MAAM,UACN,MAAM,EAAE,cACR,MAAM,GACJ,OAAO,CA2BnB;AAWD;;;;;GAKG;AACH,sDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;GAcG;AACH,6CARW,WAAW,UACX,MAAM,EAAE,cACR,MAAM,GACJ,OAAO,CAkBnB;AAnLD;;;;GAIG;AACH,8BAFU,MAAM,CAE0B"}
+{"version":3,"file":"cpu_build_hash_table.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/hash_table/cpu_build_hash_table.js"],"names":[],"mappings":"AAsEA;;;;;;GAMG;AACH,0CALW,WAAW,UACX,MAAM,OACN,MAAM,GACJ,MAAM,CAsClB;AAED;;;;;;;;;GASG;AACH,6CARW,WAAW,iBACX,MAAM,cACN,MAAM,UACN,MAAM,EAAE,cACR,MAAM,GACJ,OAAO,CA2BnB;AAWD;;;;;GAKG;AACH,sDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;GAcG;AACH,6CARW,WAAW,UACX,MAAM,EAAE,cACR,MAAM,GACJ,OAAO,CAkBnB;AA9LD;;;;;;GAMG;AACH,qCAFU,MAAM,CAEyB;AAIzC;;;;GAIG;AACH,8BAFU,MAAM,CAE0B"}

package/src/shade/renderer/gpu_primitive/hash_table/cpu_build_hash_table.js

@@ -8,12 +8,14 @@ import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
 
 /**
  * Maximum number of slots visited per operation.
- * Must match the WGSL twin ({@link chunk_hash_table_get}): a lookup probes at most this many slots,
- * so an insert that cannot place a record within the limit must report it — otherwise it would
- * create an entry that lookups can never reach.
+ * Must match the WGSL twins ({@link chunk_hash_table_get}, `chunk_hash_table_atomic`): a lookup probes
+ * at most this many slots, so an insert that cannot place a record within the limit must report it —
+ * otherwise it would create an entry that lookups can never reach.
  * @type {number}
  */
-const PROBE_LIMIT = 32;
+export const HASH_TABLE_PROBE_LIMIT = 32;
+
+const PROBE_LIMIT = HASH_TABLE_PROBE_LIMIT;
 
 /**
  * Sentinel returned on lookup miss.

package/src/shade/renderer/loader/gltf/tiny-gltf.d.ts

@@ -13,7 +13,7 @@ export class TinyGltf {
      * @readonly
      * @type {TextureFormat}
      */
-    static readonly "__#306@#UNCOMPRESSED_TARGET": TextureFormat;
+    static readonly "__#308@#UNCOMPRESSED_TARGET": TextureFormat;
     /**
      * @param {AssetManager} assetManager
      * @param {AssetRequestScope} [scope]

package/src/shade/renderer/material/resident/GPUResidentMaterialContext.d.ts

@@ -45,7 +45,7 @@ export class GPUResidentMaterialContext {
      * 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} or {@link commit}: the scene's drawn list, the manager's materials whenever its
-     * version moves, or what a card capture traces, so the check rides on walks that already happen.
+     * version moves, or what a surface bake traces, so the check rides on walks that already happen.
      *
      * @param {ShadeMaterial} material
      * @returns {MaterialInfo}

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

@@ -1 +1 @@
-{"version":3,"file":"GPUResidentMaterialContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/GPUResidentMaterialContext.js"],"names":[],"mappings":"AAgIA;IAqKI;;;;OAIG;IACH,yCAFW,eAAe,EAkDzB;IA9LD;;;OAGG;IACH,6BAEC;IAQD;;;OAGG;IACH,kCAEC;IAQD;;;OAGG;IACH,yCAEC;IAED;;;OAGG;IACH,kCAIC;IAmED;;;;;OAKG;IACH,0BAEC;IAOD;;;;;;OAMG;IACH,8BAEC;IAsJD;;;;;;;;;OASG;IACH,0BAHW,aAAa,GACX,YAAY,CAmBxB;IAgBD;;;;OAIG;IACH,wBAHW,YAAY,GACV,WAAW,CAIvB;IAGD,uBA0DC;IAuFD,wBA8EC;IAED;;;;OAIG;IACH,sCAFW,eAAe,QAUzB;IAoCD;;;;OAIG;IACH,eAGC;IAED;;;OAGG;IACH,eAGC;IAGD,gBAIC;;CACJ;8BA9vBY,OAAO,0BAA0B,EAAE,eAAe;8BAClD,OAAO,gCAAgC,EAAE,eAAe;2BACxD,OAAO,+BAA+B,EAAE,YAAY;4BACpD,OAAO,qBAAqB,EAAE,aAAa;oCAC3C,OAAO,6BAA6B,EAAE,qBAAqB;kCAC3D,OAAO,qCAAqC,EAAE,mBAAmB;kCAlB5C,oCAAoC;AAYtE;;;;;;;GAOG;AAEH;IACI,WAAM;IAEN;;;OAGG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,QAFU,qBAAqB,CAExB;IAEP;;OAEG;IACH,gBAFU,WAAW,CAEP;IAEd;;OAEG;IACH,aAFU,WAAW,CAEV;IAEX;;;;OAIG;IACH,gBAFU,WAAW,GAAC,IAAI,CAEZ;IACd;;OAEG;IACH,kBAFU,WAAW,CAEL;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEe;CAClC;AAqBD;IACI,WAAO;IAEP;;OAEG;IACH,QAFU,YAAY,CAEf;CACV"}
+{"version":3,"file":"GPUResidentMaterialContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/GPUResidentMaterialContext.js"],"names":[],"mappings":"AAgHA;IAqKI;;;;OAIG;IACH,yCAFW,eAAe,EAkDzB;IA9LD;;;OAGG;IACH,6BAEC;IAQD;;;OAGG;IACH,kCAEC;IAQD;;;OAGG;IACH,yCAEC;IAED;;;OAGG;IACH,kCAIC;IAmED;;;;;OAKG;IACH,0BAEC;IAOD;;;;;;OAMG;IACH,8BAEC;IAsJD;;;;;;;;;OASG;IACH,0BAHW,aAAa,GACX,YAAY,CAmBxB;IAgBD;;;;OAIG;IACH,wBAHW,YAAY,GACV,WAAW,CAIvB;IAGD,uBA0DC;IAuFD,wBA8EC;IAED;;;;OAIG;IACH,sCAFW,eAAe,QAUzB;IAoCD;;;;OAIG;IACH,eAGC;IAED;;;OAGG;IACH,eAGC;IAGD,gBAIC;;CACJ;8BA7uBY,OAAO,0BAA0B,EAAE,eAAe;8BAClD,OAAO,gCAAgC,EAAE,eAAe;2BACxD,OAAO,+BAA+B,EAAE,YAAY;4BACpD,OAAO,qBAAqB,EAAE,aAAa;oCAC3C,OAAO,6BAA6B,EAAE,qBAAqB;kCAC3D,OAAO,qCAAqC,EAAE,mBAAmB;kCAnB5C,oCAAoC;AAatE;;;;;;;GAOG;AAEH;IACI,WAAM;IAEN;;;OAGG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,QAFU,qBAAqB,CAExB;IAEP;;OAEG;IACH,gBAFU,WAAW,CAEP;IAEd;;OAEG;IACH,aAFU,WAAW,CAEV;IAEX;;;;OAIG;IACH,gBAFU,WAAW,GAAC,IAAI,CAEZ;IACd;;OAEG;IACH,kBAFU,WAAW,CAEL;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEe;CAClC;AAqBD;IACI,WAAO;IAEP;;OAEG;IACH,QAFU,YAAY,CAEf;CACV"}

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

@@ -17,6 +17,7 @@ import { sampler_descriptor_pack } from "../../texture/format/sampler_descriptor
 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";
+import { NEUTRAL_SURFACE } from "./NEUTRAL_SURFACE.js";
 import {
     RESIDENT_MATERIAL_TEXTURE_LAYER_SIZE,
     RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT,
@@ -109,23 +110,6 @@ class TextureInfo {
  */
 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
- * already resolve to. Without it the fields the row is written from are absent and skipped into a
- * zeroed buffer, and an opacity of 0 is a surface the rays pass through: a terrain would stop
- * casting ray-traced shadows, and a bake would see it black. The same values a flat standard
- * material gives, which is what the terrain drew with before it had a template of its own.
- */
-const NEUTRAL_SURFACE = Object.freeze({
-    diffuse_color: Object.freeze([1, 1, 1, 1]),
-    roughness_factor: 1,
-    metallic_factor: 0,
-    transmission_factor: 0,
-    ior_factor: 1.5,
-    emissive_factor: Object.freeze([0, 0, 0]),
-});
-
 export class GPUResidentMaterialContext {
 
     /**
@@ -444,7 +428,7 @@ export class GPUResidentMaterialContext {
      * 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} or {@link commit}: the scene's drawn list, the manager's materials whenever its
-     * version moves, or what a card capture traces, so the check rides on walks that already happen.
+     * version moves, or what a surface bake traces, so the check rides on walks that already happen.
      *
      * @param {ShadeMaterial} material
      * @returns {MaterialInfo}

package/src/shade/renderer/material/resident/NEUTRAL_SURFACE.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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
+ * already resolve to. Without it the fields the row is written from are absent and skipped into a
+ * zeroed buffer, and an opacity of 0 is a surface the rays pass through: a terrain would stop
+ * casting ray-traced shadows, and a bake would see it black. The same values a flat standard
+ * material gives, which is what the terrain drew with before it had a template of its own.
+ */
+export const NEUTRAL_SURFACE: Readonly<{
+    diffuse_color: readonly number[];
+    roughness_factor: 1;
+    metallic_factor: 0;
+    transmission_factor: 0;
+    ior_factor: 1.5;
+    emissive_factor: readonly number[];
+}>;
+//# sourceMappingURL=NEUTRAL_SURFACE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NEUTRAL_SURFACE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/NEUTRAL_SURFACE.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH;;;;;;;GAOG"}

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

@@ -0,0 +1,16 @@
+/**
+ * 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
+ * already resolve to. Without it the fields the row is written from are absent and skipped into a
+ * zeroed buffer, and an opacity of 0 is a surface the rays pass through: a terrain would stop
+ * casting ray-traced shadows, and a bake would see it black. The same values a flat standard
+ * material gives, which is what the terrain drew with before it had a template of its own.
+ */
+export const NEUTRAL_SURFACE = Object.freeze({
+    diffuse_color: Object.freeze([1, 1, 1, 1]),
+    roughness_factor: 1,
+    metallic_factor: 0,
+    transmission_factor: 0,
+    ior_factor: 1.5,
+    emissive_factor: Object.freeze([0, 0, 0]),
+});

package/src/shade/renderer/path_tracer/shader/INDIRECT_TEXTURE_FILTER.d.ts

@@ -4,7 +4,7 @@
  * or the other by the pipeline they are linked into.
  *
  * Whether the pass averages its reads is the pass's, so it is fixed per shader: `Stochastic`, the
- * default, for every pass that never sets it; `Exact` for the card capture, which stores each read.
+ * default, for every pass that never sets it; `Exact` for the surface caches' bake, which stores each read.
  *
  * @type {ShaderSwitch}
  */

package/src/shade/renderer/path_tracer/shader/INDIRECT_TEXTURE_FILTER.js

@@ -7,7 +7,7 @@ import { IndirectTextureFilter } from "./IndirectTextureFilter.js";
  * or the other by the pipeline they are linked into.
  *
  * Whether the pass averages its reads is the pass's, so it is fixed per shader: `Stochastic`, the
- * default, for every pass that never sets it; `Exact` for the card capture, which stores each read.
+ * default, for every pass that never sets it; `Exact` for the surface caches' bake, which stores each read.
  *
  * @type {ShaderSwitch}
  */

package/src/shade/renderer/path_tracer/shader/IndirectTextureFilter.js

@@ -10,6 +10,6 @@ export const IndirectTextureFilter = {
      * gives on average, for a pass that averages many reads into each result — the path tracer.
      */
     Stochastic: 0,
-    /** The filter itself, every tap weighed: for a pass that keeps each read as it is — the card capture. */
+    /** The filter itself, every tap weighed: for a pass that keeps each read as it is — the surface caches' bake. */
     Exact: 1,
 };

package/src/shade/renderer/path_tracer/shader/chunk_beam_texture_level.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The resident material texture level a beam reads a triangle's material at: its footprint on the
+ * triangle, in texels of a slot's level 0, as `sample_material_data` and `sample_material_alpha` take
+ * their `texture_level`:
+ *
+ * ```wgsl
+ * fn beam_texture_level(triangle: TriangleVertices, along: vec3<f32>, step_u: vec3<f32>, step_v: vec3<f32>) -> f32
+ * ```
+ *
+ * The beam runs along `along` and spans `step_u` and `step_v` across, all in the triangle's space;
+ * `along` need not be unit length. Each step is carried along the beam onto the triangle's plane and
+ * through the triangle's uv per position. For a step s, direction d and normal n that is
+ * s − d (n·s)/(n·d) on the plane, taken here times n·d, so a triangle turning edge-on, whose footprint
+ * grows without bound, reaches the last level with nothing divided by 0, as a raster's would.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_beam_texture_level: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_beam_texture_level.d.ts.map

package/src/shade/renderer/path_tracer/shader/chunk_beam_texture_level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_beam_texture_level.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_beam_texture_level.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AACH,uCAFU,SAAS,CA0CZ;0BA3DmB,oCAAoC"}

package/src/shade/renderer/path_tracer/shader/chunk_beam_texture_level.js

@@ -0,0 +1,65 @@
+import {
+    RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT,
+    RESIDENT_MATERIAL_TEXTURE_RESOLUTION
+} from "../../material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.js";
+import { TRIANGLE_VERTICES_STRUCT } from "../../shader/chunk/geometry/triangle/TRIANGLE_VERTICES_STRUCT.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * The resident material texture level a beam reads a triangle's material at: its footprint on the
+ * triangle, in texels of a slot's level 0, as `sample_material_data` and `sample_material_alpha` take
+ * their `texture_level`:
+ *
+ * ```wgsl
+ * fn beam_texture_level(triangle: TriangleVertices, along: vec3<f32>, step_u: vec3<f32>, step_v: vec3<f32>) -> f32
+ * ```
+ *
+ * The beam runs along `along` and spans `step_u` and `step_v` across, all in the triangle's space;
+ * `along` need not be unit length. Each step is carried along the beam onto the triangle's plane and
+ * through the triangle's uv per position. For a step s, direction d and normal n that is
+ * s − d (n·s)/(n·d) on the plane, taken here times n·d, so a triangle turning edge-on, whose footprint
+ * grows without bound, reaches the last level with nothing divided by 0, as a raster's would.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_beam_texture_level = CodeChunk.from(
+    //language=WGSL
+    `
+fn beam_texture_level(
+    triangle: ${TRIANGLE_VERTICES_STRUCT.wgsl_ref},
+    along: vec3<f32>,
+    step_u: vec3<f32>,
+    step_v: vec3<f32>,
+) -> f32 {
+    let edge_1 = triangle.b.position - triangle.a.position;
+    let edge_2 = triangle.c.position - triangle.a.position;
+    let normal = cross(edge_1, edge_2);
+
+    // an offset in the plane is a·edge_1 + b·edge_2, a and b its dots with these
+    let dual_1 = cross(edge_2, normal) / dot(normal, normal);
+    let dual_2 = cross(normal, edge_1) / dot(normal, normal);
+
+    let uv_1 = triangle.b.uv - triangle.a.uv;
+    let uv_2 = triangle.c.uv - triangle.a.uv;
+
+    let facing = dot(normal, along);
+
+    let on_plane_u = facing * step_u - along * dot(normal, step_u);
+    let on_plane_v = facing * step_v - along * dot(normal, step_v);
+
+    let uv_step_u = dot(on_plane_u, dual_1) * uv_1 + dot(on_plane_u, dual_2) * uv_2;
+    let uv_step_v = dot(on_plane_v, dual_1) * uv_1 + dot(on_plane_v, dual_2) * uv_2;
+
+    let span = ${RESIDENT_MATERIAL_TEXTURE_RESOLUTION}.0 * max(length(uv_step_u), length(uv_step_v));
+    let reach = abs(facing);
+
+    // a footprint of a slot or more, edge-on included, is the last level
+    return select(
+        ${RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT - 1}.0,
+        log2(max(span, reach) / reach),
+        span < ${RESIDENT_MATERIAL_TEXTURE_RESOLUTION}.0 * reach
+    );
+}
+`, [
+        TRIANGLE_VERTICES_STRUCT.declaration_chunk,
+    ]);

package/src/shade/renderer/postprocess/nss/NSS.d.ts

@@ -51,7 +51,7 @@ export class NSS {
      * @returns {number}
      */
     static recommended_jitter_sequence_size(upscale_ratio: number): number;
-    static "__#214@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
+    static "__#216@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
     /**
      * @param {GraphicsContext} graphics
      */

package/src/shade/renderer/scene/GPUSceneContext.d.ts

@@ -105,7 +105,7 @@ export class GPUSceneContext {
      * (REVIEW_LEDGER U1): `register` a container with {@link virtual_geometry_residency}, and every
      * page after the root arrives because a cut asked for it. The renderer opens and closes each
      * frame and schedules each reading, and {@link destroy} releases all of it; a host touches none
-     * of it. With them, the source of its geometries' caches and cards ({@link VGeoSDFProxies}): a virtual
+     * of it. With them, the source of its geometries' caches and surface caches ({@link VGeoSDFProxies}): a virtual
      * geometry whose cache is asked for stands in through its proxy.
      *
      * @param {Object} [options] passed to {@link GPUVirtualGeometryPool} and

package/src/shade/renderer/scene/GPUSceneContext.js

@@ -400,7 +400,7 @@ export class GPUSceneContext {
      * (REVIEW_LEDGER U1): `register` a container with {@link virtual_geometry_residency}, and every
      * page after the root arrives because a cut asked for it. The renderer opens and closes each
      * frame and schedules each reading, and {@link destroy} releases all of it; a host touches none
-     * of it. With them, the source of its geometries' caches and cards ({@link VGeoSDFProxies}): a virtual
+     * of it. With them, the source of its geometries' caches and surface caches ({@link VGeoSDFProxies}): a virtual
      * geometry whose cache is asked for stands in through its proxy.
      *
      * @param {Object} [options] passed to {@link GPUVirtualGeometryPool} and

package/src/shade/renderer/shader/chunk/material/albedo_compress.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The code `albedo_compress` (`chunk_albedo_compress.js`) gives an albedo, on the host: each channel
+ * clamped to [0, 1], its square root rounded to f32 and then to unorm8, as `pack4x8unorm` rounds, the
+ * top byte 255.
+ *
+ * @param {number} r linear
+ * @param {number} g linear
+ * @param {number} b linear
+ * @returns {number} u32
+ */
+export function albedo_compress(r: number, g: number, b: number): number;
+//# sourceMappingURL=albedo_compress.d.ts.map

package/src/shade/renderer/shader/chunk/material/albedo_compress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"albedo_compress.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/material/albedo_compress.js"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,mCALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAIlB"}

package/src/shade/renderer/shader/chunk/material/albedo_compress.js

@@ -0,0 +1,26 @@
+import { clamp01 } from "../../../../../core/math/clamp01.js";
+
+/**
+ * The code `albedo_compress` (`chunk_albedo_compress.js`) gives an albedo, on the host: each channel
+ * clamped to [0, 1], its square root rounded to f32 and then to unorm8, as `pack4x8unorm` rounds, the
+ * top byte 255.
+ *
+ * @param {number} r linear
+ * @param {number} g linear
+ * @param {number} b linear
+ * @returns {number} u32
+ */
+export function albedo_compress(r, g, b) {
+    return (unorm8_root(r) | (unorm8_root(g) << 8) | (unorm8_root(b) << 16) | (255 << 24)) >>> 0;
+}
+
+/**
+ * @param {number} v
+ * @returns {number}
+ */
+function unorm8_root(v) {
+    const root = Math.fround(Math.sqrt(Math.fround(clamp01(Math.fround(v)))));
+
+    // ⌊0.5 + 255·e⌋ of the f32 e, which a double holds exactly
+    return Math.floor(0.5 + 255 * root);
+}

package/src/shade/renderer/shader/chunk/material/chunk_albedo_compress.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A diffuse albedo, RGB on [0, 1], in a 32-bit code, as `albedo_uncompress` reads it:
+ *
+ * ```wgsl
+ * fn albedo_compress(albedo: vec3<f32>) -> u32
+ * ```
+ *
+ * Each channel is clamped to [0, 1] and stored as its square root, unorm8, which puts more codes in the
+ * dark. The top byte is 255, so a code is never 0, black
+ * included: a reader may take 0 for no albedo at all.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_albedo_compress: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_albedo_compress.d.ts.map

package/src/shade/renderer/shader/chunk/material/chunk_albedo_compress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_albedo_compress.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/material/chunk_albedo_compress.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,oCAFU,SAAS,CAQhB;0BArBuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/material/chunk_albedo_compress.js

@@ -0,0 +1,22 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * A diffuse albedo, RGB on [0, 1], in a 32-bit code, as `albedo_uncompress` reads it:
+ *
+ * ```wgsl
+ * fn albedo_compress(albedo: vec3<f32>) -> u32
+ * ```
+ *
+ * Each channel is clamped to [0, 1] and stored as its square root, unorm8, which puts more codes in the
+ * dark. The top byte is 255, so a code is never 0, black
+ * included: a reader may take 0 for no albedo at all.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_albedo_compress = CodeChunk.from(
+    //language=WGSL
+    `
+fn albedo_compress(albedo: vec3<f32>) -> u32 {
+    return pack4x8unorm(vec4<f32>(sqrt(saturate(albedo)), 1.0));
+}
+`);

package/src/shade/renderer/shader/chunk/material/chunk_albedo_uncompress.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A diffuse albedo from the code `albedo_compress` wrote:
+ *
+ * ```wgsl
+ * fn albedo_uncompress(code: u32) -> vec3<f32> // RGB on [0, 1]
+ * ```
+ *
+ * The code's low three bytes are the square roots of R, G and B, unorm8; its top byte is 255 for every
+ * albedo.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_albedo_uncompress: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_albedo_uncompress.d.ts.map

package/src/shade/renderer/shader/chunk/material/chunk_albedo_uncompress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_albedo_uncompress.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/material/chunk_albedo_uncompress.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,sCAFU,SAAS,CAUhB;0BAtBuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/material/chunk_albedo_uncompress.js

@@ -0,0 +1,23 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * A diffuse albedo from the code `albedo_compress` wrote:
+ *
+ * ```wgsl
+ * fn albedo_uncompress(code: u32) -> vec3<f32> // RGB on [0, 1]
+ * ```
+ *
+ * The code's low three bytes are the square roots of R, G and B, unorm8; its top byte is 255 for every
+ * albedo.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_albedo_uncompress = CodeChunk.from(
+    //language=WGSL
+    `
+fn albedo_uncompress(code: u32) -> vec3<f32> {
+    let root = unpack4x8unorm(code).rgb;
+
+    return root * root;
+}
+`);

package/src/shade/renderer/shader/chunk/material/chunk_metal_rough_compress.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Metalness and roughness, each on [0, 1], in a code of `METAL_ROUGH_CODE_BITS` bits, as
+ * `metal_rough_uncompress` reads it:
+ *
+ * ```wgsl
+ * fn metal_rough_compress(metal_rough: vec2<f32>) -> u32 // (metalness, roughness)
+ * ```
+ *
+ * Each is clamped to [0, 1] and rounded to the nearest of 2^{@link METAL_ROUGH_CHANNEL_BITS} even
+ * steps, metalness in the low bits.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_metal_rough_compress: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_metal_rough_compress.d.ts.map

package/src/shade/renderer/shader/chunk/material/chunk_metal_rough_compress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_metal_rough_compress.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/material/chunk_metal_rough_compress.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,yCAFU,SAAS,CAUhB;0BAxBuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/material/chunk_metal_rough_compress.js

@@ -0,0 +1,25 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+import { METAL_ROUGH_CHANNEL_BITS } from "./chunk_metal_rough_uncompress.js";
+
+/**
+ * Metalness and roughness, each on [0, 1], in a code of `METAL_ROUGH_CODE_BITS` bits, as
+ * `metal_rough_uncompress` reads it:
+ *
+ * ```wgsl
+ * fn metal_rough_compress(metal_rough: vec2<f32>) -> u32 // (metalness, roughness)
+ * ```
+ *
+ * Each is clamped to [0, 1] and rounded to the nearest of 2^{@link METAL_ROUGH_CHANNEL_BITS} even
+ * steps, metalness in the low bits.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_metal_rough_compress = CodeChunk.from(
+    //language=WGSL
+    `
+fn metal_rough_compress(metal_rough: vec2<f32>) -> u32 {
+    let q = vec2<u32>(round(saturate(metal_rough) * ${2 ** METAL_ROUGH_CHANNEL_BITS - 1}.0));
+
+    return q.x | (q.y << ${METAL_ROUGH_CHANNEL_BITS}u);
+}
+`);