@woosh/meep-engine 3.64.0 → 3.65.0

package/src/format/image/exr/exr_write.js

@@ -0,0 +1,378 @@
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+import { compress_bytes } from "../../../core/binary/compression/compress_bytes.js";
+import { EndianType } from "../../../core/binary/EndianType.js";
+import { utf8_encode_into } from "../../../core/binary/utf8/utf8_encode_into.js";
+import { utf8_encoded_length } from "../../../core/binary/utf8/utf8_encoded_length.js";
+import {
+    EXR_FLAG_LONG_NAMES,
+    EXR_LONG_NAME_BYTES,
+    EXR_MAGIC,
+    EXR_SHORT_NAME_BYTES,
+    EXR_VERSION
+} from "./exr_constants.js";
+import { exr_compare_names } from "./exr_compare_names.js";
+import { exr_sample_bits } from "./exr_sample_bits.js";
+import { exr_scanlines_per_chunk } from "./exr_scanlines_per_chunk.js";
+import { ExrCompression } from "./ExrCompression.js";
+import { ExrPixelType } from "./ExrPixelType.js";
+
+/**
+ * The largest value of the format's signed 32-bit fields: a chunk's size, and the data window's corners.
+ *
+ * @readonly
+ * @type {number}
+ */
+const INT32_MAX = 0x7FFFFFFF;
+
+/**
+ * Write an image as a scanline OpenEXR file.
+ *
+ * Each channel is written in the pixel type its array holds — a `Float16Array` as HALF, a `Float32Array`
+ * as FLOAT, a `Uint32Array` as UINT — and its samples go into the file as the bits they are. The header
+ * carries OpenEXR's required attributes and nothing else: both windows at the origin exactly covering the
+ * pixels, increasing line order, square pixels and the default screen window.
+ *
+ * Under {@link ExrCompression.ZIP} and {@link ExrCompression.ZIPS} a chunk that deflate does not make
+ * smaller is stored as it is, as OpenEXR's own writer does and every reader expects.
+ *
+ * The channels' arrays are read chunk by chunk as earlier chunks are compressed, so keep them unchanged
+ * until the promise settles.
+ *
+ * @param {ExrImage} image channels in any order, with distinct names of 1 to 255 bytes in UTF-8
+ * @param {ExrCompression} compression {@link ExrCompression.None}, {@link ExrCompression.ZIPS} or
+ * {@link ExrCompression.ZIP}
+ * @returns {Promise<ArrayBuffer>} the whole file
+ * @throws {Error} naming what about the image or the compression method cannot be written
+ *
+ * @see https://openexr.com/en/latest/OpenEXRFileLayout.html
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export async function exr_write(image, compression) {
+    const width = image.width;
+    const height = image.height;
+
+    // the data window's corners are signed 32-bit integers
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1
+        || width - 1 > INT32_MAX || height - 1 > INT32_MAX) {
+        throw new Error(`EXR: cannot write a ${width}x${height} image; a side is 1 to 2^31 pixels`);
+    }
+
+    const scanlines_per_chunk = exr_scanlines_per_chunk(compression);
+
+    const channels = sort_channels(image.channels, width * height);
+    const channel_count = channels.length;
+
+    let pixel_bytes = 0;
+    let long_names = false;
+
+    const plane_bits = new Array(channel_count);
+
+    for (let c = 0; c < channel_count; c++) {
+        const channel = channels[c];
+
+        pixel_bytes += channel.data.BYTES_PER_ELEMENT;
+        long_names ||= channel.name_bytes.length > EXR_SHORT_NAME_BYTES;
+
+        plane_bits[c] = exr_sample_bits(channel.data);
+    }
+
+    const line_bytes = width * pixel_bytes;
+    const chunk_bytes = Math.min(scanlines_per_chunk, height) * line_bytes;
+
+    if (chunk_bytes > INT32_MAX) {
+        throw new Error(`EXR: a chunk of this image would be ${chunk_bytes} bytes, more than a chunk's 32-bit size holds`);
+    }
+
+    const chunk_count = Math.ceil(height / scanlines_per_chunk);
+
+    const buffer = new BinaryBuffer();
+
+    // OpenEXR is little-endian throughout
+    buffer.endianness = EndianType.LittleEndian;
+
+    buffer.writeUint32(EXR_MAGIC);
+    buffer.writeUint32(long_names ? EXR_VERSION | EXR_FLAG_LONG_NAMES : EXR_VERSION);
+
+    write_header(buffer, channels, compression, width, height);
+
+    // No chunk is stored larger than its scanlines, so this bounds the file: the output is allocated
+    // once, and uncompressed it is exactly the file.
+    buffer.setCapacity(buffer.position + chunk_count * 16 + height * line_bytes);
+
+    // each entry is known once its chunk has been written; reserve the table and fill it in as they are
+    const table_offset = buffer.position;
+
+    for (let i = 0; i < chunk_count; i++) {
+        buffer.writeUint64(0n);
+    }
+
+    const raw = new BinaryBuffer();
+
+    raw.endianness = EndianType.LittleEndian;
+    raw.setCapacity(chunk_bytes);
+
+    const prepared = compression === ExrCompression.None ? null : new Uint8Array(chunk_bytes);
+
+    for (let i = 0; i < chunk_count; i++) {
+        const first_line = i * scanlines_per_chunk;
+        const line_count = Math.min(scanlines_per_chunk, height - first_line);
+        const unpacked_size = line_count * line_bytes;
+
+        raw.position = 0;
+
+        write_scanlines(raw, plane_bits, width, first_line, line_count);
+
+        let payload = raw.raw_bytes;
+        let payload_size = unpacked_size;
+
+        if (prepared !== null) {
+            zip_prepare(raw.raw_bytes, prepared, unpacked_size);
+
+            const compressed = await compress_bytes([prepared.subarray(0, unpacked_size)], "deflate");
+
+            if (compressed.length < unpacked_size) {
+                payload = compressed;
+                payload_size = compressed.length;
+            }
+        }
+
+        const offset = buffer.position;
+
+        buffer.position = table_offset + i * 8;
+        buffer.writeUint64(BigInt(offset));
+        buffer.position = offset;
+
+        // the data window starts at the origin, so a chunk's scanline is its first row
+        buffer.writeInt32(first_line);
+        buffer.writeInt32(payload_size);
+        buffer.writeBytes(payload, 0, payload_size);
+    }
+
+    buffer.trim();
+
+    return buffer.data;
+}
+
+/**
+ * Check the channels and sort them by {@link exr_compare_names}, which is the order a file lists them in
+ * and lays out their samples in.
+ *
+ * @param {ExrChannel[]} channels
+ * @param {number} sample_count every channel's
+ * @returns {{name: string, name_bytes: Uint8Array, data: (Float16Array|Float32Array|Uint32Array), pixel_type: ExrPixelType}[]}
+ */
+function sort_channels(channels, sample_count) {
+    const channel_count = channels.length;
+
+    if (channel_count === 0) {
+        throw new Error("EXR: the image has no channels");
+    }
+
+    const result = new Array(channel_count);
+
+    for (let c = 0; c < channel_count; c++) {
+        const { name, data } = channels[c];
+
+        if (typeof name !== "string" || name.length === 0 || name.includes("\0")) {
+            throw new Error(`EXR: channel name '${name}' is not a non-empty string without a null`);
+        }
+
+        const name_bytes = new Uint8Array(utf8_encoded_length(name));
+
+        utf8_encode_into(name, name_bytes, 0);
+
+        if (name_bytes.length > EXR_LONG_NAME_BYTES) {
+            throw new Error(`EXR: channel name '${name}' is ${name_bytes.length} bytes in UTF-8, more than ${EXR_LONG_NAME_BYTES}`);
+        }
+
+        let pixel_type;
+
+        if (data instanceof Float16Array) {
+            pixel_type = ExrPixelType.HALF;
+        } else if (data instanceof Float32Array) {
+            pixel_type = ExrPixelType.FLOAT;
+        } else if (data instanceof Uint32Array) {
+            pixel_type = ExrPixelType.UINT;
+        } else {
+            throw new Error(
+                `EXR: channel '${name}' holds ${data?.constructor?.name};`
+                + ` samples are Float16Array (HALF), Float32Array (FLOAT) or Uint32Array (UINT)`
+            );
+        }
+
+        if (data.length !== sample_count) {
+            throw new Error(`EXR: channel '${name}' holds ${data.length} samples, where the image has ${sample_count}`);
+        }
+
+        result[c] = { name, name_bytes, data, pixel_type };
+    }
+
+    result.sort((a, b) => exr_compare_names(a.name_bytes, b.name_bytes));
+
+    for (let c = 1; c < channel_count; c++) {
+        if (exr_compare_names(result[c - 1].name_bytes, result[c].name_bytes) === 0) {
+            throw new Error(`EXR: there are two channels named '${result[c].name}'`);
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Write the header: OpenEXR's required attributes, in its order, then the terminator.
+ *
+ * @param {BinaryBuffer} buffer
+ * @param {{name_bytes: Uint8Array, pixel_type: ExrPixelType}[]} channels sorted by name
+ * @param {ExrCompression} compression
+ * @param {number} width
+ * @param {number} height
+ */
+function write_header(buffer, channels, compression, width, height) {
+    let channel_list_bytes = 1;
+
+    for (let c = 0; c < channels.length; c++) {
+        // name and terminator; pixel type; pLinear and three reserved bytes; x and y sampling
+        channel_list_bytes += channels[c].name_bytes.length + 1 + 4 + 4 + 8;
+    }
+
+    write_attribute(buffer, "channels", "chlist", channel_list_bytes);
+
+    for (let c = 0; c < channels.length; c++) {
+        const name_bytes = channels[c].name_bytes;
+
+        buffer.writeBytes(name_bytes, 0, name_bytes.length);
+        buffer.writeUint8(0);
+
+        buffer.writeInt32(channels[c].pixel_type);
+        buffer.writeUint32(0);
+        buffer.writeInt32(1);
+        buffer.writeInt32(1);
+    }
+
+    buffer.writeUint8(0);
+
+    write_attribute(buffer, "compression", "compression", 1);
+    buffer.writeUint8(compression);
+
+    write_attribute(buffer, "dataWindow", "box2i", 16);
+    write_window(buffer, width, height);
+
+    write_attribute(buffer, "displayWindow", "box2i", 16);
+    write_window(buffer, width, height);
+
+    // increasing Y
+    write_attribute(buffer, "lineOrder", "lineOrder", 1);
+    buffer.writeUint8(0);
+
+    write_attribute(buffer, "pixelAspectRatio", "float", 4);
+    buffer.writeFloat32(1);
+
+    write_attribute(buffer, "screenWindowCenter", "v2f", 8);
+    buffer.writeFloat32(0);
+    buffer.writeFloat32(0);
+
+    write_attribute(buffer, "screenWindowWidth", "float", 4);
+    buffer.writeFloat32(1);
+
+    buffer.writeUint8(0);
+}
+
+/**
+ * @param {BinaryBuffer} buffer
+ * @param {string} name
+ * @param {string} type
+ * @param {number} size bytes of the value that follows
+ */
+function write_attribute(buffer, name, type, size) {
+    write_name(buffer, name);
+    write_name(buffer, type);
+
+    buffer.writeInt32(size);
+}
+
+/**
+ * @param {BinaryBuffer} buffer
+ * @param {string} name ASCII
+ */
+function write_name(buffer, name) {
+    buffer.writeASCIIString(name);
+    buffer.writeUint8(0);
+}
+
+/**
+ * A `box2i` from the origin to the last pixel.
+ *
+ * @param {BinaryBuffer} buffer
+ * @param {number} width
+ * @param {number} height
+ */
+function write_window(buffer, width, height) {
+    buffer.writeInt32(0);
+    buffer.writeInt32(0);
+    buffer.writeInt32(width - 1);
+    buffer.writeInt32(height - 1);
+}
+
+/**
+ * Gather a chunk's scanlines from the channel planes — the inverse of `read_scanlines` in `exr_read`.
+ *
+ * @param {BinaryBuffer} destination
+ * @param {(Uint16Array|Uint32Array)[]} plane_bits in channel list order
+ * @param {number} width
+ * @param {number} first_line
+ * @param {number} line_count
+ */
+function write_scanlines(destination, plane_bits, width, first_line, line_count) {
+    const channel_count = plane_bits.length;
+
+    for (let line = first_line; line < first_line + line_count; line++) {
+        const row = line * width;
+
+        for (let c = 0; c < channel_count; c++) {
+            const bits = plane_bits[c];
+
+            if (bits.BYTES_PER_ELEMENT === 2) {
+                destination.writeUint16Array(bits, row, width);
+            } else {
+                destination.writeUint32Array(bits, row, width);
+            }
+        }
+    }
+}
+
+/**
+ * Transform a chunk the way ZIP compression does before deflating it — the inverse of
+ * `zip_reconstruct` in `exr_read`.
+ *
+ * The bytes at even positions are moved ahead of those at odd ones — for half floats, the low bytes of
+ * the samples ahead of their high bytes — and the result is delta-coded byte by byte with a bias of
+ * 128, which turns smooth image data into the small, repetitive values deflate codes cheaply.
+ *
+ * @param {Uint8Array} source the chunk's pixel data
+ * @param {Uint8Array} destination
+ * @param {number} length bytes, at least one
+ */
+function zip_prepare(source, destination, length) {
+    const half = (length + 1) >> 1;
+
+    let previous = source[0];
+
+    destination[0] = previous;
+
+    for (let i = 1; i < half; i++) {
+        const value = source[2 * i];
+
+        destination[i] = value - previous + 128;
+
+        previous = value;
+    }
+
+    for (let i = half; i < length; i++) {
+        const value = source[2 * (i - half) + 1];
+
+        destination[i] = value - previous + 128;
+
+        previous = value;
+    }
+}

package/src/shade/device/shader/ShaderModuleCompiler.d.ts

@@ -8,6 +8,8 @@ export class ShaderModuleCompiler {
      */
     constructor(device: GPUDevice);
     /**
+     * The module for `descriptor`. Equal descriptors are handed the same module for as long as
+     * something holds it; once nothing does, a later call may compile it again and hand out a new one.
      *
      * @param {ShaderModuleDescriptor} descriptor
      * @returns {GPUShaderModule}

package/src/shade/device/shader/ShaderModuleCompiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShaderModuleCompiler.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/shader/ShaderModuleCompiler.js"],"names":[],"mappings":"AAGA;;GAEG;AAEH;IAaI;;;OAGG;IACH,+BAEC;IAwCD;;;;OAIG;IACH,mBAHW,sBAAsB,mBAOhC;;CAEJ;qCAzEY,OAAO,qDAAqD,EAAE,sBAAsB"}
+{"version":3,"file":"ShaderModuleCompiler.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/shader/ShaderModuleCompiler.js"],"names":[],"mappings":"AAGA;;GAEG;AAEH;IAmBI;;;OAGG;IACH,+BAEC;IAwCD;;;;;;OAMG;IACH,mBAHW,sBAAsB,mBAsBhC;;CAEJ;qCAhGY,OAAO,qDAAqD,EAAE,sBAAsB"}

package/src/shade/device/shader/ShaderModuleCompiler.js

@@ -13,8 +13,14 @@ export class ShaderModuleCompiler {
     #device
 
     /**
+     * Held weakly. A pipeline keeps the module it was built from alive in the GPU process without our
+     * help, while the browser charges every `GPUShaderModule` object the page still references to the
+     * JS heap's accounting as external memory, and the garbage a collection is allowed to gather grows
+     * with that. So a module is kept only for as long as something holds it: one nobody holds goes at
+     * the next major collection, and a later request compiles it again from the descriptor, which this
+     * map does keep.
      *
-     * @type {HashMap<ShaderModuleDescriptor, GPUShaderModule>}
+     * @type {HashMap<ShaderModuleDescriptor, WeakRef<GPUShaderModule>>}
      */
     #cache = new HashMap();
 
@@ -65,14 +71,31 @@ export class ShaderModuleCompiler {
     }
 
     /**
+     * The module for `descriptor`. Equal descriptors are handed the same module for as long as
+     * something holds it; once nothing does, a later call may compile it again and hand out a new one.
      *
      * @param {ShaderModuleDescriptor} descriptor
      * @returns {GPUShaderModule}
      */
     obtain(descriptor) {
+        const cache = this.#cache;
 
-        return this.#cache.getOrCompute(descriptor, this.#compile, this);
+        const held = cache.get(descriptor);
 
+        if (held !== undefined) {
+            const live = held.deref();
+
+            if (live !== undefined) {
+                return live;
+            }
+        }
+
+        const module = this.#compile(descriptor);
+
+        // an equal descriptor that is already a key keeps its entry, and the dead reference is replaced
+        cache.set(descriptor, new WeakRef(module));
+
+        return module;
     }
 
 }

package/src/shade/playground/grass_surfaces/index.html

@@ -0,0 +1,75 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Grass surfaces</title>
+    <style>
+        :root {
+            color-scheme: dark;
+        }
+
+        html, body {
+            margin: 0;
+            height: 100%;
+            overflow: hidden;
+            background: #101215;
+            color: #e3e5e8;
+            font: 13px/1.4 'Segoe UI', system-ui, sans-serif;
+        }
+
+        #viewport {
+            position: absolute;
+            inset: 0;
+        }
+
+        #legend {
+            position: absolute;
+            left: 12px;
+            top: 12px;
+            padding: 10px 12px;
+            background: rgba(14, 15, 20, 0.78);
+            border: 1px solid rgba(255, 255, 255, 0.1);
+            border-radius: 4px;
+            max-width: 360px;
+        }
+
+        #legend h1 {
+            font-size: 14px;
+            margin: 0 0 6px;
+        }
+
+        #legend p {
+            margin: 4px 0;
+            color: #a8adb5;
+        }
+
+        #status {
+            font-variant-numeric: tabular-nums;
+            color: #e3e5e8;
+            white-space: pre;
+        }
+
+        #message {
+            position: absolute;
+            inset: 0;
+            display: none;
+            place-items: center;
+            white-space: pre-wrap;
+            padding: 24px;
+        }
+    </style>
+</head>
+<body tabindex="0">
+<div id="viewport"></div>
+<div id="legend">
+    <h1>Grass surfaces</h1>
+    <p>A field of two sheets, a boulder sunk into one and a hill over a cave on the other, sampled as one
+        surface; and a platform of two sheets and a crate that moves as another.</p>
+    <p>A grey slab hangs over the field and is no member of it.</p>
+    <p id="status"></p>
+</div>
+<div id="message"></div>
+<script type="module" src="./main.js"></script>
+</body>
+</html>

package/src/shade/playground/grass_surfaces/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/grass_surfaces/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/grass_surfaces/main.js"],"names":[],"mappings":""}