@woosh/meep-engine 3.30.0 → 3.32.0

package/src/shade/renderer/shadow/map/csm/shader/shader_csm_caster_range.js

@@ -1,194 +1,219 @@
-import { atomic_u32, u32, vec4f } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
-import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
-import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
-import { ComputeShader } from "../../../../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
-import { chunk_aabb_atomic_f32 } from "../../../../animation/skinning/bounds_refresh/chunk_aabb_atomic_f32.js";
-import { LIGHT_DATABASE_SPEC } from "../../../../light/LIGHT_DATABASE_SPEC.js";
-import { MESHES_TABLE } from "../../../../scene/chunk_scene_database_access.js";
-import { CSM_CASTER_RANGE_UNKNOWN } from "../CSM_CASTER_RANGE_STRUCT.js";
-import { SHADOWMAP_CSM_CASCADE_COUNT } from "../SHADOWMAP_CSM_CASCADE_COUNT.js";
-
-export const CSM_CASTER_RANGE_WORKGROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
-
-/**
- * What one directional shadow map's accumulate pass runs with: the frusta the CPU fitted this
- * frame, and where in the scratch buffer this map's cascades accumulate.
- *
- * @type {WebGPUStruct}
- */
-export const CSM_CASTER_RANGE_SETTINGS_STRUCT = WebGPUStruct.from({
-    /**
-     * The light's z axis in world space — the axis a caster's light-view depth is measured along —
-     * without the cascade's own translation, which the CPU adds back when it applies the range.
-     * `w` is unused.
-     */
-    z_axis: vec4f,
-    /**
-     * The four side planes of each cascade's light frustum, four per cascade in cascade order,
-     * inward: `dot(n, p) + w >= 0` is inside. Not normalized, and they need not be.
-     */
-    planes: WebGPUArray.from(vec4f, SHADOWMAP_CSM_CASCADE_COUNT * 4),
-    /**
-     * First scratch word of this map's cascades: cascade `c` accumulates into `base + c`.
-     */
-    base: u32,
-    cascade_count: u32,
-}, "CSMCasterRangeSettings").pack();
-
-/**
- * What the publish pass runs with.
- *
- * @type {WebGPUStruct}
- */
-export const CSM_CASTER_RANGE_PUBLISH_STRUCT = WebGPUStruct.from({
-    /** the map's row of the light database's `shadow_csm_caster_range` table */
-    row: u32,
-    /** see {@link CSM_CASTER_RANGE_SETTINGS_STRUCT#base} */
-    base: u32,
-    cascade_count: u32,
-}, "CSMCasterRangePublish").pack();
-
-const WG = CSM_CASTER_RANGE_WORKGROUP_SIZE;
-const PG = MESHES_TABLE.page_iterator_symbol_prefix(WG);
-const RANGE_TABLE = LIGHT_DATABASE_SPEC.get('shadow_csm_caster_range');
-
-const accumulate_resources = new ShaderResourceSetDescriptor();
-
-accumulate_resources.createGroup()
-    .addStorageBuffer('scene_database', WebGPUArray.from(u32), false)
-    .addUniform('settings', CSM_CASTER_RANGE_SETTINGS_STRUCT)
-    // one word per cascade per map, holding plain f32 bit patterns, seeded to the largest finite
-    // f32 and reset to it by the publish
-    .addStorageBuffer('ranges', WebGPUArray.from(atomic_u32), true);
-
-/**
- * Measure how near along the light every mesh row's world bounds reach, per cascade, over the
- * rows that intersect the cascade's side planes.
- *
- * **This is what makes the cascade's near plane the GPU's to fit.** The CPU used to walk its own
- * copy of the scene's bounds tree to tighten each cascade's near plane against the casters between
- * the light and the view slice; that copy does not exist for a row the GPU composes — a skinned
- * character under a clip, a subtree the CPU stopped composing — so the measure is taken where the
- * bounds are: the `meshes` table, one thread per occupied row, after the bounds pass has refreshed
- * it for the frame. The result is read back and applied to the next frame's fit, with a margin.
- *
- * The test per cascade is the one the tree walk made: a box survives the four fixed side planes if
- * its corner furthest along each plane's normal is inside; the plane a survivor pushes is the
- * near one, to the box corner nearest along the light's axis. Per-thread CAS minimum rather than
- * a subgroup reduction first, because a scene has hundreds of rows and three cascades, and the
- * same CAS helper already bounds the skinned meshes.
- *
- * Dispatch with {@link GPUTypedTable#dispatch_group_count} of the `meshes` table at
- * {@link CSM_CASTER_RANGE_WORKGROUP_SIZE}, once per directional shadow map being drawn.
- *
- * @type {ComputeShader}
- */
-export const shader_csm_caster_range_accumulate = ComputeShader.from({
-    label: "CSM/CasterRangeAccumulate",
-    body: CodeChunk.from(
-        //language=WGSL
-        `
-@compute @workgroup_size(${WG},1,1)
-fn main(
-    @builtin(workgroup_id) wg_id: vec3<u32>,
-    @builtin(local_invocation_index) local_id: u32,
-) {
-    // page_address is uniform across the workgroup, so this branch is uniform
-    if !${PG}_setup(&scene_database, wg_id.x, local_id) {
-        return;
-    }
-
-    let slot = ${PG}_slot_in_page(local_id);
-
-    if slot >= ${PG}_ELEMENTS_PER_PAGE || !${PG}_is_occupied(slot) {
-        return;
-    }
-
-    let mesh = ${PG}_read(&scene_database, slot);
-
-    let low = vec3<f32>(mesh.bounding_box[0], mesh.bounding_box[1], mesh.bounding_box[2]);
-    let high = vec3<f32>(mesh.bounding_box[3], mesh.bounding_box[4], mesh.bounding_box[5]);
-
-    // the corner nearest along the light's axis: the low end wherever the axis points up
-    let axis = settings.z_axis.xyz;
-    let nearest = select(high, low, axis >= vec3<f32>(0.0));
-    let z = dot(axis, nearest);
-
-    let cascade_count = settings.cascade_count;
-
-    for (var c = 0u; c < cascade_count; c += 1u) {
-        var inside = true;
-
-        for (var p = 0u; p < 4u; p += 1u) {
-            let plane = settings.planes[c * 4u + p];
-
-            // the corner furthest along the normal decides whether any of the box is inside
-            let furthest = select(low, high, plane.xyz >= vec3<f32>(0.0));
-
-            if dot(plane.xyz, furthest) + plane.w < 0.0 {
-                inside = false;
-            }
-        }
-
-        if inside {
-            aabb_atomic_min_f32(&ranges[settings.base + c], z);
-        }
-    }
-}
-`, [
-            MESHES_TABLE.chunk_iterate(WG),
-            chunk_aabb_atomic_f32,
-        ]),
-    resources: accumulate_resources,
-});
-
-const publish_resources = new ShaderResourceSetDescriptor();
-
-publish_resources.setImmediate('publish', CSM_CASTER_RANGE_PUBLISH_STRUCT);
-
-publish_resources.createGroup()
-    .addStorageBuffer('ranges', WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer('light_database', WebGPUArray.from(u32), true);
-
-/**
- * Copy one map's accumulated ranges into its row of the light database's `shadow_csm_caster_range`
- * table — where the readback reads them from — and reset the scratch for the next frame.
- *
- * One workgroup, one thread: the row is one record, written whole.
- *
- * @type {ComputeShader}
- */
-export const shader_csm_caster_range_publish = ComputeShader.from({
-    label: "CSM/CasterRangePublish",
-    body: CodeChunk.from(
-        //language=WGSL
-        `
-// the reset value: see CSM_CASTER_RANGE_UNKNOWN
-const RANGE_UNKNOWN = ${CSM_CASTER_RANGE_UNKNOWN};
-
-@compute @workgroup_size(1,1,1)
-fn main() {
-    var near: array<f32, ${SHADOWMAP_CSM_CASCADE_COUNT}>;
-
-    for (var c = 0u; c < ${SHADOWMAP_CSM_CASCADE_COUNT}u; c += 1u) {
-        if c < publish.cascade_count {
-            let word = publish.base + c;
-
-            near[c] = bitcast<f32>(atomicLoad(&ranges[word]));
-
-            atomicStore(&ranges[word], bitcast<u32>(RANGE_UNKNOWN));
-        } else {
-            near[c] = RANGE_UNKNOWN;
-        }
-    }
-
-    ${RANGE_TABLE.marshalling_method_write_field('near')}(&light_database, publish.row, near);
-}
-`, [
-            RANGE_TABLE.wgsl_gen_write_field_code('near'),
-        ]),
-    resources: publish_resources,
-});
+import { WebGPUExtensionType } from "../../../../../descriptor/WebGPUExtensionType.js";
+import { atomic_u32, u32, vec4f } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_aabb_atomic_f32 } from "../../../../animation/skinning/bounds_refresh/chunk_aabb_atomic_f32.js";
+import { LIGHT_DATABASE_SPEC } from "../../../../light/LIGHT_DATABASE_SPEC.js";
+import { MESHES_TABLE } from "../../../../scene/chunk_scene_database_access.js";
+import { CSM_CASTER_RANGE_UNKNOWN } from "../CSM_CASTER_RANGE_STRUCT.js";
+import { SHADOWMAP_CSM_CASCADE_COUNT } from "../SHADOWMAP_CSM_CASCADE_COUNT.js";
+
+export const CSM_CASTER_RANGE_WORKGROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
+
+/**
+ * What one directional shadow map's accumulate pass runs with: the frusta the CPU fitted this
+ * frame, and where in the scratch buffer this map's cascades accumulate.
+ *
+ * @type {WebGPUStruct}
+ */
+export const CSM_CASTER_RANGE_SETTINGS_STRUCT = WebGPUStruct.from({
+    /**
+     * The light's z axis in world space — the axis a caster's light-view depth is measured along —
+     * without the cascade's own translation, which the CPU adds back when it applies the range.
+     * `w` is unused.
+     */
+    z_axis: vec4f,
+    /**
+     * The four side planes of each cascade's light frustum, four per cascade in cascade order,
+     * inward: `dot(n, p) + w >= 0` is inside. Not normalized, and they need not be.
+     */
+    planes: WebGPUArray.from(vec4f, SHADOWMAP_CSM_CASCADE_COUNT * 4),
+    /**
+     * First scratch word of this map's cascades: cascade `c` accumulates into `base + c`.
+     */
+    base: u32,
+    cascade_count: u32,
+}, "CSMCasterRangeSettings").pack();
+
+/**
+ * What the publish pass runs with.
+ *
+ * @type {WebGPUStruct}
+ */
+export const CSM_CASTER_RANGE_PUBLISH_STRUCT = WebGPUStruct.from({
+    /** the map's row of the light database's `shadow_csm_caster_range` table */
+    row: u32,
+    /** see {@link CSM_CASTER_RANGE_SETTINGS_STRUCT#base} */
+    base: u32,
+    cascade_count: u32,
+}, "CSMCasterRangePublish").pack();
+
+const WG = CSM_CASTER_RANGE_WORKGROUP_SIZE;
+const PG = MESHES_TABLE.page_iterator_symbol_prefix(WG);
+const RANGE_TABLE = LIGHT_DATABASE_SPEC.get('shadow_csm_caster_range');
+
+const accumulate_resources = new ShaderResourceSetDescriptor();
+
+accumulate_resources.createGroup()
+    .addStorageBuffer('scene_database', WebGPUArray.from(u32), false)
+    .addUniform('settings', CSM_CASTER_RANGE_SETTINGS_STRUCT)
+    // one word per cascade per map, holding plain f32 bit patterns, seeded to the largest finite
+    // f32 and reset to it by the publish
+    .addStorageBuffer('ranges', WebGPUArray.from(atomic_u32), true);
+
+const accumulate_body = CodeChunk.from(
+    //language=WGSL
+    `
+// what a lane with nothing to contribute reduces with: see CSM_CASTER_RANGE_UNKNOWN
+const RANGE_UNKNOWN = ${CSM_CASTER_RANGE_UNKNOWN};
+
+@compute @workgroup_size(${WG},1,1)
+fn main(
+    @builtin(workgroup_id) wg_id: vec3<u32>,
+    @builtin(local_invocation_index) local_id: u32,
+    @builtin(subgroup_invocation_id) lane_id: u32,
+) {
+    // page_address is uniform across the workgroup, so this branch is uniform
+    if !${PG}_setup(&scene_database, wg_id.x, local_id) {
+        return;
+    }
+
+    let slot = ${PG}_slot_in_page(local_id);
+
+    // A lane with no row does not return: every lane of the subgroup has to reach the reductions
+    // below, so it runs to the end and contributes the identity.
+    let live = slot < ${PG}_ELEMENTS_PER_PAGE && ${PG}_is_occupied(slot);
+
+    var low = vec3<f32>(0.0);
+    var high = vec3<f32>(0.0);
+
+    if live {
+        let mesh = ${PG}_read(&scene_database, slot);
+
+        low = vec3<f32>(mesh.bounding_box[0], mesh.bounding_box[1], mesh.bounding_box[2]);
+        high = vec3<f32>(mesh.bounding_box[3], mesh.bounding_box[4], mesh.bounding_box[5]);
+    }
+
+    // the corner nearest along the light's axis: the low end wherever the axis points up
+    let axis = settings.z_axis.xyz;
+    let nearest = select(high, low, axis >= vec3<f32>(0.0));
+    let z = dot(axis, nearest);
+
+    // from the uniform buffer, so the loop is uniform and every lane reaches every reduction
+    let cascade_count = settings.cascade_count;
+
+    for (var c = 0u; c < cascade_count; c += 1u) {
+        var inside = live;
+
+        for (var p = 0u; p < 4u; p += 1u) {
+            let plane = settings.planes[c * 4u + p];
+
+            // the corner furthest along the normal decides whether any of the box is inside
+            let furthest = select(low, high, plane.xyz >= vec3<f32>(0.0));
+
+            if dot(plane.xyz, furthest) + plane.w < 0.0 {
+                inside = false;
+            }
+        }
+
+        let near = subgroupMin(select(RANGE_UNKNOWN, z, inside));
+
+        // one atomic per subgroup rather than one per row, and none where no row was inside
+        if lane_id == 0u && near < RANGE_UNKNOWN {
+            aabb_atomic_min_f32(&ranges[settings.base + c], near);
+        }
+    }
+}
+`, [
+    MESHES_TABLE.chunk_iterate(WG),
+    chunk_aabb_atomic_f32,
+]);
+
+accumulate_body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * Measure how near along the light every mesh row's world bounds reach, per cascade, over the
+ * rows that intersect the cascade's side planes.
+ *
+ * **This is what makes the cascade's near plane the GPU's to fit.** The CPU used to walk its own
+ * copy of the scene's bounds tree to tighten each cascade's near plane against the casters between
+ * the light and the view slice; that copy does not exist for a row the GPU composes — a skinned
+ * character under a clip, a subtree the CPU stopped composing — so the measure is taken where the
+ * bounds are: the `meshes` table, one thread per occupied row, after the bounds pass has refreshed
+ * it for the frame. The result is read back and applied to the next frame's fit, with a margin.
+ *
+ * The test per cascade is the one the tree walk made: a box survives the four fixed side planes if
+ * its corner furthest along each plane's normal is inside; the plane a survivor pushes is the
+ * near one, to the box corner nearest along the light's axis.
+ *
+ * **The subgroup reduces first, and one lane merges what it found.** Every row inside a cascade
+ * merges into the same word, so a CAS per row queues every caster in the scene on three words: on
+ * an RTX 4090 that measured ~240 µs a frame at 200k rows, ~800 µs at 2M, and 3.3 ms on Caldera at
+ * 2M placements — more than the four views' instance culls together. Reduced per subgroup, 2M rows
+ * take 161 µs, which is also what the pass takes with every atomic deleted; a workgroup step
+ * through shared memory measured the same, so there is none. A lane with no row, and a row outside
+ * the cascade, reduce with {@link CSM_CASTER_RANGE_UNKNOWN} instead of returning, because every
+ * lane has to reach the reduction.
+ *
+ * Dispatch with {@link GPUTypedTable#dispatch_group_count} of the `meshes` table at
+ * {@link CSM_CASTER_RANGE_WORKGROUP_SIZE}, once per directional shadow map being drawn.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_csm_caster_range_accumulate = ComputeShader.from({
+    label: "CSM/CasterRangeAccumulate",
+    body: accumulate_body,
+    resources: accumulate_resources,
+});
+
+const publish_resources = new ShaderResourceSetDescriptor();
+
+publish_resources.setImmediate('publish', CSM_CASTER_RANGE_PUBLISH_STRUCT);
+
+publish_resources.createGroup()
+    .addStorageBuffer('ranges', WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer('light_database', WebGPUArray.from(u32), true);
+
+/**
+ * Copy one map's accumulated ranges into its row of the light database's `shadow_csm_caster_range`
+ * table — where the readback reads them from — and reset the scratch for the next frame.
+ *
+ * One workgroup, one thread: the row is one record, written whole.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_csm_caster_range_publish = ComputeShader.from({
+    label: "CSM/CasterRangePublish",
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+// the reset value: see CSM_CASTER_RANGE_UNKNOWN
+const RANGE_UNKNOWN = ${CSM_CASTER_RANGE_UNKNOWN};
+
+@compute @workgroup_size(1,1,1)
+fn main() {
+    var near: array<f32, ${SHADOWMAP_CSM_CASCADE_COUNT}>;
+
+    for (var c = 0u; c < ${SHADOWMAP_CSM_CASCADE_COUNT}u; c += 1u) {
+        if c < publish.cascade_count {
+            let word = publish.base + c;
+
+            near[c] = bitcast<f32>(atomicLoad(&ranges[word]));
+
+            atomicStore(&ranges[word], bitcast<u32>(RANGE_UNKNOWN));
+        } else {
+            near[c] = RANGE_UNKNOWN;
+        }
+    }
+
+    ${RANGE_TABLE.marshalling_method_write_field('near')}(&light_database, publish.row, near);
+}
+`, [
+            RANGE_TABLE.wgsl_gen_write_field_code('near'),
+        ]),
+    resources: publish_resources,
+});

package/src/shade/renderer/shadow/map/shadowmap_budget_carry_over.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The pool to carry into the next frame: what this frame's pool could not buy, and only while
+ * there was demand it could not meet. When the whole scene's demand was satisfied it resets, so a
+ * run of idle frames does not inflate the pool.
+ *
+ * The spend it is measured against is the BUDGETED one — the local lights. Directionals are
+ * selected unconditionally and cannot be refused, so charging their three cascades each against
+ * the pool the locals compete for could only shrink it: `views_spent` then met `budget_total` on
+ * every frame, the remainder clamped to zero on every frame, and no local map ever satisfied
+ * `views_spent + cost <= budget_total` again. Three directional lights at the default budget of 8,
+ * or one directional at a budget of 1 or 2, froze every spot and point shadow in the scene on its
+ * first frame's depth — moving casters leaving their shadows behind, with `debug_render_count`
+ * flat, which reads as converged.
+ *
+ * @param {number} budget_total the pool this frame had, carry-over included
+ * @param {number} views_spent_budgeted views the local lights took, directionals excluded
+ * @param {boolean} had_unfit_candidates whether anything in view went unrefreshed for want of pool
+ * @param {number} update_budget views granted per frame, which sets the cap
+ * @returns {number}
+ */
+export function shadowmap_budget_carry_over(budget_total: number, views_spent_budgeted: number, had_unfit_candidates: boolean, update_budget: number): number;
+/**
+ * How many frames' worth of budget the pool may grow to while nothing in it can be afforded.
+ *
+ * A candidate costing more than one frame's budget has to be reachable — the pool grows until it
+ * covers the cheapest unfit candidate — but a scene holding one absurdly expensive map should not
+ * let the pool grow without limit and then spend it all in a single frame.
+ *
+ * @type {number}
+ */
+export const SHADOWMAP_BUDGET_CARRY_OVER_FRAMES: number;
+//# sourceMappingURL=shadowmap_budget_carry_over.d.ts.map

package/src/shade/renderer/shadow/map/shadowmap_budget_carry_over.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadowmap_budget_carry_over.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/shadowmap_budget_carry_over.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0DANW,MAAM,wBACN,MAAM,wBACN,OAAO,iBACP,MAAM,GACJ,MAAM,CAiBlB;AA9CD;;;;;;;;GAQG;AACH,iDAFU,MAAM,CAEoC"}

package/src/shade/renderer/shadow/map/shadowmap_budget_carry_over.js

@@ -0,0 +1,47 @@
+/**
+ * How many frames' worth of budget the pool may grow to while nothing in it can be afforded.
+ *
+ * A candidate costing more than one frame's budget has to be reachable — the pool grows until it
+ * covers the cheapest unfit candidate — but a scene holding one absurdly expensive map should not
+ * let the pool grow without limit and then spend it all in a single frame.
+ *
+ * @type {number}
+ */
+export const SHADOWMAP_BUDGET_CARRY_OVER_FRAMES = 4;
+
+/**
+ * The pool to carry into the next frame: what this frame's pool could not buy, and only while
+ * there was demand it could not meet. When the whole scene's demand was satisfied it resets, so a
+ * run of idle frames does not inflate the pool.
+ *
+ * The spend it is measured against is the BUDGETED one — the local lights. Directionals are
+ * selected unconditionally and cannot be refused, so charging their three cascades each against
+ * the pool the locals compete for could only shrink it: `views_spent` then met `budget_total` on
+ * every frame, the remainder clamped to zero on every frame, and no local map ever satisfied
+ * `views_spent + cost <= budget_total` again. Three directional lights at the default budget of 8,
+ * or one directional at a budget of 1 or 2, froze every spot and point shadow in the scene on its
+ * first frame's depth — moving casters leaving their shadows behind, with `debug_render_count`
+ * flat, which reads as converged.
+ *
+ * @param {number} budget_total the pool this frame had, carry-over included
+ * @param {number} views_spent_budgeted views the local lights took, directionals excluded
+ * @param {boolean} had_unfit_candidates whether anything in view went unrefreshed for want of pool
+ * @param {number} update_budget views granted per frame, which sets the cap
+ * @returns {number}
+ */
+export function shadowmap_budget_carry_over(
+    budget_total,
+    views_spent_budgeted,
+    had_unfit_candidates,
+    update_budget
+) {
+    if (!had_unfit_candidates) {
+        return 0;
+    }
+
+    // A must-draw bypass can spend more than the pool held. We cannot owe future frames for past
+    // over-spend, that way lies runaway starvation.
+    const remainder = Math.max(0, budget_total - views_spent_budgeted);
+
+    return Math.min(remainder, update_budget * SHADOWMAP_BUDGET_CARRY_OVER_FRAMES);
+}

package/src/shade/renderer/shadow/vsm/VirtualShadowMap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualShadowMap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VirtualShadowMap.js"],"names":[],"mappings":"AAMA;IAEI,wBAAsB;IAEtB;;OAEG;IACH,kBAFU,iBAAiB,CAEV;IAGjB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;OAEG;IACH,qBAAM;IAEN;;OAEG;IACH,aAFU,kBAAkB,CAEX;IAEjB;;OAEG;IACH,2BAAgB;IAGhB;;;;;OAKG;IACH,yBAAa;IAEb,+BAIC;IAED;;;;;;OAMG;IACH,kGAsEC;IAED,gBAYC;CACJ;kCA7IiC,oCAAoC"}
+{"version":3,"file":"VirtualShadowMap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VirtualShadowMap.js"],"names":[],"mappings":"AAMA;IAEI,wBAAsB;IAEtB;;OAEG;IACH,kBAFU,iBAAiB,CAEV;IAGjB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;OAEG;IACH,qBAAM;IAEN;;OAEG;IACH,aAFU,kBAAkB,CAEX;IAEjB;;OAEG;IACH,2BAAgB;IAGhB;;;;;OAKG;IACH,yBAAa;IAEb,+BAIC;IAED;;;;;;OAMG;IACH,kGAgFC;IAED,gBAYC;CACJ;kCAvJiC,oCAAoC"}

package/src/shade/renderer/shadow/vsm/VirtualShadowMap.js

@@ -121,9 +121,19 @@ export class VirtualShadowMap {
 
         //
 
+        /*
+         One entry per NODE of the implicit quadtree, which is what total_tile_count computes.
+
+         The size used to be resolution_in_tiles * 4/3, a side length where a node count belongs.
+         For the 16384 / 256 configuration GPUViewShadowMaps asks for, that is 86 entries against
+         the 5461 the tree has: an indexing shader reads zeros past node 85 where storage access is
+         clamped, and fails buffer-size validation at bind time where it is not. Nothing binds this
+         today because VirtualShadowmapRenderer is never constructed, so the shape of the failure
+         matters more than the count: it would look like a shader bug.
+        */
         this.buffer_lookup = device.createBuffer({
             label:"VSM / lookup",
-            size: Uint32Array.BYTES_PER_ELEMENT * Math.ceil(this.resolution_in_tiles * 4/3),
+            size: Uint32Array.BYTES_PER_ELEMENT * this.total_tile_count,
             usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
         });
 

package/src/shade/renderer/texture/ShadeTexture.d.ts

@@ -11,6 +11,21 @@ export class ShadeTexture {
      * @return {boolean}
      */
     get isShadeTexture(): boolean;
+    /**
+     * How sampling this texture decodes, or `null` to take the image's own.
+     *
+     * **Per texture, not per image.** A colour space belongs to the (image, role) pair: one glTF
+     * image is routinely named by two textures in two slots — a base colour in one material and a
+     * metallic-roughness in another — and the two want different decodes. It used to be written
+     * onto the shared {@link ShadeImage}, as a one-way latch that only ever set sRGB and that no
+     * slot ever wrote linear back, so if any material in a document used image N as a colour map,
+     * every other texture over image N was decoded sRGB too. An authored roughness of 0.5 read
+     * back as 0.216 and the surface rendered far glossier than it was written, with no warning and
+     * for a reason that lived in another material.
+     *
+     * @type {ColorSpace|number|null}
+     */
+    color_space: ColorSpace | number | null;
     /**
      *
      * @returns {ShadeImage}
@@ -72,6 +87,7 @@ export class ShadeTexture {
     #private;
 }
 export type ShadeImage = import("./source/ShadeImage.js").ShadeImage;
+export type ColorSpace = import("./ColorSpace.js").ColorSpace;
 import { ShadeTextureFlags } from "./ShadeTextureFlags.js";
 import { TextureFilterType } from "./TextureFilterType.js";
 //# sourceMappingURL=ShadeTexture.d.ts.map

package/src/shade/renderer/texture/ShadeTexture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadeTexture.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/ShadeTexture.js"],"names":[],"mappings":"AAaA;IA4FI;;;;OAIG;IACH,oBAHW,UAAU,GACR,YAAY,CAiBxB;IA/GD,cAAW;IAOX;;;OAGG;IACH,8BAEC;IAED;;;OAGG;IACH,yDAEC;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,iBAAiB,GACtB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,iBAAiB,GACtB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,iBAAiB,SACxB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,iBAAiB,GACtB,OAAO,CAInB;IAED,cAAsB;IAEtB,kBAAqC;IACrC,kBAAqC;IAErC;;;OAGG;IACH,cAFU,iBAAiB,CAEa;IAExC,cAA+B;IAC/B,cAA+B;IAC/B,cAA+B;IAE/B;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,wBAFU,iBAAiB,GAAC,MAAM,CAEgB;IAwBlD,eAWC;IAED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAYnB;;CACJ;yBApJY,OAAO,wBAAwB,EAAE,UAAU;kCALtB,wBAAwB;kCACxB,wBAAwB"}
+{"version":3,"file":"ShadeTexture.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/ShadeTexture.js"],"names":[],"mappings":"AAcA;IA4GI;;;;OAIG;IACH,oBAHW,UAAU,GACR,YAAY,CAiBxB;IA/HD,cAAW;IAOX;;;OAGG;IACH,8BAEC;IAED;;;;;;;;;;;;;OAaG;IACH,aAFU,UAAU,GAAC,MAAM,GAAC,IAAI,CAEb;IAEnB;;;OAGG;IACH,yDAEC;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,iBAAiB,GACtB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,iBAAiB,GACtB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,iBAAiB,SACxB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,iBAAiB,GACtB,OAAO,CAInB;IAED,cAAsB;IAEtB,kBAAqC;IACrC,kBAAqC;IAErC;;;OAGG;IACH,cAFU,iBAAiB,CAEa;IAExC,cAA+B;IAC/B,cAA+B;IAC/B,cAA+B;IAE/B;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,wBAFU,iBAAiB,GAAC,MAAM,CAEgB;IAwBlD,eAWC;IAED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAYnB;;CACJ;yBArKY,OAAO,wBAAwB,EAAE,UAAU;yBAC3C,OAAO,iBAAiB,EAAE,UAAU;kCANf,wBAAwB;kCACxB,wBAAwB"}

package/src/shade/renderer/texture/ShadeTexture.js

@@ -7,6 +7,7 @@ import { TextureWrapType } from "./TextureWrapType.js";
 
 /**
  * @typedef {import("./source/ShadeImage.js").ShadeImage} ShadeImage
+ * @typedef {import("./ColorSpace.js").ColorSpace} ColorSpace
  */
 
 const DEFAULT_FLAGS = ShadeTextureFlags.GenerateMipMaps;
@@ -27,6 +28,22 @@ export class ShadeTexture {
         return true;
     }
 
+    /**
+     * How sampling this texture decodes, or `null` to take the image's own.
+     *
+     * **Per texture, not per image.** A colour space belongs to the (image, role) pair: one glTF
+     * image is routinely named by two textures in two slots — a base colour in one material and a
+     * metallic-roughness in another — and the two want different decodes. It used to be written
+     * onto the shared {@link ShadeImage}, as a one-way latch that only ever set sRGB and that no
+     * slot ever wrote linear back, so if any material in a document used image N as a colour map,
+     * every other texture over image N was decoded sRGB too. An authored roughness of 0.5 read
+     * back as 0.216 and the surface rendered far glossier than it was written, with no warning and
+     * for a reason that lived in another material.
+     *
+     * @type {ColorSpace|number|null}
+     */
+    color_space = null;
+
     /**
      *
      * @returns {ShadeImage}