@draco-rust/decoder 0.1.2 → 0.3.0

package/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/tasks.js

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

package/three.d.ts

@@ -1,65 +1,19 @@
-import type { DracoArrayType } from './index.js';
+import type { LoadingManager } from 'three';
+import { DRACOLoader as ThreeDRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
 import type { DecoderPool, DecoderPoolOptions } from './pool.js';
 
-/**
- * The three.js classes the loader builds with, passed in so the package uses
- * the application's own copy of three: `import * as THREE from "three"` will
- * do. With `InterleavedBuffer` and `InterleavedBufferAttribute`, an attribute
- * whose items are not a multiple of four bytes is padded to one, as DRACOLoader
- * pads it since r181; with `Color` and `ColorManagement`, a `.drc` file's sRGB
- * vertex colours are made linear as DRACOLoader makes them.
- */
-export interface ThreeClasses<Geometry> {
-  BufferGeometry: new () => Geometry;
-  BufferAttribute: new (array: any, itemSize: number, normalized?: boolean) => any;
-  InterleavedBuffer?: new (array: any, stride: number) => any;
-  InterleavedBufferAttribute?: new (buffer: any, itemSize: number, offset: number) => any;
-  Color?: new () => any;
-  /** `colorSpaceToWorking` since three r177, `toWorkingColorSpace` before. */
-  ColorManagement?:
-    | { colorSpaceToWorking(color: any, colorSpace: string): any }
-    | { toWorkingColorSpace(color: any, colorSpace: string): any };
-}
-
-export interface DracoLoaderOptions extends DecoderPoolOptions {
+export interface DRACOLoaderOptions extends DecoderPoolOptions {
   /** A pool to share with other loaders, instead of one of the loader's own. */
   pool?: DecoderPool;
 }
 
-export interface DecodeGeometryOptions {
-  /** three.js attribute name to Draco unique id, as glTF names them. Without
-   * it, `position`, `normal`, `color` and `uv` are read by type. */
-  attributeIDs?: Record<string, number>;
-  /** three.js attribute name to the typed array it comes back in. */
-  attributeTypes?: Record<string, DracoArrayType>;
-  /** `"srgb"` makes vertex colours linear; the default leaves them as stored. */
-  vertexColorSpace?: string;
-}
-
-/** The part of three.js's DRACOLoader that GLTFLoader and `.drc` users call. */
-export interface DracoLoader<Geometry> {
-  readonly pool: DecoderPool;
-  decodeGeometry(buffer: ArrayBuffer | ArrayBufferView, options?: DecodeGeometryOptions): Promise<Geometry>;
-  decodeDracoFile(
-    buffer: ArrayBuffer,
-    callback: (geometry: Geometry) => void,
-    attributeIDs?: Record<string, number> | null,
-    attributeTypes?: Record<string, DracoArrayType> | null,
-    vertexColorSpace?: string,
-    onError?: (error: unknown) => void,
-  ): Promise<void>;
-  parse(buffer: ArrayBuffer, onLoad: (geometry: Geometry) => void, onError?: (error: unknown) => void): void;
-  parseAsync(buffer: ArrayBuffer | ArrayBufferView): Promise<Geometry>;
-  preload(): this;
-  setWorkerLimit(workers: number): this;
-  dispose(): this;
-}
-
 /**
- * A stand-in for three.js's DRACOLoader on the decoder pool:
- * `gltfLoader.setDRACOLoader(createDracoLoader(THREE))`.
+ * 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 function createDracoLoader<Geometry>(
-  three: ThreeClasses<Geometry>,
-  options?: DracoLoaderOptions,
-): DracoLoader<Geometry>;
+export class DRACOLoader extends ThreeDRACOLoader {
+  constructor(manager?: LoadingManager, options?: DRACOLoaderOptions);
+  readonly pool: DecoderPool;
+}

package/three.js

@@ -1,123 +1,82 @@
-// What three.js's GLTFLoader and DRACOLoader users call, over the decoder pool.
-// three.js is not imported: the caller hands in the classes, so the package
-// works with whichever copy of three the application bundles.
+// 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';
 
-const SRGB = 'srgb';
-const LINEAR_SRGB = 'srgb-linear';
+// 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;
 
-// DRACOLoader's defaults for a `.drc` file, read by attribute type.
-const defaultAttributes = {
-  position: 'POSITION',
-  normal: 'NORMAL',
-  color: 'COLOR',
-  uv: 'TEX_COORD',
-};
-
-export function createDracoLoader(three, options = {}) {
-  const { BufferGeometry, BufferAttribute, InterleavedBuffer, InterleavedBufferAttribute, Color, ColorManagement } =
-    three;
-  if (typeof BufferGeometry !== 'function' || typeof BufferAttribute !== 'function') {
-    throw new TypeError("createDracoLoader needs three.js's BufferGeometry and BufferAttribute");
+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);
   }
-  const pool = options.pool ?? createDecoderPool(options);
-  // The buffer goes to the worker by transfer, which leaves nothing here to
-  // decode a second time; GLTFLoader asks again for a primitive it shares, and
-  // gets the first answer, as DRACOLoader gives it.
-  const tasks = new WeakMap();
+  return { array: out, stride };
+}
 
-  // Vertex colours a `.drc` file stores in sRGB become linear, as DRACOLoader
-  // makes them; without Color and ColorManagement they are left as stored.
-  function toWorkingColorSpace(attribute) {
-    const convert = ColorManagement?.colorSpaceToWorking ?? ColorManagement?.toWorkingColorSpace;
-    if (!Color || !convert) return;
-    const color = new Color();
-    for (let i = 0; i < attribute.count; i += 1) {
-      color.fromBufferAttribute(attribute, i);
-      convert.call(ColorManagement, color, SRGB);
-      attribute.setXYZ(i, color.r, color.g, color.b);
-    }
-  }
+export class DRACOLoader extends ThreeDRACOLoader {
+  #tasks = new WeakMap();
 
-  // An item that is not a multiple of four bytes is padded to one, and the
-  // attribute interleaved over the padding, as DRACOLoader does since r181
-  // for glTF's data alignment rule -- when the classes for it were handed in.
-  function attributeOf(array, itemSize) {
-    const bytes = array.BYTES_PER_ELEMENT;
-    const stride = Math.ceil((itemSize * bytes) / 4) * (4 / bytes);
-    if (stride === itemSize || !InterleavedBuffer || !InterleavedBufferAttribute) {
-      return new BufferAttribute(array, itemSize);
-    }
-    const count = array.length / itemSize;
-    const padded = new array.constructor(count * stride);
-    for (let i = 0; i < count; i += 1) {
-      padded.set(array.subarray(i * itemSize, (i + 1) * itemSize), i * stride);
-    }
-    return new InterleavedBufferAttribute(new InterleavedBuffer(padded, stride), itemSize, 0);
+  constructor(manager, options = {}) {
+    super(manager);
+    this.pool = options.pool ?? createDecoderPool(options);
   }
 
-  async function decode(buffer, attributeIDs, attributeTypes, vertexColorSpace) {
-    const byId = !!attributeIDs;
-    const requests = Object.entries(attributeIDs ?? defaultAttributes).map(([name, id]) => ({
+  // 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,
-      ...(byId ? { id } : { semantic: id }),
-      type: attributeTypes?.[name] ?? 'Float32Array',
+      ...(useUniqueIDs ? { id: attributeIDs[name] } : { semantic: attributeIDs[name] }),
+      type: attributeTypes[name],
     }));
-    const result = await pool.decode(buffer, requests, { transfer: buffer instanceof ArrayBuffer });
-    if (!result.success) throw new Error(result.error);
+    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;
+  }
 
-    const geometry = new BufferGeometry();
-    if (result.index) geometry.setIndex(new BufferAttribute(result.index, 1));
-    for (const { name, array, itemSize } of result.attributes) {
-      const attribute = attributeOf(array, itemSize);
-      if (name === 'color') {
-        if (vertexColorSpace === SRGB) toWorkingColorSpace(attribute);
-        attribute.normalized = !(array instanceof Float32Array);
-      }
-      geometry.setAttribute(name, attribute);
-    }
-    return geometry;
+  setWorkerLimit(workerLimit) {
+    super.setWorkerLimit(workerLimit);
+    this.pool.setWorkerLimit(workerLimit);
+    return this;
   }
 
-  function decodeGeometry(buffer, { attributeIDs, attributeTypes, vertexColorSpace = LINEAR_SRGB } = {}) {
-    const key = JSON.stringify([attributeIDs ?? null, attributeTypes ?? null, vertexColorSpace]);
-    const cached = buffer instanceof ArrayBuffer ? tasks.get(buffer) : undefined;
-    if (cached?.key === key) return cached.promise;
-    if (cached && buffer.byteLength === 0) {
-      return Promise.reject(new Error('this buffer was already decoded with other settings and handed to a worker'));
-    }
-    const promise = decode(buffer, attributeIDs, attributeTypes, vertexColorSpace);
-    if (buffer instanceof ArrayBuffer) tasks.set(buffer, { key, promise });
-    return promise;
+  preload() {
+    // A failure shows again on the first decode, which is where it is handled.
+    this.pool.preload().catch(() => {});
+    return this;
   }
 
-  const loader = {
-    pool,
-    decodeGeometry,
-    /** DRACOLoader's entry for GLTFLoader's `KHR_draco_mesh_compression`. */
-    decodeDracoFile(buffer, callback, attributeIDs, attributeTypes, vertexColorSpace = LINEAR_SRGB, onError = () => {}) {
-      return decodeGeometry(buffer, { attributeIDs, attributeTypes, vertexColorSpace }).then(callback).catch(onError);
-    },
-    /** A `.drc` file's contents, as DRACOLoader's `parse`. */
-    parse(buffer, onLoad, onError = () => {}) {
-      loader.decodeDracoFile(buffer, onLoad, null, null, SRGB, onError);
-    },
-    parseAsync(buffer) {
-      return decodeGeometry(buffer, { vertexColorSpace: SRGB });
-    },
-    preload() {
-      // A failure shows again on the first decode, which is where it is handled.
-      pool.preload().catch(() => {});
-      return loader;
-    },
-    setWorkerLimit(workers) {
-      pool.setWorkerLimit(workers);
-      return loader;
-    },
-    dispose() {
-      pool.dispose();
-      return loader;
-    },
-  };
-  return loader;
+  dispose() {
+    super.dispose();
+    this.pool.dispose();
+    return this;
+  }
 }

package/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) });
   }