useLargeWorldRendering on engine enables floatingOrigin and highMatrixPrecision. Add ability to useFloatingOrigin per-scene (#17334)

This PR solves 2 major bugs in floatingoriginmode. 
- Previously I was updating the creationOptions object but that didn't
actually update the underlying performanceConfigurator's precision, so
we were getting CPU-side calculation imprecision.
- Additionally, the floatingOriginOffset value was tied to the most
recently created scene's active camera, and didn't support multi-scene.

After this change:
- engine creation **useLargeWorldRendering** will both set
useHighPrecisionMatrix on engine and set all scenes to useFloatingOrigin
upon creation
- scene creation **useFloatingOrigin** can be used instead of the above
if user wants only some scenes to useFloatingOrigin (doing this can
improve perf for scenes that are not large worlds as we skip matrix
offsetting). If this option is used, must be used in conjunction with
engine's useHighPrecisionMatrix to achieve full precision)
- offset will always be tied to the current rendering scene's active
camera

Tested with this playground [#P3E9YP#255
](https://playground.babylonjs.com/?snapshot=refs/pull/17334/merge#P3E9YP#255)
which enables swapping between scenes and testing combinations of
floatingOrigin on / off

---------

Co-authored-by: Georgina Halpern <[email protected]>

Author: georginahalpern

packages/dev/core/src/Engines/abstractEngine.ts

@@ -132,10 +132,22 @@ export interface AbstractEngineOptions {
     doNotHandleTouchAction?: boolean;
 
     /**
-     * Make the matrix computations to be performed in 64 bits instead of 32 bits. False by default
+     * Make the matrix computations to be performed in 64 bits instead of 32 bits. False by default.
+     * Note that setting useLargeWorldRendering will also set high precision matrices
      */
     useHighPrecisionMatrix?: boolean;
 
+    /**
+     * @experimental
+     * LargeWorldRendering helps avoid floating point imprecision of rendering large worlds by
+     * 1. Forcing highPrecisionMatrices (matrix computations in 64 bits instead of 32)
+     * 2. Enabling floatingOriginMode in all scenes -- offsetting position-related uniform and attribute values before passing to shader so that active camera is centered at origin and world is offset by active camera position
+     *
+     * NOTE that if this mode is set during engineCreation, all scenes will have floatingOrigin offset and you do not need to send floatingOriginMode option to each scene creation.
+     * If you'd like to have only specific scenes using the offset logic, you can set the flag on those scenes directly -- however, to achieve proper large world rendering, you must also set the useHighPrecisionMatrix option on engine.
+     */
+    readonly useLargeWorldRendering?: boolean;
+
     /**
      * Defines whether to adapt to the device's viewport characteristics (default: false)
      */
@@ -2019,6 +2031,7 @@ export abstract class AbstractEngine {
 
     /**
      * Gets the options used for engine creation
+     * NOTE that modifying the object after engine creation will have no effect
      * @returns EngineOptions object
      */
     public getCreationOptions() {
@@ -2037,7 +2050,9 @@ export abstract class AbstractEngine {
 
         this._stencilStateComposer.stencilGlobal = this._stencilState;
 
-        PerformanceConfigurator.SetMatrixPrecision(!!options.useHighPrecisionMatrix);
+        // LargeWorldRendering set to true will set high precision matrix, regardless of useHighPrecisionMatrix value
+        // It will also set all scenes to use floatingOriginMode upon their creation
+        PerformanceConfigurator.SetMatrixPrecision(!!options.useLargeWorldRendering || !!options.useHighPrecisionMatrix);
 
         if (IsNavigatorAvailable() && navigator.userAgent) {
             // Detect if we are running on a faulty buggy OS.

packages/dev/core/src/Materials/floatingOriginMatrixOverrides.ts

@@ -9,6 +9,12 @@ import { UniformBuffer } from "./uniformBuffer";
 const TempFinalMat: Matrix = new Matrix();
 const TempMat1: Matrix = new Matrix();
 const TempMat2: Matrix = new Matrix();
+/**
+ * When rendering, each scene will reset this to ensure the correct floating origin offset is when overriding the below functions
+ */
+export const FloatingOriginCurrentScene = {
+    getScene: () => undefined as Scene | undefined,
+};
 
 function OffsetWorldToRef(offset: IVector3Like, world: DeepImmutable<IMatrixLike>, ref: Matrix): DeepImmutable<IMatrixLike> {
     const refArray = ref.asArray();
@@ -75,19 +81,25 @@ function OffsetWorldViewProjectionToRef(
     return ref;
 }
 
-function GetOffsetMatrix(uniformName: string, mat: IMatrixLike, scene: Scene): IMatrixLike {
+function GetOffsetMatrix(uniformName: string, mat: IMatrixLike): IMatrixLike {
     TempFinalMat.updateFlag = mat.updateFlag;
+    const scene = FloatingOriginCurrentScene.getScene();
+    // Early out for scenes that don't have floatingOriginMode enabled
+    if (!scene) {
+        return mat;
+    }
+    const offset = scene.floatingOriginOffset;
     switch (uniformName) {
         case "world":
-            return OffsetWorldToRef(scene.floatingOriginOffset, mat, TempFinalMat);
+            return OffsetWorldToRef(offset, mat, TempFinalMat);
         case "view":
             return OffsetViewToRef(mat, TempFinalMat);
         case "worldView":
-            return OffsetWorldViewToRef(scene.floatingOriginOffset, mat, scene.getViewMatrix(), TempFinalMat);
+            return OffsetWorldViewToRef(offset, mat, scene.getViewMatrix(), TempFinalMat);
         case "viewProjection":
             return OffsetViewProjectionToRef(scene.getViewMatrix(), scene.getProjectionMatrix(), TempFinalMat);
         case "worldViewProjection":
-            return OffsetWorldViewProjectionToRef(scene.floatingOriginOffset, mat, scene.getTransformMatrix(), scene.getViewMatrix(), scene.getProjectionMatrix(), TempFinalMat);
+            return OffsetWorldViewProjectionToRef(offset, mat, scene.getTransformMatrix(), scene.getViewMatrix(), scene.getProjectionMatrix(), TempFinalMat);
         default:
             return mat;
     }
@@ -106,14 +118,14 @@ export function ResetMatrixFunctions() {
     UniformBufferInternal.prototype._updateMatrixForUniformOverride = undefined;
 }
 
-export function OverrideMatrixFunctions(scene: Scene) {
-    EffectInternal.prototype._setMatrixOverride = Effect.prototype.setMatrix;
+export function OverrideMatrixFunctions() {
+    EffectInternal.prototype._setMatrixOverride = OriginalSetMatrix;
     EffectInternal.prototype.setMatrix = function (uniformName: string, matrix: IMatrixLike) {
-        this._setMatrixOverride(uniformName, GetOffsetMatrix(uniformName, matrix, scene));
+        this._setMatrixOverride(uniformName, GetOffsetMatrix(uniformName, matrix));
         return this;
     };
-    UniformBufferInternal.prototype._updateMatrixForUniformOverride = UniformBufferInternal.prototype._updateMatrixForUniform;
+    UniformBufferInternal.prototype._updateMatrixForUniformOverride = OriginalUpdateMatrixForUniform;
     UniformBufferInternal.prototype._updateMatrixForUniform = function (uniformName: string, matrix: IMatrixLike) {
-        this._updateMatrixForUniformOverride(uniformName, GetOffsetMatrix(uniformName, matrix, scene));
+        this._updateMatrixForUniformOverride(uniformName, GetOffsetMatrix(uniformName, matrix));
     };
 }

packages/dev/core/src/scene.ts

@@ -21,7 +21,7 @@ import type { KeyboardInfoPre, KeyboardInfo } from "./Events/keyboardEvents";
 import { ActionEvent } from "./Actions/actionEvent";
 import { PostProcessManager } from "./PostProcesses/postProcessManager";
 import type { IOfflineProvider } from "./Offline/IOfflineProvider";
-import { OverrideMatrixFunctions, ResetMatrixFunctions } from "./Materials/floatingOriginMatrixOverrides";
+import { FloatingOriginCurrentScene, OverrideMatrixFunctions, ResetMatrixFunctions } from "./Materials/floatingOriginMatrixOverrides";
 import type { RenderingGroupInfo, IRenderingManagerAutoClearSetup } from "./Rendering/renderingManager";
 import { RenderingManager } from "./Rendering/renderingManager";
 import type {
@@ -136,16 +136,18 @@ export interface SceneOptions {
      */
     useClonedMeshMap?: boolean;
 
-    /** Defines if the creation of the scene should impact the engine (Eg. UtilityLayer's scene) */
-    virtual?: boolean;
-
     /**
      * @experimental
-     * FloatingOriginMode helps avoid floating point imprecision of rendering large worlds by
-     * 1. Forcing the engine to use doublePrecision mode
-     * 2. Offsetting uniform values before passing to shader so that camera is centered at origin and world is offset by camera position
+     * When enabled, the scene can handle large world coordinate rendering without jittering caused by floating point imprecision on the GPU.
+     * This mode offsets matrices and position-related attribute values before passing to shaders, centering camera at origin and offsetting other scene objects by camera active position.
+     *
+     * IMPORTANT: Only use this scene-level option if you intend to enable floating origin on a per-scene basis. Must use in conjunction with engine creation option 'useHighPrecisionMatrix' to fix CPU-side floating point imprecision.
+     * HOWEVER if you want largeWorldRendering on ALL scenes, set the useLargeWorldRendering flag on the engine instead of this scene-level flag. Doing so will automatically set useHighPrecisionMatrix on the engine as well.
      */
-    floatingOriginMode?: boolean;
+    useFloatingOrigin?: boolean;
+
+    /** Defines if the creation of the scene should impact the engine (Eg. UtilityLayer's scene) */
+    virtual?: boolean;
 }
 
 /**
@@ -2016,10 +2018,9 @@ export class Scene implements IAnimatable, IClipPlanesHolder, IAssetContainer {
             engine.scenes.push(this);
         }
 
-        if (options?.floatingOriginMode) {
-            engine.getCreationOptions().useHighPrecisionMatrix = true;
-            OverrideMatrixFunctions(this);
-            this._floatingOriginMode = true;
+        if (engine.getCreationOptions().useLargeWorldRendering || options?.useFloatingOrigin) {
+            OverrideMatrixFunctions();
+            this._floatingOriginScene = this;
         }
 
         this._uid = null;
@@ -2779,15 +2780,14 @@ export class Scene implements IAnimatable, IClipPlanesHolder, IAssetContainer {
         this._projectionUpdateFlag = -1;
     }
 
-    private _floatingOriginMode: boolean = false;
+    private _floatingOriginScene: Scene | undefined = undefined;
     /**
      * @experimental
-     * When true, enables floatingOriginMode which helps avoid floating point imprecision when using huge coordinate system by
-     * 1. Forcing the engine to use doublePrecision mode
-     * 2. Offsetting uniform values before passing to shader so that camera is centered at origin and world is offset by camera position
+     * True if floatingOriginMode was passed to engine or this scene creation otions.
+     * This mode avoids floating point imprecision in huge coordinate system by offsetting uniform values before passing to shader, centering camera at origin and displacing rest of scene by camera position
      */
     public get floatingOriginMode(): boolean {
-        return this._floatingOriginMode;
+        return this._floatingOriginScene !== undefined;
     }
 
     private _floatingOriginOffsetDefault: Vector3 = Vector3.Zero();
@@ -5340,6 +5340,9 @@ export class Scene implements IAnimatable, IClipPlanesHolder, IAssetContainer {
         this._intermediateRendering = false;
     }
 
+    private _getFloatingOriginScene = (): Scene | undefined => {
+        return this._floatingOriginScene;
+    };
     /**
      * Render the scene
      * @param updateCameras defines a boolean indicating if cameras must update according to their inputs (true by default)
@@ -5354,6 +5357,9 @@ export class Scene implements IAnimatable, IClipPlanesHolder, IAssetContainer {
             this._checkIsReady();
         }
 
+        // Ensures that the floatingOriginOffset is grabbed from the correct scene
+        FloatingOriginCurrentScene.getScene = this._getFloatingOriginScene;
+
         this._frameId++;
         this._defaultFrameBufferCleared = false;
         this._checkCameraRenderTarget(this.activeCamera);
@@ -5684,6 +5690,13 @@ export class Scene implements IAnimatable, IClipPlanesHolder, IAssetContainer {
             this._engine.scenes.splice(index, 1);
         }
 
+        this._floatingOriginScene = undefined;
+        if (this._engine.scenes.length === 0) {
+            // If this is the last scene to be disposed, reset matrix overrides
+            // Cannot reset from within engine class due floatingOriginMatrixOverrides file import side effects
+            ResetMatrixFunctions();
+        }
+
         if (EngineStore._LastCreatedScene === this) {
             EngineStore._LastCreatedScene = null;
             let engineIndex = EngineStore.Instances.length - 1;
@@ -5758,8 +5771,6 @@ export class Scene implements IAnimatable, IClipPlanesHolder, IAssetContainer {
         this.onClearColorChangedObservable.clear();
         this.onEnvironmentTextureChangedObservable.clear();
         this.onMeshUnderPointerUpdatedObservable.clear();
-
-        ResetMatrixFunctions();
         this._isDisposed = true;
     }
 

packages/tools/tests/test/visualization/config.json

@@ -2857,7 +2857,7 @@
         },
         {
             "title": "Atmosphere Day (Planet Origin)",
-            "playgroundId": "#VO1Z0C#10",
+            "playgroundId": "#VO1Z0C#30",
             "referenceImage": "atmosphere-day.png",
             "excludedEngines": ["webgl1", "webgpu"],
             "renderCount": 2
@@ -2871,7 +2871,7 @@
         },
         {
             "title": "Atmosphere Sunset (Planet Origin)",
-            "playgroundId": "#VO1Z0C#11",
+            "playgroundId": "#VO1Z0C#31",
             "referenceImage": "atmosphere-sunset.png",
             "excludedEngines": ["webgl1", "webgpu"],
             "renderCount": 2
@@ -2885,7 +2885,7 @@
         },
         {
             "title": "Atmosphere Night (Planet Origin)",
-            "playgroundId": "#VO1Z0C#12",
+            "playgroundId": "#VO1Z0C#32",
             "referenceImage": "atmosphere-night.png",
             "excludedEngines": ["webgl1", "webgpu"],
             "renderCount": 2