@babylonjs/core 5.22.1 → 5.24.0

package/scene.js

@@ -25,7 +25,19 @@ import { UniqueIdGenerator } from "./Misc/uniqueIdGenerator.js";
 import { ReadFile, RequestFile, LoadFile } from "./Misc/fileTools.js";
 import { LightConstants } from "./Lights/lightConstants.js";
 import { ComputePressureObserverWrapper } from "./Misc/computePressure.js";
-import { ArrayTools } from "./Misc/arrayTools.js";
+import { _ObserveArray } from "./Misc/arrayTools.js";
+/**
+ * Define how the scene should favor performance over ease of use
+ */
+export var ScenePerformancePriority;
+(function (ScenePerformancePriority) {
+    /** Default mode. No change. Performance will be treated as less important than backward compatibility */
+    ScenePerformancePriority[ScenePerformancePriority["BackwardCompatible"] = 0] = "BackwardCompatible";
+    /** Some performance options will be turned on trying to strike a balance between perf and ease of use */
+    ScenePerformancePriority[ScenePerformancePriority["Intermediate"] = 1] = "Intermediate";
+    /** Performance will be top priority */
+    ScenePerformancePriority[ScenePerformancePriority["Aggressive"] = 2] = "Aggressive";
+})(ScenePerformancePriority || (ScenePerformancePriority = {}));
 /**
  * Represents a scene to be rendered by the engine.
  * @see https://doc.babylonjs.com/features/scene
@@ -70,6 +82,7 @@ export class Scene extends AbstractScene {
          * this is easier to reference from here than from all the materials.
          */
         this.environmentIntensity = 1;
+        this._performancePriority = ScenePerformancePriority.BackwardCompatible;
         this._forceWireframe = false;
         this._skipFrustumClipping = false;
         this._forcePointsCloud = false;
@@ -388,7 +401,7 @@ export class Scene extends AbstractScene {
         // Lights
         this._shadowsEnabled = true;
         this._lightsEnabled = true;
-        this._activeCameras = ArrayTools.MakeObservableArray(this.onActiveCamerasChanged, []);
+        this._unObserveActiveCameras = null;
         // Textures
         this._texturesEnabled = true;
         // Physics
@@ -667,6 +680,7 @@ export class Scene extends AbstractScene {
          * Note: Compute pressure is an experimental API.
          */
         this.onComputePressureChanged = new Observable();
+        this.activeCameras = new Array();
         const fullOptions = {
             useGeometryUniqueIdsMap: true,
             useMaterialMeshMap: true,
@@ -762,6 +776,27 @@ export class Scene extends AbstractScene {
     get imageProcessingConfiguration() {
         return this._imageProcessingConfiguration;
     }
+    /**
+     * Gets or sets a value indicating how to treat performance relatively to ease of use and backward compatibility
+     */
+    get performancePriority() {
+        return this._performancePriority;
+    }
+    set performancePriority(value) {
+        if (value === this._performancePriority) {
+            return;
+        }
+        this._performancePriority = value;
+        switch (value) {
+            case ScenePerformancePriority.Aggressive:
+                this.skipFrustumClipping = true;
+            // eslint-disable-next-line no-fallthrough
+            case ScenePerformancePriority.Intermediate:
+                this.skipPointerMovePicking = true;
+                this.autoClear = false;
+                break;
+        }
+    }
     /**
      * Gets or sets a boolean indicating if all rendering must be done in wireframe
      */
@@ -893,7 +928,7 @@ export class Scene extends AbstractScene {
      * @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, variableName = "vEyePosition", isVector3 = false) {
         const eyePosition = this._forcedViewPosition
@@ -1033,7 +1068,16 @@ export class Scene extends AbstractScene {
         return this._activeCameras;
     }
     set activeCameras(cameras) {
-        this._activeCameras = ArrayTools.MakeObservableArray(this.onActiveCamerasChanged, cameras);
+        if (this._unObserveActiveCameras) {
+            this._unObserveActiveCameras();
+            this._unObserveActiveCameras = null;
+        }
+        if (cameras) {
+            this._unObserveActiveCameras = _ObserveArray(cameras, () => {
+                this.onActiveCamerasChanged.notifyObservers(this);
+            });
+        }
+        this._activeCameras = cameras;
     }
     /** Gets or sets the current active camera */
     get activeCamera() {
@@ -1385,7 +1429,7 @@ export class Scene extends AbstractScene {
      * 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 = true) {
         if (this._isDisposed) {
@@ -2195,7 +2239,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         const camera = this.getCameraById(id);
@@ -2221,7 +2265,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.animationGroups.length; index++) {
@@ -2234,7 +2278,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.materials.length; index++) {
@@ -2247,7 +2291,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.materials.length; index++) {
@@ -2261,7 +2305,7 @@ export class Scene extends AbstractScene {
      * 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, allowMultiMaterials = false) {
         for (let index = this.materials.length - 1; index >= 0; index--) {
@@ -2281,7 +2325,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.materials.length; index++) {
@@ -2294,7 +2338,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.textures.length; index++) {
@@ -2307,7 +2351,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.textures.length; index++) {
@@ -2346,7 +2390,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.cameras.length; index++) {
@@ -2359,7 +2403,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let skeletonIndex = 0; skeletonIndex < this.skeletons.length; skeletonIndex++) {
@@ -2375,7 +2419,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let skeletonIndex = 0; skeletonIndex < this.skeletons.length; skeletonIndex++) {
@@ -2391,7 +2435,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.lights.length; index++) {
@@ -2404,7 +2448,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.lights.length; index++) {
@@ -2417,7 +2461,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.lights.length; index++) {
@@ -2430,7 +2474,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.particleSystems.length; index++) {
@@ -2443,7 +2487,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.geometries.length; index++) {
@@ -2473,7 +2517,7 @@ export class Scene extends AbstractScene {
      * 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, force) {
         if (!force && this._getGeometryByUniqueId(geometry.uniqueId)) {
@@ -2486,7 +2530,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         let index;
@@ -2528,7 +2572,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.meshes.length; index++) {
@@ -2551,7 +2595,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.transformNodes.length; index++) {
@@ -2564,7 +2608,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.transformNodes.length; index++) {
@@ -2587,7 +2631,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.meshes.length; index++) {
@@ -2600,7 +2644,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = this.meshes.length - 1; index >= 0; index--) {
@@ -2613,7 +2657,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         let index;
@@ -2642,7 +2686,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         const mesh = this.getMeshById(id);
@@ -2670,7 +2714,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         const mesh = this.getMeshByName(name);
@@ -2698,7 +2742,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.meshes.length; index++) {
@@ -2711,7 +2755,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.transformNodes.length; index++) {
@@ -2724,7 +2768,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = this.skeletons.length - 1; index >= 0; index--) {
@@ -2737,7 +2781,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.skeletons.length; index++) {
@@ -2750,7 +2794,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.skeletons.length; index++) {
@@ -2763,7 +2807,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.skeletons.length; index++) {
@@ -2776,7 +2820,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let index = 0; index < this.morphTargetManagers.length; index++) {
@@ -2789,7 +2833,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let managerIndex = 0; managerIndex < this.morphTargetManagers.length; ++managerIndex) {
@@ -2806,7 +2850,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let managerIndex = 0; managerIndex < this.morphTargetManagers.length; ++managerIndex) {
@@ -2823,7 +2867,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         for (let postProcessIndex = 0; postProcessIndex < this.postProcesses.length; ++postProcessIndex) {
@@ -2857,7 +2901,7 @@ export class Scene extends AbstractScene {
      * 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(key, data) {
         if (!this._externalData) {
@@ -2868,7 +2912,7 @@ export class Scene extends AbstractScene {
     /**
      * 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(key) {
         if (!this._externalData) {
@@ -2880,7 +2924,7 @@ export class Scene extends AbstractScene {
      * 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(key, factory) {
         if (!this._externalData) {
@@ -2891,7 +2935,7 @@ export class Scene extends AbstractScene {
     /**
      * 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) {
         return this._externalData.remove(key);
@@ -3718,6 +3762,7 @@ export class Scene extends AbstractScene {
             this.activeCamera._activeMeshes.dispose();
             this.activeCamera = null;
         }
+        this.activeCameras = null;
         this._activeMeshes.dispose();
         this._renderingManager.dispose();
         this._processedMaterials.dispose();
@@ -3801,7 +3846,8 @@ export class Scene extends AbstractScene {
         this._disposeList(this.meshes, (item) => item.dispose(true));
         this._disposeList(this.transformNodes, (item) => item.dispose(true));
         // Release cameras
-        this._disposeList(this.cameras);
+        const cameras = this.cameras;
+        this._disposeList(cameras);
         // Release materials
         if (this._defaultMaterial) {
             this._defaultMaterial.dispose();