@woosh/meep-engine 3.38.0 → 3.40.0

package/src/shade/renderer/shadow/vsm/shader/shader_vsm_skinned_movers.js

@@ -0,0 +1,109 @@
+import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
+import { SKINNING_BINDING_STRUCT } from "../../../animation/skinning/SKINNING_BINDING_STRUCT.js";
+import { chunk_scene_database_access } from "../../../scene/chunk_scene_database_access.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { mat4x4f, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { VSM_MOVERS_STRUCT } from "../VSM_MOVER_LAYOUT.js";
+import { chunk_vsm_append_mover } from "./chunk_vsm_append_mover.js";
+
+export const VSM_SKINNED_MOVERS_WORKGROUP_SIZE = 64;
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const VSM_SKINNED_MOVERS_SETTINGS_STRUCT = WebGPUStruct.from({
+    binding_count: u32,
+    capacity: u32,
+}, "VSMSkinnedMoversSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate('settings', VSM_SKINNED_MOVERS_SETTINGS_STRUCT);
+
+resources.createGroup()
+    .addStorageBuffer('scene_database', WebGPUArray.from(u32), false)
+    .addStorageBuffer('bindings', WebGPUArray.from(SKINNING_BINDING_STRUCT), false)
+    .addStorageBuffer('skin_matrices', WebGPUArray.from(mat4x4f), false)
+    .addStorageBuffer('prev_skin_matrices', WebGPUArray.from(mat4x4f), false)
+    .addStorageBuffer('movers', VSM_MOVERS_STRUCT, true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const LANES = ${VSM_SKINNED_MOVERS_WORKGROUP_SIZE}u;
+
+// set by the first lane to find a joint that moved: that lane alone lists the mesh
+var<workgroup> claimed: atomic<u32>;
+
+fn vsm_matrix_differs(a: mat4x4f, b: mat4x4f) -> bool {
+    return any(a[0] != b[0]) || any(a[1] != b[1]) || any(a[2] != b[2]) || any(a[3] != b[3]);
+}
+
+@compute @workgroup_size(${VSM_SKINNED_MOVERS_WORKGROUP_SIZE},1,1)
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let index = workgroup_id.x;
+
+    // the whole workgroup's binding, so the whole workgroup leaves
+    if (index >= settings.binding_count) {
+        return;
+    }
+
+    let binding = bindings[index];
+
+    // a lane's joints, a workgroup's width apart: as many as the skin has, over the lanes
+    var moved = false;
+
+    for (var j = lane; j < binding.skin_matrix_count; j += LANES) {
+        let row = binding.skin_matrix_offset + j;
+
+        moved = moved || vsm_matrix_differs(skin_matrices[row], prev_skin_matrices[row]);
+    }
+
+    let first = moved && atomicExchange(&claimed, 1u) == 0u;
+
+    var box_min = vec3f(0.0);
+    var box_max = vec3f(0.0);
+
+    if (first) {
+        let mesh = scene_read_mesh(&scene_database, binding.mesh_instance_index);
+
+        box_min = vec3f(mesh.bounding_box[0], mesh.bounding_box[1], mesh.bounding_box[2]);
+        box_max = vec3f(mesh.bounding_box[3], mesh.bounding_box[4], mesh.bounding_box[5]);
+    }
+
+    vsm_append_mover(first && all(box_min <= box_max), box_min, box_max, settings.capacity);
+}
+`, [
+    SKINNING_BINDING_STRUCT.declaration_chunk,
+    chunk_scene_database_access,
+    chunk_vsm_append_mover,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * List every skinned mesh whose pose changed since last frame: a joint's skin matrix differs from
+ * the one the animation manager kept from the frame before. A pose can change inside bounds that
+ * stay put — an arm swinging inside the box its feet and head set — which neither the row's
+ * transform nor its box would show; a skin held still is no mover.
+ *
+ * The mesh's box is this frame's, after the bounds refresh: a pose that changed it is also caught by
+ * {@link shader_vsm_movers}, with where the mesh was.
+ *
+ * One workgroup per skinning binding, its lanes over the skin's joints, after
+ * {@link shader_vsm_movers} into the same list.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_skinned_movers = ComputeShader.from({
+    label: "VSM/SkinnedMovers",
+    body,
+    resources,
+});

package/src/shade/renderer/shadow/vsm/shader/shader_vsm_stale.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Slots a stale-pass workgroup tests against its mover: one per lane.
+ * @type {number}
+ */
+export const VSM_STALE_WORKGROUP_SIZE: number;
+/**
+ * @type {WebGPUStruct}
+ */
+export const VSM_STALE_ARGS_SETTINGS_STRUCT: WebGPUStruct;
+/**
+ * Size the stale pass to this frame's movers: `(ceil(slots / 64), movers, 1)` workgroups, a row of
+ * workgroups per mover — or one row when the list overflowed, which marks every occupied slot. No
+ * movers, no workgroups.
+ *
+ * One thread.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_stale_args: ComputeShader;
+/**
+ * @type {WebGPUStruct}
+ */
+export const VSM_STALE_SETTINGS_STRUCT: WebGPUStruct;
+/**
+ * Mark the pool slots a mover crossed: workgroup `(x, y)` tests mover `y` against slots
+ * `[64x, 64x + 64)`, one lane a slot, so no thread loops.
+ *
+ * A slot's page is a square of its level in light space, widened by its border — the slot's whole
+ * extent, filtering included. A mover's world box goes into light space as a box around its centre:
+ * the light view's rotation of the centre, and the absolute rotation of the half-extent. A hit sets
+ * the slot's flag, which stays set until {@link shader_vsm_stale_compact} lists it for a readback, so
+ * a frame whose readback was skipped loses nothing.
+ *
+ * When the mover list overflowed, the one row of workgroups marks every occupied slot.
+ *
+ * Dispatch indirect from {@link shader_vsm_stale_args}.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_stale: ComputeShader;
+/**
+ * @type {WebGPUStruct}
+ */
+export const VSM_STALE_COMPACT_SETTINGS_STRUCT: WebGPUStruct;
+/**
+ * List the slots flagged stale into the feedback buffer, clearing their flags, and copy the frame's
+ * mover count into its header. Runs on the frames a readback is taken, after {@link shader_vsm_stale}.
+ *
+ * One thread per slot.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_stale_compact: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_vsm_stale.d.ts.map

package/src/shade/renderer/shadow/vsm/shader/shader_vsm_stale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_vsm_stale.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/vsm/shader/shader_vsm_stale.js"],"names":[],"mappings":"AAYA;;;GAGG;AACH,uCAFU,MAAM,CAE2B;AAM3C;;GAEG;AACH,6CAFU,YAAY,CAIK;AAU3B;;;;;;;;GAQG;AACH,oCAFU,aAAa,CAiBpB;AAEH;;GAEG;AACH,wCAFU,YAAY,CAIC;AAYvB;;;;;;;;;;;;;;;GAeG;AACH,+BAFU,aAAa,CA6DpB;AAEH;;GAEG;AACH,gDAFU,YAAY,CAKQ;AAW9B;;;;;;;GAOG;AACH,uCAFU,aAAa,CA8BpB;6BA5M0B,sCAAsC;8BAJrC,kCAAkC"}

package/src/shade/renderer/shadow/vsm/shader/shader_vsm_stale.js

@@ -0,0 +1,211 @@
+import { LIGHT_DATABASE_SPEC } from "../../../light/LIGHT_DATABASE_SPEC.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { VSM_FEEDBACK_LAYOUT } from "../VSM_FEEDBACK_LAYOUT.js";
+import { VSM_MOVER_CAPACITY, VSM_MOVERS_READ_STRUCT } from "../VSM_MOVER_LAYOUT.js";
+import { VSM_SLOT_EMPTY } from "../VSM_SLOT_STRUCT.js";
+import { chunk_vsm_addressing } from "./chunk_vsm_addressing.js";
+
+/**
+ * Slots a stale-pass workgroup tests against its mover: one per lane.
+ * @type {number}
+ */
+export const VSM_STALE_WORKGROUP_SIZE = 64;
+
+const RECORD_TABLE = LIGHT_DATABASE_SPEC.get('shadow_virtual');
+const SLOT_TABLE = LIGHT_DATABASE_SPEC.get('shadow_virtual_slot');
+const L = VSM_FEEDBACK_LAYOUT;
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const VSM_STALE_ARGS_SETTINGS_STRUCT = WebGPUStruct.from({
+    slot_count: u32,
+}, "VSMStaleArgsSettings");
+
+const args_resources = new ShaderResourceSetDescriptor();
+
+args_resources.setImmediate('settings', VSM_STALE_ARGS_SETTINGS_STRUCT);
+
+args_resources.createGroup()
+    .addStorageBuffer('movers', VSM_MOVERS_READ_STRUCT, false)
+    .addStorageBuffer('command', WebGPUArray.from(u32), true);
+
+/**
+ * Size the stale pass to this frame's movers: `(ceil(slots / 64), movers, 1)` workgroups, a row of
+ * workgroups per mover — or one row when the list overflowed, which marks every occupied slot. No
+ * movers, no workgroups.
+ *
+ * One thread.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_stale_args = ComputeShader.from({
+    label: "VSM/StaleArgs",
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(1, 1, 1)
+fn main() {
+    let count = movers.count;
+
+    command[0] = (settings.slot_count + ${VSM_STALE_WORKGROUP_SIZE - 1}u) / ${VSM_STALE_WORKGROUP_SIZE}u;
+    command[1] = select(count, 1u, count > ${VSM_MOVER_CAPACITY}u);
+    command[2] = 1u;
+}
+`),
+    resources: args_resources,
+});
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const VSM_STALE_SETTINGS_STRUCT = WebGPUStruct.from({
+    record_row: u32,
+}, "VSMStaleSettings");
+
+const stale_resources = new ShaderResourceSetDescriptor();
+
+stale_resources.setImmediate('settings', VSM_STALE_SETTINGS_STRUCT);
+
+stale_resources.createGroup()
+    .addStorageBuffer('light_database', WebGPUArray.from(u32), false)
+    .addStorageBuffer('movers', VSM_MOVERS_READ_STRUCT, false)
+    // persistent, one word per slot: 1 when a mover crossed the slot since the flags were last read
+    .addStorageBuffer('stale_flags', WebGPUArray.from(atomic_u32), true);
+
+/**
+ * Mark the pool slots a mover crossed: workgroup `(x, y)` tests mover `y` against slots
+ * `[64x, 64x + 64)`, one lane a slot, so no thread loops.
+ *
+ * A slot's page is a square of its level in light space, widened by its border — the slot's whole
+ * extent, filtering included. A mover's world box goes into light space as a box around its centre:
+ * the light view's rotation of the centre, and the absolute rotation of the half-extent. A hit sets
+ * the slot's flag, which stays set until {@link shader_vsm_stale_compact} lists it for a readback, so
+ * a frame whose readback was skipped loses nothing.
+ *
+ * When the mover list overflowed, the one row of workgroups marks every occupied slot.
+ *
+ * Dispatch indirect from {@link shader_vsm_stale_args}.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_stale = ComputeShader.from({
+    label: "VSM/Stale",
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${VSM_STALE_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) wg_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let record = ${RECORD_TABLE.marshalling_method_read}(&light_database, settings.record_row);
+
+    let slot = wg_id.x * ${VSM_STALE_WORKGROUP_SIZE}u + lane;
+
+    if (slot >= record.slot_count) {
+        return;
+    }
+
+    let held = ${SLOT_TABLE.marshalling_method_read}(&light_database, record.first_slot + slot);
+
+    if (held.level == ${VSM_SLOT_EMPTY}u) {
+        return;
+    }
+
+    var hit = false;
+
+    if (movers.count > ${VSM_MOVER_CAPACITY}u) {
+        // the list overflowed: every occupied slot may hold a stale shadow
+        hit = wg_id.y == 0u;
+    } else {
+        let low = movers.boxes[wg_id.y * 2u].xyz;
+        let high = movers.boxes[wg_id.y * 2u + 1u].xyz;
+
+        let centre = (low + high) * 0.5;
+        let half_extent = (high - low) * 0.5;
+
+        let view = record.view;
+        let centre_ls = (view * vec4f(centre, 1.0)).xy;
+        let reach = abs(view[0].xy) * half_extent.x + abs(view[1].xy) * half_extent.y + abs(view[2].xy) * half_extent.z;
+
+        let size = vsm_page_world_size(record, held.level);
+        let border = size * f32(record.border) / f32(record.page_size);
+
+        let slot_min = vec2f(f32(held.x), f32(held.y)) * size - border;
+        let slot_max = vec2f(f32(held.x + 1), f32(held.y + 1)) * size + border;
+
+        hit = all(centre_ls + reach >= slot_min) && all(centre_ls - reach <= slot_max);
+    }
+
+    if (hit) {
+        atomicStore(&stale_flags[slot], 1u);
+    }
+}
+`, [
+            RECORD_TABLE.chunk_read,
+            SLOT_TABLE.chunk_read,
+            chunk_vsm_addressing,
+        ]),
+    resources: stale_resources,
+});
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const VSM_STALE_COMPACT_SETTINGS_STRUCT = WebGPUStruct.from({
+    slot_count: u32,
+    request_capacity: u32,
+}, "VSMStaleCompactSettings");
+
+const compact_resources = new ShaderResourceSetDescriptor();
+
+compact_resources.setImmediate('settings', VSM_STALE_COMPACT_SETTINGS_STRUCT);
+
+compact_resources.createGroup()
+    .addStorageBuffer('movers', VSM_MOVERS_READ_STRUCT, false)
+    .addStorageBuffer('stale_flags', WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer('feedback', WebGPUArray.from(atomic_u32), true);
+
+/**
+ * List the slots flagged stale into the feedback buffer, clearing their flags, and copy the frame's
+ * mover count into its header. Runs on the frames a readback is taken, after {@link shader_vsm_stale}.
+ *
+ * One thread per slot.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vsm_stale_compact = ComputeShader.from({
+    label: "VSM/StaleCompact",
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(64, 1, 1)
+fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    let slot = global_id.x;
+
+    if (slot == 0u) {
+        atomicStore(&feedback[${L.MOVER_COUNT}u], movers.count);
+    }
+
+    if (slot >= settings.slot_count) {
+        return;
+    }
+
+    if (atomicExchange(&stale_flags[slot], 0u) == 0u) {
+        return;
+    }
+
+    let index = atomicAdd(&feedback[${L.STALE_COUNT}u], 1u);
+    let stale_offset = ${L.HEADER_WORDS}u + settings.request_capacity * ${L.REQUEST_WORDS}u;
+
+    atomicStore(&feedback[stale_offset + index], slot);
+}
+`),
+    resources: compact_resources,
+});

package/src/shade/renderer/texture/format/decode_typed_gpu_data.d.ts

@@ -2,7 +2,7 @@
  *
  * @param {BinaryDataType} type
  * @param {ArrayBuffer} buffer
- * @retuns {Uint8Array|Float32Array}
+ * @returns {Uint8Array|Float32Array}
  */
 export function decode_typed_gpu_data(type: BinaryDataType, buffer: ArrayBuffer): Uint8Array | Float32Array;
 import { BinaryDataType } from "../../../../core/binary/type/BinaryDataType.js";

package/src/shade/renderer/texture/format/decode_typed_gpu_data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decode_typed_gpu_data.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/format/decode_typed_gpu_data.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,4CAJW,cAAc,UACd,WAAW,6BA0BrB;+BA/B8B,gDAAgD"}
+{"version":3,"file":"decode_typed_gpu_data.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/format/decode_typed_gpu_data.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,4CAJW,cAAc,UACd,WAAW,GACT,UAAU,GAAC,YAAY,CAgBnC;+BAtB8B,gDAAgD"}

package/src/shade/renderer/texture/format/decode_typed_gpu_data.js

@@ -1,11 +1,10 @@
-import { half_to_float_uint16 } from "../../../../core/binary/half_to_float_uint16.js";
 import { BinaryDataType } from "../../../../core/binary/type/BinaryDataType.js";
 
 /**
  *
  * @param {BinaryDataType} type
  * @param {ArrayBuffer} buffer
- * @retuns {Uint8Array|Float32Array}
+ * @returns {Uint8Array|Float32Array}
  */
 export function decode_typed_gpu_data(type, buffer) {
 
@@ -13,16 +12,7 @@ export function decode_typed_gpu_data(type, buffer) {
         return new Float32Array(buffer).slice();
     } else if (type === BinaryDataType.Float16) {
 
-        const u16 = new Uint16Array(buffer);
-
-        const length = u16.length;
-        const result = new Float32Array(length);
-
-        for (let i = 0; i < length; i++) {
-            result[i] = half_to_float_uint16(u16[i])
-        }
-
-        return result;
+        return new Float32Array(new Float16Array(buffer));
 
     } else if (type === BinaryDataType.Uint8) {
         return new Uint8Array(buffer).slice();
@@ -30,4 +20,4 @@ export function decode_typed_gpu_data(type, buffer) {
         throw new Error(`Unsupported type '${type}'`);
     }
 
-}
+}

package/src/shade/renderer/texture/format/infer_format_from_parameters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"infer_format_from_parameters.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/format/infer_format_from_parameters.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,4DANW,MAAM,aACN,cAAc,cACd,OAAO,eACP,UAAU,oBA6EpB;+BArF8B,gDAAgD;2BAEpD,kBAAkB"}
+{"version":3,"file":"infer_format_from_parameters.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/format/infer_format_from_parameters.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,4DANW,MAAM,aACN,cAAc,cACd,OAAO,eACP,UAAU,oBA4EpB;+BApF8B,gDAAgD;2BAEpD,kBAAkB"}

package/src/shade/renderer/texture/format/infer_format_from_parameters.js

@@ -45,9 +45,8 @@ export function infer_format_from_parameters(
         } else if (data_type === BinaryDataType.Float32) {
             ending = "float";
         } else if (data_type === BinaryDataType.Float16 || data_type === BinaryDataType.Uint16) {
-            // Half-float HDR data (e.g. octahedral environment maps). parse_rgbe stores f16 bit
-            // patterns in a Uint16Array, so the same half-float payload can be classified as either
-            // Float16 or Uint16 depending on the runtime — both map to the 16-bit float format.
+            // Native Float16Array data and legacy Uint16Array-packed half-float samplers
+            // both carry binary16 bytes for the GPU.
             ending = "float";
         } else {
             throw new Error(`Unsupported data type '${data_type}'`);

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

@@ -1 +1 @@
-{"version":3,"file":"texture_write_to_gpu.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/texture_write_to_gpu.js"],"names":[],"mappings":"AAyKA;;;;;;;;;;;;GAYG;AACH,2GAFW,MAAM,QAqGhB"}
+{"version":3,"file":"texture_write_to_gpu.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/texture/texture_write_to_gpu.js"],"names":[],"mappings":"AAsKA;;;;;;;;;;;;GAYG;AACH,2GAFW,MAAM,QAwGhB"}

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

@@ -1,6 +1,4 @@
 import { assert } from "../../../core/assert.js";
-import { half_to_float_uint16 } from "../../../core/binary/half_to_float_uint16.js";
-import { to_half_float_uint16 } from "../../../core/binary/to_half_float_uint16.js";
 import { BinaryDataType } from "../../../core/binary/type/BinaryDataType.js";
 import { dataTypeByteSize } from "../../../core/binary/type/DataTypeByteSizes.js";
 import { array_copy } from "../../../core/collection/array/array_copy.js";
@@ -23,9 +21,8 @@ function channel_one_bytes(data_type) {
             return new Uint8Array([0x7F]);
         case BinaryDataType.Uint16:
         case BinaryDataType.Float16:
-            // Uint16Array-backed images carry raw binary16 by project convention (see
-            // premultiply_rgba_in_place) — 1.0 is the bit pattern 0x3C00 for both
-            return new Uint8Array(new Uint16Array([0x3C00]).buffer);
+            // Includes legacy samplers that store packed binary16 in Uint16Array.
+            return new Uint8Array(new Float16Array([1]).buffer);
         case BinaryDataType.Int16:
             return new Uint8Array(new Int16Array([0x7FFF]).buffer);
         case BinaryDataType.Float32:
@@ -59,13 +56,11 @@ function premultiply_rgba_in_place(data, data_type) {
             v[i + 2] *= a;
         }
     } else if (data_type === BinaryDataType.Float16 || data_type === BinaryDataType.Uint16) {
-        // Uint16Array-backed images carry raw binary16 bit patterns by project convention
-        // (parse_rgbe, decode_image_source_hdr — fromSampler2D classifies them as Uint16
-        // because the bit width is all a typed array exposes). Integer math on the bit
-        // patterns would destroy the texels; decode/encode through half-float instead.
-        const v = new Uint16Array(data);
+        // Float16Array reads and writes numeric values over the same binary16 bytes,
+        // including payloads from legacy Uint16Array-backed half-float samplers.
+        const v = new Float16Array(data);
         for (let i = 0; i < v.length; i += 4) {
-            const a = half_to_float_uint16(v[i + 3]);
+            const a = v[i + 3];
 
             if (a === 1) {
                 // overwhelmingly common (HDR sources write alpha = 1): identity, and
@@ -73,9 +68,11 @@ function premultiply_rgba_in_place(data, data_type) {
                 continue;
             }
 
-            v[i] = to_half_float_uint16(half_to_float_uint16(v[i]) * a);
-            v[i + 1] = to_half_float_uint16(half_to_float_uint16(v[i + 1]) * a);
-            v[i + 2] = to_half_float_uint16(half_to_float_uint16(v[i + 2]) * a);
+            for (let c = 0; c < 3; c++) {
+                const value = v[i + c] * a;
+                // Retain saturation of finite overflow; preserve NaN and infinities.
+                v[i + c] = Number.isFinite(value) ? Math.min(Math.max(value, -65504), 65504) : value;
+            }
         }
     } else {
         throw new Error(`Unsupported data type for premultiplication: ${data_type}`);
@@ -244,10 +241,13 @@ export function texture_write_to_gpu(
     if (source.isSampler2D) {
 
         const source_data = source.data;
+        const source_buffer = source_data.byteOffset === 0 && source_data.byteLength === source_data.buffer.byteLength
+            ? source_data.buffer
+            : source_data.buffer.slice(source_data.byteOffset, source_data.byteOffset + source_data.byteLength);
 
         texture_write_raw(
             image,
-            source_data.buffer,
+            source_buffer,
             queue,
             texture,
             premultiplyAlpha,
@@ -279,4 +279,4 @@ export function texture_write_to_gpu(
         );
 
     }
-}
+}

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);
 }
 
 /**