@cesium/engine 26.3.0 → 26.3.1-wasm.0

package/Source/Core/fetchWebAssemblyBinary.js

@@ -0,0 +1,52 @@
+import defined from "./defined.js";
+import Resource from "./Resource.js";
+
+/**
+ * Fetches a WebAssembly binary when a configuration provides its URL and does not already
+ * contain the binary.
+ *
+ * <code>TaskProcessor</code> posts the URL of the binary rather than its bytes, so that the
+ * document neither fetches nor compiles WebAssembly. Worker implementations call this function
+ * to obtain the bytes and pass them to an Emscripten module factory.
+ *
+ * The input configuration is not changed. If the configuration already carries
+ * <code>wasmBinary</code>, or has no <code>wasmBinaryFile</code>, this function returns undefined.
+ *
+ * @function fetchWebAssemblyBinary
+ *
+ * @param {WebAssemblyConfig} webAssemblyConfig The configuration posted by {@link TaskProcessor#initWebAssemblyModule}.
+ * @returns {Promise<ArrayBuffer|undefined>} A promise that resolves to the fetched binary, or undefined when no fetch is needed.
+ *
+ * @private
+ * @see TaskProcessor#initWebAssemblyModule
+ * @see createTaskProcessorWorker
+ */
+async function fetchWebAssemblyBinary(webAssemblyConfig) {
+  if (
+    !defined(webAssemblyConfig.wasmBinaryFile) ||
+    defined(webAssemblyConfig.wasmBinary)
+  ) {
+    return undefined;
+  }
+
+  return Resource.fetchArrayBuffer({
+    url: webAssemblyConfig.wasmBinaryFile,
+  });
+}
+
+/**
+ * The WebAssembly configuration posted to a worker by
+ * {@link TaskProcessor#initWebAssemblyModule}, as the first message that worker receives.
+ *
+ * @typedef {object} WebAssemblyConfig
+ *
+ * @property {string} [wasmBinaryFile] The absolute url of the WebAssembly binary. Undefined
+ *           when the browser does not support WebAssembly and a fallback module is used instead.
+ * @property {string} [modulePath] The absolute URL of the JavaScript wrapper module, or the
+ *           fallback module when the browser does not support WebAssembly.
+ * @property {ArrayBuffer} [wasmBinary] The binary contents, when they are already available.
+ *
+ * @private
+ */
+
+export default fetchWebAssemblyBinary;

package/Source/Scene/GaussianSplatPrimitive.js

@@ -35,6 +35,7 @@ import SplitDirection from "./SplitDirection.js";
 import destroyObject from "../Core/destroyObject.js";
 import ContextLimits from "../Renderer/ContextLimits.js";
 import Transforms from "../Core/Transforms.js";
+import getTimestamp from "../Core/getTimestamp.js";
 
 const scratchMatrix4A = new Matrix4();
 const scratchMatrix4C = new Matrix4();
@@ -144,12 +145,114 @@ const SnapshotState = {
  * @private
  */
 
-// Two stable frames avoids rebuilding during brief selected-tile jitter.
-const DEFAULT_STABLE_FRAMES = 2;
-// If selection keeps changing, force a rebuild after ~0.5s at 60fps to guarantee progress.
-// Lower values react faster but can thrash on noisy LOD transitions.
-// Higher values reduce rebuild churn but keep stale snapshots visible longer.
-const DEFAULT_MAX_SNAPSHOT_STALL_FRAMES = 30;
+// A snapshot rebuild re-aggregates every selected tile and re-uploads the
+// splat textures. Each rebuild is a burst of main-thread and GPU work, so the
+// scheduler waits for the selected tile set to settle before starting one.
+//
+// Both values below were tuned by hand on one dev machine. They have not been
+// measured across hardware or network speeds (coming shortly).
+
+// How long the selected tile set must stay unchanged, with no tiles decoding
+// or downloading, before a rebuild may start.
+const DEFAULT_SNAPSHOT_DEBOUNCE_MILLISECONDS = 500;
+
+// Upper bound on how long a pending rebuild can wait while the selection keeps
+// changing. Once passed, a rebuild is forced unless a committed snapshot
+// already covers most of the selected tiles (see the overlap check in
+// SnapshotRebuildScheduler.update).
+const DEFAULT_MAX_SNAPSHOT_WAIT_MILLISECONDS = 2000;
+
+class SnapshotRebuildScheduler {
+  constructor() {
+    this._selectedTileSet = new Set();
+    this._selectionChangedTime = undefined;
+    this._pendingSince = undefined;
+    this._lastRebuildTileSet = undefined;
+  }
+
+  get isPending() {
+    return defined(this._pendingSince);
+  }
+
+  hasSelectedTile(tile) {
+    return this._selectedTileSet.has(tile);
+  }
+
+  update(
+    timestamp,
+    {
+      selectedTiles,
+      rebuildRequested,
+      isBootstrap,
+      tilesLoaded,
+      tilesInFlight = false,
+      hasCommittedSnapshot = false,
+    },
+  ) {
+    if (selectedTiles.length === 0) {
+      this.clear();
+      return false;
+    }
+
+    const selectedTilesChanged = haveSelectedTilesChanged(
+      this._selectedTileSet,
+      selectedTiles,
+    );
+    if (selectedTilesChanged) {
+      this._selectedTileSet = new Set(selectedTiles);
+      this._selectionChangedTime = timestamp;
+    }
+
+    if (
+      (selectedTilesChanged || rebuildRequested || isBootstrap) &&
+      !this.isPending
+    ) {
+      this._pendingSince = timestamp;
+    }
+
+    if (!this.isPending) {
+      return false;
+    }
+
+    const selectionIsStable =
+      !tilesInFlight &&
+      defined(this._selectionChangedTime) &&
+      timestamp - this._selectionChangedTime >=
+        DEFAULT_SNAPSHOT_DEBOUNCE_MILLISECONDS;
+
+    let tileOverlap = 0;
+    if (defined(this._lastRebuildTileSet)) {
+      for (const tile of this._selectedTileSet) {
+        if (this._lastRebuildTileSet.has(tile)) {
+          tileOverlap++;
+        }
+      }
+      tileOverlap /= this._selectedTileSet.size;
+    }
+
+    const deadlineReached =
+      timestamp - this._pendingSince >=
+        DEFAULT_MAX_SNAPSHOT_WAIT_MILLISECONDS &&
+      // If the committed snapshot still covers at least half of the selected
+      // tiles, the stale view is close enough to keep showing. Skip the forced
+      // rebuild and wait for the selection to settle or for tilesLoaded.
+      (!hasCommittedSnapshot || tileOverlap < 0.5);
+
+    return isBootstrap || tilesLoaded || selectionIsStable || deadlineReached;
+  }
+
+  markRebuildStarted() {
+    this._lastRebuildTileSet = new Set(this._selectedTileSet);
+    this._pendingSince = undefined;
+  }
+
+  clear() {
+    this._selectedTileSet.clear();
+    this._selectionChangedTime = undefined;
+    this._pendingSince = undefined;
+  }
+}
+
 // Minimum delay between steady re-sort requests once the camera is moving.
 const DEFAULT_SORT_MIN_FRAME_INTERVAL = 3;
 // ~0.5 degree camera direction change threshold before triggering steady re-sort.
@@ -236,23 +339,18 @@ function markSteadySortStart(primitive, frameState) {
 }
 
 /**
- * Checks whether the set of currently selected tiles differs from the set
- * recorded on the primitive. This is used to detect LOD transitions that
- * require a snapshot rebuild.
- *
- * @param {GaussianSplatPrimitive} primitive The splat primitive.
- * @param {Cesium3DTile[]} selectedTiles The tiles selected this frame.
- * @returns {boolean} {@code true} if the tile set has changed.
+ * @param {Set<Cesium3DTile>} previousTiles The prior selected tile set.
+ * @param {Cesium3DTile[]} selectedTiles The current selected tiles.
+ * @returns {boolean} Whether the tile set changed.
  * @private
  */
-function haveSelectedTilesChanged(primitive, selectedTiles) {
-  const prevSet = primitive._selectedTileSet;
-  if (!defined(prevSet) || prevSet.size !== selectedTiles.length) {
+function haveSelectedTilesChanged(previousTiles, selectedTiles) {
+  if (previousTiles.size !== selectedTiles.length) {
     return true;
   }
 
   for (let i = 0; i < selectedTiles.length; i++) {
-    if (!prevSet.has(selectedTiles[i])) {
+    if (!previousTiles.has(selectedTiles[i])) {
       return true;
     }
   }
@@ -868,9 +966,7 @@ function GaussianSplatPrimitive(options) {
    * @private
    */
   this._scratchAggregateShBuffer = undefined;
-  this._selectedTilesStableFrames = 0;
-  this._needsSnapshotRebuild = false;
-  this._snapshotRebuildStallFrames = 0;
+  this._snapshotRebuildScheduler = new SnapshotRebuildScheduler();
 
   /**
    * The previous view matrix used to determine if the primitive needs to be updated.
@@ -957,7 +1053,6 @@ function GaussianSplatPrimitive(options) {
    * @private
    */
   this.selectedTileLength = 0;
-  this._selectedTileSet = new Set();
 
   /**
    * Indicates whether or not the primitive is ready for use.
@@ -1096,6 +1191,7 @@ Object.defineProperties(GaussianSplatPrimitive.prototype, {
     get: function () {
       return (
         !this._dirty &&
+        !this._snapshotRebuildScheduler.isPending &&
         (!defined(this._pendingSnapshot) ||
           this._pendingSnapshot.state === SnapshotState.READY)
       );
@@ -1197,14 +1293,15 @@ GaussianSplatPrimitive.prototype.isDestroyed = function () {
 };
 
 /**
- * Event callback for when a tile is loaded.
- * This method is called when a tile is loaded and the primitive needs to be updated.
- * It sets the dirty flag to true, indicating that the primitive needs to be rebuilt.
+ * Marks the primitive dirty when a selected tile loads new content.
+ * Loads outside the selected set do not affect the current snapshot.
  * @param {Cesium3DTile} tile
  * @private
  */
 GaussianSplatPrimitive.prototype.onTileLoad = function (tile) {
-  this._dirty = true;
+  if (this._snapshotRebuildScheduler.hasSelectedTile(tile)) {
+    this._dirty = true;
+  }
 };
 
 /**
@@ -1711,43 +1808,32 @@ GaussianSplatPrimitive.prototype.update = function (frameState) {
     return;
   }
 
+  const selectedTiles = tileset._selectedTiles;
+  const hasSelectedTiles = selectedTiles.length !== 0;
+  const statistics = tileset.statistics;
+  const isBootstrap =
+    !defined(this._snapshot) &&
+    !defined(this._pendingSnapshot) &&
+    !defined(this._drawCommand);
+  const allowSnapshotRebuild = this._snapshotRebuildScheduler.update(
+    getTimestamp(),
+    {
+      selectedTiles: selectedTiles,
+      rebuildRequested: this._dirty,
+      isBootstrap: isBootstrap,
+      tilesLoaded: tileset.tilesLoaded,
+      tilesInFlight:
+        defined(statistics) &&
+        (statistics.numberOfTilesProcessing > 0 ||
+          statistics.numberOfPendingRequests > 0),
+      hasCommittedSnapshot: defined(this._snapshot),
+    },
+  );
+
   if (this._sorterState === GaussianSplatSortingState.IDLE) {
-    const selectedTilesChanged =
-      tileset._selectedTiles.length !== 0 &&
-      haveSelectedTilesChanged(this, tileset._selectedTiles);
-    if (tileset._selectedTiles.length === 0) {
-      this._selectedTilesStableFrames = 0;
-      this._needsSnapshotRebuild = false;
-      this._snapshotRebuildStallFrames = 0;
-    } else if (selectedTilesChanged) {
-      this._selectedTilesStableFrames = 0;
-    } else {
-      this._selectedTilesStableFrames++;
-    }
-    if (selectedTilesChanged || this._dirty) {
-      this._needsSnapshotRebuild = true;
-    }
-    const isStable = this._selectedTilesStableFrames >= DEFAULT_STABLE_FRAMES;
-    const isBootstrap =
-      !defined(this._snapshot) &&
-      !defined(this._pendingSnapshot) &&
-      !defined(this._drawCommand);
-    // This prevents an indefinite wait if selected tiles never settle completely.
-    // In practice, this is the upper bound on "wait-for-stability" before forcing
-    // a rebuild to avoid visible starvation.
-    if (this._needsSnapshotRebuild && tileset._selectedTiles.length !== 0) {
-      this._snapshotRebuildStallFrames++;
-    } else {
-      this._snapshotRebuildStallFrames = 0;
-    }
-    const allowRebuild =
-      isStable ||
-      isBootstrap ||
-      this._snapshotRebuildStallFrames >= DEFAULT_MAX_SNAPSHOT_STALL_FRAMES;
     const hasPendingWork =
       this._dirty ||
-      this._needsSnapshotRebuild ||
-      selectedTilesChanged ||
+      this._snapshotRebuildScheduler.isPending ||
       defined(this._pendingSnapshot) ||
       defined(this._pendingSortPromise) ||
       !defined(this._drawCommand);
@@ -1759,10 +1845,11 @@ GaussianSplatPrimitive.prototype.update = function (frameState) {
     }
 
     if (
-      tileset._selectedTiles.length !== 0 &&
-      this._needsSnapshotRebuild &&
-      allowRebuild
+      hasSelectedTiles &&
+      this._snapshotRebuildScheduler.isPending &&
+      allowSnapshotRebuild
     ) {
+      this._snapshotRebuildScheduler.markRebuildStarted();
       this._splatDataGeneration++;
       this._activeSort = undefined;
       this._sorterPromise = undefined;
@@ -1971,11 +2058,8 @@ GaussianSplatPrimitive.prototype.update = function (frameState) {
         state: SnapshotState.BUILDING,
       };
 
-      this.selectedTileLength = tileset._selectedTiles.length;
-      this._selectedTileSet = new Set(tileset._selectedTiles);
+      this.selectedTileLength = selectedTiles.length;
       this._dirty = false;
-      this._needsSnapshotRebuild = false;
-      this._snapshotRebuildStallFrames = 0;
     }
 
     if (defined(this._pendingSnapshot)) {
@@ -2144,4 +2228,7 @@ GaussianSplatPrimitive.prototype.update = function (frameState) {
   this._dirty = false;
 };
 
+// For testing.
+GaussianSplatPrimitive._SnapshotRebuildScheduler = SnapshotRebuildScheduler;
+
 export default GaussianSplatPrimitive;

package/Source/Scene/GltfBufferViewLoader.js

@@ -2,9 +2,11 @@ import Check from "../Core/Check.js";
 import Frozen from "../Core/Frozen.js";
 import defined from "../Core/defined.js";
 import findMeshoptExtension from "./findMeshoptExtension.js";
-import { MeshoptDecoder } from "meshoptimizer";
 import ResourceLoader from "./ResourceLoader.js";
 import ResourceLoaderState from "./ResourceLoaderState.js";
+import TaskProcessor from "../Core/TaskProcessor.js";
+
+const decodeMeshoptTaskProcessor = new TaskProcessor("decodeMeshopt");
 
 /**
  * Loads a glTF buffer view.
@@ -159,29 +161,39 @@ async function loadResources(loader) {
     }
 
     const bufferTypedArray = bufferLoader.typedArray;
-    const bufferViewTypedArray = new Uint8Array(
+    let bufferViewTypedArray = new Uint8Array(
       bufferTypedArray.buffer,
       bufferTypedArray.byteOffset + loader._byteOffset,
       loader._byteLength,
     );
 
+    if (loader._hasMeshopt) {
+      // The buffer can be shared with other cached resources. Copy the encoded
+      // range before transferring it to the worker so the cache stays intact.
+      bufferViewTypedArray = new Uint8Array(bufferViewTypedArray);
+    }
+
     // Unload the buffer
     loader.unload();
 
     loader._typedArray = bufferViewTypedArray;
     if (loader._hasMeshopt) {
-      const count = loader._meshoptCount;
-      const byteStride = loader._meshoptByteStride;
-      const result = new Uint8Array(count * byteStride);
-      MeshoptDecoder.decodeGltfBuffer(
-        result,
-        count,
-        byteStride,
-        loader._typedArray,
-        loader._meshoptMode,
-        loader._meshoptFilter,
+      const result = await decodeMeshoptTaskProcessor.scheduleTask(
+        {
+          source: loader._typedArray,
+          count: loader._meshoptCount,
+          byteStride: loader._meshoptByteStride,
+          mode: loader._meshoptMode,
+          filter: loader._meshoptFilter,
+        },
+        [loader._typedArray.buffer],
       );
-      loader._typedArray = result;
+
+      if (loader.isDestroyed()) {
+        return;
+      }
+
+      loader._typedArray = new Uint8Array(result);
     }
 
     loader._state = ResourceLoaderState.READY;

package/Source/Scene/GltfSpzLoader.js

@@ -4,7 +4,7 @@ import defined from "../Core/defined.js";
 import RuntimeError from "../Core/RuntimeError.js";
 import ResourceLoader from "./ResourceLoader.js";
 import ResourceLoaderState from "./ResourceLoaderState.js";
-import { loadSpz } from "@spz-loader/core";
+import SpzDecoder from "./SpzDecoder.js";
 
 // Cumulative number of SH coefficient floats per splat per channel for each
 // degree. Degree 0 has no extra SH data (base color is stored separately in
@@ -234,9 +234,10 @@ class GltfSpzLoader extends ResourceLoader {
       }
     }
 
-    const decodePromise = loadSpz(this._bufferViewTypedArray, {
-      unpackOptions: { coordinateSystem: "UNSPECIFIED" },
-    });
+    // Buffer views can be shared by cached resources. Transfer a private copy
+    // so decoding does not detach the cached source.
+    const spzData = new Uint8Array(this._bufferViewTypedArray);
+    const decodePromise = SpzDecoder.decode(spzData);
 
     if (!defined(decodePromise)) {
       return false;

package/Source/Scene/SpzDecoder.js

@@ -0,0 +1,106 @@
+import defined from "../Core/defined.js";
+import DeveloperError from "../Core/DeveloperError.js";
+import getAbsoluteUri from "../Core/getAbsoluteUri.js";
+import TaskProcessor from "../Core/TaskProcessor.js";
+
+const defaultWorkerModuleId = "decodeSpz";
+
+function getDecoderTaskProcessor() {
+  let taskProcessor = SpzDecoder._decoderTaskProcessor;
+  if (!defined(taskProcessor)) {
+    const workerModuleUrl = SpzDecoder._workerModuleUrl;
+    const workerPath = defined(workerModuleUrl)
+      ? getAbsoluteUri(workerModuleUrl)
+      : defaultWorkerModuleId;
+    taskProcessor = new TaskProcessor(workerPath);
+    SpzDecoder._decoderTaskProcessor = taskProcessor;
+  }
+
+  return taskProcessor;
+}
+
+/**
+ * Configures the Web Worker module used to decode SPZ-compressed Gaussian
+ * splats.
+ *
+ * @alias SpzDecoder
+ * @namespace
+ *
+ * @experimental This feature is not final and is subject to change without
+ * Cesium's standard deprecation policy.
+ */
+function SpzDecoder() {}
+
+Object.defineProperties(SpzDecoder, {
+  /**
+   * The URL of the ECMAScript Web Worker module that decodes SPZ data. Set
+   * this before the first SPZ decode to use a decoder other than Cesium's
+   * bundled <code>Workers/decodeSpz.js</code> worker. Relative URLs are
+   * resolved relative to the document URL.
+   *
+   * To apply a separate Content Security Policy to the decoder, serve the
+   * module as a separate, same-origin resource. Cross-origin URLs use a
+   * <code>blob:</code> worker fallback, which inherits the document's policy.
+   *
+   * The module must use {@link createTaskProcessorWorker}, receive an object
+   * with a <code>spzData</code> {@link Uint8Array}, and return the gcloud
+   * object produced by <code>@spz-loader/core</code>. It must transfer the
+   * buffers for its typed-array attributes.
+   *
+   * @memberof SpzDecoder
+   * @type {string|undefined}
+   * @default undefined
+   * @experimental This feature is not final and is subject to change without
+   * Cesium's standard deprecation policy.
+   */
+  workerModuleUrl: {
+    get: function () {
+      return SpzDecoder._workerModuleUrl;
+    },
+    set: function (value) {
+      if (defined(SpzDecoder._decoderTaskProcessor)) {
+        throw new DeveloperError(
+          "SpzDecoder.workerModuleUrl must be configured before the first SPZ decode.",
+        );
+      }
+
+      if (defined(value) && (typeof value !== "string" || value.length === 0)) {
+        throw new DeveloperError(
+          "SpzDecoder.workerModuleUrl must be a non-empty string or undefined.",
+        );
+      }
+
+      SpzDecoder._workerModuleUrl = value;
+    },
+  },
+});
+
+/**
+ * Decodes SPZ data in the configured Web Worker.
+ *
+ * @param {Uint8Array} spzData The compressed SPZ data. Its backing buffer is
+ *        transferred to the worker.
+ * @returns {Promise<object>|undefined} A promise that resolves to the gcloud
+ *          decode result, or undefined when the worker is busy.
+ * @private
+ */
+SpzDecoder.decode = function (spzData) {
+  return getDecoderTaskProcessor().scheduleTask({ spzData: spzData }, [
+    spzData.buffer,
+  ]);
+};
+
+SpzDecoder._decoderTaskProcessor = undefined;
+SpzDecoder._workerModuleUrl = undefined;
+
+// Exposed for testing purposes.
+SpzDecoder._resetForTesting = function () {
+  const taskProcessor = SpzDecoder._decoderTaskProcessor;
+  if (defined(taskProcessor) && !taskProcessor.isDestroyed()) {
+    taskProcessor.destroy();
+  }
+  SpzDecoder._decoderTaskProcessor = undefined;
+  SpzDecoder._workerModuleUrl = undefined;
+};
+
+export default SpzDecoder;