babylonjs-loaders 9.25.0 → 9.26.0

package/babylonjs.loaders.d.ts

@@ -8878,6 +8878,408 @@ declare namespace BABYLON.GLTF1 {
 }
 declare namespace BABYLON {
 
+    export interface WorkerAsset {
+        bytes: Uint8Array;
+        fileName: string;
+        files?: Record<string, Uint8Array>;
+        resolveByFileName: boolean;
+        glueUrl?: string;
+        wasmUrl?: string;
+        dataUrl?: string;
+    }
+    export interface ExtractRequest {
+        type: "extract";
+        requestId: number;
+        asset: WorkerAsset;
+    }
+    export interface WorkerTimings {
+        totalMs: number;
+        stageOpenMs: number;
+        stageReadMs: number;
+        preparationMs: number;
+        packingMs: number;
+        heapCopyMs: number;
+    }
+    export interface WorkerStatistics {
+        nodes: number;
+        meshes: number;
+        analyticPrimitives: number;
+        instances: number;
+        materials: number;
+        vertices: number;
+        triangles: number;
+        commandBytes: number;
+        dataBytes: number;
+    }
+    export type WorkerResponse = {
+        type: "progress";
+        requestId: number;
+        progress: USDLoadProgress;
+    } | {
+        type: "log";
+        requestId: number;
+        level: number;
+        message: string;
+    } | {
+        type: "result";
+        requestId: number;
+        commands: ArrayBuffer;
+        data: ArrayBuffer;
+        timings: WorkerTimings;
+        statistics: WorkerStatistics;
+        missingAssets: string[];
+    } | {
+        type: "error";
+        requestId: number;
+        message: string;
+        stack?: string;
+    };
+
+
+    export interface MaterializationResult {
+        container: AbstractAssetContainer & {
+            dispose(): void;
+        };
+        materializeMs: number;
+    }
+    export function materializeCommandBuffers(scene: Scene, commandBuffer: ArrayBuffer, dataBuffer: ArrayBuffer, addToScene: boolean, signal?: AbortSignal): Promise<MaterializationResult>;
+
+
+    /**
+     * Binary input accepted for supporting USD layers and assets.
+     */
+    export type USDBinaryInput = ArrayBuffer | ArrayBufferView;
+    /**
+     * Virtual files supplied alongside the root USD layer, keyed by their path relative to the
+     * root layer.
+     */
+    export type USDVirtualFiles = Readonly<Record<string, USDBinaryInput>>;
+    /**
+     * Progress phases reported by the USD worker and Babylon materializer.
+     */
+    export interface USDLoadProgress {
+        /**
+         * Current importer phase.
+         */
+        phase: "initializing" | "staging" | "extracting" | "materializing";
+        /**
+         * Human-readable phase description.
+         */
+        message: string;
+    }
+    /**
+     * Options for the OpenUSD scene loader.
+     */
+    export interface USDFileLoaderOptions {
+        /**
+         * Virtual path used to stage the root layer. Set this when supporting files need
+         * to resolve relative to a directory hierarchy.
+         */
+        rootFileName?: string;
+        /**
+         * Supporting layers, payloads, and textures keyed by virtual path in the same
+         * virtual file system as `rootFileName`.
+         */
+        files?: USDVirtualFiles;
+        /**
+         * Enables conservative file-name fallback for unresolved absolute references.
+         * Defaults to true.
+         */
+        resolveByFileName?: boolean;
+        /**
+         * URL of the module worker. Defaults to the protocol-versioned worker hosted on the Babylon.js CDN.
+         */
+        workerUrl?: string | URL;
+        /**
+         * URL of the generated Emscripten JavaScript module.
+         */
+        glueUrl?: string;
+        /**
+         * URL of the OpenUSD WebAssembly binary.
+         */
+        wasmUrl?: string;
+        /**
+         * URL of the OpenUSD preloaded resource bundle.
+         */
+        dataUrl?: string;
+        /**
+         * Called when the importer moves to a new processing phase.
+         */
+        onProgress?: (progress: USDLoadProgress) => void;
+        /**
+         * Called for OpenUSD diagnostic messages.
+         */
+        onLog?: (level: "info" | "warning" | "error", message: string) => void;
+        /**
+         * Called after extraction and Babylon.js object creation complete.
+         */
+        onComplete?: (diagnostics: USDImportDiagnostics) => void;
+    }
+    /**
+     * Timing data measured by the OpenUSD worker and Babylon materializer.
+     */
+    export interface USDImportTimings {
+        /** Total extraction time, including the final Wasm heap copy. */
+        totalMs: number;
+        /** Time spent opening and composing the USD stage. */
+        stageOpenMs: number;
+        /** Time spent traversing the composed stage. */
+        stageReadMs: number;
+        /** Time spent preparing renderable vertex streams. */
+        preparationMs: number;
+        /** Time spent packing the command and raw-data buffers. */
+        packingMs: number;
+        /** Time spent copying command and data buffers from the Wasm heap. */
+        heapCopyMs: number;
+        /** Time spent creating Babylon.js objects. */
+        materializeMs: number;
+    }
+    /**
+     * Statistics reported for an imported USD stage.
+     */
+    export interface USDImportStatistics {
+        /** Number of transform nodes extracted from the composed stage. */
+        nodes: number;
+        /** Number of polygonal `UsdGeomMesh` sources. */
+        meshes: number;
+        /** Number of analytic cube, sphere, cylinder, and cone sources. */
+        analyticPrimitives: number;
+        /** Number of native Babylon instances created from shared USD geometry. */
+        instances: number;
+        /** Number of authored USD materials translated. */
+        materials: number;
+        /** Number of unique vertices in polygonal source meshes. */
+        vertices: number;
+        /** Number of unique triangles in polygonal source meshes. */
+        triangles: number;
+        /** Size of the command buffer in bytes. */
+        commandBytes: number;
+        /** Size of the raw-data buffer in bytes. */
+        dataBytes: number;
+    }
+    /**
+     * Diagnostics reported after a USD import completes.
+     */
+    export interface USDImportDiagnostics {
+        /** Timing data for extraction and Babylon.js object creation. */
+        timings: USDImportTimings;
+        /** Counts and buffer sizes reported by the OpenUSD extractor. */
+        statistics: USDImportStatistics;
+        /** Asset references OpenUSD could not resolve from the supplied virtual files. */
+        missingAssets: readonly string[];
+    }
+
+
+        interface SceneLoaderPluginOptions {
+            /**
+             * Defines options for the USD loader.
+             */
+            [USDFileLoaderMetadata.name]: Partial<USDFileLoaderOptions>;
+        }
+
+
+    /** This file must only contain pure code and pure imports */
+    /**
+     * OpenUSD scene loader backed by a WebAssembly command-buffer extractor.
+     */
+    export class USDFileLoader implements ISceneLoaderPluginAsync, ISceneLoaderPluginFactory {
+        /**
+         * Default URLs for the prebuilt OpenUSD importer assets.
+         */
+        static DefaultConfiguration: {
+            glueUrl: string;
+            wasmUrl: string;
+            dataUrl: string;
+            workerUrl: string;
+        };
+        /**
+         * Defines the name of the plugin.
+         */
+        readonly name: "usd";
+        /**
+         * Defines the extensions the plugin can load.
+         */
+        readonly extensions: {
+            readonly ".usd": {
+                readonly isBinary: true;
+            };
+            readonly ".usda": {
+                readonly isBinary: true;
+            };
+            readonly ".usdc": {
+                readonly isBinary: true;
+            };
+            readonly ".usdz": {
+                readonly isBinary: true;
+            };
+        };
+        private readonly _options;
+        private _worker;
+        private _workerUrl;
+        private _workerBlobUrl;
+        private _nextRequestId;
+        private readonly _pending;
+        private readonly _activeLoads;
+        /**
+         * Creates a USD loader.
+         * @param options Options controlling worker assets, supporting files, and diagnostics.
+         */
+        constructor(options?: Partial<USDFileLoaderOptions>);
+        /**
+         * Creates a configured plugin instance for a SceneLoader operation.
+         * @param options SceneLoader plugin options.
+         * @returns The configured USD loader.
+         */
+        createPlugin(options: SceneLoaderPluginOptions): ISceneLoaderPluginAsync;
+        /**
+         * Imports all objects from a USD stage into a scene.
+         * @param _meshesNames Mesh name filtering is not currently supported.
+         * @param scene The scene receiving the imported objects.
+         * @param data The USD, USDA, USDC, or USDZ bytes.
+         * @param rootUrl The source root URL.
+         * @param onProgress SceneLoader progress callback.
+         * @param fileName Name of the root USD layer.
+         * @returns The imported Babylon.js objects.
+         */
+        importMeshAsync(_meshesNames: string | readonly string[] | null | undefined, scene: Scene, data: unknown, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): Promise<ISceneLoaderAsyncResult>;
+        /**
+         * Loads a USD stage into a scene.
+         * @param scene The scene receiving the imported objects.
+         * @param data The USD, USDA, USDC, or USDZ bytes.
+         * @param rootUrl The source root URL.
+         * @param onProgress SceneLoader progress callback.
+         * @param fileName Name of the root USD layer.
+         */
+        loadAsync(scene: Scene, data: unknown, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): Promise<void>;
+        /**
+         * Loads a USD stage into an asset container.
+         * @param scene The scene used to create imported objects.
+         * @param data The USD, USDA, USDC, or USDZ bytes.
+         * @param rootUrl The source root URL.
+         * @param onProgress SceneLoader progress callback.
+         * @param fileName Name of the root USD layer.
+         * @returns The populated asset container.
+         */
+        loadAssetContainerAsync(scene: Scene, data: unknown, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): Promise<AssetContainer>;
+        /**
+         * Releases the worker and rejects pending loads.
+         */
+        dispose(): void;
+        private _loadAsync;
+        private _getWorker;
+        private _terminateWorker;
+    }
+    /** @internal */
+    export function _RegisterUSDLoaderDependencies(): void;
+    /**
+     * Registers the USD scene loader plugin and its Babylon.js runtime dependencies.
+     * Safe to call multiple times; only the first call has an effect.
+     */
+    export function RegisterUSDFileLoader(): void;
+
+
+    /**
+     * Defines the USD loader plugin metadata.
+     */
+    export var USDFileLoaderMetadata: {
+        readonly name: "usd";
+        readonly extensions: {
+            readonly ".usd": {
+                readonly isBinary: true;
+            };
+            readonly ".usda": {
+                readonly isBinary: true;
+            };
+            readonly ".usdc": {
+                readonly isBinary: true;
+            };
+            readonly ".usdz": {
+                readonly isBinary: true;
+            };
+        };
+    };
+
+
+    /**
+     * Re-exports the pure implementation and applies the runtime registration side effect.
+     * Import "./usdFileLoader.pure" for tree-shakeable, side-effect-free usage.
+     */
+
+
+    export const COMMAND_MAGIC = 1111774037;
+    export const PROTOCOL_VERSION = 4;
+    export const MISSING_OFFSET = 4294967295;
+    export enum Command {
+        Scene = 1,
+        Texture = 2,
+        Material = 3,
+        TransformNode = 4,
+        Skeleton = 5,
+        Geometry = 6,
+        Mesh = 7,
+        Instance = 8,
+        Animation = 9,
+        AnalyticPrimitive = 10
+    }
+    export enum AnalyticPrimitiveType {
+        Cube = 0,
+        Sphere = 1,
+        Cylinder = 2,
+        Cone = 3
+    }
+    export enum PrimitiveAxis {
+        X = 0,
+        Y = 1,
+        Z = 2
+    }
+    export enum AnimationTarget {
+        Node = 0,
+        Bone = 1
+    }
+    export enum AnimationProperty {
+        Position = 0,
+        RotationQuaternion = 1,
+        Scaling = 2,
+        Matrix = 3
+    }
+    export enum MaterialFlags {
+        DoubleSided = 1,
+        Unlit = 2,
+        AlphaBlend = 4
+    }
+    export enum MeshFlags {
+        DoubleSided = 1,
+        LeftHanded = 2
+    }
+    export enum GeometryFlags {
+        Normals = 1,
+        Tangents = 2,
+        Uv0 = 4,
+        Colors = 8,
+        Skin0 = 16,
+        Skin1 = 32
+    }
+    export interface CommandRecord {
+        opcode: Command;
+        flags: number;
+        payloadOffset: number;
+        payloadLength: number;
+    }
+    export function readCommands(buffer: ArrayBuffer): CommandRecord[];
+    export class PayloadReader {
+        #private;
+        offset: number;
+        constructor(buffer: ArrayBuffer, offset: number, length: number);
+        u32(): number;
+        f32(): number;
+    }
+
+
+    /** Pure barrel — re-exports only side-effect-free modules */
+
+
+
+
         interface SceneLoaderPluginOptions {
             /**
              * Defines options for the stl loader.
@@ -9846,6 +10248,18 @@ declare namespace BABYLON {
      * Selects which LOD value drives the {@link GaussianSplattingStream} debug wireframe colors.
      */
     export type GaussianSplattingStreamDebugLodSource = "optimal" | "current";
+    /**
+     * Immutable metadata-resolution state for a stream's total number of finest-LOD splats.
+     * @experimental
+     */
+    export type GaussianSplattingStreamLod0SplatCount = Readonly<{
+        status: "pending";
+    }> | Readonly<{
+        status: "available";
+        count: number;
+    }> | Readonly<{
+        status: "unavailable";
+    }>;
     /**
      * Options for {@link GaussianSplattingStream}.
      */
@@ -9965,6 +10379,7 @@ declare namespace BABYLON {
         private readonly _rootUrl;
         private readonly _streamOptions;
         private readonly _leafNodes;
+        private _lod0SplatCount;
         private _lodBaseDistance;
         private _lodMultiplier;
         private _lodBehindPenalty;
@@ -10129,6 +10544,19 @@ declare namespace BABYLON {
          * @experimental
          */
         get effectiveSplatBudget(): number;
+        /**
+         * The resolved maximum number of splats kept resident in the work buffer. This combines
+         * {@link IGaussianSplattingStreamOptions.maxResidentSplats} and {@link IGaussianSplattingStreamOptions.memoryBudgetMb},
+         * taking the smaller limit when both are configured. `0` means the resident budget is disabled.
+         * @experimental
+         */
+        get residentSplatBudget(): number;
+        /**
+         * The total number of splats represented by valid level-0 leaf entries. This remains pending while source
+         * metadata is loading and is unavailable when no applicable level-0 entries exist or required metadata fails.
+         * @experimental
+         */
+        get lod0SplatCount(): GaussianSplattingStreamLod0SplatCount;
         /**
          * Resolves the raw {@link splatBudget} option to a concrete cap: `undefined` ⇒ 0 (disabled), `"auto"` ⇒ a
          * device-tiered default, a positive number ⇒ itself (floored).
@@ -10298,6 +10726,11 @@ declare namespace BABYLON {
          * @returns sorted unique file indices
          */
         private _collectAllFileIds;
+        /**
+         * Settles the level-0 diagnostic from normalized renderable leaf entries after their source metadata resolves.
+         * A file may back several leaf ranges, so its source count is deliberately not used in the total.
+         */
+        private _resolveLod0SplatCount;
         /**
          * Fetches the environment bundle and every referenced file's metadata to learn splat counts, caching
          * each file's parsed metadata for the later on-demand decode. Metadata fetches run in parallel.