@draco-rust/decoder 0.1.1 → 0.2.0

package/legacy/pool.js

@@ -0,0 +1,193 @@
+// 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';
+
+/** 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;
+
+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);
+  }
+
+  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);
+    },
+    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);
+    },
+  };
+}

package/legacy/three.d.ts

@@ -0,0 +1,19 @@
+import type { LoadingManager } from 'three';
+import { DRACOLoader as ThreeDRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+import type { DecoderPool, DecoderPoolOptions } from './pool.js';
+
+export interface DRACOLoaderOptions extends DecoderPoolOptions {
+  /** A pool to share with other loaders, instead of one of the loader's own. */
+  pool?: DecoderPool;
+}
+
+/**
+ * three.js's `DRACOLoader`, decoding on this entry's worker pool instead of
+ * the Draco decoder three fetches from `setDecoderPath`. It is three's class,
+ * so it goes wherever one is expected:
+ * `gltfLoader.setDRACOLoader(new DRACOLoader())`.
+ */
+export class DRACOLoader extends ThreeDRACOLoader {
+  constructor(manager?: LoadingManager, options?: DRACOLoaderOptions);
+  readonly pool: DecoderPool;
+}

package/legacy/three.js

@@ -0,0 +1,82 @@
+// three.js's DRACOLoader, decoding on this entry's worker pool. Everything a
+// caller sees -- load, parse, decodeDracoFile, GLTFLoader's use of it, the
+// geometry it builds -- is three's own class; only the decode is replaced, so
+// the result follows whichever three the application has.
+import { REVISION } from 'three';
+import { DRACOLoader as ThreeDRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+import { createDecoderPool } from './pool.js';
+
+// From r181 DRACOLoader pads an attribute whose items are not a multiple of
+// four bytes and builds it interleaved, from the stride its worker reports.
+const PADS = Number.parseInt(REVISION, 10) >= 181;
+
+function padded(array, itemSize) {
+  const bytes = array.BYTES_PER_ELEMENT;
+  const stride = (Math.ceil((itemSize * bytes) / 4) * 4) / bytes;
+  if (!PADS || stride === itemSize) return { array, stride: itemSize };
+  const count = array.length / itemSize;
+  const out = new array.constructor(count * stride);
+  for (let i = 0; i < count; i += 1) {
+    out.set(array.subarray(i * itemSize, (i + 1) * itemSize), i * stride);
+  }
+  return { array: out, stride };
+}
+
+export class DRACOLoader extends ThreeDRACOLoader {
+  #tasks = new WeakMap();
+
+  constructor(manager, options = {}) {
+    super(manager);
+    this.pool = options.pool ?? createDecoderPool(options);
+  }
+
+  // The buffer goes to a worker by transfer, which leaves nothing here to
+  // decode again; a second request for it gets the first answer, as three's
+  // own task cache gives it.
+  decodeGeometry(buffer, taskConfig) {
+    const key = JSON.stringify(taskConfig);
+    const cached = this.#tasks.get(buffer);
+    if (cached?.key === key) return cached.promise;
+    if (cached && buffer.byteLength === 0) {
+      return Promise.reject(new Error('THREE.DRACOLoader: Unable to re-decode a buffer with different settings. Buffer has already been transferred.'));
+    }
+    const { attributeIDs, attributeTypes, useUniqueIDs, vertexColorSpace } = taskConfig;
+    const requests = Object.keys(attributeIDs).map((name) => ({
+      name,
+      ...(useUniqueIDs ? { id: attributeIDs[name] } : { semantic: attributeIDs[name] }),
+      type: attributeTypes[name],
+    }));
+    const promise = this.pool.decode(buffer, requests, { transfer: buffer instanceof ArrayBuffer }).then((result) => {
+      if (!result.success) throw new Error(`THREE.DRACOLoader: Decoding failed: ${result.error}`);
+      return this._createGeometry({
+        index: result.index ? { array: result.index, itemSize: 1 } : null,
+        attributes: result.attributes.map(({ name, array, itemSize }) => ({
+          name,
+          itemSize,
+          ...padded(array, itemSize),
+          ...(name === 'color' ? { vertexColorSpace } : {}),
+        })),
+      });
+    });
+    if (buffer instanceof ArrayBuffer) this.#tasks.set(buffer, { key, promise });
+    return promise;
+  }
+
+  setWorkerLimit(workerLimit) {
+    super.setWorkerLimit(workerLimit);
+    this.pool.setWorkerLimit(workerLimit);
+    return this;
+  }
+
+  preload() {
+    // A failure shows again on the first decode, which is where it is handled.
+    this.pool.preload().catch(() => {});
+    return this;
+  }
+
+  dispose() {
+    super.dispose();
+    this.pool.dispose();
+    return this;
+  }
+}

package/legacy/worker.js

@@ -0,0 +1,28 @@
+// 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';
+
+const web = typeof self !== 'undefined' && typeof self.postMessage === 'function';
+const port = web ? self : process.getBuiltinModule('node:worker_threads').parentPort;
+const listen = (handler) =>
+  web ? self.addEventListener('message', (event) => handler(event.data)) : port.on('message', handler);
+
+let ready = null;
+
+listen(async (message) => {
+  if (message.type === 'init') {
+    ready = init({ module_or_path: message.module });
+    return;
+  }
+  const { id, data, attributes } = 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);
+  } catch (error) {
+    port.postMessage({ id, error: String(error?.message ?? error) });
+  }
+});

package/mesh/index.d.ts

@@ -1,6 +1,76 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/** The name of a typed array `decode_draco` can convert an attribute to. */
+export type DracoArrayType =
+| "Int8Array" | "Uint8Array" | "Int16Array" | "Uint16Array"
+| "Int32Array" | "Uint32Array" | "Float32Array";
+
+/** A Draco attribute type, as `semantic` names it. */
+export type DracoSemantic = "POSITION" | "NORMAL" | "COLOR" | "TEX_COORD" | "GENERIC";
+
+/**
+ * One attribute to decode: by `id`, its unique id, or by `semantic`, the first
+ * attribute of that type. `name` is handed back unchanged.
+ */
+export interface DracoAttributeRequest {
+    name?: string;
+    id?: number;
+    semantic?: DracoSemantic;
+    type?: DracoArrayType;
+}
+
+/** The typed arrays an attribute can come back in. */
+export type DracoArray =
+| Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array
+| Float32Array | Float64Array | BigInt64Array | BigUint64Array;
+
+export interface DracoAttribute {
+    /** The request's `name`, or else the name the stream's metadata gives it. */
+    name?: string;
+    uniqueId: number;
+    semantic: DracoSemantic;
+    array: DracoArray;
+    itemSize: number;
+    normalized: boolean;
+}
+
+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;
+    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 }`.
+ */
+export function decode_draco(data: Uint8Array, attributes: DracoAttributeRequest[] | undefined): DracoDecodeResult;
+
 /**
  * Install the panic hook, so a panic reads as a message rather than a trap.
  */
@@ -25,14 +95,16 @@ 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 init: () => void;
     readonly parse_drc_bytes: (a: number, b: number) => number;
     readonly supported_extensions: (a: number) => void;
     readonly version: (a: number) => void;
-    readonly __wbindgen_export: (a: number) => void;
-    readonly __wbindgen_export2: (a: number, b: number) => number;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number) => void;
     readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
-    readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
     readonly __wbindgen_start: () => void;
 }