@woosh/meep-engine 3.11.1 → 3.11.2

package/src/shade/wgsl/emulator/cpu_texture_gather.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Read the four texels of a bilinear footprint out of a {@link CPUBitmapData} without
+ * blending them — the CPU side of WGSL's `textureGather` / `textureGatherCompare`.
+ *
+ * **The footprint is the linear filter's footprint.** `cpu_texture_sample` derives it as
+ * `px = texel_coord - 0.5`, then `floor(px)` and `floor(px) + 1` on each axis, each index
+ * passed through {@link wrap_int} for the address mode. A gather covers exactly those four
+ * texels, so this function reuses that arithmetic rather than restating it.
+ *
+ * **`magFilter` is deliberately ignored.** A gather always returns four texels — the
+ * sampler's filter mode selects nothing, because no filtering happens. This is the one
+ * place `cpu_texture_sample` cannot simply be called: under `magFilter: "nearest"` it
+ * collapses to a single texel, which is right for a sample and wrong for a gather. The
+ * address modes still apply, and they are the only part of the sampler this reads.
+ *
+ * **Mipmaps are not modelled — LOD 0 only.** Same stance, and for the same reason, as
+ * {@link cpu_texture_sample}; see its header. `textureGather` has no LOD parameter in WGSL
+ * anyway, so here the restriction costs nothing.
+ *
+ * Convention for `texel_coord`, as in {@link cpu_texture_sample}: **texel-space**
+ * coordinates (UV * size), not normalised UV. The shader-facing intrinsics in
+ * {@link WGSLLanguageCore} do the conversion before calling.
+ *
+ * Component order is WGSL's, counter-clockwise from the lower-left texel — the same order
+ * D3D and Vulkan use:
+ *
+ * ```
+ *   output[0] = (u_min, v_max)   lower-left
+ *   output[1] = (u_max, v_max)   lower-right
+ *   output[2] = (u_max, v_min)   upper-right
+ *   output[3] = (u_min, v_min)   upper-left
+ * ```
+ *
+ * so `gathered.wzxy` is the row-major (x0y0, x1y0, x0y1, x1y1) order a bilinear blend
+ * wants — which is exactly the swizzle `shadowmap_sample_filtered` applies before handing
+ * the result to `interpolate_bilinear_f32`.
+ *
+ * @param {Float32Array | number[]} output — receives the 4 gathered texel values
+ * @param {import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor} sampler
+ * @param {import("./CPUBitmapData.js").CPUBitmapData} texture
+ * @param {Float32Array | number[]} texel_coord — `[x, y]` in texel space
+ * @param {number} [component] — channel to read, 0..3. Forced to 0 for a depth texture,
+ *   which has a single channel and whose WGSL overloads take no component argument.
+ * @param {number} [offset_x] — const `vec2<i32>` offset, applied to the integer texel
+ *   indices *before* the address mode, per WGSL
+ * @param {number} [offset_y]
+ * @param {number} [layer] — array slice for the `_2d_array` forms; clamped to the
+ *   texture's depth
+ */
+export function cpu_texture_gather(output: Float32Array | number[], sampler: import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor, texture: import("./CPUBitmapData.js").CPUBitmapData, texel_coord: Float32Array | number[], component?: number, offset_x?: number, offset_y?: number, layer?: number): void;
+/**
+ * Evaluate a `GPUCompareFunction` the way a comparison sampler does.
+ *
+ * **Argument order matters and is easy to invert.** WebGPU evaluates
+ * `compare(reference, sampled)` — the shader's `depth_ref` is the LEFT operand, the value
+ * read out of the depth texture is the right one. So under `"greater"` (what the engine's
+ * {@link SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR} uses, because shadow maps are reverse-Z) a
+ * receiver passes — result 1.0, "lit" — when its own depth is *greater* than the stored
+ * occluder depth, i.e. when it is nearer to the light. Swapping the operands inverts every
+ * shadow in the engine while still producing plausible-looking output, which is why
+ * `cpu_texture_gather.spec.js` pins the direction explicitly.
+ *
+ * @param {GPUCompareFunction} compare
+ * @param {number} reference — the shader's `depth_ref`
+ * @param {number} sampled — the texel read from the depth texture
+ * @returns {number} 1.0 when the comparison passes, 0.0 when it fails
+ */
+export function evaluate_gpu_compare_function(compare: GPUCompareFunction, reference: number, sampled: number): number;
+//# sourceMappingURL=cpu_texture_gather.d.ts.map

package/src/shade/wgsl/emulator/cpu_texture_gather.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cpu_texture_gather.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/cpu_texture_gather.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,2CAZW,YAAY,GAAG,MAAM,EAAE,WACvB,OAAO,+CAA+C,EAAE,iBAAiB,WACzE,OAAO,oBAAoB,EAAE,aAAa,eAC1C,YAAY,GAAG,MAAM,EAAE,cACvB,MAAM,aAEN,MAAM,aAEN,MAAM,UACN,MAAM,QAqChB;AAwBD;;;;;;;;;;;;;;;;GAgBG;AACH,sFAJW,MAAM,WACN,MAAM,GACJ,MAAM,CAuBlB"}

package/src/shade/wgsl/emulator/cpu_texture_gather.js

@@ -0,0 +1,148 @@
+import { wrap_int } from "./cpu_texture_sample.js";
+
+/**
+ * Read the four texels of a bilinear footprint out of a {@link CPUBitmapData} without
+ * blending them — the CPU side of WGSL's `textureGather` / `textureGatherCompare`.
+ *
+ * **The footprint is the linear filter's footprint.** `cpu_texture_sample` derives it as
+ * `px = texel_coord - 0.5`, then `floor(px)` and `floor(px) + 1` on each axis, each index
+ * passed through {@link wrap_int} for the address mode. A gather covers exactly those four
+ * texels, so this function reuses that arithmetic rather than restating it.
+ *
+ * **`magFilter` is deliberately ignored.** A gather always returns four texels — the
+ * sampler's filter mode selects nothing, because no filtering happens. This is the one
+ * place `cpu_texture_sample` cannot simply be called: under `magFilter: "nearest"` it
+ * collapses to a single texel, which is right for a sample and wrong for a gather. The
+ * address modes still apply, and they are the only part of the sampler this reads.
+ *
+ * **Mipmaps are not modelled — LOD 0 only.** Same stance, and for the same reason, as
+ * {@link cpu_texture_sample}; see its header. `textureGather` has no LOD parameter in WGSL
+ * anyway, so here the restriction costs nothing.
+ *
+ * Convention for `texel_coord`, as in {@link cpu_texture_sample}: **texel-space**
+ * coordinates (UV * size), not normalised UV. The shader-facing intrinsics in
+ * {@link WGSLLanguageCore} do the conversion before calling.
+ *
+ * Component order is WGSL's, counter-clockwise from the lower-left texel — the same order
+ * D3D and Vulkan use:
+ *
+ * ```
+ *   output[0] = (u_min, v_max)   lower-left
+ *   output[1] = (u_max, v_max)   lower-right
+ *   output[2] = (u_max, v_min)   upper-right
+ *   output[3] = (u_min, v_min)   upper-left
+ * ```
+ *
+ * so `gathered.wzxy` is the row-major (x0y0, x1y0, x0y1, x1y1) order a bilinear blend
+ * wants — which is exactly the swizzle `shadowmap_sample_filtered` applies before handing
+ * the result to `interpolate_bilinear_f32`.
+ *
+ * @param {Float32Array | number[]} output — receives the 4 gathered texel values
+ * @param {import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor} sampler
+ * @param {import("./CPUBitmapData.js").CPUBitmapData} texture
+ * @param {Float32Array | number[]} texel_coord — `[x, y]` in texel space
+ * @param {number} [component] — channel to read, 0..3. Forced to 0 for a depth texture,
+ *   which has a single channel and whose WGSL overloads take no component argument.
+ * @param {number} [offset_x] — const `vec2<i32>` offset, applied to the integer texel
+ *   indices *before* the address mode, per WGSL
+ * @param {number} [offset_y]
+ * @param {number} [layer] — array slice for the `_2d_array` forms; clamped to the
+ *   texture's depth
+ */
+export function cpu_texture_gather(
+    output,
+    sampler,
+    texture,
+    texel_coord,
+    component = 0,
+    offset_x = 0,
+    offset_y = 0,
+    layer = 0
+) {
+    const w = texture.size[0];
+    const h = texture.size[1];
+    const d = texture.size[2];
+
+    // A depth texture is single-channel; its gather overloads carry no component argument.
+    const channel = texture.is_depth === true ? 0 : (component | 0);
+
+    // Same derivation as the linear branch of `cpu_texture_sample`: shift by half a texel so
+    // the footprint is anchored on texel CENTRES, then floor.
+    const x_floor = Math.floor(texel_coord[0] - 0.5) + (offset_x | 0);
+    const y_floor = Math.floor(texel_coord[1] - 0.5) + (offset_y | 0);
+
+    const x0 = wrap_int(x_floor, w, sampler.addressModeU);
+    const x1 = wrap_int(x_floor + 1, w, sampler.addressModeU);
+    const y0 = wrap_int(y_floor, h, sampler.addressModeV);
+    const y1 = wrap_int(y_floor + 1, h, sampler.addressModeV);
+
+    // The array index is not an address-mode axis — WGSL clamps it to the layer count.
+    const z = d <= 0 ? 0 : Math.min(Math.max(layer | 0, 0), d - 1);
+
+    output[0] = read_channel(texture, x0, y1, z, channel);
+    output[1] = read_channel(texture, x1, y1, z, channel);
+    output[2] = read_channel(texture, x1, y0, z, channel);
+    output[3] = read_channel(texture, x0, y0, z, channel);
+}
+
+/**
+ * One channel of one texel. Channels past the texture's `item_size` follow the same
+ * convention `cpu_texture_sample` uses for its output vector: zero, with alpha defaulting
+ * to 1 — matching WGSL's rule for formats with fewer than four channels.
+ *
+ * Coordinates arrive already wrapped by {@link wrap_int}, so no bounds check is needed.
+ *
+ * @param {import("./CPUBitmapData.js").CPUBitmapData} texture
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} component
+ * @returns {number}
+ */
+function read_channel(texture, x, y, z, component) {
+    if (component >= texture.item_size) {
+        return component === 3 ? 1 : 0;
+    }
+
+    return texture.data[texture.pixel_offset(x, y, z) + component];
+}
+
+/**
+ * Evaluate a `GPUCompareFunction` the way a comparison sampler does.
+ *
+ * **Argument order matters and is easy to invert.** WebGPU evaluates
+ * `compare(reference, sampled)` — the shader's `depth_ref` is the LEFT operand, the value
+ * read out of the depth texture is the right one. So under `"greater"` (what the engine's
+ * {@link SHADOWMAP_COMPARE_SAMPLER_DESCRIPTOR} uses, because shadow maps are reverse-Z) a
+ * receiver passes — result 1.0, "lit" — when its own depth is *greater* than the stored
+ * occluder depth, i.e. when it is nearer to the light. Swapping the operands inverts every
+ * shadow in the engine while still producing plausible-looking output, which is why
+ * `cpu_texture_gather.spec.js` pins the direction explicitly.
+ *
+ * @param {GPUCompareFunction} compare
+ * @param {number} reference — the shader's `depth_ref`
+ * @param {number} sampled — the texel read from the depth texture
+ * @returns {number} 1.0 when the comparison passes, 0.0 when it fails
+ */
+export function evaluate_gpu_compare_function(compare, reference, sampled) {
+    switch (compare) {
+        case "never":
+            return 0;
+        case "less":
+            return reference < sampled ? 1 : 0;
+        case "equal":
+            return reference === sampled ? 1 : 0;
+        case "less-equal":
+            return reference <= sampled ? 1 : 0;
+        case "greater":
+            return reference > sampled ? 1 : 0;
+        case "not-equal":
+            return reference !== sampled ? 1 : 0;
+        case "greater-equal":
+            return reference >= sampled ? 1 : 0;
+        case "always":
+            return 1;
+        default:
+            throw new Error(`evaluate_gpu_compare_function: unsupported compare function '${compare}' (expected one of "never", "less", "equal", "less-equal", "greater", "not-equal", "greater-equal", "always")`);
+    }
+}

package/src/shade/wgsl/emulator/cpu_texture_sample.d.ts

@@ -36,4 +36,20 @@
  *   `texture.dimensionality` (1, 2 or 3 entries)
  */
 export function cpu_texture_sample(output: Float32Array | number[], sampler: import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor, texture: import("./CPUBitmapData.js").CPUBitmapData, texel_coord: Float32Array | number[]): void;
+/**
+ * Wrap an integer texel index back into `[0, size)` using the address
+ * mode. Shared by both nearest and linear filtering — the linear filter
+ * passes both the floor and floor+1 indices through this so wrapping at
+ * the edge is consistent.
+ *
+ * Exported because {@link cpu_texture_gather} needs the *same* address
+ * arithmetic: a gather's 2x2 footprint is the linear filter's footprint,
+ * and a second copy of this switch would be free to drift from it.
+ *
+ * @param {number} i
+ * @param {number} size
+ * @param {GPUAddressMode} mode
+ * @returns {number}
+ */
+export function wrap_int(i: number, size: number, mode: GPUAddressMode): number;
 //# sourceMappingURL=cpu_texture_sample.d.ts.map

package/src/shade/wgsl/emulator/cpu_texture_sample.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cpu_texture_sample.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/cpu_texture_sample.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,2CARW,YAAY,GAAG,MAAM,EAAE,WAGvB,OAAO,+CAA+C,EAAE,iBAAiB,WACzE,OAAO,oBAAoB,EAAE,aAAa,eAC1C,YAAY,GAAG,MAAM,EAAE,QAsGjC"}
+{"version":3,"file":"cpu_texture_sample.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/cpu_texture_sample.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,2CARW,YAAY,GAAG,MAAM,EAAE,WAGvB,OAAO,+CAA+C,EAAE,iBAAiB,WACzE,OAAO,oBAAoB,EAAE,aAAa,eAC1C,YAAY,GAAG,MAAM,EAAE,QAsGjC;AAED;;;;;;;;;;;;;;GAcG;AACH,4BALW,MAAM,QACN,MAAM,yBAEJ,MAAM,CAsBlB"}

package/src/shade/wgsl/emulator/cpu_texture_sample.js

@@ -1,172 +1,176 @@
-import { assert } from "../../../core/assert.js";
-
-/**
- * Sample a {@link CPUBitmapData} as if it were a GPU texture bound with
- * the given sampler. Routes through nearest or linear filtering on each of
- * the texture's actual axes (1D / 2D / 3D inferred from
- * `texture.dimensionality`).
- *
- * **Mipmaps are intentionally not modelled.** The emulator runs at LOD 0
- * only — there is no mip pyramid in {@link CPUBitmapData}, and
- * `mipmapFilter` / `lodMinClamp` / `lodMaxClamp` on the sampler are
- * ignored. We pick `magFilter` for the actual filter mode, which matches
- * the intuition that emulator tests are typically up-sampling. Add a mip
- * pyramid + minification path later if a test ever needs minified
- * sampling.
- *
- * Convention for `texel_coord`: this is **TEXEL-SPACE coordinates** (i.e.
- * UV * size, NOT normalised UV in [0, 1]). The shader-facing intrinsics
- * `textureSample` / `textureSampleLevel` take normalised UV; the emulator
- * converts to texel-space before calling here so the address-mode
- * arithmetic doesn't have to special-case sub-1.0 jitter. WebGPU's
- * convention places texel `i`'s centre at texel-space `i + 0.5`, so the
- * left edge of the texture is at 0 and the right edge at `size`.
- *
- * Address-mode handling lives in {@link wrap_int}: every integer texel
- * index produced by either filter passes through it before reading the
- * backing buffer. Out-of-range fractional inputs fall out naturally from
- * floor + integer wrap, so we don't pre-clamp the fractional coord (a
- * previous version did and lost full-edge texel sampling for
- * `clamp-to-edge`).
- *
- * @param {Float32Array | number[]} output — receives 4 channel values
- *   (channels beyond `texture.item_size` are zero, with alpha forced to 1
- *   for textures with fewer than 4 channels — matches WGSL semantics)
- * @param {import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor} sampler
- * @param {import("./CPUBitmapData.js").CPUBitmapData} texture
- * @param {Float32Array | number[]} texel_coord — length matches
- *   `texture.dimensionality` (1, 2 or 3 entries)
- */
-export function cpu_texture_sample(output, sampler, texture, texel_coord) {
-    assert.defined(output, 'output');
-    assert.defined(sampler, 'sampler');
-    assert.defined(texture, 'texture');
-    assert.defined(texel_coord, 'texel_coord');
-
-    // Default channels 0..3 to 0; alpha to 1 if the texture has < 4 channels.
-    const item_size = texture.item_size;
-    for (let i = 0; i < 4; i++) output[i] = 0;
-    if (item_size < 4) output[3] = 1;
-
-    const dim = texture.dimensionality;
-    const w = texture.size[0];
-    const h = texture.size[1];
-    const d = texture.size[2];
-
-    const tx = texel_coord[0];
-    const ty = dim >= 2 ? texel_coord[1] : 0;
-    const tz = dim >= 3 ? texel_coord[2] : 0;
-
-    // Mipmaps not modelled — see header. Use magFilter as the single
-    // filter setting (sampler is bound at LOD 0 conceptually).
-    const filter = sampler.magFilter;
-
-    if (filter === "nearest") {
-        // WGSL nearest: texel index = floor(texel_coord), then wrap.
-        const ix = wrap_int(Math.floor(tx), w, sampler.addressModeU);
-        const iy = dim >= 2 ? wrap_int(Math.floor(ty), h, sampler.addressModeV) : 0;
-        const iz = dim >= 3 ? wrap_int(Math.floor(tz), d, sampler.addressModeW) : 0;
-        const base = texture.pixel_offset(ix, iy, iz);
-        const n = Math.min(item_size, 4);
-        for (let i = 0; i < n; i++) output[i] = texture.data[base + i];
-        return;
-    }
-
-    if (filter !== "linear") {
-        throw new Error(`cpu_texture_sample: unsupported magFilter '${filter}' (expected "nearest" or "linear")`);
-    }
-
-    // Linear filter. Sample 2 (1D) / 4 (2D) / 8 (3D) neighbouring texels
-    // around `texel_coord - 0.5` (the offset puts the bilinear origin at
-    // texel CENTRES) with weights `(1 - frac, frac)` per axis. Each
-    // integer index passes through `wrap_int` so the right/bottom/back
-    // neighbour falling off the edge is resolved by the address mode.
-    const px = tx - 0.5;
-    const fx_floor = Math.floor(px);
-    const ix0 = wrap_int(fx_floor, w, sampler.addressModeU);
-    const ix1 = wrap_int(fx_floor + 1, w, sampler.addressModeU);
-    const fx = px - fx_floor;
-
-    let iy0 = 0, iy1 = 0, fy = 0;
-    if (dim >= 2) {
-        const py = ty - 0.5;
-        const fy_floor = Math.floor(py);
-        iy0 = wrap_int(fy_floor, h, sampler.addressModeV);
-        iy1 = wrap_int(fy_floor + 1, h, sampler.addressModeV);
-        fy = py - fy_floor;
-    }
-
-    let iz0 = 0, iz1 = 0, fz = 0;
-    if (dim >= 3) {
-        const pz = tz - 0.5;
-        const fz_floor = Math.floor(pz);
-        iz0 = wrap_int(fz_floor, d, sampler.addressModeW);
-        iz1 = wrap_int(fz_floor + 1, d, sampler.addressModeW);
-        fz = pz - fz_floor;
-    }
-
-    const n = Math.min(item_size, 4);
-
-    // Unrolled 2-corner loop per active axis (max 8 corners total). Skip
-    // zero-weight corners early — common when the fractional offset is
-    // exactly an integer (texel-centre sample).
-    const xs = [ix0, ix1];
-    const wxs = [1 - fx, fx];
-    const ys = [iy0, iy1];
-    const wys = [1 - fy, fy];
-    const zs = [iz0, iz1];
-    const wzs = [1 - fz, fz];
-
-    const y_count = dim >= 2 ? 2 : 1;
-    const z_count = dim >= 3 ? 2 : 1;
-
-    for (let kz = 0; kz < z_count; kz++) {
-        const wz = z_count === 1 ? 1 : wzs[kz];
-        const z = zs[kz];
-        for (let ky = 0; ky < y_count; ky++) {
-            const wy = y_count === 1 ? 1 : wys[ky];
-            const y = ys[ky];
-            for (let kx = 0; kx < 2; kx++) {
-                const wx = wxs[kx];
-                const x = xs[kx];
-                const weight = wx * wy * wz;
-                if (weight === 0) continue;
-                const base = texture.pixel_offset(x, y, z);
-                for (let i = 0; i < n; i++) output[i] += texture.data[base + i] * weight;
-            }
-        }
-    }
-}
-
-/**
- * Wrap an integer texel index back into `[0, size)` using the address
- * mode. Shared by both nearest and linear filtering — the linear filter
- * passes both the floor and floor+1 indices through this so wrapping at
- * the edge is consistent.
- *
- * @param {number} i
- * @param {number} size
- * @param {GPUAddressMode} mode
- * @returns {number}
- */
-function wrap_int(i, size, mode) {
-    if (size <= 0) return 0;
-    switch (mode) {
-        case "clamp-to-edge":
-            if (i < 0) return 0;
-            if (i >= size) return size - 1;
-            return i;
-        case "repeat":
-            return ((i % size) + size) % size;
-        case "mirror-repeat": {
-            // fold the second half of the period back onto the first:
-            // w in [size, 2*size) maps to period - 1 - w in [0, size)
-            const period = size * 2;
-            let w = ((i % period) + period) % period;
-            if (w >= size) w = period - 1 - w;
-            return w;
-        }
-        default:
-            throw new Error(`cpu_texture_sample: unsupported address mode '${mode}' (expected "clamp-to-edge", "repeat", or "mirror-repeat")`);
-    }
-}
+import { assert } from "../../../core/assert.js";
+
+/**
+ * Sample a {@link CPUBitmapData} as if it were a GPU texture bound with
+ * the given sampler. Routes through nearest or linear filtering on each of
+ * the texture's actual axes (1D / 2D / 3D inferred from
+ * `texture.dimensionality`).
+ *
+ * **Mipmaps are intentionally not modelled.** The emulator runs at LOD 0
+ * only — there is no mip pyramid in {@link CPUBitmapData}, and
+ * `mipmapFilter` / `lodMinClamp` / `lodMaxClamp` on the sampler are
+ * ignored. We pick `magFilter` for the actual filter mode, which matches
+ * the intuition that emulator tests are typically up-sampling. Add a mip
+ * pyramid + minification path later if a test ever needs minified
+ * sampling.
+ *
+ * Convention for `texel_coord`: this is **TEXEL-SPACE coordinates** (i.e.
+ * UV * size, NOT normalised UV in [0, 1]). The shader-facing intrinsics
+ * `textureSample` / `textureSampleLevel` take normalised UV; the emulator
+ * converts to texel-space before calling here so the address-mode
+ * arithmetic doesn't have to special-case sub-1.0 jitter. WebGPU's
+ * convention places texel `i`'s centre at texel-space `i + 0.5`, so the
+ * left edge of the texture is at 0 and the right edge at `size`.
+ *
+ * Address-mode handling lives in {@link wrap_int}: every integer texel
+ * index produced by either filter passes through it before reading the
+ * backing buffer. Out-of-range fractional inputs fall out naturally from
+ * floor + integer wrap, so we don't pre-clamp the fractional coord (a
+ * previous version did and lost full-edge texel sampling for
+ * `clamp-to-edge`).
+ *
+ * @param {Float32Array | number[]} output — receives 4 channel values
+ *   (channels beyond `texture.item_size` are zero, with alpha forced to 1
+ *   for textures with fewer than 4 channels — matches WGSL semantics)
+ * @param {import("../../descriptor/texture/SamplerDescriptor.js").SamplerDescriptor} sampler
+ * @param {import("./CPUBitmapData.js").CPUBitmapData} texture
+ * @param {Float32Array | number[]} texel_coord — length matches
+ *   `texture.dimensionality` (1, 2 or 3 entries)
+ */
+export function cpu_texture_sample(output, sampler, texture, texel_coord) {
+    assert.defined(output, 'output');
+    assert.defined(sampler, 'sampler');
+    assert.defined(texture, 'texture');
+    assert.defined(texel_coord, 'texel_coord');
+
+    // Default channels 0..3 to 0; alpha to 1 if the texture has < 4 channels.
+    const item_size = texture.item_size;
+    for (let i = 0; i < 4; i++) output[i] = 0;
+    if (item_size < 4) output[3] = 1;
+
+    const dim = texture.dimensionality;
+    const w = texture.size[0];
+    const h = texture.size[1];
+    const d = texture.size[2];
+
+    const tx = texel_coord[0];
+    const ty = dim >= 2 ? texel_coord[1] : 0;
+    const tz = dim >= 3 ? texel_coord[2] : 0;
+
+    // Mipmaps not modelled — see header. Use magFilter as the single
+    // filter setting (sampler is bound at LOD 0 conceptually).
+    const filter = sampler.magFilter;
+
+    if (filter === "nearest") {
+        // WGSL nearest: texel index = floor(texel_coord), then wrap.
+        const ix = wrap_int(Math.floor(tx), w, sampler.addressModeU);
+        const iy = dim >= 2 ? wrap_int(Math.floor(ty), h, sampler.addressModeV) : 0;
+        const iz = dim >= 3 ? wrap_int(Math.floor(tz), d, sampler.addressModeW) : 0;
+        const base = texture.pixel_offset(ix, iy, iz);
+        const n = Math.min(item_size, 4);
+        for (let i = 0; i < n; i++) output[i] = texture.data[base + i];
+        return;
+    }
+
+    if (filter !== "linear") {
+        throw new Error(`cpu_texture_sample: unsupported magFilter '${filter}' (expected "nearest" or "linear")`);
+    }
+
+    // Linear filter. Sample 2 (1D) / 4 (2D) / 8 (3D) neighbouring texels
+    // around `texel_coord - 0.5` (the offset puts the bilinear origin at
+    // texel CENTRES) with weights `(1 - frac, frac)` per axis. Each
+    // integer index passes through `wrap_int` so the right/bottom/back
+    // neighbour falling off the edge is resolved by the address mode.
+    const px = tx - 0.5;
+    const fx_floor = Math.floor(px);
+    const ix0 = wrap_int(fx_floor, w, sampler.addressModeU);
+    const ix1 = wrap_int(fx_floor + 1, w, sampler.addressModeU);
+    const fx = px - fx_floor;
+
+    let iy0 = 0, iy1 = 0, fy = 0;
+    if (dim >= 2) {
+        const py = ty - 0.5;
+        const fy_floor = Math.floor(py);
+        iy0 = wrap_int(fy_floor, h, sampler.addressModeV);
+        iy1 = wrap_int(fy_floor + 1, h, sampler.addressModeV);
+        fy = py - fy_floor;
+    }
+
+    let iz0 = 0, iz1 = 0, fz = 0;
+    if (dim >= 3) {
+        const pz = tz - 0.5;
+        const fz_floor = Math.floor(pz);
+        iz0 = wrap_int(fz_floor, d, sampler.addressModeW);
+        iz1 = wrap_int(fz_floor + 1, d, sampler.addressModeW);
+        fz = pz - fz_floor;
+    }
+
+    const n = Math.min(item_size, 4);
+
+    // Unrolled 2-corner loop per active axis (max 8 corners total). Skip
+    // zero-weight corners early — common when the fractional offset is
+    // exactly an integer (texel-centre sample).
+    const xs = [ix0, ix1];
+    const wxs = [1 - fx, fx];
+    const ys = [iy0, iy1];
+    const wys = [1 - fy, fy];
+    const zs = [iz0, iz1];
+    const wzs = [1 - fz, fz];
+
+    const y_count = dim >= 2 ? 2 : 1;
+    const z_count = dim >= 3 ? 2 : 1;
+
+    for (let kz = 0; kz < z_count; kz++) {
+        const wz = z_count === 1 ? 1 : wzs[kz];
+        const z = zs[kz];
+        for (let ky = 0; ky < y_count; ky++) {
+            const wy = y_count === 1 ? 1 : wys[ky];
+            const y = ys[ky];
+            for (let kx = 0; kx < 2; kx++) {
+                const wx = wxs[kx];
+                const x = xs[kx];
+                const weight = wx * wy * wz;
+                if (weight === 0) continue;
+                const base = texture.pixel_offset(x, y, z);
+                for (let i = 0; i < n; i++) output[i] += texture.data[base + i] * weight;
+            }
+        }
+    }
+}
+
+/**
+ * Wrap an integer texel index back into `[0, size)` using the address
+ * mode. Shared by both nearest and linear filtering — the linear filter
+ * passes both the floor and floor+1 indices through this so wrapping at
+ * the edge is consistent.
+ *
+ * Exported because {@link cpu_texture_gather} needs the *same* address
+ * arithmetic: a gather's 2x2 footprint is the linear filter's footprint,
+ * and a second copy of this switch would be free to drift from it.
+ *
+ * @param {number} i
+ * @param {number} size
+ * @param {GPUAddressMode} mode
+ * @returns {number}
+ */
+export function wrap_int(i, size, mode) {
+    if (size <= 0) return 0;
+    switch (mode) {
+        case "clamp-to-edge":
+            if (i < 0) return 0;
+            if (i >= size) return size - 1;
+            return i;
+        case "repeat":
+            return ((i % size) + size) % size;
+        case "mirror-repeat": {
+            // fold the second half of the period back onto the first:
+            // w in [size, 2*size) maps to period - 1 - w in [0, size)
+            const period = size * 2;
+            let w = ((i % period) + period) % period;
+            if (w >= size) w = period - 1 - w;
+            return w;
+        }
+        default:
+            throw new Error(`cpu_texture_sample: unsupported address mode '${mode}' (expected "clamp-to-edge", "repeat", or "mirror-repeat")`);
+    }
+}