@woosh/meep-engine 3.38.0 → 3.39.0

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

@@ -1,6 +1,4 @@
 import { platform_compute_endianness } from "../../../../core/binary/platform_compute_endianness.js";
-import { split_by_2 } from "../../../../core/binary/split_by_2.js";
-import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
 import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
 import { VSM_UNIFORMS_STRUCT } from "./VSM_UNIFORMS_STRUCT.js";
 
@@ -44,10 +42,9 @@ export class VirtualShadowMap {
      */
     buffer_lookup
 
-    get total_tile_count(){
-        const max_mip_level = Math.log2(this.resolution_in_tiles);
-
-        return split_by_2((1 << (max_mip_level + 1)) - 1);
+    get total_tile_count() {
+        // Sum of the square grids at every level: 1 + 4 + ... + resolution_in_tiles^2.
+        return this.resolution_in_tiles === 0 ? 0 : (4 * this.resolution_in_tiles ** 2 - 1) / 3;
     }
 
     /**
@@ -55,7 +52,7 @@ export class VirtualShadowMap {
      * @param {GPUDevice} device
      * @param {number} [virtual_resolution]
      * @param {number} [physical_resolution]
-     * @param {number} [tile_size]
+     * @param {number} [tile_resolution]
      */
     initialize({
                    device,
@@ -64,32 +61,42 @@ export class VirtualShadowMap {
                    tile_resolution = 128
                }) {
 
-        if (!isPowerOfTwo(virtual_resolution)) {
-            throw new Error(`virtual_resolution must be a power of two, instead was ${virtual_resolution}`);
+        if (!Number.isSafeInteger(virtual_resolution) || virtual_resolution <= 0
+            || virtual_resolution > 0xffffffff || !Number.isInteger(Math.log2(virtual_resolution))) {
+            throw new RangeError(`virtual_resolution must be a positive u32 power of two, instead was ${virtual_resolution}`);
         }
 
-        if (!isPowerOfTwo(tile_resolution)) {
-            throw new Error(`tile_resolution must be a power of two, instead was ${tile_resolution}`);
+        if (!Number.isSafeInteger(tile_resolution) || tile_resolution <= 0
+            || tile_resolution > virtual_resolution || !Number.isInteger(Math.log2(tile_resolution))) {
+            throw new RangeError(`tile_resolution must be a positive power of two no larger than virtual_resolution, instead was ${tile_resolution}`);
         }
 
-        this.tile_resolution = tile_resolution;
+        if (!Number.isSafeInteger(physical_resolution) || physical_resolution <= 0) {
+            throw new RangeError(`physical_resolution must be a positive integer, instead was ${physical_resolution}`);
+        }
 
         const resolution_limit = device.limits.maxTextureDimension2D;
-
-        let _actual_physical_resolution;
-
-        if (physical_resolution > resolution_limit) {
-            _actual_physical_resolution = resolution_limit;
-            console.warn(`Requested physical resolution (=${physical_resolution}) exceeds device limit (=${resolution_limit}), defaulting to limit instead`);
-        } else {
-            _actual_physical_resolution = physical_resolution;
+        // Pages cannot straddle the edge of the physical atlas, including after device clamping.
+        const physical_tiles_per_side = Math.floor(Math.min(physical_resolution, resolution_limit) / tile_resolution);
+        const _actual_physical_resolution = physical_tiles_per_side * tile_resolution;
+        if (physical_tiles_per_side === 0) {
+            throw new RangeError('The physical atlas must fit at least one tile within the device texture limit');
         }
 
-        if (virtual_resolution <= _actual_physical_resolution) {
-            console.warn(`physical_resolution(=${_actual_physical_resolution}) >= virtual_resolution(=${virtual_resolution}), this is a pointless configuration. Likely a mistake`);
+        const resolution_in_tiles = virtual_resolution / tile_resolution;
+        const total_tile_count = (4 * resolution_in_tiles ** 2 - 1) / 3;
+        const lookup_size = total_tile_count * Uint32Array.BYTES_PER_ELEMENT;
+        // The shaders spread at most sixteen bits and dispatch one invocation per tree node.
+        if (resolution_in_tiles > 32768 || lookup_size > device.limits.maxBufferSize
+            || lookup_size > device.limits.maxStorageBufferBindingSize
+            || Math.ceil(total_tile_count / 256) > device.limits.maxComputeWorkgroupsPerDimension) {
+            throw new RangeError('The virtual tile tree exceeds the shader or device buffer/dispatch limits');
         }
 
-        this.resolution_in_tiles = Math.floor(virtual_resolution / this.tile_resolution);
+        // Validate first so an invalid replacement leaves the existing map intact.
+        this.destroy();
+        this.tile_resolution = tile_resolution;
+        this.resolution_in_tiles = resolution_in_tiles;
 
 
         // initialize physical texture
@@ -116,26 +123,23 @@ export class VirtualShadowMap {
 
         buffer_uniforms_view.setUint32(VSM_UNIFORMS_STRUCT.get('tile_resolution').offset, tile_resolution, platform_compute_endianness());
         buffer_uniforms_view.setUint32(VSM_UNIFORMS_STRUCT.get('resolution_in_tiles').offset, this.resolution_in_tiles, platform_compute_endianness());
+        buffer_uniforms_view.setUint32(VSM_UNIFORMS_STRUCT.get('physical_tile_count').offset, physical_tiles_per_side ** 2, platform_compute_endianness());
 
         this.buffer_uniforms.unmap();
 
         //
 
-        /*
-         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.
-        */
+        // One entry per node of the implicit quadtree.
         this.buffer_lookup = device.createBuffer({
             label:"VSM / lookup",
             size: Uint32Array.BYTES_PER_ELEMENT * this.total_tile_count,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            mappedAtCreation: true
         });
+        // Page zero is a valid allocation, so a zero-initialized table would claim that every
+        // virtual tile already has a page before the first allocation pass has run.
+        new Uint32Array(this.buffer_lookup.getMappedRange()).fill(0xffffffff);
+        this.buffer_lookup.unmap();
 
     }
 
@@ -151,5 +155,15 @@ export class VirtualShadowMap {
             this.physical_texture.destroy();
             this.physical_texture = undefined;
         }
+
+        if (this.buffer_uniforms !== undefined) {
+            this.buffer_uniforms.destroy();
+            this.buffer_uniforms = undefined;
+        }
+        if (this.buffer_lookup !== undefined) {
+            this.buffer_lookup.destroy();
+            this.buffer_lookup = undefined;
+        }
+        this.resolution_in_tiles = 0;
     }
-}
+}

package/src/shade/renderer/shadow/vsm/VirtualShadowmapRenderer.d.ts

@@ -1,3 +1,4 @@
+/** @typedef {import("./GPUViewShadowMaps.js").GPUViewShadowMaps} GPUViewShadowMaps */
 export class VirtualShadowmapRenderer {
     /**
      *
@@ -17,8 +18,10 @@ export class VirtualShadowmapRenderer {
      * @param {ShadeGPUCommandContext} encoder
      * @param {GPUViewContext} main_view
      * @param {RenderTarget} viz
+     * @param {GPUViewShadowMaps} shadows the VSM collection for this view
      */
-    render_for_view(encoder: ShadeGPUCommandContext, main_view: GPUViewContext, viz: RenderTarget): void;
+    render_for_view(encoder: ShadeGPUCommandContext, main_view: GPUViewContext, viz: RenderTarget, shadows: GPUViewShadowMaps): void;
     #private;
 }
+export type GPUViewShadowMaps = import("./GPUViewShadowMaps.js").GPUViewShadowMaps;
 //# sourceMappingURL=VirtualShadowmapRenderer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"VirtualShadowmapRenderer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VirtualShadowmapRenderer.js"],"names":[],"mappings":"AAMA;IAOI;;;OAGG;IACH,uCAIC;IAED;;;;;;OAMG;IACH,oHAkDC;IAED;;;;;OAKG;IACH,qGAYC;;CAEJ"}
+{"version":3,"file":"VirtualShadowmapRenderer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VirtualShadowmapRenderer.js"],"names":[],"mappings":"AAMA,sFAAsF;AAEtF;IAOI;;;OAGG;IACH,uCAIC;IAED;;;;;;OAMG;IACH,oHAgDC;IAED;;;;;;OAMG;IACH,wGAFW,iBAAiB,QAY3B;;CAEJ;gCA/Fa,OAAO,wBAAwB,EAAE,iBAAiB"}

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

@@ -4,6 +4,8 @@ import { vsm_coarse_bounds_pass, VSMCoarseBoundsPassData } from "./vms_pipeline_
 import { vsm_time_usage_data, VSMTileUsagePassData } from "./vsm_residence_pipeline.js";
 import { vsm_allocate_tiles_pass, VSMTileAllocationPassData } from "./vsm_tile_allocation_pipeline.js";
 
+/** @typedef {import("./GPUViewShadowMaps.js").GPUViewShadowMaps} GPUViewShadowMaps */
+
 export class VirtualShadowmapRenderer {
     /**
      * @type {GraphicsContext}
@@ -34,7 +36,7 @@ export class VirtualShadowmapRenderer {
 
         const residence_buffer_size = map.total_tile_count * Uint32Array.BYTES_PER_ELEMENT;
 
-        const res_lookup = graph.import_resource("lookup", BufferResourceDescriptor.from(0, 0), map.buffer_lookup);
+        const res_lookup = graph.import_resource("lookup", BufferResourceDescriptor.fromBuffer(map.buffer_lookup), map.buffer_lookup);
 
         const tile_usage_data = new VSMTileUsagePassData();
         tile_usage_data.map = map;
@@ -45,8 +47,7 @@ export class VirtualShadowmapRenderer {
 
         tile_usage_data.residence = tile_usage.create("residence", BufferResourceDescriptor.from(
             residence_buffer_size,
-            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-            0, residence_buffer_size
+            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
         ));
 
         const coarse_bounds_data = new VSMCoarseBoundsPassData();
@@ -67,8 +68,7 @@ export class VirtualShadowmapRenderer {
 
         allocation_data.allocation_count = allocations.create("allocation_count", BufferResourceDescriptor.from(
             Uint32Array.BYTES_PER_ELEMENT,
-            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
-            0, Uint32Array.BYTES_PER_ELEMENT
+            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
         ));
         allocation_data.lookup = allocations.write(res_lookup);
         allocation_data.residence = allocations.read(tile_usage_data.residence);
@@ -85,10 +85,9 @@ export class VirtualShadowmapRenderer {
      * @param {ShadeGPUCommandContext} encoder
      * @param {GPUViewContext} main_view
      * @param {RenderTarget} viz
+     * @param {GPUViewShadowMaps} shadows the VSM collection for this view
      */
-    render_for_view(encoder, main_view, viz) {
-
-        const shadows = main_view.lights.shadows;
+    render_for_view(encoder, main_view, viz, shadows) {
 
         const maps = shadows.maps;
 
@@ -100,4 +99,4 @@ export class VirtualShadowmapRenderer {
         }
     }
 
-}
+}

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

@@ -31,7 +31,7 @@ export function debug_inspect_residence_buffer(debug_buffer, device, map, viewpo
 
         let total_shadowed_pixels = 0;
 
-        let used_mips = new Uint32Array(max_mip_level);
+        let used_mips = new Uint32Array(max_mip_level + 1);
 
         let live_tiles = 0;
 
@@ -61,4 +61,4 @@ export function debug_inspect_residence_buffer(debug_buffer, device, map, viewpo
 
         return hits;
     });
-}
+}

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

@@ -1 +1 @@
-{"version":3,"file":"decode_tile_address.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/decode_tile_address.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,2CAHW,MAAM,GACJ;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,GAAC,IAAI,CA4BpD"}
+{"version":3,"file":"decode_tile_address.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/decode_tile_address.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,2CAHW,MAAM,GACJ;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,GAAC,IAAI,CAsBpD"}

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

@@ -1,34 +1,26 @@
-import { split_by_2 } from "../../../../core/binary/split_by_2.js";
-
 /**
  *
  * @param {number} index
  * @returns {{mip: number, x: number, y: number}|null}
  */
 export function decode_tile_address(index) {
-    for (let mip = 0; mip < 99; mip++) {
-        const resolution = 1 << mip;
-
-        const mip_mask = resolution - 1;
-
-        const index_offset = split_by_2(mip_mask);
-
-        const next_mip_mask = mip_mask << 1 | 0x1;
-
-        const index_offset_next = split_by_2(next_mip_mask);
+    if (!Number.isSafeInteger(index) || index < 0) {
+        return null;
+    }
 
-        if (index >= index_offset_next) {
-            continue;
-        }
+    // 1. Analytically find the mip level
+    const mip = Math.floor(Math.log2(3 * index + 1) / 2);
 
-        const local_index = index - index_offset;
+    // 2. Calculate the starting index offset for this mip level
+    const index_offset = (4 ** mip - 1) / 3;
 
-        const y = (local_index / resolution) | 0;
-        const x = local_index % resolution;
+    // 3. Isolate the index relative to the current mip level
+    const local_index = index - index_offset;
+    const resolution = 2 ** mip;
 
-        return { mip, x, y };
-    }
+    // 4. Resolve row-major x and y coordinates
+    const y = Math.floor(local_index / resolution);
+    const x = local_index % resolution;
 
-    // not found
-    return null;
-}
+    return { mip, x, y };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"vms_pipeline_compute_coarse_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/vms_pipeline_compute_coarse_bounds.js"],"names":[],"mappings":"AAuIA;;;;;GAKG;AACH,6CAJW,uBAAuB,0EAiDjC;AAjLD,+CAGmB;AAgGnB,2EAYG;AAGH;IACI,eAAW;IACX,kBAAc;IAEd;;OAEG;IACH,sBAAG;CACN;6BA9H4B,mCAAmC;0CAHtB,mEAAmE"}
+{"version":3,"file":"vms_pipeline_compute_coarse_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/vms_pipeline_compute_coarse_bounds.js"],"names":[],"mappings":"AAuIA;;;;;GAKG;AACH,6CAJW,uBAAuB,0EA8CjC;AA9KD,+CAGmB;AAgGnB,2EAYG;AAGH;IACI,eAAW;IACX,kBAAc;IAEd;;OAEG;IACH,sBAAG;CACN;6BA9H4B,mCAAmC;0CAHtB,mEAAmE"}

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

@@ -143,18 +143,15 @@ export function vsm_coarse_bounds_pass(data, resources, context) {
 
     const encoder = context.encoder;
 
-    const initial_bounds = encoder.allocateTransientValueBuffer(
-        WebGPUArray.from(u32, 4),
-        INITIAL_BOUNDS_AABB2
-    );
-
     const buffer_texture_bounds_coarse = resources.get(data.bounds);
 
     const map = data.map;
 
-    encoder.copyBufferToBuffer(
-        initial_bounds, 0,
-        buffer_texture_bounds_coarse, 0, initial_bounds.size
+    // Write exactly four words at this point in the command stream. A pooled transient buffer
+    // may be larger than the bounds and is not necessarily usable as a copy source.
+    encoder.writeValueBuffer(
+        buffer_texture_bounds_coarse, 0,
+        WebGPUArray.from(u32, 4), INITIAL_BOUNDS_AABB2
     );
 
     /**
@@ -184,4 +181,4 @@ export function vsm_coarse_bounds_pass(data, resources, context) {
     //
     // const device = this.#graphics.device;
     // debug_inspect_coarse_bounds_buffer(debug_buffer, device, map);
-}
+}

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

@@ -1 +1 @@
-{"version":3,"file":"vsm_residence_pipeline.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/vsm_residence_pipeline.js"],"names":[],"mappings":"AAkKA;;;;;GAKG;AACH,0CAJW,oBAAoB,0EAsD9B;AA3FD,+DAeE;AAEF;IACI,kBAAc;IACd;;OAEG;IACH,sBAAG;IAEH;;OAEG;IACH,kBAAG;IAEH;;OAEG;IACH,0BAAS;CACZ;0CA9JyC,mEAAmE"}
+{"version":3,"file":"vsm_residence_pipeline.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/vsm_residence_pipeline.js"],"names":[],"mappings":"AAyKA;;;;;GAKG;AACH,0CAJW,oBAAoB,0EAyD9B;AA9FD,+DAeE;AAEF;IACI,kBAAc;IACd;;OAEG;IACH,sBAAG;IAEH;;OAEG;IACH,kBAAG;IAEH;;OAEG;IACH,0BAAS;CACZ;0CArKyC,mEAAmE"}

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

@@ -5,6 +5,7 @@ import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
 import { chunk_split_by_2 } from "../../shader/chunk/binary/chunk_split_by_2.js";
 import { chunk_project_position_from_depth } from "../../shader/chunk/camera/chunk_project_position_from_depth.js";
 import { chunk_v3_matrix4_project } from "../../shader/chunk/geometry/vec3/chunk_v3_matrix4_project.js";
+import { chunk_ndc_to_uv } from "../../shader/chunk/texture/chunk_ndc_to_uv.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { VSM_RESIDENCE_WORKGROUP_TILE_RESOLUTION } from "./VSM_RESIDENCE_WORKGROUP_TILE_RESOLUTION.js";
 import { VSM_UNIFORMS_STRUCT } from "./VSM_UNIFORMS_STRUCT.js";
@@ -48,8 +49,6 @@ let index_offset = split_by_2(lod_mask);
 return index_offset + y * lod_resolution + x;
 }
 
-const SQRT1_2 = 0.7071067811865475;
-
 @compute @workgroup_size(${VSM_RESIDENCE_WORKGROUP_TILE_RESOLUTION}, ${VSM_RESIDENCE_WORKGROUP_TILE_RESOLUTION}, 1)
 fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
 
@@ -63,12 +62,19 @@ fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
     let pixel_coordinates = global_id.xy;
         
     let depth_sample = textureLoad(texture_depth, pixel_coordinates, 0);
+    // The renderer clears reverse-Z depth to zero: these pixels have no receiver surface.
+    if (depth_sample == 0.0) {
+        return;
+    }
     
     // - we need to compute world bounds of the pixel based on the depth sample    
     
-    let pixel_size = 1.0;
-    
     let view_pixel_center = vec2f(pixel_coordinates) + 0.5;
+    let world_center = getWorldFromUVDepth(view_pixel_center / vec2f(input_texture_size), depth_sample);
+    let shadow_clip = shadow_camera.view_projection_matrix * vec4f(world_center, 1.0);
+    if (shadow_clip.w <= 0.0 || shadow_clip.z < 0.0 || shadow_clip.z > shadow_clip.w) {
+        return;
+    }
     
     let world_00 =  getWorldFromUVDepth( ( view_pixel_center + vec2(-0.5, -0.5)) / vec2f(input_texture_size), depth_sample);
     let world_10 =  getWorldFromUVDepth( ( view_pixel_center + vec2( 0.5, -0.5)) / vec2f(input_texture_size), depth_sample);
@@ -88,7 +94,7 @@ fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
     
         
     // - get UV coordinate of the pixel in shadowmap space
-    let shadow_uv = (shadow_texel_bounds_max + shadow_texel_bounds_min) * 0.25 + 0.5;
+    let shadow_uv = ndc_to_uv(shadow_clip.xy / shadow_clip.w);
     
     if(shadow_uv.x < 0.0 || shadow_uv.x >= 1.0 || shadow_uv.y < 0.0 || shadow_uv.y >= 1.0){
         // outside of the shadow
@@ -99,12 +105,12 @@ fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
         
     let shadow_dxy = (shadow_texel_bounds_max - shadow_texel_bounds_min)*0.5;
     
-    let shadow_pixel_size = max( 1.0, f32(shadowmap_resolution) * length( shadow_dxy ) * SQRT1_2);
+    // An isotropic mip must account for the larger axis of a rectangular pixel footprint.
+    let shadow_pixel_size = max(1.0, f32(shadowmap_resolution) * max(shadow_dxy.x, shadow_dxy.y));
     
     // - figure out LOD based on the UV bounds
-    let shadow_lod_count = countTrailingZeros(vsm.resolution_in_tiles); // fast log2 alternative
-    
-    let shadow_lod_max = shadow_lod_count - 1u;
+    // A grid with 2^k tiles has k+1 levels, including both the root and the finest grid.
+    let shadow_lod_max = countTrailingZeros(vsm.resolution_in_tiles);
     
     let mip_level = clamp( u32( floor( log2(shadow_pixel_size) ))  , 0u, shadow_lod_max  ) ;
     let shadow_lod = shadow_lod_max - mip_level;
@@ -122,6 +128,7 @@ fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
     [
         chunk_project_position_from_depth,
         chunk_v3_matrix4_project,
+        chunk_ndc_to_uv,
     ]
 ).compile().text;
 
@@ -182,6 +189,9 @@ export function vsm_time_usage_data(data, resources, context) {
 
     const depth_texture = viz.depth_attachment;
 
+    // Demand belongs to this frame, including when the graph reuses a buffer from its pool.
+    encoder.clearBuffer(residence_buffer);
+
     const residence_pass = encoder.constructComputePass({
         label: "VSM / Compute Residence",
         pipeline: vsm_residence_pipeline,

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

@@ -1 +1 @@
-{"version":3,"file":"vsm_tile_allocation_pipeline.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/vsm_tile_allocation_pipeline.js"],"names":[],"mappings":"AAuEA;;;;;GAKG;AACH,8CAJW,yBAAyB,0EAyCnC;AArED,qEAaG;AAEH;IACI,yBAAqB;IACrB,kBAAc;IACd,eAAW;IAEX;;OAEG;IACH,sBAAG;CACN;0CAnEyC,mEAAmE"}
+{"version":3,"file":"vsm_tile_allocation_pipeline.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/vsm_tile_allocation_pipeline.js"],"names":[],"mappings":"AAmFA;;;;;GAKG;AACH,8CAJW,yBAAyB,0EAyCnC;AArED,qEAaG;AAEH;IACI,yBAAqB;IACrB,kBAAc;IACd,eAAW;IAEX;;OAEG;IACH,sBAAG;CACN;0CA/EyC,mEAAmE"}

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

@@ -16,7 +16,7 @@ ${chunk_split_by_2}
 @group(1) @binding(0) var<storage, read_write> counter: atomic<u32>;
 @group(1) @binding(1) var<storage, read_write> allocation: array<u32>;
 
-const INVALID_ALLOCATION = ${UINT32_MAX};
+const INVALID_ALLOCATION: u32 = ${UINT32_MAX}u;
 
 @compute @workgroup_size(256,1,1)
 fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
@@ -38,9 +38,21 @@ fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
         return;
     }
     
-    let allocated_page_index = atomicAdd(&counter, 1u);
-    
-    allocation[tile_index] = allocated_page_index;
+    // Only successful reservations advance the count. An unconditional atomicAdd would return
+    // pages outside the atlas, and clamping the count afterwards could grant duplicate pages.
+    var page = atomicLoad(&counter);
+    loop {
+        if (page >= vsm.physical_tile_count) {
+            allocation[tile_index] = INVALID_ALLOCATION;
+            return;
+        }
+        let reservation = atomicCompareExchangeWeak(&counter, page, page + 1u);
+        if (reservation.exchanged) {
+            allocation[tile_index] = page;
+            return;
+        }
+        page = reservation.old_value;
+    }
 }
 `;
 export const vsm_tile_allocation_pipeline = ComputePipelineDescriptor.simplified({
@@ -84,7 +96,7 @@ export function vsm_allocate_tiles_pass(data, resources, context) {
 
     const map = data.map;
 
-    encoder.clearBuffer(lookup_buffer);
+    encoder.clearBuffer(allocation_count);
 
     const allocation_pass = encoder.constructComputePass({
         pipeline: vsm_tile_allocation_pipeline,
@@ -112,4 +124,4 @@ export function vsm_allocate_tiles_pass(data, resources, context) {
     // }).then(arr => {
     //     console.log(`Allocated tiles: ${arr[0]}`)
     // });
-}
+}

package/src/shade/renderer/texture/util/BLACK_PIXEL_TEXTURE.d.ts

@@ -1,2 +1,2 @@
-export const BLACK_PIXEL_TEXTURE: import("../ShadeTexture.js").ShadeTexture;
+export const BLACK_PIXEL_TEXTURE: ShadeTexture;
 //# sourceMappingURL=BLACK_PIXEL_TEXTURE.d.ts.map

package/src/shade/renderer/texture/util/BLACK_PIXEL_TEXTURE.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BLACK_PIXEL_TEXTURE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/util/BLACK_PIXEL_TEXTURE.js"],"names":[],"mappings":"AAGA,4EAAyE"}
+{"version":3,"file":"BLACK_PIXEL_TEXTURE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/util/BLACK_PIXEL_TEXTURE.js"],"names":[],"mappings":"AAGA,+CAAyE"}

package/src/shade/renderer/texture/util/PIXEL_TEXTURE_NORMAL.d.ts

@@ -1,2 +1,19 @@
-export const PIXEL_TEXTURE_NORMAL: import("../ShadeTexture.js").ShadeTexture;
+/**
+ * What a material without a normal map samples in its place: the flat tangent-space normal
+ * (0, 0, 1), stored the way every normal map stores one, `n * 0.5 + 0.5`.
+ *
+ * **Half-float, because that is 0.5 and no unorm format can hold it** — k / (2^n - 1) = 1/2 asks for
+ * an odd number to be even. In 8 bits it was 128/255, which {@link chunk_decode_tangent_normal}
+ * read as xy = (1/255, 1/255): every surface without a normal map shaded with a normal leaning 0.32
+ * degrees along its tangent diagonal. 0.5 is exact in binary16, so this decodes to the geometric
+ * normal exactly.
+ *
+ * The texel is what changed rather than the decode, because `v * 2 - 1` is what every normal map
+ * in the engine is written for — the normal mip filter re-encodes with `n * 0.5 + 0.5`, and the
+ * importers hand maps over as authored — and the alternative, `(255v - 128) / 127`, would move every
+ * texel of every one of them but the brightest.
+ *
+ * @type {ShadeTexture}
+ */
+export const PIXEL_TEXTURE_NORMAL: ShadeTexture;
 //# sourceMappingURL=PIXEL_TEXTURE_NORMAL.d.ts.map

package/src/shade/renderer/texture/util/PIXEL_TEXTURE_NORMAL.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PIXEL_TEXTURE_NORMAL.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/util/PIXEL_TEXTURE_NORMAL.js"],"names":[],"mappings":"AAGA,6EAAyF"}
+{"version":3,"file":"PIXEL_TEXTURE_NORMAL.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/util/PIXEL_TEXTURE_NORMAL.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AACH,gDAA+E"}

package/src/shade/renderer/texture/util/PIXEL_TEXTURE_NORMAL.js

@@ -1,5 +1,26 @@
-import { Color } from "../../../../core/color/Color.js";
-import { get_single_pixel_texture } from "./get_single_pixel_texture.js";
+import { Sampler2D } from "../../../../engine/graphics/texture/sampler/Sampler2D.js";
+import { single_pixel_texture_from_sampler } from "./single_pixel_texture_from_sampler.js";
 
-export const PIXEL_TEXTURE_NORMAL = get_single_pixel_texture(Color.fromRGB(0.5, 0.5, 1));
+const sampler = Sampler2D.float16(4, 1, 1);
+
+sampler.data.set([0.5, 0.5, 1, 1]);
+
+/**
+ * What a material without a normal map samples in its place: the flat tangent-space normal
+ * (0, 0, 1), stored the way every normal map stores one, `n * 0.5 + 0.5`.
+ *
+ * **Half-float, because that is 0.5 and no unorm format can hold it** — k / (2^n - 1) = 1/2 asks for
+ * an odd number to be even. In 8 bits it was 128/255, which {@link chunk_decode_tangent_normal}
+ * read as xy = (1/255, 1/255): every surface without a normal map shaded with a normal leaning 0.32
+ * degrees along its tangent diagonal. 0.5 is exact in binary16, so this decodes to the geometric
+ * normal exactly.
+ *
+ * The texel is what changed rather than the decode, because `v * 2 - 1` is what every normal map
+ * in the engine is written for — the normal mip filter re-encodes with `n * 0.5 + 0.5`, and the
+ * importers hand maps over as authored — and the alternative, `(255v - 128) / 127`, would move every
+ * texel of every one of them but the brightest.
+ *
+ * @type {ShadeTexture}
+ */
+export const PIXEL_TEXTURE_NORMAL = single_pixel_texture_from_sampler(sampler);
 PIXEL_TEXTURE_NORMAL.label = "normal";

package/src/shade/renderer/texture/util/WHITE_PIXEL_TEXTURE.d.ts

@@ -1,2 +1,2 @@
-export const WHITE_PIXEL_TEXTURE: import("../ShadeTexture.js").ShadeTexture;
+export const WHITE_PIXEL_TEXTURE: ShadeTexture;
 //# sourceMappingURL=WHITE_PIXEL_TEXTURE.d.ts.map

package/src/shade/renderer/texture/util/WHITE_PIXEL_TEXTURE.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WHITE_PIXEL_TEXTURE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/util/WHITE_PIXEL_TEXTURE.js"],"names":[],"mappings":"AAGA,4EAAyE"}
+{"version":3,"file":"WHITE_PIXEL_TEXTURE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/util/WHITE_PIXEL_TEXTURE.js"],"names":[],"mappings":"AAGA,+CAAyE"}

package/src/shade/renderer/texture/util/get_single_pixel_texture.d.ts

@@ -4,5 +4,4 @@
  * @returns {ShadeTexture}
  */
 export function get_single_pixel_texture(color: Color): ShadeTexture;
-import { ShadeTexture } from "../ShadeTexture.js";
 //# sourceMappingURL=get_single_pixel_texture.d.ts.map

package/src/shade/renderer/texture/util/get_single_pixel_texture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get_single_pixel_texture.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/util/get_single_pixel_texture.js"],"names":[],"mappings":"AAsDA;;;;GAIG;AACH,wDAFa,YAAY,CAMxB;6BAzD4B,oBAAoB"}
+{"version":3,"file":"get_single_pixel_texture.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/util/get_single_pixel_texture.js"],"names":[],"mappings":"AAiCA;;;;GAIG;AACH,qEAIC"}

package/src/shade/renderer/texture/util/get_single_pixel_texture.js

@@ -3,12 +3,7 @@ import { Cache } from "../../../../core/cache/Cache.js";
 import { invokeObjectEquals } from "../../../../core/model/object/invokeObjectEquals.js";
 import { invokeObjectHash } from "../../../../core/model/object/invokeObjectHash.js";
 import { Sampler2D } from "../../../../engine/graphics/texture/sampler/Sampler2D.js";
-import { ColorSpace } from "../ColorSpace.js";
-import { ShadeTexture } from "../ShadeTexture.js";
-import { ShadeTextureFlags } from "../ShadeTextureFlags.js";
-import { ShadeImage } from "../source/ShadeImage.js";
-import { TextureFilterType } from "../TextureFilterType.js";
-import { TextureWrapType } from "../TextureWrapType.js";
+import { single_pixel_texture_from_sampler } from "./single_pixel_texture_from_sampler.js";
 
 /**
  *
@@ -33,23 +28,7 @@ function make_single_pixel_texture(color) {
     sampler.data[2] = float_to_uint8(color.b);
     sampler.data[3] = float_to_uint8(color.a);
 
-    const image = ShadeImage.fromSampler2D(sampler);
-
-    image.color_space = ColorSpace.LinearSRGB;
-
-    const texture = ShadeTexture.from(image);
-
-    texture.wrapS = TextureWrapType.ClampToEdge;
-    texture.wrapT = TextureWrapType.ClampToEdge;
-
-    texture.mipmapFilter = TextureFilterType.Nearest;
-    texture.minFilter = TextureFilterType.Nearest;
-    texture.magFilter = TextureFilterType.Nearest;
-
-    // no mip maps
-    texture.clearFlag(ShadeTextureFlags.GenerateMipMaps);
-
-    return texture;
+    return single_pixel_texture_from_sampler(sampler);
 }
 
 /**

package/src/shade/renderer/texture/util/single_pixel_texture_from_sampler.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A texture of one texel, which reads the same at every UV: clamped, unfiltered, no mips.
+ *
+ * The texel's format is the sampler's — its typed array and channel count, in linear space.
+ *
+ * @param {Sampler2D} sampler 1x1
+ * @returns {ShadeTexture}
+ */
+export function single_pixel_texture_from_sampler(sampler: Sampler2D): ShadeTexture;
+import { ShadeTexture } from "../ShadeTexture.js";
+//# sourceMappingURL=single_pixel_texture_from_sampler.d.ts.map

package/src/shade/renderer/texture/util/single_pixel_texture_from_sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"single_pixel_texture_from_sampler.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/util/single_pixel_texture_from_sampler.js"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,uEAFa,YAAY,CAoBxB;6BAhC4B,oBAAoB"}