@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/shader/chunk/subgroup/chunk_subgroup_append_slot.js

@@ -0,0 +1,60 @@
+import { UINT32_MAX } from "../../../../../core/binary/UINT32_MAX.js";
+import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * What {@link chunk_subgroup_append_slot} hands a lane that holds no slot: one that did not append,
+ * or one whose place fell at or past the capacity. The engine's one "no index" word, which no
+ * capacity reaches, so `slot < capacity` tests for it as well as `slot != SUBGROUP_APPEND_NONE` does.
+ *
+ * @type {number}
+ */
+export const SUBGROUP_APPEND_NONE = UINT32_MAX;
+
+/**
+ * Claim a lane's slot in an append-only list, one atomic per subgroup: the subgroup counts the lanes
+ * that append, its first active lane adds that many to `count` with one `atomicAdd`, and each
+ * appending lane takes its place by its exclusive prefix over the subgroup.
+ *
+ * `fn subgroup_append_slot(count: ptr<storage, atomic<u32>, read_write>, want: bool, capacity: u32) -> u32`
+ *
+ * Returns the lane's slot, below `capacity`, or {@link SUBGROUP_APPEND_NONE}. Past `capacity` the
+ * count still rises — so whoever reads the list can tell it overflowed, and by how much — but no slot
+ * is handed out: what the list holds is only ever its first `capacity` entries, and the caller writes
+ * only into a slot it was given.
+ *
+ * Every lane of the subgroup calls it, appending or not, from subgroup-uniform control flow.
+ * The order of entries across subgroups is whatever order their atomics land in.
+ *
+ * Nothing here assumes how subgroups map onto `local_invocation_index`.
+ *
+ * @see chunk_collection_u32_append for a list of `u32`s
+ * @type {CodeChunk}
+ */
+export const chunk_subgroup_append_slot = CodeChunk.from(
+    //language=WGSL
+    `
+fn subgroup_append_slot(count: ptr<storage, atomic<u32>, read_write>, want: bool, capacity: u32) -> u32 {
+    let wanted = select(0u, 1u, want);
+
+    // where this lane's entry falls among the subgroup's, and how many the subgroup appends
+    let offset = subgroupExclusiveAdd(wanted);
+    let total = subgroupAdd(wanted);
+    let elected = subgroupElect();
+
+    var base = 0u;
+
+    if (elected && total > 0u) {
+        base = atomicAdd(count, total);
+    }
+
+    // the elected lane is the first active one, and that is whose value this hands to every lane
+    base = subgroupBroadcastFirst(base);
+
+    let slot = base + offset;
+
+    return select(${SUBGROUP_APPEND_NONE}u, slot, want && slot < capacity);
+}
+`);
+
+chunk_subgroup_append_slot.addExtension(WebGPUExtensionType.Subgroups);

package/src/shade/renderer/shader/chunk/subgroup/chunk_subgroup_atomic_add.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Add every lane's `value` to a counter with one atomic per subgroup: the subgroup sums the values,
+ * and its first active lane adds the sum with one `atomicAdd`, skipped when the sum is 0.
+ *
+ * `fn subgroup_atomic_add_u32(counter: ptr<storage, atomic<u32>, read_write>, value: u32)`
+ *
+ * Every lane of the subgroup calls it, from subgroup-uniform control flow. Nothing here assumes how
+ * subgroups map onto `local_invocation_index`.
+ *
+ * @see chunk_subgroup_append_slot for a count that hands each lane its place
+ * @type {CodeChunk}
+ */
+export const chunk_subgroup_atomic_add: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_subgroup_atomic_add.d.ts.map

package/src/shade/renderer/shader/chunk/subgroup/chunk_subgroup_atomic_add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_subgroup_atomic_add.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/subgroup/chunk_subgroup_atomic_add.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,wCAFU,SAAS,CAahB;0BAzBuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/subgroup/chunk_subgroup_atomic_add.js

@@ -0,0 +1,29 @@
+import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * Add every lane's `value` to a counter with one atomic per subgroup: the subgroup sums the values,
+ * and its first active lane adds the sum with one `atomicAdd`, skipped when the sum is 0.
+ *
+ * `fn subgroup_atomic_add_u32(counter: ptr<storage, atomic<u32>, read_write>, value: u32)`
+ *
+ * Every lane of the subgroup calls it, from subgroup-uniform control flow. Nothing here assumes how
+ * subgroups map onto `local_invocation_index`.
+ *
+ * @see chunk_subgroup_append_slot for a count that hands each lane its place
+ * @type {CodeChunk}
+ */
+export const chunk_subgroup_atomic_add = CodeChunk.from(
+    //language=WGSL
+    `
+fn subgroup_atomic_add_u32(counter: ptr<storage, atomic<u32>, read_write>, value: u32) {
+    let total = subgroupAdd(value);
+    let elected = subgroupElect();
+
+    if (elected && total > 0u) {
+        atomicAdd(counter, total);
+    }
+}
+`);
+
+chunk_subgroup_atomic_add.addExtension(WebGPUExtensionType.Subgroups);

package/src/shade/renderer/shader/chunk/texture/TEXTURE3D_TRILINEAR_CORNERS_STRUCT.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The eight texels of a trilinear tap on a single channel of a 3-D texture, and where the point sits
+ * between them.
+ *
+ * - `z0`: the four corners on the lower z face, x fastest: `(x0 y0, x1 y0, x0 y1, x1 y1)` — the
+ *   order `interpolate_bilinear_f32` takes;
+ * - `z1`: the same four on the upper z face;
+ * - `weight`: the fraction from the lower corner toward the upper one along x, y and z, in [0, 1].
+ *
+ * Interpolation is `texture3d_trilinear_interpolate`; the eight values themselves are what a
+ * MacCormack limiter clamps its correction to.
+ */
+export const TEXTURE3D_TRILINEAR_CORNERS_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../type/WebGPUStruct.js";
+//# sourceMappingURL=TEXTURE3D_TRILINEAR_CORNERS_STRUCT.d.ts.map

package/src/shade/renderer/shader/chunk/texture/TEXTURE3D_TRILINEAR_CORNERS_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TEXTURE3D_TRILINEAR_CORNERS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/texture/TEXTURE3D_TRILINEAR_CORNERS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,8DAIgC;6BAlBH,4BAA4B"}

package/src/shade/renderer/shader/chunk/texture/TEXTURE3D_TRILINEAR_CORNERS_STRUCT.js

@@ -0,0 +1,20 @@
+import { vec3f, vec4f } from "../../type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../type/WebGPUStruct.js";
+
+/**
+ * The eight texels of a trilinear tap on a single channel of a 3-D texture, and where the point sits
+ * between them.
+ *
+ * - `z0`: the four corners on the lower z face, x fastest: `(x0 y0, x1 y0, x0 y1, x1 y1)` — the
+ *   order `interpolate_bilinear_f32` takes;
+ * - `z1`: the same four on the upper z face;
+ * - `weight`: the fraction from the lower corner toward the upper one along x, y and z, in [0, 1].
+ *
+ * Interpolation is `texture3d_trilinear_interpolate`; the eight values themselves are what a
+ * MacCormack limiter clamps its correction to.
+ */
+export const TEXTURE3D_TRILINEAR_CORNERS_STRUCT = WebGPUStruct.from({
+    z0: vec4f,
+    z1: vec4f,
+    weight: vec3f,
+}, "Texture3DTrilinearCorners");

package/src/shade/renderer/shader/chunk/texture/chunk_texel_coordinate_to_uv3.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A 3-D texel coordinate to UVW, cell-centred: texel `c` covers `[c, c + 1)` in texel units and is
+ * centred at coordinate `c`, which lands at `(c + 0.5) / size` — the convention of a texture
+ * sampled with a linear filter, and the one the volumetrics noise tap documents. The 3-D sibling of
+ * `texel_coordinate_to_uv`; {@link chunk_uv3_to_texel_coordinate} is its inverse.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_texel_coordinate_to_uv3: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_texel_coordinate_to_uv3.d.ts.map

package/src/shade/renderer/shader/chunk/texture/chunk_texel_coordinate_to_uv3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_texel_coordinate_to_uv3.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/texture/chunk_texel_coordinate_to_uv3.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,4CAFU,SAAS,CASjB;0BAjBwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/texture/chunk_texel_coordinate_to_uv3.js

@@ -0,0 +1,18 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * A 3-D texel coordinate to UVW, cell-centred: texel `c` covers `[c, c + 1)` in texel units and is
+ * centred at coordinate `c`, which lands at `(c + 0.5) / size` — the convention of a texture
+ * sampled with a linear filter, and the one the volumetrics noise tap documents. The 3-D sibling of
+ * `texel_coordinate_to_uv`; {@link chunk_uv3_to_texel_coordinate} is its inverse.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_texel_coordinate_to_uv3 = CodeChunk.from(
+    //language=WGSL
+    `
+fn texel_coordinate_to_uv3(coordinate: vec3<f32>, texture_size: vec3<u32>) -> vec3<f32> {
+    return (coordinate + 0.5) / vec3<f32>(texture_size);
+}
+    `
+);

package/src/shade/renderer/shader/chunk/texture/chunk_uv3_to_texel_coordinate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * UVW to a 3-D texel coordinate, cell-centred: uv 0 is the near edge of texel 0, half a texel
+ * before its centre at coordinate 0, so the result is `uv * size - 0.5` and its floor and fraction
+ * are a trilinear tap's lower corner and weights. The 3-D sibling of `uv_to_texel_coordinate`;
+ * {@link chunk_texel_coordinate_to_uv3} is its inverse.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_uv3_to_texel_coordinate: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_uv3_to_texel_coordinate.d.ts.map

package/src/shade/renderer/shader/chunk/texture/chunk_uv3_to_texel_coordinate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_uv3_to_texel_coordinate.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/texture/chunk_uv3_to_texel_coordinate.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,4CAFU,SAAS,CASjB;0BAjBwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/texture/chunk_uv3_to_texel_coordinate.js

@@ -0,0 +1,18 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * UVW to a 3-D texel coordinate, cell-centred: uv 0 is the near edge of texel 0, half a texel
+ * before its centre at coordinate 0, so the result is `uv * size - 0.5` and its floor and fraction
+ * are a trilinear tap's lower corner and weights. The 3-D sibling of `uv_to_texel_coordinate`;
+ * {@link chunk_texel_coordinate_to_uv3} is its inverse.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_uv3_to_texel_coordinate = CodeChunk.from(
+    //language=WGSL
+    `
+fn uv3_to_texel_coordinate(uv: vec3<f32>, texture_size: vec3<u32>) -> vec3<f32> {
+    return fma(uv, vec3<f32>(texture_size), vec3(-0.5));
+}
+`
+);

package/src/shade/renderer/shader/chunk/texture/sample/chunk_texture3d_trilinear_corners.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The eight texels at `lo` and `hi`, absolute texel coordinates of the lower and upper corner along
+ * each axis (equal on an axis held at an edge), and `weight`, the fraction from `lo` toward `hi`.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_corners_load: CodeChunk;
+/**
+ * The corners of a tap at a texel coordinate in a region of the texture: texel `c` of the region is
+ * centred at coordinate `c`, the region starts at `region_offset` and is `region_size` texels
+ * across. Each corner is clamped to the region on its own, so a coordinate past an edge reads the
+ * edge texel on both sides — clamp-to-edge, and nothing outside the region is ever loaded.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_corners: CodeChunk;
+/**
+ * Corner-aligned: uv 0 is the centre of the region's first texel and uv 1 the centre of its last,
+ * so the texel coordinate is `uv · (size − 1)`; uv outside [0, 1] reads the edge. How the geometry
+ * SDF reads a tile of its atlas.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_corners_corner_aligned: CodeChunk;
+/**
+ * Cell-centred: texel `c` covers `[c, c + 1)` and is centred at uv `(c + 0.5) / size`, so the
+ * texel coordinate is `uv · size − 0.5`; past the outer half texel the edge is held. How a linear
+ * sampler reads a texture, and how a grid of cells (a fluid's) is read.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_corners_cell_centred: CodeChunk;
+/**
+ * The trilinear blend of a tap's corners: bilinear across each z face, then along z.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_interpolate: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_texture3d_trilinear_corners.d.ts.map

package/src/shade/renderer/shader/chunk/texture/sample/chunk_texture3d_trilinear_corners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_texture3d_trilinear_corners.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/texture/sample/chunk_texture3d_trilinear_corners.js"],"names":[],"mappings":"AAwBA;;;;GAIG;AACH,qDAFU,SAAS,CA8BjB;AAEF;;;;;;GAMG;AACH,gDAFU,SAAS,CA0BjB;AAEF;;;;;GAKG;AACH,+DAFU,SAAS,CAmBjB;AAEF;;;;;GAKG;AACH,6DAFU,SAAS,CAkBjB;AAEF;;;GAGG;AACH,oDAFU,SAAS,CAejB;0BA9JwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/texture/sample/chunk_texture3d_trilinear_corners.js

@@ -0,0 +1,159 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_uv3_to_texel_coordinate } from "../chunk_uv3_to_texel_coordinate.js";
+import { TEXTURE3D_TRILINEAR_CORNERS_STRUCT } from "../TEXTURE3D_TRILINEAR_CORNERS_STRUCT.js";
+import { chunk_interpolate_bilinear_f32 } from "./chunk_interpolate_bilinear_f32.js";
+
+/*
+ A trilinear tap on the first channel of a texture_3d<f32>, done by hand: eight textureLoads and
+ f32 weights, where a filtering sampler gives as little as 4 bits of weight. Two uses: the blend
+ (texture3d_trilinear_interpolate), and the eight corners themselves, which bound the blend and are
+ what a MacCormack limiter clamps its correction to.
+
+ The pieces, smallest first:
+ - texture3d_trilinear_corners_load: the eight texels at given lower and upper corners. A reader
+   with its own addressing (a toroidal window wraps each corner on its own) computes the corners
+   and calls this.
+ - texture3d_trilinear_corners: a region of the texture, a texel coordinate with texel c centred at
+   c, and the corners clamped to the region (clamp-to-edge; nothing outside the region is read).
+ - two concrete alignments over uv in [0, 1] of the region:
+   - corner-aligned: uv 0 is the first texel's centre and uv 1 the last's, uv outside [0, 1] the
+     edge. A distance field sampled at its own lattice points reads this way.
+   - cell-centred: texel c covers [c, c + 1) and is centred at uv (c + 0.5) / n. A grid of cells (a
+     fluid's) reads this way, as a linear sampler would.
+*/
+
+/**
+ * The eight texels at `lo` and `hi`, absolute texel coordinates of the lower and upper corner along
+ * each axis (equal on an axis held at an edge), and `weight`, the fraction from `lo` toward `hi`.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_corners_load = CodeChunk.from(
+    //language=WGSL
+    `
+fn texture3d_trilinear_corners_load(
+    source: texture_3d<f32>,
+    lo: vec3<u32>,
+    hi: vec3<u32>,
+    weight: vec3<f32>
+) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    let c000 = textureLoad(source, lo, 0).r;
+    let c100 = textureLoad(source, vec3<u32>(hi.x, lo.y, lo.z), 0).r;
+    let c010 = textureLoad(source, vec3<u32>(lo.x, hi.y, lo.z), 0).r;
+    let c110 = textureLoad(source, vec3<u32>(hi.x, hi.y, lo.z), 0).r;
+
+    let c001 = textureLoad(source, vec3<u32>(lo.x, lo.y, hi.z), 0).r;
+    let c101 = textureLoad(source, vec3<u32>(hi.x, lo.y, hi.z), 0).r;
+    let c011 = textureLoad(source, vec3<u32>(lo.x, hi.y, hi.z), 0).r;
+    let c111 = textureLoad(source, hi, 0).r;
+
+    return ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}(
+        vec4<f32>(c000, c100, c010, c110),
+        vec4<f32>(c001, c101, c011, c111),
+        weight
+    );
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+    ]
+);
+
+/**
+ * The corners of a tap at a texel coordinate in a region of the texture: texel `c` of the region is
+ * centred at coordinate `c`, the region starts at `region_offset` and is `region_size` texels
+ * across. Each corner is clamped to the region on its own, so a coordinate past an edge reads the
+ * edge texel on both sides — clamp-to-edge, and nothing outside the region is ever loaded.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_corners = CodeChunk.from(
+    //language=WGSL
+    `
+fn texture3d_trilinear_corners(
+    source: texture_3d<f32>,
+    region_offset: vec3<u32>,
+    region_size: vec3<u32>,
+    texel: vec3<f32>
+) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    // floor before converting: a negative coordinate truncated toward zero would take the wrong
+    // lower corner, while the weight below would still be measured from the floor
+    let base = floor(texel);
+    let base_i = vec3<i32>(base);
+    let max_texel = vec3<i32>(region_size) - vec3<i32>(1);
+
+    let lo = vec3<u32>(clamp(base_i, vec3<i32>(0), max_texel));
+    let hi = vec3<u32>(clamp(base_i + vec3<i32>(1), vec3<i32>(0), max_texel));
+
+    return texture3d_trilinear_corners_load(source, region_offset + lo, region_offset + hi, texel - base);
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+        chunk_texture3d_trilinear_corners_load,
+    ]
+);
+
+/**
+ * Corner-aligned: uv 0 is the centre of the region's first texel and uv 1 the centre of its last,
+ * so the texel coordinate is `uv · (size − 1)`; uv outside [0, 1] reads the edge. How the geometry
+ * SDF reads a tile of its atlas.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_corners_corner_aligned = CodeChunk.from(
+    //language=WGSL
+    `
+fn texture3d_trilinear_corners_corner_aligned(
+    source: texture_3d<f32>,
+    region_offset: vec3<u32>,
+    region_size: vec3<u32>,
+    uv: vec3<f32>
+) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    let texel = saturate(uv) * vec3<f32>(region_size - vec3<u32>(1u));
+
+    return texture3d_trilinear_corners(source, region_offset, region_size, texel);
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+        chunk_texture3d_trilinear_corners,
+    ]
+);
+
+/**
+ * Cell-centred: texel `c` covers `[c, c + 1)` and is centred at uv `(c + 0.5) / size`, so the
+ * texel coordinate is `uv · size − 0.5`; past the outer half texel the edge is held. How a linear
+ * sampler reads a texture, and how a grid of cells (a fluid's) is read.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_corners_cell_centred = CodeChunk.from(
+    //language=WGSL
+    `
+fn texture3d_trilinear_corners_cell_centred(
+    source: texture_3d<f32>,
+    region_offset: vec3<u32>,
+    region_size: vec3<u32>,
+    uv: vec3<f32>
+) -> ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref} {
+    return texture3d_trilinear_corners(source, region_offset, region_size, uv3_to_texel_coordinate(uv, region_size));
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+        chunk_texture3d_trilinear_corners,
+        chunk_uv3_to_texel_coordinate,
+    ]
+);
+
+/**
+ * The trilinear blend of a tap's corners: bilinear across each z face, then along z.
+ * @type {CodeChunk}
+ */
+export const chunk_texture3d_trilinear_interpolate = CodeChunk.from(
+    //language=WGSL
+    `
+fn texture3d_trilinear_interpolate(corners: ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}) -> f32 {
+    let lower = interpolate_bilinear_f32(corners.z0, corners.weight.xy);
+    let upper = interpolate_bilinear_f32(corners.z1, corners.weight.xy);
+
+    return mix(lower, upper, corners.weight.z);
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+        chunk_interpolate_bilinear_f32,
+    ]
+);

package/src/shade/renderer/shader/compiler/CodeChunk.d.ts

@@ -1,7 +1,12 @@
 /**
+ * @typedef {import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor} ShaderResourceDescriptor
  * @typedef {import("./ShaderSwitch.js").ShaderSwitch} ShaderSwitch
  * @typedef {import("./ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
  */
+/**
+ * A binding some chunk of a linked graph reads, and the first chunk in link order that declared it.
+ * @typedef {{resource: ShaderResourceDescriptor, chunk: CodeChunk}} CodeChunkResourceRequirement
+ */
 export class CodeChunk {
     /**
      * Special singleton
@@ -21,7 +26,7 @@ export class CodeChunk {
      * @param {Map<CodeChunk, CodeChunk>} memo what each chunk of this call's graph became
      * @returns {CodeChunk}
      */
-    static "__#71@#specialize"(chunk: CodeChunk, set: ShaderSwitchSet, memo: Map<CodeChunk, CodeChunk>): CodeChunk;
+    static "__#77@#specialize"(chunk: CodeChunk, set: ShaderSwitchSet, memo: Map<CodeChunk, CodeChunk>): CodeChunk;
     get isCodeChunk(): boolean;
     /**
      *
@@ -39,6 +44,22 @@ export class CodeChunk {
      * @returns {boolean} true iff added, false if already present
      */
     addLanguageExtension(extension: string): boolean;
+    /**
+     * Declare that this chunk's own text reads the binding `resource` describes. A link collects these
+     * over the graph it links, as it does extensions ({@link compile}), and a shader checks each against
+     * the resources it binds, so a missing or mistyped binding is an error naming this chunk.
+     *
+     * @param {ShaderResourceDescriptor} resource a declaration, see {@link ShaderResourceDescriptor.uniform} and its siblings
+     * @returns {boolean} true iff added, false if already present
+     */
+    requireResource(resource: ShaderResourceDescriptor): boolean;
+    /**
+     * The bindings this chunk's own text declares it reads; see {@link requireResource}. Its
+     * dependencies declare their own.
+     *
+     * @returns {ShaderResourceDescriptor[]}
+     */
+    get required_resources(): import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor[];
     /**
      *
      * @param {CodeChunk} dependency
@@ -88,12 +109,16 @@ export class CodeChunk {
      */
     coalesceDependencies(): CodeChunk[];
     /**
-     * @returns {{text:string, extensions: string[], language_extensions: string[]}}
+     * `resources` holds every binding a chunk of the graph declared it reads ({@link requireResource}),
+     * once per declaration, with the first chunk in link order that declared it.
+     *
+     * @returns {{text:string, extensions: string[], language_extensions: string[], resources: CodeChunkResourceRequirement[]}}
      */
     compile(): {
         text: string;
         extensions: string[];
         language_extensions: string[];
+        resources: CodeChunkResourceRequirement[];
     };
     toString(): string;
     /**
@@ -119,7 +144,15 @@ export class CodeChunk {
     equals(other: CodeChunk): boolean;
     #private;
 }
+export type ShaderResourceDescriptor = import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor;
 export type ShaderSwitch = import("./ShaderSwitch.js").ShaderSwitch;
 export type ShaderSwitchSet = import("./ShaderSwitchSet.js").ShaderSwitchSet;
+/**
+ * A binding some chunk of a linked graph reads, and the first chunk in link order that declared it.
+ */
+export type CodeChunkResourceRequirement = {
+    resource: ShaderResourceDescriptor;
+    chunk: CodeChunk;
+};
 import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
 //# sourceMappingURL=CodeChunk.d.ts.map

package/src/shade/renderer/shader/compiler/CodeChunk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CodeChunk.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/compiler/CodeChunk.js"],"names":[],"mappings":"AAMA;;;GAGG;AAGH;IAMI;;;OAGG;IACH,cAFU,SAAS,SAAS,CAAC,CAEoB;IAkGjD;;;;;OAKG;IACH,kBAHW,MAAM,iBADN,SAAS,EAAE,GAET,SAAS,CAqBrB;IA+JD;;;;;OAKG;IACH,kCALW,SAAS,OACT,eAAe,QACf,IAAI,SAAS,EAAE,SAAS,CAAC,GACvB,SAAS,CAsDrB;IA5VD,2BAEC;IAcD;;;OAGG;IACH,mBAEC;IAeD;;;;OAIG;IACH,wBAHW,mBAAmB,GACjB,OAAO,CAMnB;IAkBD;;;OAGG;IACH,gCAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;OAIG;IACH,0BAHW,SAAS,GACP,OAAO,CAmBnB;IAqCD;;;;OAIG;IACH,6CAHW,IAAI,SAAS,CAAC,GACZ,OAAO,CAgBnB;IAED;;;;OAIG;IACH,+BAHW,SAAS,GACP,OAAO,CAqBnB;IAED;;;OAGG;IACH,uBAFa,SAAS,EAAE,CAuCvB;IAED;;;;;;OAMG;IACH,mBAFa,YAAY,EAAE,CA0C1B;IAED;;;;;;;;;;OAUG;IACH,gBAHW,eAAe,GACb,SAAS,CAOrB;IA8DD;;;OAGG;IACH,wBAFY,SAAS,EAAE,CAgDtB;IAED;;OAEG;IACH,WAFa;QAAC,IAAI,EAAC,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,mBAAmB,EAAE,MAAM,EAAE,CAAA;KAAC,CA4C9E;IAED,mBAEC;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,YAFW,SAAS,QAOnB;IAED;;;OAGG;IACH,SAFY,SAAS,CAQpB;IAED;;;;OAIG;IACH,cAHW,SAAS,GACP,OAAO,CAgBnB;;CACJ;2BA/fY,OAAO,mBAAmB,EAAE,YAAY;8BACxC,OAAO,sBAAsB,EAAE,eAAe;oCAJvB,4CAA4C"}
+{"version":3,"file":"CodeChunk.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/compiler/CodeChunk.js"],"names":[],"mappings":"AAMA;;;;GAIG;AAEH;;;GAGG;AAGH;IAMI;;;OAGG;IACH,cAFU,SAAS,SAAS,CAAC,CAEoB;IAiIjD;;;;;OAKG;IACH,kBAHW,MAAM,iBADN,SAAS,EAAE,GAET,SAAS,CAqBrB;IA+JD;;;;;OAKG;IACH,kCALW,SAAS,OACT,eAAe,QACf,IAAI,SAAS,EAAE,SAAS,CAAC,GACvB,SAAS,CAuDrB;IA5XD,2BAEC;IAcD;;;OAGG;IACH,mBAEC;IAeD;;;;OAIG;IACH,wBAHW,mBAAmB,GACjB,OAAO,CAMnB;IAkBD;;;OAGG;IACH,gCAHW,MAAM,GACJ,OAAO,CAMnB;IAQD;;;;;;;OAOG;IACH,0BAHW,wBAAwB,GACtB,OAAO,CAOnB;IAED;;;;;OAKG;IACH,uGAEC;IAED;;;;OAIG;IACH,0BAHW,SAAS,GACP,OAAO,CAmBnB;IAqCD;;;;OAIG;IACH,6CAHW,IAAI,SAAS,CAAC,GACZ,OAAO,CAgBnB;IAED;;;;OAIG;IACH,+BAHW,SAAS,GACP,OAAO,CAqBnB;IAED;;;OAGG;IACH,uBAFa,SAAS,EAAE,CAuCvB;IAED;;;;;;OAMG;IACH,mBAFa,YAAY,EAAE,CA0C1B;IAED;;;;;;;;;;OAUG;IACH,gBAHW,eAAe,GACb,SAAS,CAOrB;IA+DD;;;OAGG;IACH,wBAFY,SAAS,EAAE,CAgDtB;IAED;;;;;OAKG;IACH,WAFa;QAAC,IAAI,EAAC,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,mBAAmB,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,4BAA4B,EAAE,CAAA;KAAC,CAiEzH;IAED,mBAEC;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,YAFW,SAAS,QAQnB;IAED;;;OAGG;IACH,SAFY,SAAS,CAQpB;IAED;;;;OAIG;IACH,cAHW,SAAS,GACP,OAAO,CAgBnB;;CACJ;uCA9jBY,OAAO,yCAAyC,EAAE,wBAAwB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;8BACxC,OAAO,sBAAsB,EAAE,eAAe;;;;2CAK9C;IAAC,QAAQ,EAAE,wBAAwB,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAC;oCAV/B,4CAA4C"}

package/src/shade/renderer/shader/compiler/CodeChunk.js

@@ -5,10 +5,16 @@ import { computeStringHash } from "../../../../core/primitives/strings/computeSt
 import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
 
 /**
+ * @typedef {import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor} ShaderResourceDescriptor
  * @typedef {import("./ShaderSwitch.js").ShaderSwitch} ShaderSwitch
  * @typedef {import("./ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
  */
 
+/**
+ * A binding some chunk of a linked graph reads, and the first chunk in link order that declared it.
+ * @typedef {{resource: ShaderResourceDescriptor, chunk: CodeChunk}} CodeChunkResourceRequirement
+ */
+
 
 export class CodeChunk {
 
@@ -86,6 +92,37 @@ export class CodeChunk {
         return array_push_if_unique(this.#language_extensions, extension);
     }
 
+    /**
+     * Bindings this chunk's own text reads.
+     * @type {ShaderResourceDescriptor[]}
+     */
+    #resources = [];
+
+    /**
+     * Declare that this chunk's own text reads the binding `resource` describes. A link collects these
+     * over the graph it links, as it does extensions ({@link compile}), and a shader checks each against
+     * the resources it binds, so a missing or mistyped binding is an error naming this chunk.
+     *
+     * @param {ShaderResourceDescriptor} resource a declaration, see {@link ShaderResourceDescriptor.uniform} and its siblings
+     * @returns {boolean} true iff added, false if already present
+     */
+    requireResource(resource) {
+        assert.defined(resource, 'resource');
+        assert.equal(resource.isShaderResourceDescriptor, true, 'resource.isShaderResourceDescriptor !== true');
+
+        return array_push_if_unique(this.#resources, resource);
+    }
+
+    /**
+     * The bindings this chunk's own text declares it reads; see {@link requireResource}. Its
+     * dependencies declare their own.
+     *
+     * @returns {ShaderResourceDescriptor[]}
+     */
+    get required_resources() {
+        return this.#resources;
+    }
+
     /**
      *
      * @param {CodeChunk} dependency
@@ -355,6 +392,7 @@ export class CodeChunk {
             r.#dependencies = specialized;
             r.#extensions = chunk.#extensions.slice();
             r.#language_extensions = chunk.#language_extensions.slice();
+            r.#resources = chunk.#resources.slice();
         }
 
         memo.set(chunk, r);
@@ -415,7 +453,10 @@ export class CodeChunk {
     }
 
     /**
-     * @returns {{text:string, extensions: string[], language_extensions: string[]}}
+     * `resources` holds every binding a chunk of the graph declared it reads ({@link requireResource}),
+     * once per declaration, with the first chunk in link order that declared it.
+     *
+     * @returns {{text:string, extensions: string[], language_extensions: string[], resources: CodeChunkResourceRequirement[]}}
      */
     compile() {
 
@@ -425,6 +466,16 @@ export class CodeChunk {
         const extension_hash = {};
         const language_extension_hash = {};
 
+        /**
+         * @type {CodeChunkResourceRequirement[]}
+         */
+        const resources = [];
+
+        /**
+         * @type {Set<ShaderResourceDescriptor>}
+         */
+        const required = new Set();
+
         /**
          *
          * @type {string[]}
@@ -446,6 +497,16 @@ export class CodeChunk {
             for (let j = 0; j < lang_ext.length; j++) {
                 language_extension_hash[lang_ext[j]] = true;
             }
+
+            const res = chunk.#resources;
+            for (let j = 0; j < res.length; j++) {
+                const resource = res[j];
+
+                if (!required.has(resource)) {
+                    required.add(resource);
+                    resources.push({ resource, chunk });
+                }
+            }
         }
 
         // Enable required extensions
@@ -457,7 +518,8 @@ export class CodeChunk {
         return {
             text,
             extensions,
-            language_extensions
+            language_extensions,
+            resources
         };
     }
 
@@ -482,6 +544,7 @@ export class CodeChunk {
         this.#dependencies = other.#dependencies.slice();
         this.#extensions = other.#extensions.slice();
         this.#language_extensions = other.#language_extensions.slice();
+        this.#resources = other.#resources.slice();
     }
 
     /**

package/src/shade/renderer/shader/compiler/CodeChunkChoice.d.ts

@@ -1,4 +1,5 @@
 /**
+ * @typedef {import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor} ShaderResourceDescriptor
  * @typedef {import("./ShaderSwitch.js").ShaderSwitch} ShaderSwitch
  * @typedef {import("./ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
  */
@@ -68,6 +69,7 @@ export class CodeChunkChoice extends CodeChunk {
     readonly isCodeChunkChoice: boolean;
     #private;
 }
+export type ShaderResourceDescriptor = import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor;
 export type ShaderSwitch = import("./ShaderSwitch.js").ShaderSwitch;
 export type ShaderSwitchSet = import("./ShaderSwitchSet.js").ShaderSwitchSet;
 import { CodeChunk } from "./CodeChunk.js";

package/src/shade/renderer/shader/compiler/CodeChunkChoice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CodeChunkChoice.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/compiler/CodeChunkChoice.js"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAsHI;;;OAGG;IACH,2BAHW,YAAY,GACV,eAAe,CAW3B;IA7HD;;OAEG;IACH,8DAEC;IAQD;;;OAGG;IACH,gCAEC;IAED;;;;;OAKG;IACH,WALW,MAAM,GAAC,OAAO,eAEd,SAAS,QAcnB;IAED;;;;OAIG;IACH,qBAJW,eAAe,GACb,SAAS,CAarB;IAkBD;;OAEG;IACH,gBAEC;IAWD;;OAEG;IACH,YAFW,eAAe,QAKzB;IAED;;OAEG;IACH,SAFa,eAAe,CAQ3B;IAsBL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;2BA3JY,OAAO,mBAAmB,EAAE,YAAY;8BACxC,OAAO,sBAAsB,EAAE,eAAe;0BAJjC,gBAAgB"}
+{"version":3,"file":"CodeChunkChoice.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/compiler/CodeChunkChoice.js"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA+HI;;;OAGG;IACH,2BAHW,YAAY,GACV,eAAe,CAW3B;IAtID;;OAEG;IACH,8DAEC;IAQD;;;OAGG;IACH,gCAEC;IAED;;;;;OAKG;IACH,WALW,MAAM,GAAC,OAAO,eAEd,SAAS,QAcnB;IAED;;;;OAIG;IACH,qBAJW,eAAe,GACb,SAAS,CAarB;IA2BD;;OAEG;IACH,gBAEC;IAWD;;OAEG;IACH,YAFW,eAAe,QAKzB;IAED;;OAEG;IACH,SAFa,eAAe,CAQ3B;IAsBL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;uCArKY,OAAO,yCAAyC,EAAE,wBAAwB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;8BACxC,OAAO,sBAAsB,EAAE,eAAe;0BALjC,gBAAgB"}