@onerjs/core 8.55.8 → 8.55.9

package/Meshes/GaussianSplatting/gaussianSplattingMesh.pure.d.ts

@@ -28,6 +28,24 @@ interface IGaussianSplattingPartSource {
      */
     _isReservedEmpty?: boolean;
 }
+/**
+ * A LOD engine (e.g. a streamed part) that participates in a compound's shared splat budget. The compound
+ * apportions {@link GaussianSplattingMesh.splatBudget} (net of static parts) across all registered participants
+ * by demand and pushes each its allocation. Defined here (core) so the compound never depends on the loader's
+ * streaming engine; the engine implements this and registers via
+ * {@link GaussianSplattingMesh.registerLodBudgetParticipant}.
+ * @experimental
+ */
+export interface IGaussianSplattingLodBudgetParticipant {
+    /** The number of splats this participant would render at full (distance-optimal) detail — its budget demand. */
+    getBudgetDemand(): number;
+    /**
+     * Sets the participant's apportioned share of the compound budget (in splats). `null` clears coordination so
+     * the participant reverts to its own budget; `0` keeps it coordinated at the coarsest level.
+     * @param splats the apportioned splat allocation, or null to release coordination
+     */
+    setBudgetAllocation(splats: Nullable<number>): void;
+}
 /**
  * Handle to a region of a compound Gaussian Splatting mesh reserved for dynamic (streamed) content by
  * {@link GaussianSplattingMesh.reserveStreamingPart}. It lets a streaming engine populate the region's
@@ -161,6 +179,20 @@ export declare class GaussianSplattingMesh extends GaussianSplattingMeshBase {
     protected _hasStreamingPart: boolean;
     /** Mutable bookkeeping for each reserved streaming region, so {@link compactAtlas} can relocate them. */
     private _streamingStates;
+    /**
+     * Shared LOD splat budget for the whole compound (0 = disabled). When set, {@link _apportionBudget} divides it
+     * (net of static parts) across the registered {@link IGaussianSplattingLodBudgetParticipant}s each frame, so
+     * all hosted streams together stay within one cap. See {@link splatBudget}.
+     * Protected so {@link GaussianSplattingStream} can reuse it as its own per-stream budget.
+     */
+    protected _splatBudget: number;
+    /** LOD engines sharing {@link _splatBudget} (e.g. hosted streamed parts). */
+    private _lodBudgetParticipants;
+    /** Per-frame budget apportionment observer, installed only while a budget and participants are both present. */
+    private _budgetObserver;
+    private readonly _budgetDemands;
+    private readonly _budgetAlloc;
+    private readonly _budgetSettled;
     /**
      * Max SH degree contributed by the live (non-tombstoned) streaming parts. Recomputed by
      * {@link _refreshStreamingShState} whenever parts change, so removing the last SH stream turns the shared SH
@@ -284,6 +316,46 @@ export declare class GaussianSplattingMesh extends GaussianSplattingMeshBase {
      * Gets the number of parts in the compound.
      */
     get partCount(): number;
+    /**
+     * Shared LOD splat budget for the whole compound: a cap on the total splats its budget-participating LOD
+     * engines (hosted streamed parts) render together, net of static parts. `0`/undefined disables it (each stream
+     * uses its own budget, or none). Setting it apportions the cap across all registered participants by demand and
+     * takes effect on the next frame. See {@link IGaussianSplattingLodBudgetParticipant}.
+     * @experimental
+     */
+    get splatBudget(): number;
+    set splatBudget(value: number);
+    /**
+     * Registers a LOD engine to share this compound's {@link splatBudget}. The compound apportions the budget
+     * across all registered participants each frame. No-op if already registered.
+     * @param participant the LOD engine (e.g. a hosted streamed part)
+     * @experimental
+     */
+    registerLodBudgetParticipant(participant: IGaussianSplattingLodBudgetParticipant): void;
+    /**
+     * Removes a previously registered budget participant and releases its coordinated allocation (it reverts to its
+     * own budget).
+     * @param participant the LOD engine to remove
+     * @experimental
+     */
+    unregisterLodBudgetParticipant(participant: IGaussianSplattingLodBudgetParticipant): void;
+    /**
+     * Total splats contributed by static (non-streaming) parts — the fixed floor subtracted from the budget before
+     * the streamable remainder is apportioned. Streaming regions are excluded (their rendered count is LOD-driven).
+     * @returns the static parts' splat count
+     */
+    private _staticSplatCount;
+    /**
+     * Installs or removes the per-frame apportionment observer so it runs only while a budget and at least one
+     * participant are both present. When coordination turns off, participants are released to their own budgets.
+     */
+    private _updateBudgetCoordination;
+    /**
+     * Apportions {@link splatBudget} (net of {@link _staticSplatCount}) across the registered participants by demand
+     * via water-filling: each gets `min(demand, fairShare)` and any leftover is redistributed to the still-unmet
+     * ones. Pushes each participant its allocation.
+     */
+    private _apportionBudget;
     /**
      * Gets the part visibility array.
      */

package/Meshes/GaussianSplatting/gaussianSplattingMesh.pure.js

@@ -110,6 +110,21 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
         this._hasStreamingPart = false;
         /** Mutable bookkeeping for each reserved streaming region, so {@link compactAtlas} can relocate them. */
         this._streamingStates = [];
+        /**
+         * Shared LOD splat budget for the whole compound (0 = disabled). When set, {@link _apportionBudget} divides it
+         * (net of static parts) across the registered {@link IGaussianSplattingLodBudgetParticipant}s each frame, so
+         * all hosted streams together stay within one cap. See {@link splatBudget}.
+         * Protected so {@link GaussianSplattingStream} can reuse it as its own per-stream budget.
+         */
+        this._splatBudget = 0;
+        /** LOD engines sharing {@link _splatBudget} (e.g. hosted streamed parts). */
+        this._lodBudgetParticipants = [];
+        /** Per-frame budget apportionment observer, installed only while a budget and participants are both present. */
+        this._budgetObserver = null;
+        // Reused per-participant scratch for the per-frame water-fill (avoids allocating three arrays every frame).
+        this._budgetDemands = [];
+        this._budgetAlloc = [];
+        this._budgetSettled = [];
         /**
          * Max SH degree contributed by the live (non-tombstoned) streaming parts. Recomputed by
          * {@link _refreshStreamingShState} whenever parts change, so removing the last SH stream turns the shared SH
@@ -255,6 +270,11 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
      * @param doNotRecurse Set to true to not recurse into each children
      */
     dispose(doNotRecurse) {
+        if (this._budgetObserver) {
+            this.getScene().onBeforeRenderObservable.remove(this._budgetObserver);
+            this._budgetObserver = null;
+        }
+        this._lodBudgetParticipants = [];
         for (const proxy of this._partProxies) {
             proxy.dispose();
         }
@@ -366,6 +386,149 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
     get partCount() {
         return this._partMatrices.length;
     }
+    /**
+     * Shared LOD splat budget for the whole compound: a cap on the total splats its budget-participating LOD
+     * engines (hosted streamed parts) render together, net of static parts. `0`/undefined disables it (each stream
+     * uses its own budget, or none). Setting it apportions the cap across all registered participants by demand and
+     * takes effect on the next frame. See {@link IGaussianSplattingLodBudgetParticipant}.
+     * @experimental
+     */
+    get splatBudget() {
+        return this._splatBudget;
+    }
+    set splatBudget(value) {
+        const budget = value > 0 ? Math.floor(value) : 0;
+        if (budget === this._splatBudget) {
+            return;
+        }
+        this._splatBudget = budget;
+        this._updateBudgetCoordination();
+    }
+    /**
+     * Registers a LOD engine to share this compound's {@link splatBudget}. The compound apportions the budget
+     * across all registered participants each frame. No-op if already registered.
+     * @param participant the LOD engine (e.g. a hosted streamed part)
+     * @experimental
+     */
+    registerLodBudgetParticipant(participant) {
+        if (this._lodBudgetParticipants.indexOf(participant) === -1) {
+            this._lodBudgetParticipants.push(participant);
+            this._updateBudgetCoordination();
+        }
+    }
+    /**
+     * Removes a previously registered budget participant and releases its coordinated allocation (it reverts to its
+     * own budget).
+     * @param participant the LOD engine to remove
+     * @experimental
+     */
+    unregisterLodBudgetParticipant(participant) {
+        const i = this._lodBudgetParticipants.indexOf(participant);
+        if (i !== -1) {
+            this._lodBudgetParticipants.splice(i, 1);
+            participant.setBudgetAllocation(null);
+            this._updateBudgetCoordination();
+        }
+    }
+    /**
+     * Total splats contributed by static (non-streaming) parts — the fixed floor subtracted from the budget before
+     * the streamable remainder is apportioned. Streaming regions are excluded (their rendered count is LOD-driven).
+     * @returns the static parts' splat count
+     */
+    _staticSplatCount() {
+        let proxied = 0;
+        let sum = 0;
+        for (const proxy of this._partProxies) {
+            if (!proxy) {
+                continue;
+            }
+            proxied += proxy._vertexCount; // all proxies feed the legacy part-0 derivation below
+            // Count only static (non-streaming), non-tombstoned parts: streaming regions are LOD-driven, and a
+            // tombstoned part renders nothing (empty active range) until compaction reclaims its rows.
+            if (!this._streamingStates.some((s) => s.proxy === proxy) && !this._tombstonedPartIndices.has(proxy.partIndex)) {
+                sum += proxy._vertexCount;
+            }
+        }
+        // Legacy layout: the compound's own splat data is an implicit, unproxied part 0 (always static). Its count
+        // is the atlas total minus every proxied part — the same derivation used in _addPartsInternal. Excluded when
+        // part 0 has been tombstoned.
+        if (!this._partProxies[0] && !this._tombstonedPartIndices.has(0)) {
+            sum += Math.max(0, this._vertexCount - proxied);
+        }
+        return sum;
+    }
+    /**
+     * Installs or removes the per-frame apportionment observer so it runs only while a budget and at least one
+     * participant are both present. When coordination turns off, participants are released to their own budgets.
+     */
+    _updateBudgetCoordination() {
+        const active = this._splatBudget > 0 && this._lodBudgetParticipants.length > 0;
+        if (active && !this._budgetObserver) {
+            // Runs before the streams' own onBeforeRender LOD frames (the compound is created before its streams),
+            // so each stream reads a fresh allocation the same frame; a one-frame lag is harmless regardless.
+            this._budgetObserver = this.getScene().onBeforeRenderObservable.add(() => this._apportionBudget());
+        }
+        else if (!active && this._budgetObserver) {
+            this.getScene().onBeforeRenderObservable.remove(this._budgetObserver);
+            this._budgetObserver = null;
+            for (const participant of this._lodBudgetParticipants) {
+                participant.setBudgetAllocation(null);
+            }
+        }
+    }
+    /**
+     * Apportions {@link splatBudget} (net of {@link _staticSplatCount}) across the registered participants by demand
+     * via water-filling: each gets `min(demand, fairShare)` and any leftover is redistributed to the still-unmet
+     * ones. Pushes each participant its allocation.
+     */
+    _apportionBudget() {
+        const participants = this._lodBudgetParticipants;
+        if (this._splatBudget <= 0 || participants.length === 0) {
+            return;
+        }
+        const streamable = Math.max(0, this._splatBudget - this._staticSplatCount());
+        // Reuse the scratch arrays (resized in place) so this per-frame path allocates nothing for a stable participant set.
+        const n = participants.length;
+        const demands = this._budgetDemands;
+        const alloc = this._budgetAlloc;
+        const settled = this._budgetSettled;
+        demands.length = n;
+        alloc.length = n;
+        settled.length = n;
+        for (let i = 0; i < n; i++) {
+            demands[i] = Math.max(0, participants[i].getBudgetDemand());
+            alloc[i] = 0;
+            settled[i] = false;
+        }
+        let remaining = streamable;
+        let activeCount = participants.length;
+        // Water-fill: repeatedly satisfy every participant whose demand is at or below the equal share, then split
+        // the remainder among the rest. Terminates in ≤ participants.length passes.
+        for (let pass = 0; pass < participants.length && activeCount > 0 && remaining > 0; pass++) {
+            const share = remaining / activeCount;
+            let progressed = false;
+            for (let i = 0; i < participants.length; i++) {
+                if (!settled[i] && demands[i] <= share) {
+                    alloc[i] = demands[i];
+                    remaining -= demands[i];
+                    settled[i] = true;
+                    activeCount--;
+                    progressed = true;
+                }
+            }
+            if (!progressed) {
+                for (let i = 0; i < participants.length; i++) {
+                    if (!settled[i]) {
+                        alloc[i] = share;
+                    }
+                }
+                break;
+            }
+        }
+        for (let i = 0; i < participants.length; i++) {
+            participants[i].setBudgetAllocation(Math.floor(alloc[i]));
+        }
+    }
     /**
      * Gets the part visibility array.
      */
@@ -1813,7 +1976,7 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
                 const newPartIndex = proxyMesh.partIndex;
                 mesh._partProxies[newPartIndex] = proxyMesh;
                 mesh.setWorldMatrixForPart(newPartIndex, proxyMesh.getWorldMatrix());
-                mesh.setPartVisibility(newPartIndex, proxyMesh.visibility);
+                mesh.setPartVisibility(newPartIndex, proxyMesh.isEnabled() ? proxyMesh.visibility : 0);
             }
         }
         return mesh;