@babylonjs/core 5.22.1 → 5.24.0

package/scene.d.ts

@@ -30,7 +30,6 @@ import type { LoadFileError, RequestFileError, ReadFileError } from "./Misc/file
 import type { IClipPlanesHolder } from "./Misc/interfaces/iClipPlanesHolder";
 import type { IPointerEvent } from "./Events/deviceInputEvents";
 import type { IComputePressureData } from "./Misc/computePressure";
-import type { INotifyArrayChangeType } from "./Misc/arrayTools";
 declare type Ray = import("./Culling/ray").Ray;
 declare type TrianglePickingPredicate = import("./Culling/ray").TrianglePickingPredicate;
 declare type Animation = import("./Animations/animation").Animation;
@@ -85,6 +84,17 @@ export interface SceneOptions {
     /** Defines if the creation of the scene should impact the engine (Eg. UtilityLayer's scene) */
     virtual?: boolean;
 }
+/**
+ * Define how the scene should favor performance over ease of use
+ */
+export declare enum ScenePerformancePriority {
+    /** Default mode. No change. Performance will be treated as less important than backward compatibility */
+    BackwardCompatible = 0,
+    /** Some performance options will be turned on trying to strike a balance between perf and ease of use */
+    Intermediate = 1,
+    /** Performance will be top priority */
+    Aggressive = 2
+}
 /**
  * Represents a scene to be rendered by the engine.
  * @see https://doc.babylonjs.com/features/scene
@@ -182,6 +192,12 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
      * No setter as we it is a shared configuration, you can set the values instead.
      */
     get imageProcessingConfiguration(): ImageProcessingConfiguration;
+    private _performancePriority;
+    /**
+     * Gets or sets a value indicating how to treat performance relatively to ease of use and backward compatibility
+     */
+    get performancePriority(): ScenePerformancePriority;
+    set performancePriority(value: ScenePerformancePriority);
     private _forceWireframe;
     /**
      * Gets or sets a boolean indicating if all rendering must be done in wireframe
@@ -462,7 +478,7 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
     /**
      * An event triggered when the activeCameras property is updated
      */
-    onActiveCamerasChanged: Observable<INotifyArrayChangeType<import("./Cameras/camera").Camera>>;
+    onActiveCamerasChanged: Observable<Scene>;
     /**
      * This Observable will be triggered before rendering each renderingGroup of each rendered camera.
      * The RenderingGroupInfo class contains all the information about the context in which the observable is called
@@ -562,7 +578,7 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
      * @param effect The effect to be bound
      * @param variableName name of the shader variable that will hold the eye position
      * @param isVector3 true to indicates that variableName is a Vector3 and not a Vector4
-     * @return the computed eye position
+     * @returns the computed eye position
      */
     bindEyePosition(effect: Nullable<Effect>, variableName?: string, isVector3?: boolean): Vector4;
     /**
@@ -674,6 +690,7 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
     set lightsEnabled(value: boolean);
     get lightsEnabled(): boolean;
     private _activeCameras;
+    private _unObserveActiveCameras;
     /** All of the active cameras added to this scene. */
     get activeCameras(): Nullable<Camera[]>;
     set activeCameras(cameras: Nullable<Camera[]>);
@@ -1179,7 +1196,7 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
      * This function will check if the scene can be rendered (textures are loaded, shaders are compiled)
      * Delay loaded resources are not taking in account
      * @param checkRenderTargets true to also check that the meshes rendered as part of a render target are ready (default: true)
-     * @return true if all required resources are ready
+     * @returns true if all required resources are ready
      */
     isReady(checkRenderTargets?: boolean): boolean;
     /** Resets all cached information relative to material (including effect and visibility) */
@@ -1474,7 +1491,7 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
     /**
      * sets the active camera of the scene using its Id
      * @param id defines the camera's Id
-     * @return the new active camera or null if none found.
+     * @returns the new active camera or null if none found.
      */
     setActiveCameraById(id: string): Nullable<Camera>;
     /**
@@ -1486,44 +1503,44 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
     /**
      * get an animation group using its name
      * @param name defines the material's name
-     * @return the animation group or null if none found.
+     * @returns the animation group or null if none found.
      */
     getAnimationGroupByName(name: string): Nullable<AnimationGroup>;
     /**
      * Get a material using its unique id
      * @param uniqueId defines the material's unique id
-     * @return the material or null if none found.
+     * @returns the material or null if none found.
      */
     getMaterialByUniqueID(uniqueId: number): Nullable<Material>;
     /**
      * get a material using its id
      * @param id defines the material's Id
-     * @return the material or null if none found.
+     * @returns the material or null if none found.
      */
     getMaterialById(id: string): Nullable<Material>;
     /**
      * Gets a the last added material using a given id
      * @param id defines the material's Id
      * @param allowMultiMaterials determines whether multimaterials should be considered
-     * @return the last material with the given id or null if none found.
+     * @returns the last material with the given id or null if none found.
      */
     getLastMaterialById(id: string, allowMultiMaterials?: boolean): Nullable<Material>;
     /**
      * Gets a material using its name
      * @param name defines the material's name
-     * @return the material or null if none found.
+     * @returns the material or null if none found.
      */
     getMaterialByName(name: string): Nullable<Material>;
     /**
      * Get a texture using its unique id
      * @param uniqueId defines the texture's unique id
-     * @return the texture or null if none found.
+     * @returns the texture or null if none found.
      */
     getTextureByUniqueId(uniqueId: number): Nullable<BaseTexture>;
     /**
      * Gets a texture using its name
      * @param name defines the texture's name
-     * @return the texture or null if none found.
+     * @returns the texture or null if none found.
      */
     getTextureByName(name: string): Nullable<BaseTexture>;
     /**
@@ -1541,49 +1558,49 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
     /**
      * Gets a camera using its name
      * @param name defines the camera's name
-     * @return the camera or null if none found.
+     * @returns the camera or null if none found.
      */
     getCameraByName(name: string): Nullable<Camera>;
     /**
      * Gets a bone using its Id
      * @param id defines the bone's Id
-     * @return the bone or null if not found
+     * @returns the bone or null if not found
      */
     getBoneById(id: string): Nullable<Bone>;
     /**
      * Gets a bone using its id
      * @param name defines the bone's name
-     * @return the bone or null if not found
+     * @returns the bone or null if not found
      */
     getBoneByName(name: string): Nullable<Bone>;
     /**
      * Gets a light node using its name
      * @param name defines the the light's name
-     * @return the light or null if none found.
+     * @returns the light or null if none found.
      */
     getLightByName(name: string): Nullable<Light>;
     /**
      * Gets a light node using its Id
      * @param id defines the light's Id
-     * @return the light or null if none found.
+     * @returns the light or null if none found.
      */
     getLightById(id: string): Nullable<Light>;
     /**
      * Gets a light node using its scene-generated unique Id
      * @param uniqueId defines the light's unique Id
-     * @return the light or null if none found.
+     * @returns the light or null if none found.
      */
     getLightByUniqueId(uniqueId: number): Nullable<Light>;
     /**
      * Gets a particle system by Id
      * @param id defines the particle system Id
-     * @return the corresponding system or null if none found
+     * @returns the corresponding system or null if none found
      */
     getParticleSystemById(id: string): Nullable<IParticleSystem>;
     /**
      * Gets a geometry using its Id
      * @param id defines the geometry's Id
-     * @return the geometry or null if none found.
+     * @returns the geometry or null if none found.
      */
     getGeometryById(id: string): Nullable<Geometry>;
     private _getGeometryByUniqueId;
@@ -1591,13 +1608,13 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
      * Add a new geometry to this scene
      * @param geometry defines the geometry to be added to the scene.
      * @param force defines if the geometry must be pushed even if a geometry with this id already exists
-     * @return a boolean defining if the geometry was added or not
+     * @returns a boolean defining if the geometry was added or not
      */
     pushGeometry(geometry: Geometry, force?: boolean): boolean;
     /**
      * Removes an existing geometry
      * @param geometry defines the geometry to be removed from the scene
-     * @return a boolean defining if the geometry was removed or not
+     * @returns a boolean defining if the geometry was removed or not
      */
     removeGeometry(geometry: Geometry): boolean;
     /**
@@ -1608,7 +1625,7 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
     /**
      * Gets the first added mesh found of a given Id
      * @param id defines the Id to search for
-     * @return the mesh found or null if not found at all
+     * @returns the mesh found or null if not found at all
      */
     getMeshById(id: string): Nullable<AbstractMesh>;
     /**
@@ -1620,13 +1637,13 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
     /**
      * Gets the first added transform node found of a given Id
      * @param id defines the Id to search for
-     * @return the found transform node or null if not found at all.
+     * @returns the found transform node or null if not found at all.
      */
     getTransformNodeById(id: string): Nullable<TransformNode>;
     /**
      * Gets a transform node with its auto-generated unique Id
      * @param uniqueId defines the unique Id to search for
-     * @return the found transform node or null if not found at all.
+     * @returns the found transform node or null if not found at all.
      */
     getTransformNodeByUniqueId(uniqueId: number): Nullable<TransformNode>;
     /**
@@ -1638,91 +1655,91 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
     /**
      * Gets a mesh with its auto-generated unique Id
      * @param uniqueId defines the unique Id to search for
-     * @return the found mesh or null if not found at all.
+     * @returns the found mesh or null if not found at all.
      */
     getMeshByUniqueId(uniqueId: number): Nullable<AbstractMesh>;
     /**
      * Gets a the last added mesh using a given Id
      * @param id defines the Id to search for
-     * @return the found mesh or null if not found at all.
+     * @returns the found mesh or null if not found at all.
      */
     getLastMeshById(id: string): Nullable<AbstractMesh>;
     /**
      * Gets a the last added node (Mesh, Camera, Light) using a given Id
      * @param id defines the Id to search for
-     * @return the found node or null if not found at all
+     * @returns the found node or null if not found at all
      */
     getLastEntryById(id: string): Nullable<Node>;
     /**
      * Gets a node (Mesh, Camera, Light) using a given Id
      * @param id defines the Id to search for
-     * @return the found node or null if not found at all
+     * @returns the found node or null if not found at all
      */
     getNodeById(id: string): Nullable<Node>;
     /**
      * Gets a node (Mesh, Camera, Light) using a given name
      * @param name defines the name to search for
-     * @return the found node or null if not found at all.
+     * @returns the found node or null if not found at all.
      */
     getNodeByName(name: string): Nullable<Node>;
     /**
      * Gets a mesh using a given name
      * @param name defines the name to search for
-     * @return the found mesh or null if not found at all.
+     * @returns the found mesh or null if not found at all.
      */
     getMeshByName(name: string): Nullable<AbstractMesh>;
     /**
      * Gets a transform node using a given name
      * @param name defines the name to search for
-     * @return the found transform node or null if not found at all.
+     * @returns the found transform node or null if not found at all.
      */
     getTransformNodeByName(name: string): Nullable<TransformNode>;
     /**
      * Gets a skeleton using a given Id (if many are found, this function will pick the last one)
      * @param id defines the Id to search for
-     * @return the found skeleton or null if not found at all.
+     * @returns the found skeleton or null if not found at all.
      */
     getLastSkeletonById(id: string): Nullable<Skeleton>;
     /**
      * Gets a skeleton using a given auto generated unique id
      * @param  uniqueId defines the unique id to search for
-     * @return the found skeleton or null if not found at all.
+     * @returns the found skeleton or null if not found at all.
      */
     getSkeletonByUniqueId(uniqueId: number): Nullable<Skeleton>;
     /**
      * Gets a skeleton using a given id (if many are found, this function will pick the first one)
      * @param id defines the id to search for
-     * @return the found skeleton or null if not found at all.
+     * @returns the found skeleton or null if not found at all.
      */
     getSkeletonById(id: string): Nullable<Skeleton>;
     /**
      * Gets a skeleton using a given name
      * @param name defines the name to search for
-     * @return the found skeleton or null if not found at all.
+     * @returns the found skeleton or null if not found at all.
      */
     getSkeletonByName(name: string): Nullable<Skeleton>;
     /**
      * Gets a morph target manager  using a given id (if many are found, this function will pick the last one)
      * @param id defines the id to search for
-     * @return the found morph target manager or null if not found at all.
+     * @returns the found morph target manager or null if not found at all.
      */
     getMorphTargetManagerById(id: number): Nullable<MorphTargetManager>;
     /**
      * Gets a morph target using a given id (if many are found, this function will pick the first one)
      * @param id defines the id to search for
-     * @return the found morph target or null if not found at all.
+     * @returns the found morph target or null if not found at all.
      */
     getMorphTargetById(id: string): Nullable<MorphTarget>;
     /**
      * Gets a morph target using a given name (if many are found, this function will pick the first one)
      * @param name defines the name to search for
-     * @return the found morph target or null if not found at all.
+     * @returns the found morph target or null if not found at all.
      */
     getMorphTargetByName(name: string): Nullable<MorphTarget>;
     /**
      * Gets a post process using a given name (if many are found, this function will pick the first one)
      * @param name defines the name to search for
-     * @return the found post process or null if not found at all.
+     * @returns the found post process or null if not found at all.
      */
     getPostProcessByName(name: string): Nullable<PostProcess>;
     /**
@@ -1741,26 +1758,26 @@ export declare class Scene extends AbstractScene implements IAnimatable, IClipPl
      * If you don't care and just want to get the data no matter what, use the more convenient getOrAddExternalDataWithFactory() method.
      * @param key the unique key that identifies the data
      * @param data the data object to associate to the key for this Engine instance
-     * @return true if no such key were already present and the data was added successfully, false otherwise
+     * @returns true if no such key were already present and the data was added successfully, false otherwise
      */
-    addExternalData<T>(key: string, data: T): boolean;
+    addExternalData<T extends Object>(key: string, data: T): boolean;
     /**
      * Get an externally attached data from its key
      * @param key the unique key that identifies the data
-     * @return the associated data, if present (can be null), or undefined if not present
+     * @returns the associated data, if present (can be null), or undefined if not present
      */
     getExternalData<T>(key: string): Nullable<T>;
     /**
      * Get an externally attached data from its key, create it using a factory if it's not already present
      * @param key the unique key that identifies the data
      * @param factory the factory that will be called to create the instance if and only if it doesn't exists
-     * @return the associated data, can be null if the factory returned null.
+     * @returns the associated data, can be null if the factory returned null.
      */
-    getOrAddExternalDataWithFactory<T>(key: string, factory: (k: string) => T): T;
+    getOrAddExternalDataWithFactory<T extends Object>(key: string, factory: (k: string) => T): T;
     /**
      * Remove an externally attached data from the Engine instance
      * @param key the unique key that identifies the data
-     * @return true if the data was successfully removed, false if it doesn't exist
+     * @returns true if the data was successfully removed, false if it doesn't exist
      */
     removeExternalData(key: string): boolean;
     private _evaluateSubMesh;
@@ -2157,28 +2174,28 @@ declare module "./scene" {
         /**
          * Sets the active camera of the scene using its Id
          * @param id defines the camera's Id
-         * @return the new active camera or null if none found.
+         * @returns the new active camera or null if none found.
          * @deprecated Please use setActiveCameraById instead
          */
         setActiveCameraByID(id: string): Nullable<Camera>;
         /**
          * Get a material using its id
          * @param id defines the material's Id
-         * @return the material or null if none found.
+         * @returns the material or null if none found.
          * @deprecated Please use getMaterialById instead
          */
         getMaterialByID(id: string): Nullable<Material>;
         /**
          * Gets a the last added material using a given id
          * @param id defines the material's Id
-         * @return the last material with the given id or null if none found.
+         * @returns the last material with the given id or null if none found.
          * @deprecated Please use getLastMaterialById instead
          */
         getLastMaterialByID(id: string): Nullable<Material>;
         /**
          * Get a texture using its unique id
          * @param uniqueId defines the texture's unique id
-         * @return the texture or null if none found.
+         * @returns the texture or null if none found.
          * @deprecated Please use getTextureByUniqueId instead
          */
         getTextureByUniqueID(uniqueId: number): Nullable<BaseTexture>;
@@ -2199,56 +2216,56 @@ declare module "./scene" {
         /**
          * Gets a bone using its Id
          * @param id defines the bone's Id
-         * @return the bone or null if not found
+         * @returns the bone or null if not found
          * @deprecated Please use getBoneById instead
          */
         getBoneByID(id: string): Nullable<Bone>;
         /**
          * Gets a light node using its Id
          * @param id defines the light's Id
-         * @return the light or null if none found.
+         * @returns the light or null if none found.
          * @deprecated Please use getLightById instead
          */
         getLightByID(id: string): Nullable<Light>;
         /**
          * Gets a light node using its scene-generated unique Id
          * @param uniqueId defines the light's unique Id
-         * @return the light or null if none found.
+         * @returns the light or null if none found.
          * @deprecated Please use getLightByUniqueId instead
          */
         getLightByUniqueID(uniqueId: number): Nullable<Light>;
         /**
          * Gets a particle system by Id
          * @param id defines the particle system Id
-         * @return the corresponding system or null if none found
+         * @returns the corresponding system or null if none found
          * @deprecated Please use getParticleSystemById instead
          */
         getParticleSystemByID(id: string): Nullable<IParticleSystem>;
         /**
          * Gets a geometry using its Id
          * @param id defines the geometry's Id
-         * @return the geometry or null if none found.
+         * @returns the geometry or null if none found.
          * @deprecated Please use getGeometryById instead
          */
         getGeometryByID(id: string): Nullable<Geometry>;
         /**
          * Gets the first added mesh found of a given Id
          * @param id defines the Id to search for
-         * @return the mesh found or null if not found at all
+         * @returns the mesh found or null if not found at all
          * @deprecated Please use getMeshById instead
          */
         getMeshByID(id: string): Nullable<AbstractMesh>;
         /**
          * Gets a mesh with its auto-generated unique Id
          * @param uniqueId defines the unique Id to search for
-         * @return the found mesh or null if not found at all.
+         * @returns the found mesh or null if not found at all.
          * @deprecated Please use getMeshByUniqueId instead
          */
         getMeshByUniqueID(uniqueId: number): Nullable<AbstractMesh>;
         /**
          * Gets a the last added mesh using a given Id
          * @param id defines the Id to search for
-         * @return the found mesh or null if not found at all.
+         * @returns the found mesh or null if not found at all.
          * @deprecated Please use getLastMeshById instead
          */
         getLastMeshByID(id: string): Nullable<AbstractMesh>;
@@ -2262,14 +2279,14 @@ declare module "./scene" {
         /**
          * Gets the first added transform node found of a given Id
          * @param id defines the Id to search for
-         * @return the found transform node or null if not found at all.
+         * @returns the found transform node or null if not found at all.
          * @deprecated Please use getTransformNodeById instead
          */
         getTransformNodeByID(id: string): Nullable<TransformNode>;
         /**
          * Gets a transform node with its auto-generated unique Id
          * @param uniqueId defines the unique Id to search for
-         * @return the found transform node or null if not found at all.
+         * @returns the found transform node or null if not found at all.
          * @deprecated Please use getTransformNodeByUniqueId instead
          */
         getTransformNodeByUniqueID(uniqueId: number): Nullable<TransformNode>;
@@ -2283,21 +2300,21 @@ declare module "./scene" {
         /**
          * Gets a node (Mesh, Camera, Light) using a given Id
          * @param id defines the Id to search for
-         * @return the found node or null if not found at all
+         * @returns the found node or null if not found at all
          * @deprecated Please use getNodeById instead
          */
         getNodeByID(id: string): Nullable<Node>;
         /**
          * Gets a the last added node (Mesh, Camera, Light) using a given Id
          * @param id defines the Id to search for
-         * @return the found node or null if not found at all
+         * @returns the found node or null if not found at all
          * @deprecated Please use getLastEntryById instead
          */
         getLastEntryByID(id: string): Nullable<Node>;
         /**
          * Gets a skeleton using a given Id (if many are found, this function will pick the last one)
          * @param id defines the Id to search for
-         * @return the found skeleton or null if not found at all.
+         * @returns the found skeleton or null if not found at all.
          * @deprecated Please use getLastSkeletonById instead
          */
         getLastSkeletonByID(id: string): Nullable<Skeleton>;