@draco-rust/decoder 0.1.0 → 0.1.2

package/three.d.ts

@@ -0,0 +1,65 @@
+import type { DracoArrayType } from './index.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 {
+  /** 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))`.
+ */
+export function createDracoLoader<Geometry>(
+  three: ThreeClasses<Geometry>,
+  options?: DracoLoaderOptions,
+): DracoLoader<Geometry>;

package/three.js

@@ -0,0 +1,123 @@
+// 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.
+import { createDecoderPool } from './pool.js';
+
+const SRGB = 'srgb';
+const LINEAR_SRGB = 'srgb-linear';
+
+// 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");
+  }
+  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();
+
+  // 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);
+    }
+  }
+
+  // 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);
+  }
+
+  async function decode(buffer, attributeIDs, attributeTypes, vertexColorSpace) {
+    const byId = !!attributeIDs;
+    const requests = Object.entries(attributeIDs ?? defaultAttributes).map(([name, id]) => ({
+      name,
+      ...(byId ? { id } : { semantic: id }),
+      type: attributeTypes?.[name] ?? 'Float32Array',
+    }));
+    const result = await pool.decode(buffer, requests, { transfer: buffer instanceof ArrayBuffer });
+    if (!result.success) throw new Error(result.error);
+
+    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;
+  }
+
+  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;
+  }
+
+  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;
+}

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