@draco-rust/decoder 0.1.0 → 0.1.2

package/README.md

@@ -11,10 +11,14 @@ Each entry is a separate module. A bundler includes only the one you import.
 
 | import | decodes | gzip |
 |---|---|---|
-| `@draco-rust/decoder` | meshes and point clouds | ~87 KiB |
-| `@draco-rust/decoder/mesh` | meshes only, which is all glTF's `KHR_draco_mesh_compression` allows | ~72 KiB |
-| `@draco-rust/decoder/point-cloud` | point clouds only (scans, splats) | ~58 KiB |
-| `@draco-rust/decoder/legacy` | meshes and point clouds, plus bitstreams older than 2.2 | ~97 KiB |
+| `@draco-rust/decoder` | meshes and point clouds | ~92 KiB |
+| `@draco-rust/decoder/mesh` | meshes only, which is all glTF's `KHR_draco_mesh_compression` allows | ~77 KiB |
+| `@draco-rust/decoder/point-cloud` | point clouds only (scans, splats) | ~63 KiB |
+| `@draco-rust/decoder/legacy` | meshes and point clouds, plus bitstreams older than 2.2 | ~103 KiB |
+
+Each entry also has a worker pool and a three.js loader of its own, which use
+that entry's module: `@draco-rust/decoder/pool` and `@draco-rust/decoder/three`,
+or `@draco-rust/decoder/mesh/pool`, `@draco-rust/decoder/mesh/three` and so on.
 
 ## Usage
 
@@ -36,6 +40,77 @@ triangle corners, which is empty for a point cloud. `normals` and `uvs` are
 such attribute. Attributes the stream carries beyond those are in
 `meshes[0].extras`, and `result.warnings` says what was not interpreted.
 
+### Attributes the way a loader asks for them
+
+`decode_draco` returns every attribute as a typed array, or the ones a loader
+asks for, converted to the array type it needs. Upstream Draco's decoder makes
+the same conversions, and this one matches it byte for byte, refusing where it
+refuses.
+
+```js
+import init, { decode_draco } from "@draco-rust/decoder/mesh";
+
+await init();
+// By unique id, as glTF's KHR_draco_mesh_compression names them, or by type.
+const result = decode_draco(bytes, [
+  { name: "position", id: 0, type: "Float32Array" },
+  { name: "color", semantic: "COLOR", type: "Uint16Array" },
+]);
+if (!result.success) throw new Error(result.error);
+const { index, attributes } = result; // attributes[i]: { name, array, itemSize, normalized, ... }
+```
+
+Without the second argument every attribute comes back in its own type.
+
+### On workers
+
+Decoding runs on the calling thread. `createDecoderPool` runs it on workers
+instead, so a page stays responsive while several streams decode at once:
+
+```js
+import { createDecoderPool } from "@draco-rust/decoder/mesh/pool";
+
+const pool = createDecoderPool({ workers: 4 }); // default: cores - 1, at most 4
+const result = await pool.decode(bytes, requests); // what decode_draco returns
+pool.dispose();
+```
+
+The workers start as work arrives, and the wasm is compiled once for all of
+them. The stream is copied to the worker; `pool.decode(bytes, requests, {
+transfer: true })` hands over the buffer itself instead. The pool runs on Web
+Workers, on Node's worker threads (Node 20.16 and later), and from a CDN. With
+`workers: 0`, or where there are no workers, it decodes on the calling thread.
+A bundler that follows `new URL("./worker.js", import.meta.url)`, as Vite and
+webpack do, emits the worker on its own.
+
+### With three.js
+
+`createDracoLoader` stands in for three.js's `DRACOLoader`, on the pool. It
+takes three's classes rather than importing three, so it builds with your own
+copy:
+
+```js
+import * as THREE from "three";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { createDracoLoader } from "@draco-rust/decoder/mesh/three";
+
+const gltfLoader = new GLTFLoader();
+gltfLoader.setDRACOLoader(createDracoLoader(THREE));
+const gltf = await gltfLoader.loadAsync("model.glb");
+```
+
+For a `.drc` file, `await loader.parseAsync(arrayBuffer)` returns a
+`BufferGeometry`, and `parse(buffer, onLoad, onError)` works as DRACOLoader's
+does. Vertex colours from a `.drc` file are converted from sRGB, as
+DRACOLoader converts them, and an attribute whose items are not a multiple of
+four bytes is padded and interleaved, as DRACOLoader pads it since r181. The
+geometry is the one DRACOLoader builds, byte for byte, with one difference: an
+attribute that does not convert to the type asked for -- a negative value
+into a `Uint16Array`, say -- is an error here, where DRACOLoader fills the
+attribute with whatever its failed conversion left in memory. `setWorkerLimit`,
+`preload` and `dispose` are there too. In TypeScript, `setDRACOLoader` expects the `DRACOLoader` class, so cast
+the loader: `createDracoLoader(THREE) as unknown as DRACOLoader`.
+
 ### From a CDN, without a bundler
 
 ```js
@@ -61,9 +136,9 @@ For a subpath entry, resolve its own file, for example
 
 - Runs in every browser with WebAssembly, in Node 20.6 and later, in Deno and
   in Bun.
-- Decoding happens on the calling thread. Call it from a Web Worker to keep a
-  page responsive.
+- `parse_drc_bytes` and `decode_draco` decode on the calling thread; the pool
+  decodes on workers.
 - Licensed under Apache-2.0, like Draco.
 ## This build
 
-`@draco-rust/decoder@0.1.0` was built from draco-rust commit `40227fd4`, with draco-core 2.3.0, draco-io 0.5.2, draco-gltf 0.6.0.
+`@draco-rust/decoder@0.1.2` was built from draco-rust commit `6bc95d5c`, with draco-core 2.3.2, draco-io 0.6.0, draco-gltf 0.7.0.

package/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.
  */
@@ -24,36 +94,38 @@ export function version(): string;
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
-  readonly memory: WebAssembly.Memory;
-  readonly parse_drc_bytes: (a: number, b: number) => number;
-  readonly supported_extensions: (a: number) => void;
-  readonly version: (a: number) => void;
-  readonly init: () => void;
-  readonly __wbindgen_export: (a: number) => void;
-  readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
-  readonly __wbindgen_export2: (a: number, b: number, c: number) => void;
-  readonly __wbindgen_export3: (a: number, b: number) => number;
-  readonly __wbindgen_start: () => void;
+    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, 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_export4: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_start: () => void;
 }
 
 export type SyncInitInput = BufferSource | WebAssembly.Module;
 
 /**
-* Instantiates the given `module`, which can either be bytes or
-* a precompiled `WebAssembly.Module`.
-*
-* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
-*
-* @returns {InitOutput}
-*/
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
 export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
 
 /**
-* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
-* for everything else, calls `WebAssembly.instantiate` directly.
-*
-* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
-*
-* @returns {Promise<InitOutput>}
-*/
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
 export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;