@draco-rust/decoder 0.1.2 → 0.3.0

package/mesh/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/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.1.2",
+  "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": "6bc95d5c",
+    "commit": "4b72cfc8",
     "draco-core": "2.3.2",
     "draco-io": "0.6.0",
     "draco-gltf": "0.7.0"
@@ -72,6 +72,14 @@
     "**/*.d.ts",
     "**/*.wasm"
   ],
+  "peerDependencies": {
+    "three": ">=0.150.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   }

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;