@downdraft/engine 0.0.0 → 0.1.1

package/libraries/models/src/codecs/basisu-codec.ts

@@ -0,0 +1,180 @@
+// ============================================================================
+// basisu texture codec — transcodes KHR_texture_basisu KTX2 → GPU texture.
+// ============================================================================
+//
+// KHR_texture_basisu points a glTF texture at an image whose bufferView holds
+// KTX2-encoded bytes with Basis Universal supercompression (vkFormat=0). The
+// engine's KTX2 reader (parseKTX2FromBuffer) only handles KTX2 with concrete
+// vkFormats (BC/ASTC/ETC/uncompressed) — it cannot transcode Basisu. This
+// codec bridges that gap: it transcodes Basisu KTX2 → RGBA32 (uncompressed)
+// using @h00w/basis-universal-transcoder (wasm, ~486KB, lazy-loaded).
+//
+// Transcoding to RGBA32 is the universally-compatible first pass: every
+// WebGPU device supports rgba8unorm. The Basisu win is on-disk/download size
+// (ETC1S/UASTC are far smaller than PNG/JPG). A follow-up can transcode to
+// BC7/ASTC per-GPU for VRAM savings (the engine's createGPUTextureFromData
+// already handles compressed formats).
+//
+// The transcoder wasm is loaded lazily on first decode(). In the Vite
+// renderer the wasm URL is resolved via a `?url` import; in Node it is read
+// from the package on disk. Override with configureBasisuWasmPath().
+//
+
+import type { TextureCodec, TextureCodecInput, TextureCodecOutput } from "./registry";
+
+// Vite resolves this to a hashed asset URL in the renderer build. In Node the
+// import is unused (we read from disk). `vite/client` types declare `*?url`.
+// Loaded lazily: Deno rejects the `?url` package subpath at resolution time.
+let wasmUrlCached: string | null = null;
+async function getWasmUrl(): Promise<string> {
+  if (wasmUrlCached === null) {
+    try {
+      const mod = await import("@h00w/basis-universal-transcoder/basis_capi_transcoder.wasm?url") as { default: string };
+      wasmUrlCached = mod.default;
+    } catch {
+      wasmUrlCached = "";
+    }
+  }
+  return wasmUrlCached;
+}
+
+export interface BasisuWasmConfig {
+  wasmUrl?: string;
+  wasmBinary?: ArrayBuffer;
+}
+
+let basisuWasmConfig: BasisuWasmConfig = {};
+
+/** Override the transcoder wasm source (URL or pre-loaded ArrayBuffer). */
+export function configureBasisuWasmPath(config: BasisuWasmConfig): void {
+  basisuWasmConfig = config;
+  basisuPromise = null;
+}
+
+// Minimal typed surface of @h00w/basis-universal-transcoder.
+interface TranscodeResult {
+  data: Uint8Array;
+  width: number;
+  height: number;
+}
+interface KTX2TranscoderT {
+  init(data: Uint8Array): boolean;
+  getHeader(): { width: number; height: number; levels: number };
+  startTranscoding(): boolean;
+  transcodeImageLevel(opts: {
+    format: number;
+    level?: number;
+    layer?: number;
+    face?: number;
+  }): TranscodeResult | null;
+  dispose(): void;
+}
+interface BasisUniversalT {
+  createKTX2Transcoder(): KTX2TranscoderT;
+}
+type TranscoderTextureFormat = number;
+const cTFRGBA32 = 13 as TranscoderTextureFormat;
+
+let basisuPromise: Promise<BasisUniversalT> | null = null;
+
+async function loadBasisu(): Promise<BasisUniversalT> {
+  if (basisuPromise) return basisuPromise;
+  basisuPromise = (async () => {
+    const mod = await import("@h00w/basis-universal-transcoder");
+    const { BasisUniversal } = mod as unknown as {
+      BasisUniversal: {
+        getInstance(instantiate: (imports: WebAssembly.Imports) => Promise<WebAssembly.WebAssemblyInstantiatedSource>): Promise<BasisUniversalT>;
+      };
+    };
+
+    const instantiate = async (imports: WebAssembly.Imports): Promise<WebAssembly.WebAssemblyInstantiatedSource> => {
+      // Explicit override wins.
+      if (basisuWasmConfig.wasmBinary) {
+        return WebAssembly.instantiate(basisuWasmConfig.wasmBinary, imports);
+      }
+      const url = basisuWasmConfig.wasmUrl ?? (await getWasmUrl());
+      // Browser/renderer: fetch the URL if it's a valid http/https URL.
+      // The `?url` import produces a real URL in Vite; in Node/bun it may
+      // produce an invalid string, so we validate before fetching.
+      if (typeof fetch === "function" && /^https?:\/\//.test(url)) {
+        const res = await fetch(url);
+        const bytes = await res.arrayBuffer();
+        return WebAssembly.instantiate(bytes, imports);
+      }
+      // Node fallback: read the wasm from the package on disk.
+      const fs = await import("node:fs");
+      const path = await import("node:path");
+      const { createRequire } = await import("node:module");
+      const require = createRequire(import.meta.url);
+      const pkgPath = require.resolve("@h00w/basis-universal-transcoder/package.json");
+      const wasmPath = path.join(path.dirname(pkgPath), "dist", "basis_capi_transcoder.wasm");
+      const bytes = fs.readFileSync(wasmPath);
+      return WebAssembly.instantiate(bytes, imports);
+    };
+
+    return BasisUniversal.getInstance(instantiate);
+  })();
+  return basisuPromise;
+}
+
+export function createBasisuTextureCodec(): TextureCodec {
+  return {
+    uri: "KHR_texture_basisu",
+    async decode(input: TextureCodecInput): Promise<TextureCodecOutput> {
+      const basisu = await loadBasisu();
+      const data = input.data;
+      const transcoder = basisu.createKTX2Transcoder();
+
+      if (!transcoder.init(data)) {
+        transcoder.dispose();
+        throw new Error("KHR_texture_basisu: failed to init KTX2 transcoder");
+      }
+      if (!transcoder.startTranscoding()) {
+        transcoder.dispose();
+        throw new Error("KHR_texture_basisu: failed to start transcoding");
+      }
+
+      const header = transcoder.getHeader();
+      const levels = header.levels;
+      const w0 = header.width;
+      const h0 = header.height;
+
+      // Transcode each mip level to RGBA32 and concatenate.
+      const levelBytes: Uint8Array[] = [];
+      let totalSize = 0;
+      for (let level = 0; level < levels; level++) {
+        const result = transcoder.transcodeImageLevel({ format: cTFRGBA32, level });
+        if (!result) {
+          // Some encoders emit fewer levels than the header claims; stop at
+          // the first missing level rather than failing the whole texture.
+          break;
+        }
+        // The wasm memory is invalidated on the next transcode call — copy now.
+        const copy = new Uint8Array(result.data);
+        levelBytes.push(copy);
+        totalSize += copy.byteLength;
+      }
+      transcoder.dispose();
+
+      if (levelBytes.length === 0) {
+        throw new Error("KHR_texture_basisu: no mip levels transcoded");
+      }
+
+      const combined = new Uint8Array(totalSize);
+      let offset = 0;
+      levelBytes.forEach((lb) => {
+        combined.set(lb, offset);
+        offset += lb.byteLength;
+      });
+
+      return {
+        data: combined,
+        width: w0,
+        height: h0,
+        format: "rgba8unorm",
+        mipLevels: levelBytes.length,
+        isHDR: false,
+      };
+    },
+  };
+}

package/libraries/models/src/codecs/draco-codec.ts

@@ -0,0 +1,372 @@
+// ============================================================================
+// Draco mesh codec — decodes KHR_draco_mesh_compression primitives.
+// ============================================================================
+//
+// Uses the `draco3dgltf` WASM decoder. The decoder module is loaded lazily on
+// first decode() call and cached for the process lifetime. The WASM binary
+// path is resolved via `locateFile`; see `configureDracoWasmPath()`.
+//
+// KHR_draco_mesh_compression maps each glTF attribute semantic to a Draco
+// attribute unique id. We decode the whole primitive once and return per-
+// attribute typed arrays.
+//
+
+/// <reference path="./draco3dgltf.d.ts" />
+
+import { assertCount, MAX_DECOMPRESS_SIZE, MAX_FACE_COUNT, MAX_VERTEX_COUNT } from "@downdraft/engine";
+import type {
+    AccessorLike,
+    DecodedPrimitive,
+    MeshCodec,
+    MeshCodecInput,
+} from "./registry";
+
+// Draco component type constants (mirrors glTF componentType).
+const COMPONENT_TYPE_BYTES: Record<number, number> = {
+  5120: 1, // BYTE
+  5121: 1, // UNSIGNED_BYTE
+  5122: 2, // SHORT
+  5123: 2, // UNSIGNED_SHORT
+  5125: 4, // UNSIGNED_INT
+  5126: 4, // FLOAT
+};
+
+const TYPE_COMPONENTS: Record<string, number> = {
+  SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16,
+};
+
+// Emscripten decoder module factory + the resolved module instance.
+type DracoModuleFactory = (config: {
+  locateFile?: (file: string, prefix: string) => string;
+  wasmBinary?: ArrayBuffer;
+  onRuntimeInitialized?: () => void;
+}) => Promise<DracoModule>;
+
+interface DracoModule {
+  DecoderBuffer: new () => DracoDecoderBuffer;
+  Decoder: new () => DracoDecoder;
+  Mesh: new () => DracoMesh;
+  PointCloud: new () => DracoPointCloud;
+  AttributeData: new () => DracoAttributeData;
+  // Typed array constructors bound to the module's heap.
+  // The emscripten module exposes heap views; we use module-provided arrays.
+  _malloc: (n: number) => number;
+  _free: (ptr: number) => void;
+  HEAPF32: Float32Array;
+  HEAPU8: Uint8Array;
+  // Draco status enum values
+  POINT_CLOUD: number;
+  TRIANGULAR_MESH: number;
+  // Attribute data type enum (DT_FLOAT32, DT_UINT8, etc.) — accessed lazily.
+  [key: string]: unknown;
+}
+
+interface DracoDecoderBuffer {
+  Init(data: Uint8Array, length: number): void;
+  delete(): void;
+}
+
+interface DracoDecoder {
+  GetEncodedGeometryType(buffer: DracoDecoderBuffer): number;
+  DecodeBufferToMesh(buffer: DracoDecoderBuffer, mesh: DracoMesh): number;
+  DecodeBufferToPointCloud(buffer: DracoDecoderBuffer, pc: DracoPointCloud): number;
+  GetMeshAttribute(mesh: DracoMesh, uniqueId: number): DracoAttributeData;
+  GetAttribute(mesh: DracoMesh, i: number): DracoAttributeData;
+  GetFaceFromMesh(mesh: DracoMesh, faceId: number, out: DracoFace): boolean;
+  // Read an attribute into a pre-allocated typed array at a heap pointer.
+  GetAttributeDataArrayForAllPoints(
+    mesh: DracoMesh | DracoPointCloud,
+    attr: DracoAttributeData,
+    dataType: number,
+    outSize: number,
+    outPtr: number,
+  ): boolean;
+  GetAttributeFloatArray(
+    mesh: DracoMesh | DracoPointCloud,
+    attr: DracoAttributeData,
+    outSize: number,
+    outPtr: number,
+  ): boolean;
+  skipAttributeTransform(type: number): void;
+  delete(): void;
+}
+
+interface DracoMesh {
+  num_attributes(): number;
+  num_points(): number;
+  num_faces(): number;
+  delete(): void;
+}
+
+interface DracoPointCloud {
+  num_attributes(): number;
+  num_points(): number;
+  delete(): void;
+}
+
+interface DracoAttributeData {
+  unique_id(): number;
+  attribute_type(): number;
+  data_type(): number;
+  num_components(): number;
+  normalized(): boolean;
+  size(): number;
+  delete(): void;
+}
+
+interface DracoFace {
+  // DracoDecoder.GetFaceFromMesh writes 3 ints; we use a heap Int32 view.
+}
+
+// Draco data type enum (subset we care about).
+const DT_FLOAT32 = 9;
+const DT_INT8 = 2;
+const DT_UINT8 = 3;
+const DT_INT16 = 4;
+const DT_UINT16 = 5;
+const DT_INT32 = 6;
+const DT_UINT32 = 7;
+
+// Map glTF componentType → Draco data type for output array allocation.
+function componentTypeToDracoDataType(componentType: number): number {
+  switch (componentType) {
+    case 5126: return DT_FLOAT32;
+    case 5121: return DT_UINT8;
+    case 5120: return DT_INT8;
+    case 5123: return DT_UINT16;
+    case 5122: return DT_INT16;
+    case 5125: return DT_UINT32;
+    default: return DT_FLOAT32;
+  }
+}
+
+function makeTypedArray(
+  module: DracoModule,
+  ptr: number,
+  componentType: number,
+  count: number,
+): ArrayBufferView {
+  const n = count;
+  switch (componentType) {
+    case 5126: return module.HEAPF32.subarray(ptr / 4, ptr / 4 + n).slice();
+    case 5121: return module.HEAPU8.subarray(ptr, ptr + n).slice();
+    case 5120: return new Int8Array(module.HEAPU8.buffer, ptr, n).slice();
+    case 5123: {
+      const view = new Uint16Array(module.HEAPU8.buffer);
+      return view.subarray(ptr / 2, ptr / 2 + n).slice();
+    }
+    case 5122: {
+      const view = new Int16Array(module.HEAPU8.buffer);
+      return view.subarray(ptr / 2, ptr / 2 + n).slice();
+    }
+    case 5125: {
+      const view = new Uint32Array(module.HEAPU8.buffer);
+      return view.subarray(ptr / 4, ptr / 4 + n).slice();
+    }
+    default: return module.HEAPF32.subarray(ptr / 4, ptr / 4 + n).slice();
+  }
+}
+
+// --- Module loading --------------------------------------------------------
+let modulePromise: Promise<DracoModule> | null = null;
+
+/**
+ * Override the WASM binary path for the Draco decoder. Set this before any
+ * Draco-compressed asset is loaded if the default resolution does not work in
+ * your runtime (e.g. a renderer that needs a served URL rather than a path).
+ *
+ * Pass either a URL string (located via fetch) or a pre-loaded ArrayBuffer.
+ */
+export interface DracoWasmConfig {
+  wasmUrl?: string;
+  wasmBinary?: ArrayBuffer;
+}
+
+let dracoWasmConfig: DracoWasmConfig = {};
+
+export function configureDracoWasmPath(config: DracoWasmConfig): void {
+  dracoWasmConfig = config;
+  // Invalidate cached module so next load uses the new config.
+  modulePromise = null;
+}
+
+async function loadDracoModule(): Promise<DracoModule> {
+  if (modulePromise) return modulePromise;
+  modulePromise = (async () => {
+    // Dynamic import of the CommonJS package; Bun/Node interop returns the
+    // module.exports object. In a bundler (Vite) this is converted to ESM.
+    const pkg = (await import("draco3dgltf")) as unknown as {
+      createDecoderModule: DracoModuleFactory;
+    };
+    const factory = pkg.createDecoderModule;
+
+    const config: Parameters<DracoModuleFactory>[0] = {};
+    if (dracoWasmConfig.wasmBinary) {
+      config.wasmBinary = dracoWasmConfig.wasmBinary;
+    } else if (dracoWasmConfig.wasmUrl) {
+      const url = dracoWasmConfig.wasmUrl;
+      config.locateFile = (file: string) => {
+        // Only redirect the .wasm file; the JS glue is already loaded.
+        if (file.endsWith(".wasm")) return url;
+        return file;
+      };
+    }
+    // else: rely on the module's default locateFile (works in Node where the
+    // .wasm sits next to the JS glue; in browsers it needs configuration).
+
+    const mod = (await factory(config)) as unknown as DracoModule;
+    return mod;
+  })();
+  return modulePromise;
+}
+
+// --- Codec -----------------------------------------------------------------
+
+export function createDracoMeshCodec(): MeshCodec {
+  return {
+    uri: "KHR_draco_mesh_compression",
+    async decode(input: MeshCodecInput): Promise<DecodedPrimitive> {
+      const mod = await loadDracoModule();
+
+      const decoderBuffer = new mod.DecoderBuffer();
+      decoderBuffer.Init(input.bufferViewData, input.bufferViewData.length);
+
+      const decoder = new mod.Decoder();
+
+      try {
+        const geomType = decoder.GetEncodedGeometryType(decoderBuffer);
+        const isMesh = geomType === mod.TRIANGULAR_MESH;
+
+        const attributes = new Map<string, ArrayBufferView>();
+        let vertexCount = 0;
+        let indexCount = 0;
+        let indices: ArrayBufferView | undefined;
+
+        if (isMesh) {
+          const mesh = new mod.Mesh();
+          const ok = decoder.DecodeBufferToMesh(decoderBuffer, mesh);
+          if (!ok) throw new Error("Draco: DecodeBufferToMesh failed");
+          vertexCount = mesh.num_points();
+          indexCount = mesh.num_faces() * 3;
+          assertCount("draco vertices", vertexCount, MAX_VERTEX_COUNT);
+          assertCount("draco indices", indexCount, MAX_FACE_COUNT * 3);
+
+          // Decode each attribute by glTF semantic → Draco unique id.
+          for (const [semantic, uniqueId] of Object.entries(input.attributes)) {
+            const attr = decoder.GetMeshAttribute(mesh, uniqueId as number) as any;
+            if (!attr) {
+              continue;
+            }
+            const accessor = input.accessors.get(uniqueId as number);
+            const componentType = accessor?.componentType ?? 5126;
+            const components = accessor ? TYPE_COMPONENTS[accessor.type] ?? 1 : attr.num_components();
+            const totalComponents = vertexCount * components;
+            const bytesPer = COMPONENT_TYPE_BYTES[componentType] ?? 4;
+            if (totalComponents * bytesPer > MAX_DECOMPRESS_SIZE) {
+              throw new RangeError(
+                `Draco: attribute ${semantic} decoded size ${totalComponents * bytesPer} exceeds max ${MAX_DECOMPRESS_SIZE}`,
+              );
+            }
+            const ptr = mod._malloc(totalComponents * bytesPer);
+            try {
+              const dataType = componentTypeToDracoDataType(componentType);
+              const success = decoder.GetAttributeDataArrayForAllPoints(
+                mesh,
+                attr,
+                dataType,
+                totalComponents * bytesPer,
+                ptr,
+              );
+              if (!success) {
+                throw new Error(`Draco: failed to decode attribute ${semantic}`);
+              }
+              attributes.set(semantic, makeTypedArray(mod, ptr, componentType, totalComponents));
+            } finally {
+              mod._free(ptr);
+              attr.delete();
+            }
+          }
+
+          // Decode indices (faces → triangle index buffer).
+          if (input.indices !== undefined) {
+            const accessor = input.accessors.get(input.indices);
+            const componentType = accessor?.componentType ?? 5123;
+            const bytesPer = COMPONENT_TYPE_BYTES[componentType] ?? 2;
+            const ptr = mod._malloc(indexCount * bytesPer);
+            try {
+              // Draco face indices are uint32; we read via GetFaceFromMesh
+              // would be slow per-face. Use the typed-array path: Draco
+              // exposes mesh indices through the same array API when the
+              // "indices" attribute is requested. Fall back to per-face read.
+              const indexArray = componentType === 5125
+                ? new Uint32Array(indexCount)
+                : componentType === 5122
+                  ? new Int16Array(indexCount)
+                  : new Uint16Array(indexCount);
+              const faceView = new Int32Array(mod.HEAPU8.buffer);
+              const facePtr = mod._malloc(12);
+              try {
+                for (let f = 0; f < mesh.num_faces(); f++) {
+                  decoder.GetFaceFromMesh(mesh, f, { ptr: facePtr } as unknown as DracoFace);
+                  const i0 = faceView[facePtr / 4];
+                  const i1 = faceView[facePtr / 4 + 1];
+                  const i2 = faceView[facePtr / 4 + 2];
+                  indexArray[f * 3] = i0;
+                  indexArray[f * 3 + 1] = i1;
+                  indexArray[f * 3 + 2] = i2;
+                }
+              } finally {
+                mod._free(facePtr);
+              }
+              indices = indexArray;
+            } finally {
+              mod._free(ptr);
+            }
+          }
+
+          mesh.delete();
+        } else {
+          // Point cloud (no indices).
+          const pc = new mod.PointCloud();
+          const ok = decoder.DecodeBufferToPointCloud(decoderBuffer, pc);
+          if (!ok) throw new Error("Draco: DecodeBufferToPointCloud failed");
+          vertexCount = pc.num_points();
+
+          for (const [semantic, uniqueId] of Object.entries(input.attributes)) {
+            const attr = decoder.GetMeshAttribute(pc as unknown as DracoMesh, uniqueId as number);
+            if (!attr) continue;
+            const accessor = input.accessors.get(uniqueId as number);
+            const componentType = accessor?.componentType ?? 5126;
+            const components = accessor ? TYPE_COMPONENTS[accessor.type] ?? 1 : attr.num_components();
+            const totalComponents = vertexCount * components;
+            const bytesPer = COMPONENT_TYPE_BYTES[componentType] ?? 4;
+            const ptr = mod._malloc(totalComponents * bytesPer);
+            try {
+              const dataType = componentTypeToDracoDataType(componentType);
+              const success = decoder.GetAttributeDataArrayForAllPoints(
+                pc as unknown as DracoMesh,
+                attr,
+                dataType,
+                totalComponents * bytesPer,
+                ptr,
+              );
+              if (!success) throw new Error(`Draco: failed to decode attribute ${semantic}`);
+              attributes.set(semantic, makeTypedArray(mod, ptr, componentType, totalComponents));
+            } finally {
+              mod._free(ptr);
+              attr.delete();
+            }
+          }
+          pc.delete();
+        }
+
+        return { attributes, indices, vertexCount, indexCount };
+      } finally {
+        decoder.delete();
+        decoderBuffer.delete();
+      }
+    },
+  };
+}
+
+export type { AccessorLike };

package/libraries/models/src/codecs/draco3dgltf.d.ts

@@ -0,0 +1,40 @@
+declare module "draco3dgltf" {
+  interface DracoDecoderModule {
+    decoder: any;
+    Decoder: any;
+    DecoderBuffer: any;
+    Mesh: any;
+    PointCloud: any;
+    AttributeEnum: any;
+    STATUS_OK: number;
+    ERROR: number;
+    INVALID_GEOMETRY_TYPE: number;
+    TRIVIAL: number;
+    POINT_CLOUD: number;
+    TRIANGULAR_MESH: number;
+    INVALID_ATTRIBUTE_TYPE: number;
+    POSITION: number;
+    NORMAL: number;
+    COLOR: number;
+    TEX_COORD: number;
+    GENERIC: number;
+    INVALID_DATA_TYPE: number;
+    DT_FLOAT: number;
+    DT_INT8: number;
+    DT_UINT8: number;
+    DT_INT16: number;
+    DT_UINT16: number;
+    DT_INT32: number;
+    DT_UINT32: number;
+    destroy(obj: any): void;
+  }
+
+  interface DracoModuleOptions {
+    onModuleLoaded?: (module: DracoDecoderModule) => void;
+    locateFile?: (path: string, prefix: string) => string;
+  }
+
+  export function createDecoderModule(options: DracoModuleOptions): Promise<DracoDecoderModule>;
+  export function createEncoderModule(options: DracoModuleOptions): Promise<unknown>;
+  export function setDracoDecoderPath(path: string): void;
+}

package/libraries/models/src/codecs/index.ts

@@ -0,0 +1,22 @@
+// Codec registry + bundled codecs for the glTF asset pipeline.
+export { configureBasisuWasmPath, createBasisuTextureCodec } from "./basisu-codec";
+export type { BasisuWasmConfig } from "./basisu-codec";
+export { configureDracoWasmPath, createDracoMeshCodec } from "./draco-codec";
+export type { DracoWasmConfig } from "./draco-codec";
+export { createMeshoptBufferViewCodec } from "./meshopt-codec";
+export {
+    getDefaultCodecRegistry, GLTFCodecRegistry, registerDefaultCodecs,
+    setDefaultCodecRegistry
+} from "./registry";
+export type {
+    AccessorLike,
+    BufferViewCodec,
+    BufferViewCodecInput,
+    DecodedPrimitive,
+    MeshCodec,
+    MeshCodecInput,
+    TextureCodec,
+    TextureCodecInput,
+    TextureCodecOutput
+} from "./registry";
+