Make SceneLoader module level functions PascalCase and add GetRegiste…

…redSceneLoaderPluginMetadata (#16154)
BabylonJS · Feb 7, 2025 · 42dcaa2 · 42dcaa2
1 parent 7aedc45
commit 42dcaa2
Show file tree

Hide file tree

Showing 7 changed files with 113 additions and 26 deletions.
diff --git a/packages/dev/core/src/Loading/sceneLoader.ts b/packages/dev/core/src/Loading/sceneLoader.ts
@@ -1,6 +1,6 @@
 import { Tools } from "../Misc/tools";
 import { Observable } from "../Misc/observable";
-import type { Nullable } from "../types";
+import type { DeepImmutable, Nullable } from "../types";
 import { Scene } from "../scene";
 import { EngineStore } from "../Engines/engineStore";
 import type { AbstractMesh } from "../Meshes/abstractMesh";
@@ -781,7 +781,7 @@ function _getFileInfo(rootUrl: string, sceneSource: SceneSource): Nullable<IFile
  * Adds a new plugin to the list of registered plugins
  * @param plugin defines the plugin to add
  */
-export function registerSceneLoaderPlugin(plugin: ISceneLoaderPlugin | ISceneLoaderPluginAsync | ISceneLoaderPluginFactory): void {
+export function RegisterSceneLoaderPlugin(plugin: ISceneLoaderPlugin | ISceneLoaderPluginAsync | ISceneLoaderPluginFactory): void {
     if (typeof plugin.extensions === "string") {
         const extension = plugin.extensions;
         registeredPlugins[extension.toLowerCase()] = {
@@ -800,6 +800,46 @@ export function registerSceneLoaderPlugin(plugin: ISceneLoaderPlugin | ISceneLoa
     }
 }
 
+/**
+ * Adds a new plugin to the list of registered plugins
+ * @deprecated Please use `RegisterSceneLoaderPlugin` instead.
+ * @param plugin defines the plugin to add
+ */
+export function registerSceneLoaderPlugin(plugin: ISceneLoaderPlugin | ISceneLoaderPluginAsync | ISceneLoaderPluginFactory): void {
+    RegisterSceneLoaderPlugin(plugin);
+}
+
+/**
+ * Gets metadata for all currently registered scene loader plugins.
+ * @returns An array where each entry has metadata for a single scene loader plugin.
+ */
+export function GetRegisteredSceneLoaderPluginMetadata(): DeepImmutable<
+    Array<
+        Pick<ISceneLoaderPluginMetadata, "name"> & {
+            /**
+             * The extensions supported by the plugin.
+             */
+            extensions: ({
+                /**
+                 * The file extension.
+                 */
+                extension: string;
+            } & ISceneLoaderPluginExtensions[string])[];
+        }
+    >
+> {
+    return Array.from(
+        Object.entries(registeredPlugins).reduce((pluginMap, [extension, extensionRegistration]) => {
+            let pluginMetadata = pluginMap.get(extensionRegistration.plugin.name);
+            if (!pluginMetadata) {
+                pluginMap.set(extensionRegistration.plugin.name, (pluginMetadata = []));
+            }
+            pluginMetadata.push({ extension, isBinary: extensionRegistration.isBinary, mimeType: extensionRegistration.mimeType });
+            return pluginMap;
+        }, new Map<string, ({ extension: string } & ISceneLoaderPluginExtensions[string])[]>())
+    ).map(([name, extensions]) => ({ name, extensions }));
+}
+
 async function importMeshAsync(
     meshNames: string | readonly string[] | null | undefined,
     rootUrl: string,
@@ -982,17 +1022,28 @@ async function loadSceneImplAsync(
 
 /**
  * Load a scene
- * @experimental
  * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
  * @param engine is the instance of BABYLON.Engine to use to create the scene
  * @param options an object that configures aspects of how the scene is loaded
  * @returns The loaded scene
  */
-export function loadSceneAsync(source: SceneSource, engine: AbstractEngine, options?: LoadOptions): Promise<Scene> {
+export function LoadSceneAsync(source: SceneSource, engine: AbstractEngine, options?: LoadOptions): Promise<Scene> {
     const { rootUrl = "", onProgress, pluginExtension, name, pluginOptions } = options ?? {};
     return loadSceneSharedAsync(rootUrl, source, engine, onProgress, pluginExtension, name, pluginOptions);
 }
 
+/**
+ * Load a scene
+ * @deprecated Please use `LoadSceneAsync` instead.
+ * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
+ * @param engine is the instance of BABYLON.Engine to use to create the scene
+ * @param options an object that configures aspects of how the scene is loaded
+ * @returns The loaded scene
+ */
+export function loadSceneAsync(source: SceneSource, engine: AbstractEngine, options?: LoadOptions): Promise<Scene> {
+    return LoadSceneAsync(source, engine, options);
+}
+
 // This function is shared between the new module level loadSceneAsync and the legacy SceneLoader.LoadAsync
 function loadSceneSharedAsync(
     rootUrl: string,
@@ -1131,16 +1182,28 @@ async function appendSceneImplAsync(
 
 /**
  * Append a scene
- * @experimental
  * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
  * @param scene is the instance of BABYLON.Scene to append to
  * @param options an object that configures aspects of how the scene is loaded
+ * @returns A promise that resolves when the scene is appended
  */
-export async function appendSceneAsync(source: SceneSource, scene: Scene, options?: AppendOptions): Promise<void> {
+export async function AppendSceneAsync(source: SceneSource, scene: Scene, options?: AppendOptions): Promise<void> {
     const { rootUrl = "", onProgress, pluginExtension, name, pluginOptions } = options ?? {};
     await appendSceneSharedAsync(rootUrl, source, scene, onProgress, pluginExtension, name, pluginOptions);
 }
 
+/**
+ * Append a scene
+ * @deprecated Please use `AppendSceneAsync` instead.
+ * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
+ * @param scene is the instance of BABYLON.Scene to append to
+ * @param options an object that configures aspects of how the scene is loaded
+ * @returns A promise that resolves when the scene is appended
+ */
+export function appendSceneAsync(source: SceneSource, scene: Scene, options?: AppendOptions): Promise<void> {
+    return AppendSceneAsync(source, scene, options);
+}
+
 // This function is shared between the new module level appendSceneAsync and the legacy SceneLoader.AppendAsync
 function appendSceneSharedAsync(
     rootUrl: string,
@@ -1278,17 +1341,28 @@ async function loadAssetContainerImplAsync(
 
 /**
  * Load a scene into an asset container
- * @experimental
  * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
  * @param scene is the instance of Scene to append to
  * @param options an object that configures aspects of how the scene is loaded
  * @returns The loaded asset container
  */
-export function loadAssetContainerAsync(source: SceneSource, scene: Scene, options?: LoadAssetContainerOptions): Promise<AssetContainer> {
+export function LoadAssetContainerAsync(source: SceneSource, scene: Scene, options?: LoadAssetContainerOptions): Promise<AssetContainer> {
     const { rootUrl = "", onProgress, pluginExtension, name, pluginOptions } = options ?? {};
     return loadAssetContainerSharedAsync(rootUrl, source, scene, onProgress, pluginExtension, name, pluginOptions);
 }
 
+/**
+ * Load a scene into an asset container
+ * @deprecated Please use `LoadAssetContainerAsync` instead.
+ * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
+ * @param scene is the instance of Scene to append to
+ * @param options an object that configures aspects of how the scene is loaded
+ * @returns The loaded asset container
+ */
+export function loadAssetContainerAsync(source: SceneSource, scene: Scene, options?: LoadAssetContainerOptions): Promise<AssetContainer> {
+    return LoadAssetContainerAsync(source, scene, options);
+}
+
 // This function is shared between the new module level loadAssetContainerAsync and the legacy SceneLoader.LoadAssetContainerAsync
 function loadAssetContainerSharedAsync(
     rootUrl: string,
@@ -1403,16 +1477,28 @@ async function importAnimationsImplAsync(
 
 /**
  * Import animations from a file into a scene
- * @experimental
  * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
  * @param scene is the instance of BABYLON.Scene to append to
  * @param options an object that configures aspects of how the scene is loaded
+ * @returns A promise that resolves when the animations are imported
  */
-export async function importAnimationsAsync(source: SceneSource, scene: Scene, options?: ImportAnimationsOptions): Promise<void> {
+export async function ImportAnimationsAsync(source: SceneSource, scene: Scene, options?: ImportAnimationsOptions): Promise<void> {
     const { rootUrl = "", overwriteAnimations, animationGroupLoadingMode, targetConverter, onProgress, pluginExtension, name, pluginOptions } = options ?? {};
     await importAnimationsSharedAsync(rootUrl, source, scene, overwriteAnimations, animationGroupLoadingMode, targetConverter, onProgress, pluginExtension, name, pluginOptions);
 }
 
+/**
+ * Import animations from a file into a scene
+ * @deprecated Please use `ImportAnimationsAsync` instead.
+ * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
+ * @param scene is the instance of BABYLON.Scene to append to
+ * @param options an object that configures aspects of how the scene is loaded
+ * @returns A promise that resolves when the animations are imported
+ */
+export function importAnimationsAsync(source: SceneSource, scene: Scene, options?: ImportAnimationsOptions): Promise<void> {
+    return ImportAnimationsAsync(source, scene, options);
+}
+
 // This function is shared between the new module level importAnimationsAsync and the legacy SceneLoader.ImportAnimationsAsync
 function importAnimationsSharedAsync(
     rootUrl: string,
@@ -1455,6 +1541,7 @@ function importAnimationsSharedAsync(
 /**
  * Class used to load scene from various file formats using registered plugins
  * @see https://doc.babylonjs.com/features/featuresDeepDive/importers/loadingFileTypes
+ * @deprecated The module level functions (such as LoadAssetContainerAsync) are more efficient for bundler tree shaking and allow plugin options to be passed through. Future improvements to scene loading will primarily be in the module level functions. The SceneLoader class will remain available, but it will be beneficial to prefer the module level functions.
  */
 export class SceneLoader {
     /**
@@ -1564,7 +1651,7 @@ export class SceneLoader {
      * @param plugin defines the plugin to add
      */
     public static RegisterPlugin(plugin: ISceneLoaderPlugin | ISceneLoaderPluginAsync | ISceneLoaderPluginFactory): void {
-        registerSceneLoaderPlugin(plugin);
+        RegisterSceneLoaderPlugin(plugin);
     }
 
     /**

diff --git a/packages/dev/loaders/src/OBJ/objFileLoader.ts b/packages/dev/loaders/src/OBJ/objFileLoader.ts
@@ -3,7 +3,7 @@ import { Vector2 } from "core/Maths/math.vector";
 import { Tools } from "core/Misc/tools";
 import type { AbstractMesh } from "core/Meshes/abstractMesh";
 import type { ISceneLoaderPluginAsync, ISceneLoaderPluginFactory, ISceneLoaderPlugin, ISceneLoaderAsyncResult } from "core/Loading/sceneLoader";
-import { registerSceneLoaderPlugin } from "core/Loading/sceneLoader";
+import { RegisterSceneLoaderPlugin } from "core/Loading/sceneLoader";
 import { AssetContainer } from "core/assetContainer";
 import type { Scene } from "core/scene";
 import type { WebRequest } from "core/Misc/webRequest";
@@ -361,4 +361,4 @@ export class OBJFileLoader implements ISceneLoaderPluginAsync, ISceneLoaderPlugi
 }
 
 //Add this loader into the register plugin
-registerSceneLoaderPlugin(new OBJFileLoader());
+RegisterSceneLoaderPlugin(new OBJFileLoader());
diff --git a/packages/dev/loaders/src/SPLAT/splatFileLoader.ts b/packages/dev/loaders/src/SPLAT/splatFileLoader.ts
@@ -1,5 +1,5 @@
 import type { ISceneLoaderPluginAsync, ISceneLoaderPluginFactory, ISceneLoaderAsyncResult, ISceneLoaderProgressEvent, SceneLoaderPluginOptions } from "core/Loading/sceneLoader";
-import { registerSceneLoaderPlugin } from "core/Loading/sceneLoader";
+import { RegisterSceneLoaderPlugin } from "core/Loading/sceneLoader";
 import { SPLATFileLoaderMetadata } from "./splatFileLoader.metadata";
 import { GaussianSplattingMesh } from "core/Meshes/GaussianSplatting/gaussianSplattingMesh";
 import { AssetContainer } from "core/assetContainer";
@@ -565,4 +565,4 @@ export class SPLATFileLoader implements ISceneLoaderPluginAsync, ISceneLoaderPlu
 }
 
 // Add this loader into the register plugin
-registerSceneLoaderPlugin(new SPLATFileLoader());
+RegisterSceneLoaderPlugin(new SPLATFileLoader());
diff --git a/packages/dev/loaders/src/STL/stlFileLoader.ts b/packages/dev/loaders/src/STL/stlFileLoader.ts
@@ -5,7 +5,7 @@ import { VertexBuffer } from "core/Buffers/buffer";
 import type { AbstractMesh } from "core/Meshes/abstractMesh";
 import { Mesh } from "core/Meshes/mesh";
 import type { ISceneLoaderPlugin } from "core/Loading/sceneLoader";
-import { registerSceneLoaderPlugin } from "core/Loading/sceneLoader";
+import { RegisterSceneLoaderPlugin } from "core/Loading/sceneLoader";
 import { AssetContainer } from "core/assetContainer";
 import type { Scene } from "core/scene";
 import { STLFileLoaderMetadata } from "./stlFileLoader.metadata";
@@ -285,4 +285,4 @@ export class STLFileLoader implements ISceneLoaderPlugin {
     }
 }
 
-registerSceneLoaderPlugin(new STLFileLoader());
+RegisterSceneLoaderPlugin(new STLFileLoader());
diff --git a/packages/dev/loaders/src/dynamic.ts b/packages/dev/loaders/src/dynamic.ts
@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/naming-convention */
 
 import type { ISceneLoaderPluginFactory, SceneLoaderPluginOptions } from "core/Loading/sceneLoader";
-import { registerSceneLoaderPlugin } from "core/Loading/sceneLoader";
+import { RegisterSceneLoaderPlugin } from "core/Loading/sceneLoader";
 
 import { GLTFFileLoaderMetadata } from "./glTF/glTFFileLoader.metadata";
 import { OBJFileLoaderMetadata } from "./OBJ/objFileLoader.metadata";
@@ -16,7 +16,7 @@ import { registerBuiltInGLTFExtensions } from "./glTF/2.0/Extensions/dynamic";
  */
 export function registerBuiltInLoaders() {
     // Register the glTF loader (2.0) specifically/only.
-    registerSceneLoaderPlugin({
+    RegisterSceneLoaderPlugin({
         ...GLTFFileLoaderMetadata,
         createPlugin: async (options: SceneLoaderPluginOptions) => {
             const { GLTFFileLoader } = await import("./glTF/2.0/glTFLoader");
@@ -28,7 +28,7 @@ export function registerBuiltInLoaders() {
     registerBuiltInGLTFExtensions();
 
     // Register the OBJ loader.
-    registerSceneLoaderPlugin({
+    RegisterSceneLoaderPlugin({
         ...OBJFileLoaderMetadata,
         createPlugin: async () => {
             const { OBJFileLoader } = await import("./OBJ/objFileLoader");
@@ -37,7 +37,7 @@ export function registerBuiltInLoaders() {
     } satisfies ISceneLoaderPluginFactory);
 
     // Register the SPLAT loader.
-    registerSceneLoaderPlugin({
+    RegisterSceneLoaderPlugin({
         ...SPLATFileLoaderMetadata,
         createPlugin: async (options: SceneLoaderPluginOptions) => {
             const { SPLATFileLoader } = await import("./SPLAT/splatFileLoader");
@@ -46,7 +46,7 @@ export function registerBuiltInLoaders() {
     } satisfies ISceneLoaderPluginFactory);
 
     // Register the STL loader.
-    registerSceneLoaderPlugin({
+    RegisterSceneLoaderPlugin({
         ...STLFileLoaderMetadata,
         createPlugin: async () => {
             const { STLFileLoader } = await import("./STL/stlFileLoader");

diff --git a/packages/dev/loaders/src/glTF/glTFFileLoader.ts b/packages/dev/loaders/src/glTF/glTFFileLoader.ts
@@ -10,7 +10,7 @@ import type { BaseTexture } from "core/Materials/Textures/baseTexture";
 import type { Material } from "core/Materials/material";
 import type { AbstractMesh } from "core/Meshes/abstractMesh";
 import type { ISceneLoaderPluginFactory, ISceneLoaderPluginAsync, ISceneLoaderProgressEvent, ISceneLoaderAsyncResult, SceneLoaderPluginOptions } from "core/Loading/sceneLoader";
-import { registerSceneLoaderPlugin } from "core/Loading/sceneLoader";
+import { RegisterSceneLoaderPlugin } from "core/Loading/sceneLoader";
 import { AssetContainer } from "core/assetContainer";
 import type { Scene, IDisposable } from "core/scene";
 import type { WebRequest } from "core/Misc/webRequest";
@@ -1392,4 +1392,4 @@ export class GLTFFileLoader extends GLTFLoaderOptions implements IDisposable, IS
     private _endPerformanceCounterDisabled(counterName: string): void {}
 }
 
-registerSceneLoaderPlugin(new GLTFFileLoader());
+RegisterSceneLoaderPlugin(new GLTFFileLoader());
diff --git a/packages/tools/viewer/src/viewer.ts b/packages/tools/viewer/src/viewer.ts
@@ -23,7 +23,7 @@ import type { MaterialVariantsController } from "loaders/glTF/2.0/Extensions/KHR
 import { ArcRotateCamera } from "core/Cameras/arcRotateCamera";
 import { PointerEventTypes } from "core/Events/pointerEvents";
 import { HemisphericLight } from "core/Lights/hemisphericLight";
-import { loadAssetContainerAsync } from "core/Loading/sceneLoader";
+import { LoadAssetContainerAsync } from "core/Loading/sceneLoader";
 import { ImageProcessingConfiguration } from "core/Materials/imageProcessingConfiguration";
 import { PBRMaterial } from "core/Materials/PBR/pbrMaterial";
 import { CubeTexture } from "core/Materials/Textures/cubeTexture";
@@ -1029,7 +1029,7 @@ export class Viewer implements IDisposable {
         this._snapshotHelper.disableSnapshotRendering();
 
         try {
-            const assetContainer = await loadAssetContainerAsync(source, this._scene, options);
+            const assetContainer = await LoadAssetContainerAsync(source, this._scene, options);
             assetContainer.animationGroups.forEach((group) => {
                 group.start(true, this.animationSpeed);
                 group.pause();