@loaders.gl/scene 5.0.0-beta.1 → 5.0.0-beta.2

package/src/draco/lib/draco-library-loader.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+
+import {
+  isBrowser,
+  isWorker,
+  loadLibrary as loadCoreLibrary,
+  type LoadLibraryOptions
+} from '@loaders.gl/core/worker-utils';
+
+export {isBrowser, type LoadLibraryOptions};
+
+/** Resolves local Draco assets inside scene without changing core's format-neutral library paths. */
+export async function loadLibrary(
+  libraryUrl: string,
+  moduleName: string | null = null,
+  options: LoadLibraryOptions = {},
+  libraryName: string | null = null,
+  moduleLibraryName: string | null = null
+): Promise<unknown> {
+  if (
+    isBrowser &&
+    options.useLocalLibraries &&
+    !options.CDN &&
+    libraryName &&
+    options.modules?.[libraryName] === undefined
+  ) {
+    const directory = isWorker ? './libs' : `modules/${moduleName}/dist/libs`;
+    options = {
+      ...options,
+      modules: {
+        [libraryName]: `${directory}/${libraryName}`,
+        ...(moduleLibraryName ? {[moduleLibraryName]: `${directory}/${moduleLibraryName}`} : {}),
+        ...options.modules
+      }
+    };
+  }
+  return await loadCoreLibrary(libraryUrl, moduleName, options, libraryName, moduleLibraryName);
+}

package/src/draco/lib/draco-module-loader.ts

@@ -0,0 +1,370 @@
+// SPDX-License-Identifier: MIT
+
+// Dynamic DRACO module loading inspired by THREE.DRACOLoader
+// https://github.com/mrdoob/three.js/blob/dev/examples/jsm/loaders/DRACOLoader.js
+// by Don McCurdy / https://www.donmccurdy.com / MIT license
+
+import {initializeWasmModule} from '@loaders.gl/core/loader-utils';
+import {isBrowser, loadLibrary, type LoadLibraryOptions} from './draco-library-loader';
+import type {Draco3D} from '../draco3d/draco3d-types';
+
+import {DRACO_EXTERNAL_LIBRARIES, DRACO_EXTERNAL_LIBRARY_URLS} from '../draco-libraries';
+export {DRACO_EXTERNAL_LIBRARIES, DRACO_EXTERNAL_LIBRARY_URLS} from '../draco-libraries';
+
+/** Initialized Draco module returned to the parser or builder. */
+export type LoadedDracoModule = {draco: Draco3D};
+
+/** Draco decoder build selected for general data or glTF-compatible bitstreams. */
+export type DracoDecoderProfile = 'full' | 'gltf';
+
+/** Subset of the `draco3d` npm package accepted through `options.modules`. */
+export type Draco3DModule = {
+  /** Creates an initialized decoder module. */
+  createDecoderModule?: (options?: Record<string, unknown>) => Promise<Draco3D>;
+  /** Creates an initialized encoder module. */
+  createEncoderModule?: (options?: Record<string, unknown>) => Promise<Draco3D>;
+};
+
+type DracoDecoderModule = Required<Pick<Draco3DModule, 'createDecoderModule'>>;
+type DracoEncoderModule = Required<Pick<Draco3DModule, 'createEncoderModule'>>;
+
+type DracoModuleInitializerOptions = {
+  /** Optional preloaded WASM bytes. */
+  wasmBinary?: ArrayBuffer;
+  /** Reports an initialized Emscripten module. */
+  onModuleLoaded?: (draco: Draco3D) => void;
+};
+
+type DracoModuleInitializer = (
+  options: DracoModuleInitializerOptions
+) => Promise<Draco3D> | undefined;
+
+type DracoGlobal = typeof globalThis & {
+  DracoDecoderModule?: DracoModuleInitializer;
+  DracoEncoderModule?: DracoModuleInitializer;
+};
+
+const libraryDecoderPromises = new Map<string, Promise<LoadedDracoModule>>();
+const libraryEncoderPromises = new Map<string, Promise<LoadedDracoModule>>();
+const injectedDecoderPromises = new WeakMap<DracoDecoderModule, Promise<LoadedDracoModule>>();
+const injectedEncoderPromises = new WeakMap<DracoEncoderModule, Promise<LoadedDracoModule>>();
+
+/** Loads a Draco decoder from either an injected `draco3d` package or external libraries. */
+export async function loadDracoDecoderModule(
+  options: LoadLibraryOptions = {},
+  type: 'wasm' | 'js',
+  profile: DracoDecoderProfile = 'full'
+): Promise<LoadedDracoModule> {
+  const draco3DModule = getInjectedDraco3DModule(options);
+  if (draco3DModule) {
+    return await loadDracoDecoderModuleFromDraco3D(draco3DModule);
+  }
+
+  return await loadDracoDecoderModuleFromLibrary(
+    options,
+    type === 'js' ? 'javascript' : type,
+    profile
+  );
+}
+
+/** Loads a Draco decoder from external WASM or JavaScript fallback libraries. */
+export async function loadDracoDecoderModuleFromLibrary(
+  options: LoadLibraryOptions = {},
+  type: 'wasm' | 'javascript',
+  profile: DracoDecoderProfile = 'full'
+): Promise<LoadedDracoModule> {
+  const cacheKey = getLibraryCacheKey(`${type}:${profile}`, options);
+  let decoderPromise = libraryDecoderPromises.get(cacheKey);
+  if (!decoderPromise) {
+    decoderPromise = loadDracoDecoderWithFallback(options, type, profile);
+    libraryDecoderPromises.set(cacheKey, decoderPromise);
+  }
+  return await decoderPromise;
+}
+
+/** Loads a decoder from an injected `draco3d` npm package. */
+export async function loadDracoDecoderModuleFromDraco3D(
+  draco3DModule: unknown
+): Promise<LoadedDracoModule> {
+  const typedDraco3DModule = validateDracoDecoderModule(draco3DModule);
+  let decoderPromise = injectedDecoderPromises.get(typedDraco3DModule);
+  if (!decoderPromise) {
+    decoderPromise = initializeWasmModule(
+      () => typedDraco3DModule.createDecoderModule({}),
+      draco => ({draco})
+    );
+    injectedDecoderPromises.set(typedDraco3DModule, decoderPromise);
+  }
+  return await decoderPromise;
+}
+
+/** Loads a Draco encoder from an injected `draco3d` package or external WASM libraries. */
+export async function loadDracoEncoderModule(
+  options: LoadLibraryOptions = {}
+): Promise<LoadedDracoModule> {
+  const draco3DModule = getInjectedDraco3DModule(options);
+  if (draco3DModule) {
+    const typedDraco3DModule = validateDracoEncoderModule(draco3DModule);
+    let encoderPromise = injectedEncoderPromises.get(typedDraco3DModule);
+    if (!encoderPromise) {
+      encoderPromise = initializeWasmModule(
+        () => typedDraco3DModule.createEncoderModule({}),
+        draco => ({draco})
+      );
+      injectedEncoderPromises.set(typedDraco3DModule, encoderPromise);
+    }
+    return await encoderPromise;
+  }
+
+  const cacheKey = getLibraryCacheKey('encoder', options);
+  let encoderPromise = libraryEncoderPromises.get(cacheKey);
+  if (!encoderPromise) {
+    encoderPromise = loadDracoEncoder(options);
+    libraryEncoderPromises.set(cacheKey, encoderPromise);
+  }
+  return await encoderPromise;
+}
+
+/** Loads the selected decoder and retries with the JavaScript backend after a WASM failure. */
+async function loadDracoDecoderWithFallback(
+  options: LoadLibraryOptions,
+  type: 'wasm' | 'javascript',
+  profile: DracoDecoderProfile
+): Promise<LoadedDracoModule> {
+  try {
+    return await loadDracoDecoder(options, type, profile);
+  } catch (wasmError) {
+    if (type === 'javascript') {
+      throw wasmError;
+    }
+    try {
+      return await loadDracoDecoder(options, 'javascript', 'full');
+    } catch (javascriptError) {
+      throw new AggregateError(
+        [wasmError, javascriptError],
+        'Draco decoder could not load either the WebAssembly or JavaScript backend'
+      );
+    }
+  }
+}
+
+let decoderInitializationQueue = Promise.resolve();
+
+/** Loads and initializes one external Draco decoder backend. */
+async function loadDracoDecoder(
+  options: LoadLibraryOptions,
+  type: 'wasm' | 'javascript',
+  profile: DracoDecoderProfile
+): Promise<LoadedDracoModule> {
+  const initialization = decoderInitializationQueue.then(() =>
+    loadDracoDecoderInternal(options, type, profile)
+  );
+  decoderInitializationQueue = initialization.then(
+    () => undefined,
+    () => undefined
+  );
+  return await initialization;
+}
+
+/** Performs decoder loading after preceding global initializers have completed. */
+async function loadDracoDecoderInternal(
+  options: LoadLibraryOptions,
+  type: 'wasm' | 'javascript',
+  profile: DracoDecoderProfile
+): Promise<LoadedDracoModule> {
+  if (type === 'javascript') {
+    let decoderLibrary: unknown;
+    try {
+      decoderLibrary = await loadLibrary(
+        DRACO_EXTERNAL_LIBRARY_URLS[DRACO_EXTERNAL_LIBRARIES.FALLBACK_DECODER],
+        'scene',
+        options,
+        DRACO_EXTERNAL_LIBRARIES.FALLBACK_DECODER,
+        'draco_decoder.mjs'
+      );
+    } catch (error) {
+      if (isBrowser || options.useLocalLibraries) {
+        throw error;
+      }
+      decoderLibrary = await loadLibrary(
+        DRACO_EXTERNAL_LIBRARY_URLS[DRACO_EXTERNAL_LIBRARIES.FALLBACK_DECODER],
+        'scene',
+        {...options, useLocalLibraries: true},
+        DRACO_EXTERNAL_LIBRARIES.FALLBACK_DECODER,
+        'draco_decoder.mjs'
+      );
+    }
+    const decoderInitializer =
+      getLibraryExport(decoderLibrary, 'DracoDecoderModule') ||
+      (globalThis as DracoGlobal).DracoDecoderModule;
+    return await initializeDracoModule(decoderInitializer);
+  }
+
+  let decoderLibrary: unknown;
+  let wasmBinary: ArrayBuffer;
+  try {
+    [decoderLibrary, wasmBinary] = await loadDecoderWasmAssets(options, profile);
+  } catch (error) {
+    if (isBrowser || options.useLocalLibraries) {
+      throw error;
+    }
+    [decoderLibrary, wasmBinary] = await loadDecoderWasmAssets(
+      {...options, useLocalLibraries: true},
+      profile
+    );
+  }
+  const decoderInitializer =
+    getLibraryExport(decoderLibrary, 'DracoDecoderModule') ||
+    (globalThis as DracoGlobal).DracoDecoderModule;
+  return await initializeDracoModule(decoderInitializer, wasmBinary);
+}
+
+/** Loads the decoder wrapper and WASM binary concurrently. */
+async function loadDecoderWasmAssets(
+  options: LoadLibraryOptions,
+  profile: DracoDecoderProfile
+): Promise<[unknown, ArrayBuffer]> {
+  const decoderLibrary =
+    profile === 'gltf' ? DRACO_EXTERNAL_LIBRARIES.GLTF_DECODER : DRACO_EXTERNAL_LIBRARIES.DECODER;
+  const decoderWasm =
+    profile === 'gltf'
+      ? DRACO_EXTERNAL_LIBRARIES.GLTF_DECODER_WASM
+      : DRACO_EXTERNAL_LIBRARIES.DECODER_WASM;
+  return await Promise.all([
+    loadLibrary(
+      DRACO_EXTERNAL_LIBRARY_URLS[decoderLibrary],
+      'scene',
+      options,
+      decoderLibrary,
+      profile === 'gltf' ? 'draco_wasm_wrapper_gltf.mjs' : 'draco_wasm_wrapper.mjs'
+    ),
+    loadLibrary(
+      DRACO_EXTERNAL_LIBRARY_URLS[decoderWasm],
+      'scene',
+      options,
+      decoderWasm
+    ) as Promise<ArrayBuffer>
+  ]);
+}
+
+/** Loads and initializes the external Draco WASM encoder. */
+async function loadDracoEncoder(options: LoadLibraryOptions): Promise<LoadedDracoModule> {
+  let encoderLibrary: unknown;
+  let wasmBinary: ArrayBuffer;
+  try {
+    [encoderLibrary, wasmBinary] = await loadEncoderWasmAssets(options);
+  } catch (error) {
+    if (isBrowser || options.useLocalLibraries) {
+      throw error;
+    }
+    [encoderLibrary, wasmBinary] = await loadEncoderWasmAssets({
+      ...options,
+      useLocalLibraries: true
+    });
+  }
+  const encoderInitializer =
+    getLibraryExport(encoderLibrary, 'DracoEncoderModule') ||
+    (globalThis as DracoGlobal).DracoEncoderModule;
+  return await initializeDracoModule(encoderInitializer, wasmBinary);
+}
+
+/** Loads the encoder wrapper and WASM binary concurrently. */
+async function loadEncoderWasmAssets(options: LoadLibraryOptions): Promise<[unknown, ArrayBuffer]> {
+  return await Promise.all([
+    loadLibrary(
+      DRACO_EXTERNAL_LIBRARY_URLS[DRACO_EXTERNAL_LIBRARIES.ENCODER],
+      'scene',
+      options,
+      DRACO_EXTERNAL_LIBRARIES.ENCODER,
+      'draco_encoder.mjs'
+    ),
+    loadLibrary(
+      DRACO_EXTERNAL_LIBRARY_URLS[DRACO_EXTERNAL_LIBRARIES.ENCODER_WASM],
+      'scene',
+      options,
+      DRACO_EXTERNAL_LIBRARIES.ENCODER_WASM
+    ) as Promise<ArrayBuffer>
+  ]);
+}
+
+/** Initializes an Emscripten Draco factory that may use callbacks, promises, or both. */
+function initializeDracoModule(
+  initializer: DracoModuleInitializer | undefined,
+  wasmBinary?: ArrayBuffer
+): Promise<LoadedDracoModule> {
+  if (typeof initializer !== 'function') {
+    throw new Error('Draco module initializer could not be loaded');
+  }
+
+  return initializeWasmModule(
+    onInitialized =>
+      initializer({
+        ...(wasmBinary ? {wasmBinary} : {}),
+        onModuleLoaded: onInitialized
+      }),
+    (draco: Draco3D) => ({draco})
+  );
+}
+
+/** Resolves a Draco initializer from a direct, named, or default library export. */
+function getLibraryExport(
+  library: unknown,
+  exportName: 'DracoDecoderModule' | 'DracoEncoderModule'
+): DracoModuleInitializer | undefined {
+  if (typeof library === 'function') {
+    return library as DracoModuleInitializer;
+  }
+  if (library && typeof library === 'object') {
+    const exports = library as Record<string, unknown>;
+    const exportedInitializer = exports[exportName] || exports.default;
+    return typeof exportedInitializer === 'function'
+      ? (exportedInitializer as DracoModuleInitializer)
+      : undefined;
+  }
+  return undefined;
+}
+
+/** Returns and validates the optional injected `draco3d` package reference. */
+function getInjectedDraco3DModule(options: LoadLibraryOptions): Draco3DModule | undefined {
+  const module = options.modules?.draco3d;
+  if (!module) {
+    return undefined;
+  }
+  if (typeof module !== 'object' && typeof module !== 'function') {
+    throw new Error('Invalid draco3d module');
+  }
+  return module as Draco3DModule;
+}
+
+/** Narrows an injected package to the decoder factory interface. */
+function validateDracoDecoderModule(module: unknown): DracoDecoderModule {
+  const typedModule = module as Draco3DModule;
+  if (typeof typedModule?.createDecoderModule !== 'function') {
+    throw new Error('Invalid draco3d decoder module');
+  }
+  return typedModule as DracoDecoderModule;
+}
+
+/** Narrows an injected package to the encoder factory interface. */
+function validateDracoEncoderModule(module: unknown): DracoEncoderModule {
+  const typedModule = module as Draco3DModule;
+  if (typeof typedModule?.createEncoderModule !== 'function') {
+    throw new Error('Invalid draco3d encoder module');
+  }
+  return typedModule as DracoEncoderModule;
+}
+
+/** Builds a stable cache key from the backend and external-library configuration. */
+function getLibraryCacheKey(type: string, options: LoadLibraryOptions): string {
+  const libraryOverrides = Object.entries(options.modules || {})
+    .filter(([name]) => name !== 'draco3d')
+    .map(([name, value]) => `${name}:${String(value)}`)
+    .sort()
+    .join('|');
+  return [
+    type,
+    options.useLocalLibraries ? 'local' : 'remote',
+    options.CDN || '',
+    libraryOverrides
+  ].join('|');
+}