babylonjs-loaders 9.7.0 → 9.9.0

package/babylonjs.loaders.d.ts

@@ -638,6 +638,11 @@ declare namespace BABYLON.GLTF2 {
          * Gets the underlying material
          */
         get material(): PBRMaterial;
+        /**
+         * No-op: PBRMaterial has no deferred finalization.
+         * @param _loader Unused.
+         */
+        finalizeAsync(_loader: BABYLON.GLTF2.GLTFLoader): Promise<void>;
         /**
          * Whether the material should be treated as unlit
          */
@@ -2053,10 +2058,9 @@ declare namespace BABYLON.GLTF2 {
         set geometryCoatNormalTextureScale(value: number);
         /**
          * Finalizes material properties after all loading is complete.
-         * @param signal An AbortSignal that fires when the loader is disposed. Intermediate
-         *   textures are disposed and the method returns early when aborted.
+         * @param loader The glTF loader; `loader._disposed` is polled between texture passes to bail early on dispose.
          */
-        finalizeAsync(signal: AbortSignal): Promise<void>;
+        finalizeAsync(loader: BABYLON.GLTF2.GLTFLoader): Promise<void>;
         private copySurfaceToCoatAsync;
     }
 
@@ -2077,20 +2081,17 @@ declare namespace BABYLON.GLTF2 {
          * Gets the underlying material
          */
         readonly material: Material;
-        /** @deprecated Use finalizeAsync instead. */
-        finalize?(): void;
         /**
          * Finalizes material properties after all loading is complete.
-         * May return a Promise for async work (e.g. GPU texture processing). Any returned
-         * Promise is tracked by the loader and awaited before the COMPLETE state is reached,
-         * so callers can rely on onCompleteObservable for fully processed materials.
+         * May do async work (e.g. GPU texture processing); the returned Promise is tracked
+         * by the loader and awaited before the COMPLETE state is reached, so callers can rely
+         * on onCompleteObservable for fully processed materials.
          *
-         * The loader passes an AbortSignal that is aborted when the loader is disposed.
-         * Implementations should check `signal.aborted` after each await point and, if
-         * aborted, release any intermediate resources and return early.
-         * @param signal An AbortSignal that fires when the loader is disposed mid-flight.
+         * Implementations should check `loader._disposed` between awaits to bail out early
+         * when the loader is disposed mid-flight.
+         * @param loader The glTF loader driving the finalize step.
          */
-        finalizeAsync?(signal: AbortSignal): Promise<void> | void;
+        finalizeAsync(loader: BABYLON.GLTF2.GLTFLoader): Promise<void>;
         /**
          * Whether the material should be treated as unlit
          */
@@ -3025,8 +3026,6 @@ declare namespace BABYLON.GLTF2 {
     export class GLTFLoader implements IGLTFLoader {
         /** @internal */
         readonly _completePromises: Promise<unknown>[];
-        /** AbortController used to cancel in-flight finalizeAsync() calls when dispose() is called. */
-        private _finalizeController;
         /** @internal */
         _assetContainer: Nullable<AssetContainer>;
         /** Storage */
@@ -3039,7 +3038,8 @@ declare namespace BABYLON.GLTF2 {
         _skipStartAnimationStep: boolean;
         private readonly _parent;
         private readonly _extensions;
-        private _disposed;
+        /** @internal */
+        _disposed: boolean;
         private _rootUrl;
         private _fileName;
         private _uniqueRootUrl;
@@ -3051,12 +3051,17 @@ declare namespace BABYLON.GLTF2 {
         private readonly _postSceneLoadActions;
         private readonly _materialAdapterCache;
         private readonly _materialAdapters;
-        /** @internal */
-        _pbrMaterialImpl: Nullable<Readonly<PBRMaterialImplementation>> | false;
         /**
-         * Test if the given material is of the same type as the one used by the loader
+         * Loaded PBR material implementations, keyed by their identifier (e.g. "pbr", "openpbr").
+         * Only populated after the load has started and only for the types actually needed by the asset.
+         * Empty when PBR materials are disabled (skipMaterials).
+         * @internal
+         */
+        readonly _pbrMaterialImpls: Map<string, Readonly<PBRMaterialImplementation>>;
+        /**
+         * Test if the given material is an instance of any PBR material type known to this loader.
          * @param material The material to test
-         * @returns true if the material is of the same type, false otherwise
+         * @returns true if the material matches one of the loaded PBR implementations
          */
         isMatchingMaterialType(material: Nullable<Material>): boolean;
         /**
@@ -3251,6 +3256,21 @@ declare namespace BABYLON.GLTF2 {
          * @internal
          */
         _loadMaterialAsync(context: string, material: BABYLON.GLTF2.Loader.IMaterial, babylonMesh: Nullable<Mesh>, babylonDrawMode: number, assign?: (babylonMaterial: Material) => void): Promise<Material>;
+        /**
+         * Selects the appropriate PBR material implementation for a given glTF material.
+         * Uses OpenPBR when the material carries a "KHR_materials_openpbr" extension or when
+         * the loader-level `useOpenPBR` flag is set; falls back to standard PBR otherwise.
+         * @param material The glTF material
+         * @returns The matching loaded implementation
+         */
+        private _selectImplForGltfMaterial;
+        /**
+         * Returns the default PBR material implementation used when there is no per-material
+         * selection context (e.g. when creating the built-in default material for primitives
+         * that have no glTF material assigned).  Prefers OpenPBR when `useOpenPBR` is set.
+         * @returns The default loaded implementation
+         */
+        private _getDefaultImpl;
         private _createDefaultMaterial;
         /**
          * Creates a Babylon material from a glTF material.
@@ -3406,6 +3426,164 @@ declare namespace BABYLON.GLTF2 {
 
 
 
+}
+declare namespace BABYLON {
+
+
+}
+declare namespace BABYLON.GLTF2.Loader.Extensions {
+        /**
+     * Describes a material class and its corresponding loading adapter.
+     * Passed to TransmissionHelper so it can classify and interact with materials
+     * independently of any specific loader instance.
+     */
+    export interface ITransmissionHelperMaterialImpl {
+        /** The material class constructor */
+        materialClass: typeof Material;
+        /** The adapter class constructor */
+        adapterClass: new (material: Material) => BABYLON.GLTF2.IMaterialLoadingAdapter;
+    }
+    /**
+     * @internal
+     */
+    export interface ITransmissionHelperHolder {
+        /** The transmission helper instance, if created on the scene */
+        _transmissionHelper: TransmissionHelper | undefined;
+    }
+    /**
+     * Options for the TransmissionHelper.
+     */
+    export interface ITransmissionHelperOptions {
+        /**
+         * The size of the render buffers (default: 1024)
+         */
+        renderSize: number;
+        /**
+         * The number of samples to use when generating the render target texture for opaque meshes (default: 4)
+         */
+        samples: number;
+        /**
+         * Scale to apply when selecting the LOD level to sample the refraction texture (default: 1)
+         */
+        lodGenerationScale: number;
+        /**
+         * Offset to apply when selecting the LOD level to sample the refraction texture (default: -4)
+         */
+        lodGenerationOffset: number;
+        /**
+         * Type of the refraction render target texture (default: TEXTURETYPE_HALF_FLOAT)
+         */
+        renderTargetTextureType: number;
+        /**
+         * Defines if the mipmaps for the refraction render target texture must be generated (default: true)
+         */
+        generateMipmaps: boolean;
+        /**
+         * Clear color of the opaque texture. If not provided, use the scene clear color (which will be converted to linear space).
+         * If provided, should be in linear space
+         */
+        clearColor?: Color4;
+    }
+    /**
+     * A class to handle setting up the rendering of opaque objects to be shown through transmissive objects.
+     * @internal
+     */
+    export class TransmissionHelper {
+        /**
+         * Creates the default options for the helper.
+         * @returns the default options
+         */
+        private static _GetDefaultOptions;
+        private readonly _scene;
+        private _options;
+        private _opaqueRenderTarget;
+        private _opaqueMeshesCache;
+        private _transparentMeshesCache;
+        private _materialObservers;
+        private readonly _materialImpls;
+        private readonly _adapterCache;
+        /**
+         * This observable will be notified with any error during the creation of the environment,
+         * mainly texture creation errors.
+         */
+        onErrorObservable: Observable<{
+            message?: string;
+            exception?: any;
+        }>;
+        private _translucentMaterialIndices;
+        private _opaqueOnlySubMeshes;
+        private _savedSubMeshes;
+        /**
+         * constructor
+         * @param options Defines the options we want to customize the helper
+         * @param scene The scene to add the material to
+         */
+        constructor(options: Partial<ITransmissionHelperOptions>, scene: Scene);
+        /**
+         * Registers a material implementation with the helper so it can classify and create
+         * adapters for materials of that type. Safe to call multiple times with the same
+         * implementation — duplicates are ignored.
+         * @param impl The material implementation to register
+         */
+        addMaterialImpl(impl: ITransmissionHelperMaterialImpl): void;
+        /**
+         * Updates the helper options.
+         * @param options the options to update
+         */
+        updateOptions(options: Partial<ITransmissionHelperOptions>): void;
+        /**
+         * @returns the opaque render target texture or null if not available.
+         */
+        getOpaqueTarget(): Nullable<Texture>;
+        private _getOrCreateAdapter;
+        /**
+         * Classify a mesh's materials as transparent, opaque, or mixed.
+         * Sets the refraction background texture on any translucent materials found.
+         * For mixed MultiMaterial meshes, populates _translucentMaterialIndices so
+         * their translucent submeshes can be excluded from the opaque render target.
+         * @param mesh - The mesh to classify
+         * @returns 'transparent' if all materials are translucent, 'opaque' if none are, 'mixed' if both
+         */
+        private _classifyMeshMaterials;
+        /**
+         * Rebuild the cached opaque-only submesh array for a mixed mesh.
+         * Called when classification changes so the per-frame swap is allocation-free.
+         * @param mesh - The mesh to rebuild for
+         * @param translucentIndices - Set of materialIndex values that are translucent
+         */
+        private _rebuildOpaqueOnlySubMeshes;
+        private _addMesh;
+        private _removeMesh;
+        private _parseScene;
+        private _onMeshMaterialChanged;
+        /**
+         * @internal
+         * Check if the opaque render target has not been disposed and can still be used.
+         * @returns
+         */
+        _isRenderTargetValid(): boolean;
+        /**
+         * @internal
+         * Setup the render targets according to the specified options.
+         */
+        _setupRenderTargets(): void;
+        /**
+         * Dispose all the elements created by the Helper.
+         */
+        dispose(): void;
+    }
+    /**
+     * Ensures a TransmissionHelper exists on the scene and has all of the loader's material
+     * implementations registered with it. Creates the helper if one does not yet exist on the
+     * scene, and recreates its render target if it has been disposed. Does nothing when the
+     * loader's parent has `dontUseTransmissionHelper` set.
+     * @param loader The glTF loader whose material implementations should be registered
+     * @param babylonMaterial A material belonging to the scene where the helper should live
+     */
+    export function ensureTransmissionHelper(loader: BABYLON.GLTF2.GLTFLoader, babylonMaterial: Material): void;
+
+
+
 }
 declare namespace BABYLON {