@woosh/meep-engine 3.8.0 → 3.10.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.8.0",
+  "version": "3.10.0",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",
@@ -38,7 +38,8 @@
     "package.json",
     "README.md",
     "!src/**/*.spec.js",
-    "!editor/**/*.spec.js"
+    "!editor/**/*.spec.js",
+    "!src/**/__fixtures__/**"
   ],
   "dependencies": {
     "opentype.js": "1.3.3",

package/src/avif/encode_image_source.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Encoding one image source, whichever side of a worker boundary it happens on.
+ *
+ * The encoder is meep's own, under `./native` — pure JavaScript, synchronous and portable — so the
+ * same two functions serve the worker pool and the fallback for environments that have no workers.
+ * Keeping them here rather than in the worker is what stops the two paths from drifting apart.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * The effort a caller's `speed` asks for.
+ *
+ * `speed` is the dial the WebAssembly encoder took: zero is slowest and best, ten is fastest. The
+ * native encoder names three points on that curve instead of eleven, because those are the three
+ * that measure differently; this maps one onto the other so that existing callers keep meaning what
+ * they meant.
+ *
+ * @param {number} [speed] `0 .. 10`
+ * @returns {number} one of the `EFFORT_*` constants
+ */
+export function effort_of_speed(speed?: number): number;
+/**
+ * An encode context to hand back to the functions below.
+ *
+ * One per worker, or one per process for the inline path: it holds the planes and contexts an
+ * encode needs, and reusing it is what keeps a run of encodes from allocating a fresh set each time.
+ *
+ * @returns {Av1EncodeContext}
+ */
+export function create_encoder(): Av1EncodeContext;
+/**
+ * Encode an image bitmap.
+ *
+ * Needs a canvas to read the bitmap's samples back out — a bitmap is an opaque handle, and drawing
+ * it is the only way to see it. That is a platform capability rather than a codec one, which is why
+ * this is the operation that can be unavailable where the other cannot.
+ *
+ * @param {{bitmap: ImageBitmap, quality: number, speed: (number|undefined)}} request the bitmap is
+ *   closed once it has been read
+ * @param {Av1EncodeContext} encoder
+ * @returns {ArrayBuffer}
+ */
+export function encode_bitmap_source(request: {
+    bitmap: ImageBitmap;
+    quality: number;
+    speed: (number | undefined);
+}, encoder: Av1EncodeContext): ArrayBuffer;
+/**
+ * Encode a sampler.
+ *
+ * Half float samplers are taken as linear light in the renderer's normalisation and coded through
+ * the PQ transfer function; eight bit ones are coded as ordinary sRGB. Which of the two it is comes
+ * from the data itself, so it survives being posted to a worker.
+ *
+ * @param {{data: TypedArray, width: number, height: number, item_size: number, quality: number,
+ *   speed: (number|undefined)}} request
+ * @param {Av1EncodeContext} encoder
+ * @returns {ArrayBuffer}
+ */
+export function encode_sampler_source(request: {
+    data: TypedArray;
+    width: number;
+    height: number;
+    item_size: number;
+    quality: number;
+    speed: (number | undefined);
+}, encoder: Av1EncodeContext): ArrayBuffer;
+import { Av1EncodeContext } from './native/av1/encode/Av1EncodeContext.js';
+//# sourceMappingURL=encode_image_source.d.ts.map

package/src/avif/encode_image_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode_image_source.d.ts","sourceRoot":"","sources":["../../../src/avif/encode_image_source.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,wCAHW,MAAM,GACJ,MAAM,CAgBlB;AAED;;;;;;;GAOG;AACH,kCAFa,gBAAgB,CAI5B;AAED;;;;;;;;;;;GAWG;AACH;YALoB,WAAW;aAAW,MAAM;WAAS,CAAC,MAAM,GAAC,SAAS,CAAC;YAEhE,gBAAgB,GACd,WAAW,CA6BvB;AAED;;;;;;;;;;;GAWG;AACH;;WALqC,MAAM;YAAU,MAAM;eAAa,MAAM;aAAW,MAAM;WACnF,CAAC,MAAM,GAAC,SAAS,CAAC;YACnB,gBAAgB,GACd,WAAW,CAUvB;iCApHgC,yCAAyC"}

package/src/avif/encode_image_source.js

@@ -0,0 +1,117 @@
+import { Av1EncodeContext } from './native/av1/encode/Av1EncodeContext.js';
+import { EFFORT_BALANCED, EFFORT_FAST, EFFORT_THOROUGH, apply_effort } from './native/av1/encode/encode_effort.js';
+import { encode_avif } from './native/api/encode_avif.js';
+import { sampler2d_to_avif } from './native/api/sampler2d_to_avif.js';
+
+/**
+ * Encoding one image source, whichever side of a worker boundary it happens on.
+ *
+ * The encoder is meep's own, under `./native` — pure JavaScript, synchronous and portable — so the
+ * same two functions serve the worker pool and the fallback for environments that have no workers.
+ * Keeping them here rather than in the worker is what stops the two paths from drifting apart.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * The effort a caller's `speed` asks for.
+ *
+ * `speed` is the dial the WebAssembly encoder took: zero is slowest and best, ten is fastest. The
+ * native encoder names three points on that curve instead of eleven, because those are the three
+ * that measure differently; this maps one onto the other so that existing callers keep meaning what
+ * they meant.
+ *
+ * @param {number} [speed] `0 .. 10`
+ * @returns {number} one of the `EFFORT_*` constants
+ */
+export function effort_of_speed(speed) {
+    if (speed === undefined) {
+        return EFFORT_BALANCED;
+    }
+
+    if (speed <= 2) {
+        return EFFORT_THOROUGH;
+    }
+
+    if (speed <= 7) {
+        return EFFORT_BALANCED;
+    }
+
+    return EFFORT_FAST;
+}
+
+/**
+ * An encode context to hand back to the functions below.
+ *
+ * One per worker, or one per process for the inline path: it holds the planes and contexts an
+ * encode needs, and reusing it is what keeps a run of encodes from allocating a fresh set each time.
+ *
+ * @returns {Av1EncodeContext}
+ */
+export function create_encoder() {
+    return new Av1EncodeContext();
+}
+
+/**
+ * Encode an image bitmap.
+ *
+ * Needs a canvas to read the bitmap's samples back out — a bitmap is an opaque handle, and drawing
+ * it is the only way to see it. That is a platform capability rather than a codec one, which is why
+ * this is the operation that can be unavailable where the other cannot.
+ *
+ * @param {{bitmap: ImageBitmap, quality: number, speed: (number|undefined)}} request the bitmap is
+ *   closed once it has been read
+ * @param {Av1EncodeContext} encoder
+ * @returns {ArrayBuffer}
+ */
+export function encode_bitmap_source(request, encoder) {
+    const { bitmap, quality, speed } = request;
+
+    if (typeof OffscreenCanvas === 'undefined') {
+        bitmap.close();
+
+        throw new Error('encoding an ImageBitmap needs OffscreenCanvas, which this environment does not have');
+    }
+
+    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+    const context = canvas.getContext('2d');
+
+    context.drawImage(bitmap, 0, 0);
+
+    const image_data = context.getImageData(0, 0, canvas.width, canvas.height);
+
+    bitmap.close();
+
+    apply_effort(encoder, effort_of_speed(speed));
+
+    const file = encode_avif({
+        data: image_data.data,
+        width: image_data.width,
+        height: image_data.height
+    }, { quality: Math.ceil(quality * 100) }, encoder);
+
+    return file.buffer;
+}
+
+/**
+ * Encode a sampler.
+ *
+ * Half float samplers are taken as linear light in the renderer's normalisation and coded through
+ * the PQ transfer function; eight bit ones are coded as ordinary sRGB. Which of the two it is comes
+ * from the data itself, so it survives being posted to a worker.
+ *
+ * @param {{data: TypedArray, width: number, height: number, item_size: number, quality: number,
+ *   speed: (number|undefined)}} request
+ * @param {Av1EncodeContext} encoder
+ * @returns {ArrayBuffer}
+ */
+export function encode_sampler_source(request, encoder) {
+    const { data, width, height, item_size, quality, speed } = request;
+
+    apply_effort(encoder, effort_of_speed(speed));
+
+    const file = sampler2d_to_avif({ data, width, height, itemSize: item_size }, quality, {}, encoder);
+
+    return file.buffer;
+}

package/src/avif/encoder_worker.js

@@ -1,131 +1,20 @@
 // AVIF encoder worker. Receives image sources, returns encoded AVIF buffers.
 //
-// Uses the single-threaded AVIF encoder directly (bypassing encode.js's auto
-// mt selection) so a pool of N of these workers gives exactly N concurrent
-// encodes rather than N * pthread-pool-size oversubscribed threads.
-
-import avifEncoderFactory from './codec/enc/avif_enc.js';
-import { initEmscriptenModule } from './utils.js';
-import { defaultOptions } from './meta.js';
-import { to_half_float_uint16 } from '../core/binary/to_half_float_uint16.js';
-import { linear_to_PQ } from '../core/color/PQ/linear_to_PQ.js';
-import { PQ_SDR_WHITE_LINEAR } from '../core/color/PQ/PQ_constants.js';
-
-const AVIF_DEFAULT_SPEED = 5;
-
-const AvifSubsample = {
-    YUV400: 0,
-    YUV420: 1,
-    YUV422: 2,
-    YUV444: 3,
-};
-
-let encoder_promise = null;
-
-function get_encoder() {
-    if (encoder_promise === null) {
-        encoder_promise = initEmscriptenModule(avifEncoderFactory);
-    }
-    return encoder_promise;
-}
-
-async function encode_raw(data, options) {
-    const _options = { ...defaultOptions, ...options };
-    const module = await get_encoder();
-    const output = module.encode(
-        new Uint8Array(data.data.buffer, data.data.byteOffset, data.data.byteLength),
-        data.width,
-        data.height,
-        _options
-    );
-    if (!output) {
-        throw new Error('AVIF encoding error');
-    }
-    return output.buffer;
-}
-
-async function encode_bitmap(payload) {
-    const { bitmap, quality, speed = AVIF_DEFAULT_SPEED } = payload;
-
-    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
-    const ctx = canvas.getContext('2d');
-    ctx.drawImage(bitmap, 0, 0);
-
-    const image_data = ctx.getImageData(0, 0, canvas.width, canvas.height);
-
-    bitmap.close();
-
-    return encode_raw(image_data, {
-        speed,
-        quality: Math.ceil(quality * 100)
-    });
-}
-
-function expand_to_rgba_uint16(data, item_size, width, height) {
-    if (item_size === 4) {
-        return data;
-    }
-
-    const expanded = new Uint16Array(width * height * 4);
-    const ONE = to_half_float_uint16(1);
-    const pixel_count = width * height;
-
-    for (let i = 0; i < pixel_count; i++) {
-        const dst = i * 4;
-        const src = i * item_size;
-        for (let c = 0; c < item_size; c++) {
-            expanded[dst + c] = data[src + c];
-        }
-        // alpha defaults to 1.0
-        expanded[dst + 3] = ONE;
-    }
-
-    return expanded;
-}
-
-function rgba_float16_to_pq_uint16(f16_view, width, height) {
-    const out = new Uint16Array(width * height * 4);
-
-    for (let i = 0; i < f16_view.length; i += 4) {
-        for (let c = 0; c < 3; c++) {
-            const linear = Math.max(f16_view[i + c], 0);
-            // Engine linear is normalized to SDR reference white; PQ's is normalized to its own
-            // 10000-nit peak, so cross over before encoding.
-            const pq = linear_to_PQ(linear * PQ_SDR_WHITE_LINEAR);
-            out[i + c] = Math.round(pq * 4095);
-        }
-        // alpha: linear 0..1 mapped directly to 0..4095
-        out[i + 3] = Math.round(Math.min(Math.max(f16_view[i + 3], 0), 1) * 4095);
-    }
-
-    return out;
-}
-
-async function encode_sampler2d(payload) {
-    const { data, width, height, item_size, is_hdr, quality, speed = AVIF_DEFAULT_SPEED } = payload;
-    const q100 = Math.ceil(quality * 100);
-
-    if (is_hdr) {
-        const rgba = expand_to_rgba_uint16(data, item_size, width, height);
-        const f16_view = new Float16Array(rgba.buffer, rgba.byteOffset, rgba.length);
-        const pq_data = rgba_float16_to_pq_uint16(f16_view, width, height);
+// The encoder itself is meep's own, under ./native — synchronous, allocation-light and portable.
+// It runs here rather than on the main thread for the same reason it always did: encoding a large
+// image takes long enough to be worth keeping off it, and a pool of these gives exactly N
+// concurrent encodes.
+//
+// The two operations live in ./encode_image_source.js, because the dispatcher runs them directly
+// wherever workers are not to be had.
 
-        return encode_raw({ data: pq_data, width, height }, {
-            subsample: AvifSubsample.YUV422,
-            bitDepth: 12,
-            speed,
-            quality: q100,
-            colorPrimaries: 1,           // BT.709
-            transferCharacteristics: 16, // PQ (ST 2084)
-            matrixCoefficients: 1,       // BT.709
-        });
-    }
+import { create_encoder, encode_bitmap_source, encode_sampler_source } from './encode_image_source.js';
 
-    return encode_raw({ data, width, height }, {
-        speed,
-        quality: q100
-    });
-}
+/**
+ * One encoder per worker, reused across requests: a worker encodes one image at a time, and the
+ * context holds everything an encode would otherwise allocate.
+ */
+const encoder = create_encoder();
 
 self.onmessage = async (event) => {
     const { id, type, payload } = event.data;
@@ -133,9 +22,9 @@ self.onmessage = async (event) => {
     try {
         let buffer;
         if (type === 'encode_bitmap') {
-            buffer = await encode_bitmap(payload);
+            buffer = encode_bitmap_source(payload, encoder);
         } else if (type === 'encode_sampler2d') {
-            buffer = await encode_sampler2d(payload);
+            buffer = encode_sampler_source(payload, encoder);
         } else {
             throw new Error(`Unknown encode type: ${type}`);
         }

package/src/avif/index.d.ts

@@ -1,3 +1,5 @@
-export { default as encode } from "./encode.js";
-export { default as decode } from "./decode.js";
+export * from "./native/index.js";
+export { decode_avif as decode } from "./native/api/decode_avif.js";
+export { encode_avif as encode } from "./native/api/encode_avif.js";
+export { ThreadedImageEncoder, get_threaded_image_encoder } from "./threaded_image_encoder.js";
 //# sourceMappingURL=index.d.ts.map

package/src/avif/index.js

@@ -1,2 +1,21 @@
-export { default as encode } from './encode.js';
-export { default as decode } from './decode.js';
+/**
+ * AVIF, as meep does it.
+ *
+ * The codec is `./native`: pure JavaScript, synchronous, no WebAssembly and no worker of its own.
+ * This is its public face, plus the pool dispatcher for callers that would rather not encode on the
+ * thread they are on.
+ *
+ * `decode` and `encode` keep the names the WebAssembly wrappers used, and hand back the same shapes
+ * — a decode is `{ data, width, height }`. They are synchronous now, which an `await` on the result
+ * does not notice; a caller holding one as a promise does.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+export * from './native/index.js';
+
+export { decode_avif as decode } from './native/api/decode_avif.js';
+export { encode_avif as encode } from './native/api/encode_avif.js';
+
+export { ThreadedImageEncoder, get_threaded_image_encoder } from './threaded_image_encoder.js';