Improved splatBudget behaviour to allow both increase and decrease LOD (#8230)

* Improved splatBudget behaviour to allow both increase and decrease LOD

* jsdocs

---------

Co-authored-by: Martin Valigursky <[email protected]>

Author: mvaligursky

src/scene/gsplat-unified/gsplat-octree-instance.js

@@ -459,10 +459,10 @@ class GSplatOctreeInstance {
         // Pass 1: Evaluate optimal LOD for each node (distance-based)
         const totalOptimalSplats = this.evaluateNodeLods(cameraNode, maxLod, lodDistances, rangeMin, rangeMax, params);
 
-        // Enforce splat budget if enabled and over budget
+        // Enforce splat budget if enabled (bidirectional: degrade or upgrade)
         const { splatBudget } = params;
-        if (splatBudget > 0 && totalOptimalSplats > splatBudget) {
-            this.enforceSplatBudget(totalOptimalSplats, splatBudget, rangeMax);
+        if (splatBudget > 0) {
+            this.enforceSplatBudget(totalOptimalSplats, splatBudget, rangeMin, rangeMax);
         }
 
         // Pass 2: Calculate desired LOD (underfill) and apply changes
@@ -559,16 +559,19 @@ class GSplatOctreeInstance {
     }
 
     /**
-     * Adjusts optimal LOD indices to fit within the splat budget by degrading quality
-     * for lower-importance nodes first. Uses multiple passes, degrading by one level per pass,
-     * until within budget or all nodes are at maximum coarseness (rangeMax).
+     * Adjusts optimal LOD indices to fit within the splat budget bidirectionally.
+     * When over budget: degrades quality for lower-importance nodes first.
+     * When under budget: upgrades quality for higher-importance nodes first.
+     * Uses multiple passes, adjusting by one level per pass, until budget is reached
+     * or all nodes hit their respective limits (rangeMin or rangeMax).
      *
      * @param {number} totalSplats - Current total splat count with optimal LODs.
-     * @param {number} splatBudget - Maximum allowed splat count.
+     * @param {number} splatBudget - Target splat count to reach.
+     * @param {number} rangeMin - Minimum allowed LOD index.
      * @param {number} rangeMax - Maximum allowed LOD index.
      * @private
      */
-    enforceSplatBudget(totalSplats, splatBudget, rangeMax) {
+    enforceSplatBudget(totalSplats, splatBudget, rangeMin, rangeMax) {
         const nodes = this.octree.nodes;
         const nodeInfos = this.nodeInfos;
 
@@ -586,36 +589,76 @@ class GSplatOctreeInstance {
 
         let currentSplats = totalSplats;
 
-        // Multiple passes: degrade by one level per pass until within budget
-        while (currentSplats > splatBudget) {
-            let degradedAnyNode = false;
+        // Skip if already at budget
+        if (currentSplats === splatBudget) {
+            return;
+        }
 
-            // Try degrading each node by one level (starting from lowest importance)
-            for (let i = 0; i < nodeIndices.length; i++) {
-                if (currentSplats <= splatBudget) {
-                    break; // Within budget
-                }
+        // Determine direction and set iteration parameters
+        const isOverBudget = currentSplats > splatBudget;
+        const lodDelta = isOverBudget ? 1 : -1;
+
+        // Multiple passes: adjust by one LOD level per pass until budget is reached
+        while (isOverBudget ? currentSplats > splatBudget : currentSplats < splatBudget) {
+            let modified = false;
+
+            if (isOverBudget) {
+
+                // DEGRADE: process from lowest to highest importance
+                for (let i = 0; i < nodeIndices.length; i++) {
+                    const nodeIndex = nodeIndices[i];
+                    const nodeInfo = nodeInfos[nodeIndex];
+                    const node = nodes[nodeIndex];
+                    const currentOptimalLod = nodeInfo.optimalLod;
+
+                    // Try degrading to next coarser LOD (respect rangeMax constraint)
+                    if (currentOptimalLod < rangeMax) {
+                        const currentLod = node.lods[currentOptimalLod];
+                        const nextLod = node.lods[currentOptimalLod + 1];
+                        const splatsSaved = currentLod.count - nextLod.count;
 
-                const nodeIndex = nodeIndices[i];
-                const nodeInfo = nodeInfos[nodeIndex];
-                const node = nodes[nodeIndex];
-                const currentOptimalLod = nodeInfo.optimalLod;
-
-                // Try degrading to next coarser LOD (respect rangeMax constraint)
-                if (currentOptimalLod < rangeMax) {
-                    const currentLod = node.lods[currentOptimalLod];
-                    const nextLod = node.lods[currentOptimalLod + 1];
-                    const splatsSaved = currentLod.count - nextLod.count;
-
-                    // Degrade to coarser LOD
-                    nodeInfo.optimalLod = currentOptimalLod + 1;
-                    currentSplats -= splatsSaved;
-                    degradedAnyNode = true;
+                        // Degrade to coarser LOD
+                        nodeInfo.optimalLod += lodDelta;
+                        currentSplats -= splatsSaved;
+                        modified = true;
+
+                        if (currentSplats <= splatBudget) {
+                            break; // Within budget
+                        }
+                    }
+                }
+            } else {
+
+                // UPGRADE: process from highest to lowest importance
+                for (let i = nodeIndices.length - 1; i >= 0; i--) {
+                    const nodeIndex = nodeIndices[i];
+                    const nodeInfo = nodeInfos[nodeIndex];
+                    const node = nodes[nodeIndex];
+                    const currentOptimalLod = nodeInfo.optimalLod;
+
+                    // Try upgrading to next finer LOD (respect rangeMin constraint)
+                    if (currentOptimalLod > rangeMin) {
+                        const currentLod = node.lods[currentOptimalLod];
+                        const nextLod = node.lods[currentOptimalLod - 1];
+                        const splatsAdded = nextLod.count - currentLod.count;
+
+                        // Only upgrade if we won't exceed budget
+                        if (currentSplats + splatsAdded <= splatBudget) {
+                            // Upgrade to finer LOD
+                            nodeInfo.optimalLod += lodDelta;
+                            currentSplats += splatsAdded;
+                            modified = true;
+
+                            if (currentSplats >= splatBudget) {
+                                break; // At budget
+                            }
+                        }
+                    }
                 }
             }
 
-            // If no nodes could be degraded, all are at rangeMax - can't reduce further
-            if (!degradedAnyNode) {
+            // If no nodes were modified, we can't adjust further
+            if (!modified) {
                 break;
             }
         }

src/scene/gsplat-unified/gsplat-params.js

@@ -212,9 +212,13 @@ class GSplatParams {
     _splatBudget = 0;
 
     /**
-     * Soft limit on the total number of splats to render. When the optimal LOD selections would
-     * exceed this budget, the system will adjust LOD levels to stay within the limit while
-     * prioritizing quality for closer/more important geometry.
+     * Target number of splats to render. The system will adjust LOD levels bidirectionally to
+     * reach this budget:
+     * - When over budget: degrades quality for less important geometry
+     * - When under budget: upgrades quality for more important geometry
+     *
+     * This ensures optimal use of available rendering budget while prioritizing quality for
+     * closer/more important geometry.
      *
      * Set to 0 to disable the budget (default). When disabled, optimal LOD is determined purely
      * by distance and configured LOD parameters.