@babylonjs/loaders 9.19.1 → 9.20.1

package/SPLAT/gaussianSplattingWorkBuffer.js

@@ -1,3 +1,4 @@
+import { Logger } from "@babylonjs/core/Misc/logger.js";
 import { MultiRenderTarget } from "@babylonjs/core/Materials/Textures/multiRenderTarget.js";
 import { ShaderMaterial } from "@babylonjs/core/Materials/shaderMaterial.js";
 import { Constants } from "@babylonjs/core/Engines/constants.js";
@@ -5,13 +6,13 @@ import { Mesh } from "@babylonjs/core/Meshes/mesh.js";
 import { VertexData } from "@babylonjs/core/Meshes/mesh.vertexData.js";
 import { Color4 } from "@babylonjs/core/Maths/math.color.js";
 import { Vector3, Vector4 } from "@babylonjs/core/Maths/math.vector.js";
-import { GaussianSplattingWorkBufferVertexShaderGLSL, GaussianSplattingWorkBufferFragmentShaderGLSL, GaussianSplattingWorkBufferVertexShaderWGSL, GaussianSplattingWorkBufferFragmentShaderWGSL, GaussianSplattingWorkBufferRelayoutFragmentShaderGLSL, GaussianSplattingWorkBufferRelayoutFragmentShaderWGSL, GaussianSplattingWorkBufferRelayoutShaderName, } from "./gaussianSplattingWorkBufferShaders.js";
+import { GaussianSplattingWorkBufferVertexShaderGLSL, GaussianSplattingWorkBufferFragmentShaderGLSL, GaussianSplattingWorkBufferVertexShaderWGSL, GaussianSplattingWorkBufferFragmentShaderWGSL, GaussianSplattingWorkBufferRelayoutFragmentShaderGLSL, GaussianSplattingWorkBufferRelayoutFragmentShaderWGSL, GaussianSplattingWorkBufferRelayoutShaderName, GaussianSplattingWorkBufferShDecodeShaderName, GaussianSplattingWorkBufferShDecodeFragmentShaderGLSL, GaussianSplattingWorkBufferShDecodeFragmentShaderWGSL, GaussianSplattingWorkBufferShCopyShaderName, GaussianSplattingWorkBufferShCopyFragmentShaderGLSL, GaussianSplattingWorkBufferShCopyFragmentShaderWGSL, GaussianSplattingWorkBufferRotationDecodeShaderName, GaussianSplattingWorkBufferRotationDecodeFragmentShaderGLSL, GaussianSplattingWorkBufferRotationDecodeFragmentShaderWGSL, GaussianSplattingWorkBufferRotCopyShaderName, GaussianSplattingWorkBufferRotCopyFragmentShaderGLSL, GaussianSplattingWorkBufferRotCopyFragmentShaderWGSL, } from "./gaussianSplattingWorkBufferShaders.js";
 import { RawTexture } from "@babylonjs/core/Materials/Textures/rawTexture.js";
 /**
  * A unified, GPU-decoded Gaussian Splatting work buffer.
  *
  * Holds a square MRT texture set (centers / covA / covB / colors) sized to a fixed splat capacity
- * (PlayCanvas-style: `ceil(sqrt(capacity))`). Each streamed SOG file is decoded directly on the GPU
+ * (`ceil(sqrt(capacity))`). Each streamed SOG file is decoded directly on the GPU
  * (no CPU readback) into its allocated pixel range. The decoded textures are consumed unchanged by the
  * standard (non-SOG) Gaussian Splatting draw path.
  *
@@ -43,30 +44,271 @@ export class GaussianSplattingWorkBuffer {
     get textures() {
         return this._mrt.textures;
     }
+    /**
+     * The baked higher-order SH textures (packed-u32, one per `ceil(coeffs*3/16)`), consumed by the draw path's
+     * `computeSHWeighted`/`decompose` as `shTexture0..N`. Empty when SH decoding is not enabled.
+     */
+    get shTextures() {
+        return this._shMrts.map((m) => m.textures[0]);
+    }
+    /**
+     * The decoded rotation/scale textures ([rotationsA, rotationsB, rotationScale], half-float), consumed by the
+     * voxel-IBL path as `rotationsATexture`/`rotationsBTexture`/`rotationScaleTexture`. Empty when rotation decode
+     * is not enabled.
+     */
+    get rotationTextures() {
+        return this._rotMrt ? this._rotMrt.textures : [];
+    }
     /**
      * Creates a work buffer sized to hold `capacity` splats.
+     *
+     * Standalone (default): the work buffer creates and owns a square MRT sized `ceil(sqrt(capacity))`, with
+     * decodes addressed from splat 0.
+     *
+     * Hosted (`externalAtlas` provided): the work buffer decodes/reads back into an externally-owned MRT (a
+     * compound mesh's shared atlas) instead of creating its own. Decodes are placed at `externalAtlas.baseOffset`
+     * (the reserved region's first splat) and addressed over `externalAtlas.width` (the wide atlas width), so the
+     * streamed splats land in the compound's atlas and sort/draw together with the static parts.
      * @param scene hosting scene
      * @param capacity total number of splats the work buffer must address
+     * @param externalAtlas optional external atlas to decode into instead of creating an owned square MRT
+     * @param sh optional higher-order SH decode configuration. `textureCount = ceil(coeffs*3/16)` for the max SH
+     *   degree across the streamed files. Standalone: the work buffer creates that many owned single-attachment
+     *   integer render targets. Hosted: `externalMrts` are the compound's shared SH atlas targets (borrowed).
+     * @param rotationScale optional rotation/scale decode configuration (for voxel-IBL shadows). When present the
+     *   work buffer decodes each splat's rotation matrix + scale into a 3-attachment half-float target. Standalone:
+     *   the work buffer creates and owns that target. Hosted: `externalMrt` is the compound's shared rotation atlas.
      */
-    constructor(scene, capacity) {
+    constructor(scene, capacity, externalAtlas, sh, rotationScale) {
         // Relayout (defrag) copy material, created lazily on first relayout.
         this._copyMaterial = null;
         // Reusable destination->source index map for the relayout pass (created lazily, sized to the work buffer).
         this._relayoutMapData = null;
         this._relayoutMapTexture = null;
+        // Transient backup of a hosted region's four textures, held between backupRegion() and restoreRegion() so the
+        // GPU-decoded data survives the compound recreating its atlas on a grow (adding a part / a second stream).
+        this._backupMrt = null;
         this._disposed = false;
         // Reused WebGL framebuffer for the async centers readback (created lazily, freed in dispose).
         this._readFbo = null;
+        // Higher-order spherical-harmonics. Each SH texture is its own single-attachment integer render target
+        // (RGBA_INTEGER/UNSIGNED_INTEGER, 16 SH scalar-bytes per texel) so a decode/relayout pass writes exactly one
+        // attachment, keeping within WebGPU's per-sample color-attachment byte budget. Empty when SH is off.
+        this._shMrts = [];
+        // True when this work buffer owns (and disposes) its SH render targets (standalone). False when they are the
+        // hosting compound's shared SH atlas (hosted) — borrowed, not disposed. Rebound alongside the core atlas.
+        this._ownsShMrts = false;
+        // The SH decode material (packed-u32 dequant), created only when SH is requested. Reused across files/passes.
+        this._shMaterial = null;
+        // Integer SH relayout/backup copy material (usampler2D -> uvec4), created lazily alongside the float copy.
+        this._shCopyMaterial = null;
+        // Transient region-sized integer backups of the SH textures, held between backupRegion() and restoreRegion()
+        // so the baked SH survives the compound recreating its SH atlas on a grow/compaction (parallel to _backupMrt).
+        this._backupShMrts = null;
+        // Rotation/scale. One 3-attachment half-float render target (rotA / rotB / rotScale) holding the per-splat
+        // rotation matrix + scale that voxel-based IBL shadowing consumes. Null when rotation decode is off.
+        this._rotMrt = null;
+        // True when this work buffer owns (and disposes) its rotation target (standalone). False when it is the hosting
+        // compound's shared rotation atlas (hosted) — borrowed, rebound alongside the core atlas, never disposed here.
+        this._ownsRotMrt = false;
+        // The rotation/scale decode material, created only when rotation is requested. Reused across files.
+        this._rotMaterial = null;
+        // Rotation/scale relayout/backup copy material (3-out float copy), created lazily alongside the float copy.
+        this._rotCopyMaterial = null;
+        // Transient region-sized backup of the rotation textures, held between backupRegion() and restoreRegion() so the
+        // decoded rotation/scale survives the compound recreating its rotation atlas on a grow/compaction.
+        this._backupRotMrt = null;
         this._scene = scene;
         this._shaderLanguage = scene.getEngine().isWebGPU ? 1 /* ShaderLanguage.WGSL */ : 0 /* ShaderLanguage.GLSL */;
-        this._textureSize = Math.max(1, Math.ceil(Math.sqrt(Math.max(1, capacity))));
-        // The decode buffer accumulates (clear disabled) so each decode preserves previously-decoded files.
-        this._mrt = this._createMrt("gsWorkBuffer", true);
+        this._capacity = Math.max(1, capacity);
+        if (externalAtlas) {
+            this._mrt = externalAtlas.mrt;
+            this._textureSize = externalAtlas.width;
+            this._baseOffset = externalAtlas.baseOffset;
+            this._ownsMrt = false;
+        }
+        else {
+            this._textureSize = Math.max(1, Math.ceil(Math.sqrt(Math.max(1, capacity))));
+            this._baseOffset = 0;
+            this._ownsMrt = true;
+            // The decode buffer accumulates (clear disabled) so each decode preserves previously-decoded files.
+            this._mrt = this._createMrt("gsWorkBuffer", true);
+        }
+        // Higher-order SH: one single-attachment integer target per packed-u32 SH texture. Standalone owns square
+        // targets sized like the core atlas; hosted borrows the compound's wide shared SH atlas targets.
+        if (sh && sh.textureCount > 0) {
+            if (sh.externalMrts) {
+                this._shMrts = sh.externalMrts.slice(0, sh.textureCount);
+                this._ownsShMrts = false;
+            }
+            else {
+                for (let k = 0; k < sh.textureCount; k++) {
+                    this._shMrts.push(this._createShMrt(`gsWorkBufferSh${k}`, true));
+                }
+                this._ownsShMrts = true;
+            }
+            this._shMaterial = this._createShMaterial();
+        }
+        // Rotation/scale: one 3-attachment half-float target. Standalone owns a square target sized like the core
+        // atlas; hosted borrows the compound's wide shared rotation atlas.
+        if (rotationScale) {
+            if (rotationScale.externalMrt) {
+                this._rotMrt = rotationScale.externalMrt;
+                this._ownsRotMrt = false;
+            }
+            else {
+                this._rotMrt = this._createRotMrt("gsWorkBufferRot", true);
+                this._ownsRotMrt = true;
+            }
+            this._rotMaterial = this._createRotMaterial();
+        }
         // One persistent decode material + fullscreen-triangle quad, reused (with per-file uniforms)
         // for every decode so the shader is compiled only once.
         this._material = this._createMaterial();
         this._quad = this._createQuad();
         this._quad.material = this._material;
+        // Hosted: start compiling the copy shader now so backupRegion()/restoreRegion() are ready by the time
+        // the compound grows its atlas (a synchronous, non-frame-driven event we can't wait on).
+        if (!this._ownsMrt) {
+            this.isRelayoutReady();
+        }
+    }
+    /**
+     * Rebinds a hosted work buffer to a new atlas MRT (after the compound recreated it on a grow). No-op for a
+     * standalone work buffer, which owns its MRT.
+     * @param mrt the compound's new shared atlas
+     */
+    rebindAtlas(mrt) {
+        if (!this._ownsMrt) {
+            this._mrt = mrt;
+        }
+    }
+    /**
+     * Rebinds a hosted work buffer to the compound's NEW shared SH atlas (after the compound recreated it on a
+     * grow/compaction). No-op when SH isn't in use or the work buffer owns its SH targets (standalone).
+     * @param shMrts the compound's new shared SH render targets (one per packed-u32 SH texture)
+     */
+    rebindShAtlas(shMrts) {
+        if (!this._ownsShMrts && shMrts && this._shMrts.length) {
+            this._shMrts = shMrts.slice(0, this._shMrts.length);
+        }
+    }
+    /**
+     * Rebinds a hosted work buffer to the compound's NEW shared rotation atlas (after the compound recreated it on a
+     * grow/compaction). No-op when rotation isn't in use or the work buffer owns its rotation target (standalone).
+     * @param rotMrt the compound's new shared rotation atlas
+     */
+    rebindRotAtlas(rotMrt) {
+        if (!this._ownsRotMrt && rotMrt && this._rotMrt) {
+            this._rotMrt = rotMrt;
+        }
+    }
+    /**
+     * Relocates this hosted region to a new base splat offset in the shared atlas (used when the compound
+     * compacts its atlas and this region's rows move). Subsequent decode/render/readback and
+     * {@link restoreRegion} all address from the new base. Call between {@link backupRegion} (which read from
+     * the old base) and {@link restoreRegion} (which will write to the new base). No-op for a standalone
+     * work buffer, which owns its square MRT at base 0.
+     * @param baseOffset the region's new first splat index in the atlas
+     */
+    setBaseOffset(baseOffset) {
+        if (!this._ownsMrt) {
+            this._baseOffset = baseOffset;
+        }
+    }
+    /**
+     * True once the backup/restore/relayout copy shaders are compiled, so {@link backupRegion} can preserve the
+     * region across an atlas rebuild. Callers that decode into a hosted region should await this before writing
+     * data, so a later grow/compaction can never race shader compilation and drop the region.
+     */
+    get canBackup() {
+        return this._disposed || this._ownsMrt ? false : this.isRelayoutReady();
+    }
+    /**
+     * Copies this hosted region's four decoded textures out of the shared atlas into an internal backup MRT so
+     * they survive the compound recreating the atlas on a grow. Call immediately before the atlas is recreated,
+     * then {@link rebindAtlas} + {@link restoreRegion} after.
+     */
+    backupRegion() {
+        if (this._disposed || this._ownsMrt) {
+            return;
+        }
+        if (!this.isRelayoutReady()) {
+            // The copy shaders should be compiled well before any grow (callers warm them before decoding), so this
+            // path means a grow raced compilation; warn rather than silently drop the region's GPU data on the restore.
+            Logger.Warn("GaussianSplattingWorkBuffer: backup skipped because the copy shaders are not ready; streamed region data may be lost on the atlas rebuild.");
+            return;
+        }
+        const width = this._textureSize;
+        const regionRows = Math.max(1, Math.floor(this._capacity / width));
+        const baseRow = Math.floor(this._baseOffset / width);
+        if (!this._backupMrt) {
+            this._backupMrt = this._createMrt("gsAtlasBackup", false, width, regionRows);
+        }
+        // Identity copy of the region out of the atlas: with useMap=0 and dstBaseRow=-baseRow the shader reads
+        // atlas texel ((p.y + baseRow) * width + p.x) — the region's global texel — into backup texel p.
+        this._renderRelayoutPass(this._backupMrt, this._mrt.textures, this._mrt.textures[0], 0, width, width, 0, -baseRow);
+        // Same for each baked SH texture (one integer copy pass per texture).
+        if (this._shMrts.length && this._shCopyMaterial) {
+            if (!this._backupShMrts) {
+                this._backupShMrts = this._shMrts.map((_, k) => this._createShMrt(`gsShAtlasBackup${k}`, false, width, regionRows));
+            }
+            for (let k = 0; k < this._shMrts.length; k++) {
+                this._renderShCopyPass(this._backupShMrts[k], this._shMrts[k].textures[0], this._mrt.textures[0], 0, width, width, 0, -baseRow);
+            }
+        }
+        // Same for the rotation/scale textures (one 3-out float copy pass).
+        if (this._rotMrt && this._rotCopyMaterial) {
+            if (!this._backupRotMrt) {
+                this._backupRotMrt = this._createRotMrt("gsRotAtlasBackup", false, width, regionRows);
+            }
+            this._renderRotCopyPass(this._backupRotMrt, this._rotMrt.textures, this._mrt.textures[0], 0, width, width, 0, -baseRow);
+        }
+        this._quad.material = this._material;
+    }
+    /**
+     * Restores the backed-up region into the (new) atlas, confined by a scissor to the region's rows so no other
+     * part is touched. Call {@link rebindAtlas} to the new atlas first. Frees the backup afterwards.
+     */
+    restoreRegion() {
+        if (this._disposed || this._ownsMrt || !this._backupMrt || !this._copyMaterial) {
+            return;
+        }
+        const width = this._textureSize;
+        const regionRows = Math.max(1, Math.floor(this._capacity / width));
+        const baseRow = Math.floor(this._baseOffset / width);
+        const engine = this._scene.getEngine();
+        engine.enableScissor(0, baseRow, width, regionRows);
+        try {
+            // useMap=0 identity with dstBaseRow=baseRow: atlas texel p reads backup texel ((p.y - baseRow)*width + p.x).
+            this._renderRelayoutPass(this._mrt, this._backupMrt.textures, this._backupMrt.textures[0], 0, width, width, 0, baseRow);
+            // Restore each baked SH texture the same way (scissored to the region's rows). The map placeholder must
+            // be a FLOAT texture (uMapTex is texture_2d<f32>) even though useMap=0 doesn't sample it — WebGPU still
+            // validates the bound texture's sample type against the layout. Use the atlas centers (F32).
+            if (this._backupShMrts && this._shMrts.length && this._shCopyMaterial) {
+                for (let k = 0; k < this._shMrts.length && k < this._backupShMrts.length; k++) {
+                    this._renderShCopyPass(this._shMrts[k], this._backupShMrts[k].textures[0], this._mrt.textures[0], 0, width, width, 0, baseRow);
+                }
+            }
+            // Restore the rotation/scale textures the same way (3-out float copy, scissored to the region's rows).
+            if (this._backupRotMrt && this._rotMrt && this._rotCopyMaterial) {
+                this._renderRotCopyPass(this._rotMrt, this._backupRotMrt.textures, this._mrt.textures[0], 0, width, width, 0, baseRow);
+            }
+        }
+        finally {
+            engine.disableScissor();
+            this._quad.material = this._material;
+        }
+        this._backupMrt.dispose();
+        this._backupMrt = null;
+        if (this._backupShMrts) {
+            for (const mrt of this._backupShMrts) {
+                mrt.dispose();
+            }
+            this._backupShMrts = null;
+        }
+        this._backupRotMrt?.dispose();
+        this._backupRotMrt = null;
     }
     /**
      * Creates a 4-attachment MRT (centers F32 / covA / covB / colors U8) sized to the work buffer. covA/covB
@@ -77,11 +319,13 @@ export class GaussianSplattingWorkBuffer {
      * @param name MRT and attachment base name
      * @param disableClear when true, clearing is suppressed so renders accumulate (the decode buffer); when
      *   false the MRT clears to zero on each render (the temporary relayout buffer, so gaps stay zeroed)
+     * @param width texture width (defaults to the work-buffer size; the region row width for a scoped relayout)
+     * @param height texture height (defaults to the work-buffer size; the region row count for a scoped relayout)
      * @returns the created MRT
      */
-    _createMrt(name, disableClear) {
+    _createMrt(name, disableClear, width = this._textureSize, height = this._textureSize) {
         const covType = this._scene.getEngine()._caps.textureHalfFloatRender ? Constants.TEXTURETYPE_HALF_FLOAT : Constants.TEXTURETYPE_FLOAT;
-        const mrt = new MultiRenderTarget(name, { width: this._textureSize, height: this._textureSize }, 4, this._scene, {
+        const mrt = new MultiRenderTarget(name, { width, height }, 4, this._scene, {
             types: [Constants.TEXTURETYPE_FLOAT, covType, covType, Constants.TEXTURETYPE_UNSIGNED_BYTE],
             samplingModes: [
                 Constants.TEXTURE_NEAREST_SAMPLINGMODE,
@@ -101,6 +345,59 @@ export class GaussianSplattingWorkBuffer {
         }
         return mrt;
     }
+    /**
+     * Creates a single-attachment integer render target (RGBA_INTEGER / UNSIGNED_INTEGER) that holds one packed-u32
+     * baked-SH texture. One attachment per pass keeps within WebGPU's per-sample color-attachment byte budget and
+     * matches the format/type of the draw path's `shTexture0..N` samplers (`_GaussianSplattingBytesPerShTexel`).
+     * @param name attachment name
+     * @param disableClear when true, clearing is suppressed so SH decodes accumulate across files
+     * @param width texture width (defaults to the work-buffer size)
+     * @param height texture height (defaults to the work-buffer size)
+     * @returns the created single-attachment integer MRT
+     */
+    _createShMrt(name, disableClear, width = this._textureSize, height = this._textureSize) {
+        const mrt = new MultiRenderTarget(name, { width, height }, 1, this._scene, {
+            types: [Constants.TEXTURETYPE_UNSIGNED_INTEGER],
+            formats: [Constants.TEXTUREFORMAT_RGBA_INTEGER],
+            samplingModes: [Constants.TEXTURE_NEAREST_SAMPLINGMODE],
+            generateDepthBuffer: false,
+            generateDepthTexture: false,
+            generateMipMaps: false,
+        }, [name]);
+        mrt.clearColor = new Color4(0, 0, 0, 0);
+        mrt.renderList = [];
+        if (disableClear) {
+            mrt.onClearObservable.add(() => { });
+        }
+        return mrt;
+    }
+    /**
+     * Creates a 3-attachment half-float MRT ([rotA, rotB, rotScale]) holding the per-splat rotation matrix + scale
+     * consumed by voxel-IBL shadowing. RGBA half-float when the engine can render to it (matching the covariance
+     * precision), else full float. 3 attachments = 24 B/sample, within WebGPU's per-sample budget (its own pass).
+     * @param name MRT and attachment base name
+     * @param disableClear when true, clearing is suppressed so decodes accumulate (the decode buffer)
+     * @param width texture width (defaults to the work-buffer size; the region row width for a scoped relayout)
+     * @param height texture height (defaults to the work-buffer size; the region row count for a scoped relayout)
+     * @returns the created MRT
+     */
+    _createRotMrt(name, disableClear, width = this._textureSize, height = this._textureSize) {
+        const rotType = this._scene.getEngine()._caps.textureHalfFloatRender ? Constants.TEXTURETYPE_HALF_FLOAT : Constants.TEXTURETYPE_FLOAT;
+        const mrt = new MultiRenderTarget(name, { width, height }, 3, this._scene, {
+            types: [rotType, rotType, rotType],
+            formats: [Constants.TEXTUREFORMAT_RGBA, Constants.TEXTUREFORMAT_RGBA, Constants.TEXTUREFORMAT_RGBA],
+            samplingModes: [Constants.TEXTURE_NEAREST_SAMPLINGMODE, Constants.TEXTURE_NEAREST_SAMPLINGMODE, Constants.TEXTURE_NEAREST_SAMPLINGMODE],
+            generateDepthBuffer: false,
+            generateDepthTexture: false,
+            generateMipMaps: false,
+        }, [`${name}A`, `${name}B`, `${name}Scale`]);
+        mrt.clearColor = new Color4(0, 0, 0, 0);
+        mrt.renderList = [];
+        if (disableClear) {
+            mrt.onClearObservable.add(() => { });
+        }
+        return mrt;
+    }
     /**
      * Decodes one SOG file into the work buffer at the given splat offset (accumulating; previously
      * decoded files are preserved). Resolves once the GPU decode has been issued. The caller may
@@ -112,7 +409,17 @@ export class GaussianSplattingWorkBuffer {
         if (this._disposed) {
             return;
         }
-        this._applyPack(pack, offset);
+        this._applyPack(pack);
+        // When SH is enabled, bake EVERY file's region — even a file with no higher-order SH (a coarse LOD may drop
+        // it): those get uCoeffs=0 so the whole region neutral-fills (128), keeping mixed-degree files consistent.
+        const decodeSh = this._shMaterial !== null && this._shMrts.length > 0;
+        if (decodeSh) {
+            this._applyShPack(pack);
+        }
+        const decodeRot = this._rotMaterial !== null && this._rotMrt !== null;
+        if (decodeRot) {
+            this._applyRotPack(pack);
+        }
         // Render the decode pass at the start of a frame (the safe point for custom render targets),
         // once the shader is compiled — never re-entrantly from a promise/observable continuation.
         await new Promise((resolve) => {
@@ -121,12 +428,54 @@ export class GaussianSplattingWorkBuffer {
                     resolve();
                     return;
                 }
-                if (!this._material.isReady(this._quad)) {
+                if (!this._material.isReady(this._quad) || (decodeSh && !this._shMaterial.isReady(this._quad)) || (decodeRot && !this._rotMaterial.isReady(this._quad))) {
                     this._scene.onBeforeRenderObservable.addOnce(attempt);
                     return;
                 }
-                this._mrt.renderList = [this._quad];
-                this._mrt.render();
+                // Scissor every pass to just this file's atlas rows so the fullscreen triangle only shades the region
+                // it writes, not the whole (wide) atlas. Correct because the shaders already discard outside the exact
+                // splat range, and the row band is a superset of it.
+                const width = this._textureSize;
+                // Bind uOffset at render time from the live _baseOffset so it shares one value with the scissor below:
+                // compactAtlas() can relocate this region (via setBaseOffset) during the defer window.
+                const globalOffset = this._baseOffset + offset;
+                this._material.setInt("uOffset", globalOffset);
+                if (decodeSh) {
+                    this._shMaterial.setInt("uOffset", globalOffset);
+                }
+                if (decodeRot) {
+                    this._rotMaterial.setInt("uOffset", globalOffset);
+                }
+                const firstRow = Math.floor(globalOffset / width);
+                const rowCount = Math.max(1, Math.ceil((globalOffset + pack.splatCount) / width) - firstRow);
+                const engine = this._scene.getEngine();
+                engine.enableScissor(0, firstRow, width, rowCount);
+                try {
+                    this._quad.material = this._material;
+                    this._mrt.renderList = [this._quad];
+                    this._mrt.render();
+                    // Bake this file's higher-order SH: one pass per packed-u32 SH texture (uShTextureIndex selects the
+                    // 16 SH scalars written this pass). Files with fewer coefficients neutral-fill (128) higher bands.
+                    if (decodeSh) {
+                        for (let k = 0; k < this._shMrts.length; k++) {
+                            this._shMaterial.setInt("uShTextureIndex", k);
+                            this._quad.material = this._shMaterial;
+                            this._shMrts[k].renderList = [this._quad];
+                            this._shMrts[k].render();
+                        }
+                        this._quad.material = this._material;
+                    }
+                    // Bake this file's rotation/scale into the 3-attachment half-float rotation target (one pass).
+                    if (decodeRot) {
+                        this._quad.material = this._rotMaterial;
+                        this._rotMrt.renderList = [this._quad];
+                        this._rotMrt.render();
+                        this._quad.material = this._material;
+                    }
+                }
+                finally {
+                    engine.disableScissor();
+                }
                 resolve();
             };
             this._scene.onBeforeRenderObservable.addOnce(attempt);
@@ -144,7 +493,46 @@ export class GaussianSplattingWorkBuffer {
         if (!this._copyMaterial) {
             this._copyMaterial = this._createCopyMaterial();
         }
-        return this._copyMaterial.isReady(this._quad);
+        // When SH is in use, the integer copy shader must also be compiled before a backup/restore/relayout can run.
+        if (this._shMrts.length && !this._shCopyMaterial) {
+            this._shCopyMaterial = this._createShCopyMaterial();
+        }
+        // Same for the rotation/scale 3-out float copy shader when rotation is in use.
+        if (this._rotMrt && !this._rotCopyMaterial) {
+            this._rotCopyMaterial = this._createRotCopyMaterial();
+        }
+        // `isReady` reports "not ready" when a bound sampler points at a disposed texture (a previous backup/relayout
+        // binds its temp MRTs as sources, then frees them). The copy passes bind fresh textures every call, so re-point
+        // the materials at the live atlas textures first; the check then reflects only whether the shader compiled.
+        this._bindCopyMaterialsToAtlas();
+        const shReady = this._shMrts.length === 0 || (this._shCopyMaterial !== null && this._shCopyMaterial.isReady(this._quad));
+        const rotReady = !this._rotMrt || (this._rotCopyMaterial !== null && this._rotCopyMaterial.isReady(this._quad));
+        return this._copyMaterial.isReady(this._quad) && shReady && rotReady;
+    }
+    /**
+     * Re-points the relayout/backup copy materials' samplers at the live atlas textures (valid, never freed), so a
+     * later {@link isRelayoutReady} check isn't tripped by a stale binding to a disposed temp/backup MRT.
+     */
+    _bindCopyMaterialsToAtlas() {
+        const t = this._mrt.textures;
+        if (this._copyMaterial) {
+            this._copyMaterial.setTexture("uMapTex", t[0]);
+            this._copyMaterial.setTexture("uSrc0", t[0]);
+            this._copyMaterial.setTexture("uSrc1", t[1]);
+            this._copyMaterial.setTexture("uSrc2", t[2]);
+            this._copyMaterial.setTexture("uSrc3", t[3]);
+        }
+        if (this._shCopyMaterial && this._shMrts.length) {
+            this._shCopyMaterial.setTexture("uMapTex", t[0]);
+            this._shCopyMaterial.setTexture("uSrcSh", this._shMrts[0].textures[0]);
+        }
+        if (this._rotCopyMaterial && this._rotMrt) {
+            const r = this._rotMrt.textures;
+            this._rotCopyMaterial.setTexture("uMapTex", t[0]);
+            this._rotCopyMaterial.setTexture("uSrc0", r[0]);
+            this._rotCopyMaterial.setTexture("uSrc1", r[1]);
+            this._rotCopyMaterial.setTexture("uSrc2", r[2]);
+        }
     }
     /**
      * Relayouts the decoded work-buffer textures to a new (defragmented) splat layout, keeping the same
@@ -159,32 +547,104 @@ export class GaussianSplattingWorkBuffer {
         if (this._disposed || !this._copyMaterial) {
             return;
         }
-        const size = this._textureSize;
-        // Reuse the map buffer and its GPU texture across relayouts (the work-buffer size is fixed).
+        // Map dimensions: standalone maps the whole square buffer; hosted maps just the region's rows.
+        const width = this._textureSize;
+        const mapW = width;
+        const mapH = this._ownsMrt ? width : Math.max(1, Math.floor(this._capacity / width));
+        // Reuse the map buffer + its GPU texture across relayouts (dimensions are fixed for a work buffer).
         if (!this._relayoutMapData) {
-            this._relayoutMapData = new Float32Array(size * size);
+            this._relayoutMapData = new Float32Array(mapW * mapH);
         }
         const mapData = this._relayoutMapData;
         mapData.fill(-1);
         mapData.set(srcIndexByDst.subarray(0, Math.min(srcIndexByDst.length, mapData.length)));
         if (!this._relayoutMapTexture) {
-            this._relayoutMapTexture = new RawTexture(mapData, size, size, Constants.TEXTUREFORMAT_R, this._scene, false, false, Constants.TEXTURE_NEAREST_SAMPLINGMODE, Constants.TEXTURETYPE_FLOAT);
+            this._relayoutMapTexture = new RawTexture(mapData, mapW, mapH, Constants.TEXTUREFORMAT_R, this._scene, false, false, Constants.TEXTURE_NEAREST_SAMPLINGMODE, Constants.TEXTURETYPE_FLOAT);
         }
         else {
             this._relayoutMapTexture.update(mapData);
         }
         const mapTexture = this._relayoutMapTexture;
-        // The temporary ping-pong MRT is (re)created per relayout rather than kept resident: it is the same size
-        // as the work buffer, so a persistent copy would double GPU memory and defeat the streaming memory budget.
-        const temp = this._createMrt("gsRelayoutTemp", false);
+        if (this._ownsMrt) {
+            // Standalone: the work buffer owns the whole square texture, so a full ping-pong is safe.
+            const temp = this._createMrt("gsRelayoutTemp", false);
+            try {
+                this._renderRelayoutPass(temp, this._mrt.textures, mapTexture, 1); // old -> temp via map (gaps cleared)
+                this._renderRelayoutPass(this._mrt, temp.textures, mapTexture, 0); // temp -> old, identity full overwrite
+            }
+            finally {
+                temp.dispose();
+            }
+            // Same ping-pong for each baked SH texture (integer copy, one temp per texture).
+            if (this._shMrts.length && this._shCopyMaterial) {
+                for (let k = 0; k < this._shMrts.length; k++) {
+                    const shTemp = this._createShMrt("gsShRelayoutTemp", false);
+                    try {
+                        this._renderShCopyPass(shTemp, this._shMrts[k].textures[0], mapTexture, 1);
+                        this._renderShCopyPass(this._shMrts[k], shTemp.textures[0], mapTexture, 0);
+                    }
+                    finally {
+                        shTemp.dispose();
+                    }
+                }
+            }
+            // Same ping-pong for the rotation/scale textures (3-out float copy).
+            if (this._rotMrt && this._rotCopyMaterial) {
+                const rotTemp = this._createRotMrt("gsRotRelayoutTemp", false);
+                try {
+                    this._renderRotCopyPass(rotTemp, this._rotMrt.textures, mapTexture, 1);
+                    this._renderRotCopyPass(this._rotMrt, rotTemp.textures, mapTexture, 0);
+                }
+                finally {
+                    rotTemp.dispose();
+                }
+            }
+            this._quad.material = this._material;
+            return;
+        }
+        // Hosted (shared compound atlas): scope the ping-pong to THIS region's row band so other parts are never
+        // touched. `_baseOffset` and `_capacity` are row-aligned (reserveStreamingPart), so the band is exact.
+        const baseRow = Math.floor(this._baseOffset / width);
+        const regionRows = mapH;
+        const engine = this._scene.getEngine();
+        // Region-sized temp (width x regionRows) — memory stays proportional to the region, not the whole atlas.
+        const temp = this._createMrt("gsRelayoutTemp", false, width, regionRows);
+        // One region-sized integer temp per baked SH texture (same ping-pong, integer format).
+        const shTemps = this._shMrts.length && this._shCopyMaterial ? this._shMrts.map((_, k) => this._createShMrt(`gsShRelayoutTemp${k}`, false, width, regionRows)) : [];
+        // One region-sized rotation temp (3-attachment float) when rotation is in use.
+        const rotTemp = this._rotMrt && this._rotCopyMaterial ? this._createRotMrt("gsRotRelayoutTemp", false, width, regionRows) : null;
         try {
-            // Pass 1: old -> temp using the map (temp gets the new layout; gaps stay zeroed by the clear).
-            this._renderRelayoutPass(temp, this._mrt.textures, mapTexture, 1);
-            // Pass 2: temp -> old, identity (old textures get the new layout, full overwrite).
-            this._renderRelayoutPass(this._mrt, temp.textures, mapTexture, 0);
+            // Pass 1: atlas region -> temp via map. The map is region-local; uSrcBaseOffset shifts each source
+            // index to its GLOBAL atlas texel (uSrcWidth = atlas width). Temp is exactly the band, so no scissor.
+            this._renderRelayoutPass(temp, this._mrt.textures, mapTexture, 1, /*dstWidth*/ width, /*srcWidth*/ width, /*srcBaseOffset*/ this._baseOffset, /*dstBaseRow*/ 0);
+            for (let k = 0; k < shTemps.length; k++) {
+                this._renderShCopyPass(shTemps[k], this._shMrts[k].textures[0], mapTexture, 1, width, width, this._baseOffset, 0);
+            }
+            if (rotTemp) {
+                this._renderRotCopyPass(rotTemp, this._rotMrt.textures, mapTexture, 1, width, width, this._baseOffset, 0);
+            }
+            // Pass 2: temp -> atlas region, identity within the band. uDstBaseRow maps the atlas destination row
+            // back into the region-local temp; the scissor confines writes to the band so static parts are safe.
+            engine.enableScissor(0, baseRow, width, regionRows);
+            try {
+                this._renderRelayoutPass(this._mrt, temp.textures, mapTexture, 0, /*dstWidth*/ width, /*srcWidth*/ width, /*srcBaseOffset*/ 0, /*dstBaseRow*/ baseRow);
+                for (let k = 0; k < shTemps.length; k++) {
+                    this._renderShCopyPass(this._shMrts[k], shTemps[k].textures[0], mapTexture, 0, width, width, 0, baseRow);
+                }
+                if (rotTemp) {
+                    this._renderRotCopyPass(this._rotMrt, rotTemp.textures, mapTexture, 0, width, width, 0, baseRow);
+                }
+            }
+            finally {
+                engine.disableScissor();
+            }
         }
         finally {
             temp.dispose();
+            for (const t of shTemps) {
+                t.dispose();
+            }
+            rotTemp?.dispose();
             this._quad.material = this._material;
         }
     }
@@ -192,19 +652,25 @@ export class GaussianSplattingWorkBuffer {
      * Renders one relayout copy pass into the target MRT, sampling the given source textures.
      * @param target destination MRT
      * @param sources the four source work-buffer textures
-     * @param mapTexture the R32F destination-to-source index map
+     * @param mapTexture the R32F destination-to-source index map (only sampled when `useMap` is 1; any bound texture otherwise)
      * @param useMap 1 to read source indices from the map (gaps discarded), 0 for an identity copy
+     * @param dstWidth destination width used to linearize the destination texel (defaults to the work-buffer size)
+     * @param srcWidth source width used to convert a linear source index to a texel (defaults to the work-buffer size)
+     * @param srcBaseOffset added to each mapped source index so a region-local map reads the correct global atlas texel (hosted relayout)
+     * @param dstBaseRow subtracted from the destination row so an identity copy reads the region-local temp (hosted relayout)
      */
-    _renderRelayoutPass(target, sources, mapTexture, useMap) {
+    _renderRelayoutPass(target, sources, mapTexture, useMap, dstWidth = this._textureSize, srcWidth = this._textureSize, srcBaseOffset = 0, dstBaseRow = 0) {
         const material = this._copyMaterial;
         material.setTexture("uMapTex", mapTexture);
         material.setTexture("uSrc0", sources[0]);
         material.setTexture("uSrc1", sources[1]);
         material.setTexture("uSrc2", sources[2]);
         material.setTexture("uSrc3", sources[3]);
-        material.setInt("uDstWidth", this._textureSize);
-        material.setInt("uSrcWidth", this._textureSize);
+        material.setInt("uDstWidth", dstWidth);
+        material.setInt("uSrcWidth", srcWidth);
         material.setInt("uUseMap", useMap);
+        material.setInt("uSrcBaseOffset", srcBaseOffset);
+        material.setInt("uDstBaseRow", dstBaseRow);
         this._quad.material = material;
         target.renderList = [this._quad];
         target.render();
@@ -216,7 +682,7 @@ export class GaussianSplattingWorkBuffer {
             fragmentSource: isWGSL ? GaussianSplattingWorkBufferRelayoutFragmentShaderWGSL : GaussianSplattingWorkBufferRelayoutFragmentShaderGLSL,
         }, {
             attributes: ["position"],
-            uniforms: ["uDstWidth", "uSrcWidth", "uUseMap"],
+            uniforms: ["uDstWidth", "uSrcWidth", "uUseMap", "uSrcBaseOffset", "uDstBaseRow"],
             samplers: ["uMapTex", "uSrc0", "uSrc1", "uSrc2", "uSrc3"],
             shaderLanguage: this._shaderLanguage,
         });
@@ -224,6 +690,88 @@ export class GaussianSplattingWorkBuffer {
         material.disableDepthWrite = true;
         return material;
     }
+    /**
+     * Renders one INTEGER SH copy pass (one packed-u32 SH texture) into the target, sampling one integer source.
+     * Same index/map/base math as {@link _renderRelayoutPass} but for the integer SH format.
+     * @param target destination single-attachment integer MRT
+     * @param srcSh the integer SH source texture
+     * @param mapTexture the R32F destination-to-source index map (sampled only when `useMap` is 1)
+     * @param useMap 1 to read source indices from the map (gaps discarded), 0 for an identity copy
+     * @param dstWidth destination width used to linearize the destination texel
+     * @param srcWidth source width used to convert a linear source index to a texel
+     * @param srcBaseOffset added to each mapped source index (region-local map -> global atlas texel)
+     * @param dstBaseRow subtracted from the destination row for an identity copy of a region-local temp
+     */
+    _renderShCopyPass(target, srcSh, mapTexture, useMap, dstWidth = this._textureSize, srcWidth = this._textureSize, srcBaseOffset = 0, dstBaseRow = 0) {
+        const material = this._shCopyMaterial;
+        material.setTexture("uMapTex", mapTexture);
+        material.setTexture("uSrcSh", srcSh);
+        material.setInt("uDstWidth", dstWidth);
+        material.setInt("uSrcWidth", srcWidth);
+        material.setInt("uUseMap", useMap);
+        material.setInt("uSrcBaseOffset", srcBaseOffset);
+        material.setInt("uDstBaseRow", dstBaseRow);
+        this._quad.material = material;
+        target.renderList = [this._quad];
+        target.render();
+    }
+    _createShCopyMaterial() {
+        const isWGSL = this._shaderLanguage === 1 /* ShaderLanguage.WGSL */;
+        const material = new ShaderMaterial(GaussianSplattingWorkBufferShCopyShaderName, this._scene, {
+            vertexSource: isWGSL ? GaussianSplattingWorkBufferVertexShaderWGSL : GaussianSplattingWorkBufferVertexShaderGLSL,
+            fragmentSource: isWGSL ? GaussianSplattingWorkBufferShCopyFragmentShaderWGSL : GaussianSplattingWorkBufferShCopyFragmentShaderGLSL,
+        }, {
+            attributes: ["position"],
+            uniforms: ["uDstWidth", "uSrcWidth", "uUseMap", "uSrcBaseOffset", "uDstBaseRow"],
+            samplers: ["uMapTex", "uSrcSh"],
+            shaderLanguage: this._shaderLanguage,
+        });
+        material.backFaceCulling = false;
+        material.disableDepthWrite = true;
+        return material;
+    }
+    /**
+     * Renders one rotation/scale copy pass (the three half-float rotation textures) into the target. Same
+     * index/map/base math as {@link _renderRelayoutPass} but with three attachments.
+     * @param target destination 3-attachment MRT
+     * @param sources the three source rotation textures ([rotA, rotB, rotScale])
+     * @param mapTexture the R32F destination-to-source index map (sampled only when `useMap` is 1)
+     * @param useMap 1 to read source indices from the map (gaps discarded), 0 for an identity copy
+     * @param dstWidth destination width used to linearize the destination texel
+     * @param srcWidth source width used to convert a linear source index to a texel
+     * @param srcBaseOffset added to each mapped source index (region-local map -> global atlas texel)
+     * @param dstBaseRow subtracted from the destination row for an identity copy of a region-local temp
+     */
+    _renderRotCopyPass(target, sources, mapTexture, useMap, dstWidth = this._textureSize, srcWidth = this._textureSize, srcBaseOffset = 0, dstBaseRow = 0) {
+        const material = this._rotCopyMaterial;
+        material.setTexture("uMapTex", mapTexture);
+        material.setTexture("uSrc0", sources[0]);
+        material.setTexture("uSrc1", sources[1]);
+        material.setTexture("uSrc2", sources[2]);
+        material.setInt("uDstWidth", dstWidth);
+        material.setInt("uSrcWidth", srcWidth);
+        material.setInt("uUseMap", useMap);
+        material.setInt("uSrcBaseOffset", srcBaseOffset);
+        material.setInt("uDstBaseRow", dstBaseRow);
+        this._quad.material = material;
+        target.renderList = [this._quad];
+        target.render();
+    }
+    _createRotCopyMaterial() {
+        const isWGSL = this._shaderLanguage === 1 /* ShaderLanguage.WGSL */;
+        const material = new ShaderMaterial(GaussianSplattingWorkBufferRotCopyShaderName, this._scene, {
+            vertexSource: isWGSL ? GaussianSplattingWorkBufferVertexShaderWGSL : GaussianSplattingWorkBufferVertexShaderGLSL,
+            fragmentSource: isWGSL ? GaussianSplattingWorkBufferRotCopyFragmentShaderWGSL : GaussianSplattingWorkBufferRotCopyFragmentShaderGLSL,
+        }, {
+            attributes: ["position"],
+            uniforms: ["uDstWidth", "uSrcWidth", "uUseMap", "uSrcBaseOffset", "uDstBaseRow"],
+            samplers: ["uMapTex", "uSrc0", "uSrc1", "uSrc2"],
+            shaderLanguage: this._shaderLanguage,
+        });
+        material.backFaceCulling = false;
+        material.disableDepthWrite = true;
+        return material;
+    }
     /**
      * Asynchronously reads back the decoded splat centers (stride-4 xyzw, w=1) for a contiguous splat range
      * from the work buffer's centers texture, using a non-blocking GPU readback (WebGL2 PBO + fence, or WebGPU
@@ -240,14 +788,17 @@ export class GaussianSplattingWorkBuffer {
             return null;
         }
         const width = this._textureSize;
+        // Shift the region-local offset by the atlas base so the readback targets the same global texels the
+        // decode wrote (0 base for a standalone work buffer).
+        const globalOffset = this._baseOffset + splatOffset;
         // The range maps to whole texel rows [rowStart, rowEnd); read that rectangle and slice the exact range.
         // Splat i lives at texel (i % width, floor(i / width)) in both decode and draw, so the readback (which
         // indexes the same texture storage directly, with no UV/flip) yields splat i at buffer position
         // i - rowStart * width on every backend.
-        const rowStart = Math.floor(splatOffset / width);
-        const rowEnd = Math.ceil((splatOffset + splatCount) / width);
+        const rowStart = Math.floor(globalOffset / width);
+        const rowEnd = Math.ceil((globalOffset + splatCount) / width);
         const rowCount = rowEnd - rowStart;
-        const startInBuffer = (splatOffset - rowStart * width) * 4;
+        const startInBuffer = (globalOffset - rowStart * width) * 4;
         const sliceEnd = startInBuffer + splatCount * 4;
         const centers = this._mrt.textures[0];
         const engine = this._scene.getEngine();
@@ -306,9 +857,38 @@ export class GaussianSplattingWorkBuffer {
         }
         this._quad.dispose();
         this._material.dispose(true, false);
+        this._shMaterial?.dispose(true, false);
+        this._rotMaterial?.dispose(true, false);
         this._copyMaterial?.dispose(true, false);
+        this._shCopyMaterial?.dispose(true, false);
+        this._rotCopyMaterial?.dispose(true, false);
         this._relayoutMapTexture?.dispose();
-        this._mrt.dispose();
+        this._backupMrt?.dispose();
+        this._backupMrt = null;
+        if (this._backupShMrts) {
+            for (const mrt of this._backupShMrts) {
+                mrt.dispose();
+            }
+            this._backupShMrts = null;
+        }
+        this._backupRotMrt?.dispose();
+        this._backupRotMrt = null;
+        // Only dispose the MRT when we own it; an external atlas belongs to the hosting compound mesh.
+        if (this._ownsMrt) {
+            this._mrt.dispose();
+        }
+        // Same ownership rule for the SH targets (standalone owns; hosted borrows the compound's shared SH atlas).
+        if (this._ownsShMrts) {
+            for (const mrt of this._shMrts) {
+                mrt.dispose();
+            }
+        }
+        this._shMrts = [];
+        // Same ownership rule for the rotation target.
+        if (this._ownsRotMrt) {
+            this._rotMrt?.dispose();
+        }
+        this._rotMrt = null;
     }
     _createQuad() {
         const quad = new Mesh("gsWorkBufferQuad", this._scene);
@@ -336,7 +916,7 @@ export class GaussianSplattingWorkBuffer {
         material.disableDepthWrite = true;
         return material;
     }
-    _applyPack(pack, offset) {
+    _applyPack(pack) {
         const material = this._material;
         const srcWidth = pack.meansTextureL.getSize().width;
         material.setTexture("sogMeansLTex", pack.meansTextureL);
@@ -357,7 +937,75 @@ export class GaussianSplattingWorkBuffer {
         material.setVector4("sogSh0Min", new Vector4(c0Min[0], c0Min[1], c0Min[2], c0Min[3]));
         material.setVector4("sogSh0Max", new Vector4(c0Max[0], c0Max[1], c0Max[2], c0Max[3]));
         material.setInt("uVersion", pack.version);
-        material.setInt("uOffset", offset);
+        // uOffset is bound at render time in decodeAsync (from the live _baseOffset).
+        material.setInt("uCount", pack.splatCount);
+        material.setInt("uDestWidth", this._textureSize);
+        material.setInt("uSrcWidth", srcWidth);
+    }
+    _createShMaterial() {
+        const isWGSL = this._shaderLanguage === 1 /* ShaderLanguage.WGSL */;
+        const material = new ShaderMaterial(GaussianSplattingWorkBufferShDecodeShaderName, this._scene, {
+            vertexSource: isWGSL ? GaussianSplattingWorkBufferVertexShaderWGSL : GaussianSplattingWorkBufferVertexShaderGLSL,
+            fragmentSource: isWGSL ? GaussianSplattingWorkBufferShDecodeFragmentShaderWGSL : GaussianSplattingWorkBufferShDecodeFragmentShaderGLSL,
+        }, {
+            attributes: ["position"],
+            uniforms: ["sogShnMin", "sogShnMax", "uVersion", "uOffset", "uCount", "uDestWidth", "uSrcWidth", "uCoeffs", "uShTextureIndex"],
+            samplers: ["sogShLabelsTex", "sogShCentroidsTex", "sogCodebookTex"],
+            shaderLanguage: this._shaderLanguage,
+        });
+        material.backFaceCulling = false;
+        material.disableDepthWrite = true;
+        return material;
+    }
+    _applyShPack(pack) {
+        const material = this._shMaterial;
+        // A file may carry no higher-order SH (coarse LOD): fall back to sh0Texture as a harmless placeholder for the
+        // label/centroid samplers and set uCoeffs=0 so the shader neutral-fills every coefficient (128 -> 0 lighting).
+        const hasSh = !!pack.shLabelsTexture && !!pack.shCentroidsTexture;
+        const labels = pack.shLabelsTexture ?? pack.sh0Texture;
+        const centroids = pack.shCentroidsTexture ?? pack.sh0Texture;
+        material.setTexture("sogShLabelsTex", labels);
+        material.setTexture("sogShCentroidsTex", centroids);
+        // Codebook only used for v2; bind a harmless placeholder otherwise so the sampler is always set.
+        material.setTexture("sogCodebookTex", pack.codebookTexture ?? labels);
+        material.setFloat("sogShnMin", pack.shnMin ?? 0);
+        material.setFloat("sogShnMax", pack.shnMax ?? 0);
+        material.setInt("uVersion", pack.version);
+        // uOffset is bound at render time in decodeAsync (from the live _baseOffset).
+        material.setInt("uCount", pack.splatCount);
+        material.setInt("uDestWidth", this._textureSize);
+        material.setInt("uSrcWidth", labels.getSize().width);
+        // Higher-order coefficient count for THIS file (bands=3 -> 15). 0 when the file has no SH -> full neutral fill.
+        material.setInt("uCoeffs", hasSh ? pack.shCoeffCount : 0);
+    }
+    _createRotMaterial() {
+        const isWGSL = this._shaderLanguage === 1 /* ShaderLanguage.WGSL */;
+        const material = new ShaderMaterial(GaussianSplattingWorkBufferRotationDecodeShaderName, this._scene, {
+            vertexSource: isWGSL ? GaussianSplattingWorkBufferVertexShaderWGSL : GaussianSplattingWorkBufferVertexShaderGLSL,
+            fragmentSource: isWGSL ? GaussianSplattingWorkBufferRotationDecodeFragmentShaderWGSL : GaussianSplattingWorkBufferRotationDecodeFragmentShaderGLSL,
+        }, {
+            attributes: ["position"],
+            uniforms: ["sogScalesMin", "sogScalesMax", "uVersion", "uOffset", "uCount", "uDestWidth", "uSrcWidth"],
+            samplers: ["sogScalesTex", "sogQuatsTex", "sogCodebookTex"],
+            shaderLanguage: this._shaderLanguage,
+        });
+        material.backFaceCulling = false;
+        material.disableDepthWrite = true;
+        return material;
+    }
+    _applyRotPack(pack) {
+        const material = this._rotMaterial;
+        const srcWidth = pack.scalesTexture.getSize().width;
+        material.setTexture("sogScalesTex", pack.scalesTexture);
+        material.setTexture("sogQuatsTex", pack.quatsTexture);
+        // Codebook only used for v2; bind a harmless placeholder otherwise so the sampler is always set.
+        material.setTexture("sogCodebookTex", pack.codebookTexture ?? pack.scalesTexture);
+        const sMin = pack.scalesMin ?? [0, 0, 0];
+        const sMax = pack.scalesMax ?? [0, 0, 0];
+        material.setVector3("sogScalesMin", new Vector3(sMin[0], sMin[1], sMin[2]));
+        material.setVector3("sogScalesMax", new Vector3(sMax[0], sMax[1], sMax[2]));
+        material.setInt("uVersion", pack.version);
+        // uOffset is bound at render time in decodeAsync (from the live _baseOffset).
         material.setInt("uCount", pack.splatCount);
         material.setInt("uDestWidth", this._textureSize);
         material.setInt("uSrcWidth", srcWidth);