@draco-rust/decoder 0.2.0 → 0.3.0

package/mesh/pool.d.ts

@@ -1,28 +1,11 @@
-import type { DracoAttributeRequest, DracoDecodeResult } from './index.js';
+import type { DracoAttributeRequest, DracoDecodeOptions, DracoDecodeResult } from './index.js';
+import type { Pool, PoolOptions, TaskOptions } from './pool-core.js';
 
-export interface DecoderPoolOptions {
-  /**
-   * How many workers to run at most; they start as work arrives. Defaults to
-   * one less than the cores, between one and four. `0` decodes on the calling
-   * thread, as does an environment without workers.
-   */
-  workers?: number;
-  /**
-   * The entry's wasm, when it is not next to this module where the pool looks
-   * for it: a URL, a `Response`, the bytes, or a compiled module.
-   */
-  wasm?: string | URL | Response | BufferSource | WebAssembly.Module;
-}
+export type DecoderPoolOptions = PoolOptions;
 
-export interface DecodeOptions {
-  /**
-   * Hand the stream's buffer to the worker instead of copying it, leaving it
-   * detached here. For a buffer nothing else reads afterwards.
-   */
-  transfer?: boolean;
-}
+export interface DecodeOptions extends DracoDecodeOptions, TaskOptions {}
 
-export interface DecoderPool {
+export interface DecoderPool extends Pool {
   /**
    * `decode_draco` on a worker. A stream that does not decode resolves with
    * `success: false`, as `decode_draco` returns it; a worker that fails rejects
@@ -33,13 +16,7 @@ export interface DecoderPool {
     attributes?: DracoAttributeRequest[],
     options?: DecodeOptions,
   ): Promise<DracoDecodeResult>;
-  /** Compiles the wasm and starts one worker ahead of the first decode. */
-  preload(): Promise<void>;
-  /** Changes the worker limit; idle workers past it stop now, busy ones when done. */
-  setWorkerLimit(workers: number): void;
-  readonly workerLimit: number;
-  /** Stops every worker and rejects what they held. */
-  dispose(): void;
 }
 
 export function createDecoderPool(options?: DecoderPoolOptions): DecoderPool;
+export { createDecoderPool as createPool };

package/mesh/pool.js

@@ -1,193 +1,24 @@
-// Decoding off the calling thread: a pool of workers, each running this entry's
-// own module. The wasm is compiled once here and handed to every worker, the
-// stream goes over by transfer and the arrays come back the same way, so a
-// decode copies nothing it does not have to.
-import init, { decode_draco } from './index.js';
+// Decoding off the calling thread, on the shared pool: decode_draco on a
+// worker, with the stream copied over unless the caller hands it away.
+import { createPool as createTaskPool } from './pool-core.js';
 
-/** Leaves a core for the page, and stops at four, past which a page rarely has
- * that many streams in flight at once. */
-const defaultWorkers = () =>
-  Math.max(1, Math.min(4, (globalThis.navigator?.hardwareConcurrency ?? 4) - 1));
-
-const builtin = (name) =>
-  typeof process !== 'undefined' && typeof process.getBuiltinModule === 'function'
-    ? process.getBuiltinModule(name)
-    : undefined;
-
-async function compile(wasm) {
-  if (wasm instanceof WebAssembly.Module) return wasm;
-  let source = wasm ?? new URL('./index_bg.wasm', import.meta.url);
-  if (typeof source === 'string' || source instanceof URL) {
-    const url = new URL(source, import.meta.url);
-    // Node's fetch does not read files.
-    const fs = url.protocol === 'file:' ? builtin('node:fs/promises') : undefined;
-    if (fs) return WebAssembly.compile(await fs.readFile(url));
-    source = await fetch(url);
-  }
-  if (typeof Response !== 'undefined' && source instanceof Response) {
-    if (!source.ok) throw new Error(`failed to fetch ${source.url}: ${source.status}`);
-    if (source.headers.get('content-type') === 'application/wasm') {
-      return WebAssembly.compileStreaming(source);
-    }
-    source = await source.arrayBuffer();
-  }
-  return WebAssembly.compile(source);
-}
-
-/** What the pool needs of a worker, the same over a Web Worker and a Node
- * worker thread. */
-function spawn(blobUrl) {
-  if (typeof Worker === 'function') {
-    const url = new URL('./worker.js', import.meta.url);
-    // A bundler recognises this exact form and emits the worker as a chunk.
-    const worker =
-      typeof location === 'undefined' || url.origin === location.origin
-        ? new Worker(new URL('./worker.js', import.meta.url), { type: 'module' })
-        : new Worker(blobUrl(url), { type: 'module' });
-    return {
-      post: (message, transfer) => worker.postMessage(message, transfer),
-      listen: (onMessage, onError) => {
-        worker.addEventListener('message', (event) => onMessage(event.data));
-        worker.addEventListener('error', (event) => {
-          event.preventDefault();
-          onError(new Error(event.message || 'the decoder worker failed'));
-        });
-        worker.addEventListener('messageerror', () => onError(new Error('a decode result could not be read')));
-      },
-      busy: () => {},
-      terminate: () => worker.terminate(),
-    };
-  }
-  const threads = builtin('node:worker_threads');
-  if (!threads) return null;
-  const worker = new threads.Worker(new URL('./worker.js', import.meta.url));
-  // An idle worker does not keep Node running; one with work does.
-  worker.unref();
-  return {
-    post: (message, transfer) => worker.postMessage(message, transfer),
-    listen: (onMessage, onError) => {
-      worker.on('message', onMessage);
-      worker.on('error', onError);
-      worker.on('exit', (code) => onError(new Error(`the decoder worker exited with code ${code}`)));
-    },
-    busy: (busy) => (busy ? worker.ref() : worker.unref()),
-    terminate: () => worker.terminate(),
-  };
-}
-
-const workersAvailable = () =>
-  typeof Worker === 'function' || builtin('node:worker_threads') !== undefined;
+const bytesOf = (data) =>
+  ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : new Uint8Array(data);
 
 export function createDecoderPool(options = {}) {
-  let limit = options.workers ?? defaultWorkers();
-  let compiled = null;
-  let local = null;
-  let blob = null;
-  let disposed = false;
-  let nextId = 0;
-  const slots = [];
-
-  const load = () => (compiled ??= compile(options.wasm));
-  // A worker script must share the page's origin. From a CDN, a worker made
-  // here imports it instead, which a module worker may do across origins.
-  const blobUrl = (url) =>
-    (blob ??= URL.createObjectURL(
-      new Blob([`import ${JSON.stringify(url.href)};`], { type: 'text/javascript' }),
-    ));
-
-  function retire(slot, error) {
-    const at = slots.indexOf(slot);
-    if (at >= 0) slots.splice(at, 1);
-    slot.worker.terminate();
-    for (const { reject } of slot.pending.values()) reject(error);
-    slot.pending.clear();
-  }
-
-  function open(module) {
-    const worker = spawn(blobUrl);
-    if (!worker) return null;
-    const slot = { worker, pending: new Map() };
-    worker.listen(
-      (message) => {
-        const task = slot.pending.get(message.id);
-        if (!task) return;
-        slot.pending.delete(message.id);
-        if (slot.pending.size === 0) {
-          worker.busy(false);
-          if (slots.indexOf(slot) >= limit) retire(slot);
-        }
-        if ('error' in message) task.reject(new Error(message.error));
-        else task.resolve(message.result);
-      },
-      // A worker that fails takes only its own tasks down; the next decode
-      // starts another.
-      (error) => {
-        if (slots.includes(slot)) retire(slot, error);
-      },
-    );
-    worker.post({ type: 'init', module });
-    slots.push(slot);
-    return slot;
-  }
-
-  /** The least loaded worker, or a new one while every worker is busy and
-   * the limit allows another. */
-  function pick(module) {
-    let best = null;
-    for (const slot of slots.slice(0, limit)) {
-      if (!best || slot.pending.size < best.pending.size) best = slot;
-    }
-    if ((!best || best.pending.size > 0) && slots.length < limit) return open(module) ?? best;
-    return best;
-  }
-
-  const onThisThread = () =>
-    (local ??= load().then((module) => init({ module_or_path: module })));
-
-  async function decode(data, attributes, { transfer = false } = {}) {
-    if (disposed) throw new Error('the decoder pool was disposed');
-    const bytes = ArrayBuffer.isView(data)
-      ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
-      : new Uint8Array(data);
-    if (limit > 0 && workersAvailable()) {
-      const module = await load();
-      if (disposed) throw new Error('the decoder pool was disposed');
-      const slot = pick(module);
-      if (slot) {
-        const id = nextId++;
-        const sent = transfer ? bytes : bytes.slice();
-        return new Promise((resolve, reject) => {
-          slot.pending.set(id, { resolve, reject });
-          slot.worker.busy(true);
-          slot.worker.post({ id, data: sent, attributes }, [sent.buffer]);
-        });
-      }
-    }
-    await onThisThread();
-    return decode_draco(bytes, attributes);
-  }
-
+  const pool = createTaskPool(options);
   return {
-    decode,
-    async preload() {
-      if (limit > 0 && workersAvailable()) {
-        const module = await load();
-        if (!disposed && slots.length === 0) open(module);
-      } else {
-        await onThisThread();
-      }
-    },
-    setWorkerLimit(workers) {
-      limit = workers;
-      for (const slot of slots.slice(limit)) if (slot.pending.size === 0) retire(slot);
+    decode(data, attributes, { transfer = false, signal, index } = {}) {
+      const decodeOptions = index === undefined ? undefined : { index };
+      return pool.run('decode_draco', [bytesOf(data), attributes, decodeOptions], { transfer, signal });
     },
+    preload: () => pool.preload(),
+    setWorkerLimit: (workers) => pool.setWorkerLimit(workers),
     get workerLimit() {
-      return limit;
-    },
-    dispose() {
-      disposed = true;
-      for (const slot of [...slots]) retire(slot, new Error('the decoder pool was disposed'));
-      if (blob) URL.revokeObjectURL(blob);
+      return pool.workerLimit;
     },
+    dispose: () => pool.dispose(),
   };
 }
+
+export { createDecoderPool as createPool };

package/mesh/tasks.js

@@ -0,0 +1,2 @@
+// What the pool's workers may run for this entry.
+export { decode_draco } from './index.js';

package/mesh/worker.js

@@ -1,7 +1,9 @@
-// A decoder worker. The pool sends it the compiled module once, then streams
-// to decode; it answers each with its result, handing the arrays back by
-// transfer. Runs as a Web Worker and as a Node worker thread.
-import init, { decode_draco } from './index.js';
+// A pool worker. The pool sends it the compiled module once, then tasks by
+// name from this entry's `tasks.js`; it answers each with its result, handing
+// every array in it back by transfer. Runs as a Web Worker and as a Node
+// worker thread.
+import init from './index.js';
+import * as tasks from './tasks.js';
 
 const web = typeof self !== 'undefined' && typeof self.postMessage === 'function';
 const port = web ? self : process.getBuiltinModule('node:worker_threads').parentPort;
@@ -10,18 +12,30 @@ const listen = (handler) =>
 
 let ready = null;
 
+/** Every buffer in a result, except the module's own memory, which stays. */
+function buffersOf(value, memory, found = new Set()) {
+  if (ArrayBuffer.isView(value)) {
+    if (value.buffer instanceof ArrayBuffer && value.buffer !== memory) found.add(value.buffer);
+  } else if (value instanceof ArrayBuffer) {
+    if (value !== memory) found.add(value);
+  } else if (Array.isArray(value)) {
+    for (const item of value) buffersOf(item, memory, found);
+  } else if (value !== null && typeof value === 'object') {
+    for (const item of Object.values(value)) buffersOf(item, memory, found);
+  }
+  return found;
+}
+
 listen(async (message) => {
   if (message.type === 'init') {
     ready = init({ module_or_path: message.module });
     return;
   }
-  const { id, data, attributes } = message;
+  const { id, task, args } = message;
   try {
-    await ready;
-    const result = decode_draco(data, attributes);
-    const transfer = result.attributes.map((attribute) => attribute.array.buffer);
-    if (result.index) transfer.push(result.index.buffer);
-    port.postMessage({ id, result }, transfer);
+    const { memory } = await ready;
+    const result = await tasks[task](...args);
+    port.postMessage({ id, result }, [...buffersOf(result, memory.buffer)]);
   } catch (error) {
     port.postMessage({ id, error: String(error?.message ?? error) });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@draco-rust/decoder",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Draco geometry decoder in WebAssembly, a safe Rust port of Google Draco: meshes, point clouds and older bitstreams, each as its own small entry.",
   "keywords": [
     "draco",
@@ -24,7 +24,7 @@
     "directory": "web/npm/decoder"
   },
   "draco-rust": {
-    "commit": "8650e1ca",
+    "commit": "4b72cfc8",
     "draco-core": "2.3.2",
     "draco-io": "0.6.0",
     "draco-gltf": "0.7.0"

package/point-cloud/index.d.ts

@@ -35,41 +35,37 @@ export interface DracoAttribute {
     normalized: boolean;
 }
 
+export interface DracoDecodeOptions {
+    /**
+     * The index's array: `"Uint32Array"`, the default, or `"auto"`, which uses a
+     * `Uint16Array` when every point number fits, at most 65536 points, and
+     * halves what a worker sends back.
+     */
+    index?: "Uint32Array" | "auto";
+}
+
 export interface DracoDecodeResult {
     success: boolean;
     error?: string;
     warnings: string[];
     geometry?: "mesh" | "point_cloud";
     /** Triangle corners for a mesh, `null` for a point cloud. */
-    index: Uint32Array | null;
+    index: Uint32Array | Uint16Array | null;
     attributes: DracoAttribute[];
 }
 
-
-
 /**
- * Decodes a Draco stream and returns its attributes as typed arrays.
- *
- * `attributes` is `undefined` for every attribute in its own component type,
- * or an array of requests `{ name, id, semantic, type }`:
- *
- * - `id`, a unique id, finds that attribute, as glTF's
- *   `KHR_draco_mesh_compression` names them; a missing one is an error.
- * - `semantic` (`"POSITION"`, `"NORMAL"`, `"COLOR"`, `"TEX_COORD"` or
- *   `"GENERIC"`) finds the first attribute of that type instead, as a `.drc`
- *   file is read; a missing one is left out.
- * - `type`, a typed array's name such as `"Float32Array"` or
- *   `"Uint16Array"`, converts the values the way upstream's
- *   `GetAttributeDataArrayForAllPoints` does; without it the values keep
- *   their own type. A value the type cannot hold is an error.
- *
- * The result is `{ success, error, warnings, geometry, index, attributes }`,
- * where `geometry` is `"mesh"` or `"point_cloud"` as the stream's header says,
- * `index` a `Uint32Array` of triangle corners for a mesh and `null` for a
- * point cloud, and each attribute `{ name, uniqueId, semantic, array,
- * itemSize, normalized }`.
+ * Decodes a Draco stream and returns its attributes as typed arrays: every
+ * attribute in its own type, or the ones `attributes` requests, converted as
+ * upstream's `GetAttributeDataArrayForAllPoints` converts them.
  */
-export function decode_draco(data: Uint8Array, attributes: DracoAttributeRequest[] | undefined): DracoDecodeResult;
+export function decode_draco(
+data: Uint8Array,
+attributes?: DracoAttributeRequest[],
+options?: DracoDecodeOptions,
+): DracoDecodeResult;
+
+
 
 /**
  * Install the panic hook, so a panic reads as a message rather than a trap.
@@ -95,7 +91,7 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
-    readonly decode_draco: (a: number, b: number, c: number) => number;
+    readonly decode_draco: (a: number, b: number, c: number, d: number) => number;
     readonly init: () => void;
     readonly parse_drc_bytes: (a: number, b: number) => number;
     readonly supported_extensions: (a: number) => void;

package/point-cloud/index.js

@@ -18,17 +18,22 @@
  *
  * The result is `{ success, error, warnings, geometry, index, attributes }`,
  * where `geometry` is `"mesh"` or `"point_cloud"` as the stream's header says,
- * `index` a `Uint32Array` of triangle corners for a mesh and `null` for a
- * point cloud, and each attribute `{ name, uniqueId, semantic, array,
- * itemSize, normalized }`.
+ * `index` the triangle corners for a mesh and `null` for a point cloud, and
+ * each attribute `{ name, uniqueId, semantic, array, itemSize, normalized }`.
+ * The index is a `Uint32Array`, or with `options.index` set to `"auto"` a
+ * `Uint16Array` where the points number at most 65536.
+ *
+ * Its TypeScript declaration is written by hand in the section above, where
+ * the trailing parameters can be optional.
  * @param {Uint8Array} data
- * @param {DracoAttributeRequest[] | undefined} attributes
- * @returns {DracoDecodeResult}
+ * @param {any} attributes
+ * @param {object | null} [options]
+ * @returns {any}
  */
-export function decode_draco(data, attributes) {
+export function decode_draco(data, attributes, options) {
     const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_export);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.decode_draco(ptr0, len0, addHeapObject(attributes));
+    const ret = wasm.decode_draco(ptr0, len0, addHeapObject(attributes), isLikeNone(options) ? 0 : addHeapObject(options));
     return takeObject(ret);
 }
 

package/point-cloud/index_bg.wasm.d.ts

@@ -1,7 +1,7 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
-export const decode_draco: (a: number, b: number, c: number) => number;
+export const decode_draco: (a: number, b: number, c: number, d: number) => number;
 export const init: () => void;
 export const parse_drc_bytes: (a: number, b: number) => number;
 export const supported_extensions: (a: number) => void;

package/point-cloud/pool-core.d.ts

@@ -0,0 +1,44 @@
+export interface PoolOptions {
+  /**
+   * How many workers to run at most; they start as work arrives. Defaults to
+   * one less than the cores, between one and four. `0` runs on the calling
+   * thread, as does an environment without workers.
+   */
+  workers?: number;
+  /**
+   * The entry's wasm, when it is not next to this module where the pool looks
+   * for it: a URL, a `Response`, the bytes, or a compiled module.
+   */
+  wasm?: string | URL | Response | BufferSource | WebAssembly.Module;
+}
+
+export interface TaskOptions {
+  /**
+   * Hand the input's buffers to the worker instead of copying them, leaving
+   * them detached here. For buffers nothing else reads afterwards.
+   */
+  transfer?: boolean;
+  /**
+   * Abandons the task: the promise rejects with the signal's reason at once.
+   * A task a worker has already started still runs to its end, and its result
+   * is dropped; one not yet sent is never sent.
+   */
+  signal?: AbortSignal;
+}
+
+export interface Pool {
+  /** Compiles the wasm and starts one worker ahead of the first task. */
+  preload(): Promise<void>;
+  /** Changes the worker limit; idle workers past it stop now, busy ones when done. */
+  setWorkerLimit(workers: number): void;
+  readonly workerLimit: number;
+  /** Stops every worker and rejects what they held. */
+  dispose(): void;
+}
+
+export interface TaskPool extends Pool {
+  /** Runs the task `tasks.js` exports under `name` on a worker. */
+  run(name: string, args?: unknown[], options?: TaskOptions): Promise<any>;
+}
+
+export function createPool(options?: PoolOptions): TaskPool;