Merge pull request #926 from CesiumGS/shared-assets

Cache images across glTFs to avoid duplication

CHANGES.md

@@ -5,11 +5,34 @@
 ##### Breaking Changes :mega:
 
 - Renamed `CesiumUtility/Gunzip.h` to `CesiumUtility/Gzip.h`.
+- Renamed `ImageCesium` to `ImageAsset`.
+- The `cesium` field in `CesiumGltf::Image` is now named `pAsset` and is an `IntrusivePointer` to an `ImageAsset`.
+- The `image` field in `LoadedRasterOverlayImage` is now named `pImage` and is an `IntrusivePointer` to an `ImageAsset`.
+- Deprecated the `readImage` and `generateMipMaps` methods on `GltfReader`. These methods are now found on `ImageDecoder`.
 
 ##### Additions :tada:
 
 - Added `CesiumUtility::gzip`.
 - Added `CesiumGeometry::Transforms::getUpAxisTransform` to get the transform that converts from one up axis to another.
+- Added `TilesetSharedAssetSystem` to `Cesium3DTilesSelection` and `GltfSharedAssetSystem` to `CesiumGltfReader`.
+- Added `SharedAsset` to `CesiumUtility` to serve as the base class for assets such as `ImageAsset`.
+- Added `SharedAssetDepot` to `CesiumAsync` for managing assets, such as images, that can be shared among multiple models or other objects.
+- Added `NetworkAssetDescriptor` and `NetworkImageAssetDescriptor`.
+- `ImageAsset` (formerly `ImageCesium`) is now an `ExtensibleObject`.
+- Added `VertexAttributeSemantics` to `CesiumGltf`.
+- Added `ImageDecoder` to `CesiumGltfReader`.
+- Added `DoublyLinkedListAdvanced` to `CesiumUtility`. It is equivalent to `DoublyLinkedList` except it allows the next and previous pointers to be in a base class of the node class.
+- Added `contains` method to `DoublyLinkedList` (and `DoublyLinkedListAdvanced`).
+- Added static `error` and `warning` methods to `ErrorList`, making it easy to create an instance with a single error or warning.
+- `ExtensibleObject::addExtension` now takes arguments that are passed through to the extension's constructor.
+- Added `Hash` to `CesiumUtility`.
+- Added `emplace` and `reset` methods to `IntrusivePointer`.
+- Added `Result<T>` and `ResultPointer<T>` classes to represent the result of an operation that might complete with warnings and errors.
+
+##### Fixes :wrench:
+
+- Fixed a bug in `AsyncSystem::all` where the resolved values of individual futures were copied instead of moved into the output array.
+- Improved the hash function for `QuadtreeTileID`.
 
 ### v0.40.1 - 2024-10-01
 

Cesium3DTilesSelection/include/Cesium3DTilesSelection/IPrepareRendererResources.h

@@ -20,7 +20,6 @@ struct Rectangle;
 }
 
 namespace CesiumGltf {
-struct ImageCesium;
 struct Model;
 } // namespace CesiumGltf
 

Cesium3DTilesSelection/include/Cesium3DTilesSelection/Tileset.h

@@ -23,10 +23,12 @@
 #include <vector>
 
 namespace Cesium3DTilesSelection {
+
 class TilesetContentManager;
 class TilesetMetadata;
 class TilesetHeightQuery;
 class TilesetHeightRequest;
+class TilesetSharedAssetSystem;
 
 /**
  * @brief A <a
@@ -181,6 +183,14 @@ class CESIUM3DTILESSELECTION_API Tileset final {
   /** @copydoc Tileset::getOverlays() */
   const RasterOverlayCollection& getOverlays() const noexcept;
 
+  /**
+   * @brief Returns the {@link TilesetSharedAssetSystem} of this tileset.
+   */
+  TilesetSharedAssetSystem& getSharedAssetSystem() noexcept;
+
+  /** @copydoc Tileset::getSharedAssetSystem() */
+  const TilesetSharedAssetSystem& getSharedAssetSystem() const noexcept;
+
   /**
    * @brief Updates this view but waits for all tiles that meet sse to finish
    * loading and ready to be rendered before returning the function. This method

Cesium3DTilesSelection/include/Cesium3DTilesSelection/TilesetExternals.h

@@ -2,6 +2,7 @@
 
 #include "Library.h"
 #include "TileOcclusionRendererProxy.h"
+#include "TilesetSharedAssetSystem.h"
 #include "spdlog-cesium.h"
 
 #include <CesiumAsync/AsyncSystem.h>
@@ -69,6 +70,13 @@ class CESIUM3DTILESSELECTION_API TilesetExternals final {
    */
   std::shared_ptr<TileOcclusionRendererProxyPool> pTileOcclusionProxyPool =
       nullptr;
+
+  /**
+   * @brief The shared asset system used to facilitate sharing of common assets,
+   * such as images, between and within tilesets.
+   */
+  CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem> pSharedAssetSystem =
+      TilesetSharedAssetSystem::getDefault();
 };
 
 } // namespace Cesium3DTilesSelection

Cesium3DTilesSelection/include/Cesium3DTilesSelection/TilesetSharedAssetSystem.h

@@ -0,0 +1,18 @@
+#pragma once
+
+#include <CesiumGltfReader/GltfSharedAssetSystem.h>
+
+namespace Cesium3DTilesSelection {
+
+/**
+ * @brief Contains assets that are potentially shared across multiple Tilesets.
+ */
+class TilesetSharedAssetSystem
+    : public CesiumGltfReader::GltfSharedAssetSystem {
+public:
+  static CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem> getDefault();
+
+  virtual ~TilesetSharedAssetSystem() = default;
+};
+
+} // namespace Cesium3DTilesSelection

Cesium3DTilesSelection/src/Tile.cpp

@@ -175,7 +175,9 @@ int64_t Tile::computeByteSize() const noexcept {
 
       // sizeBytes is set in TilesetContentManager::ContentKindSetter, if not
       // sooner (e.g., by the renderer implementation).
-      bytes += image.cesium.sizeBytes;
+      if (image.pAsset) {
+        bytes += image.pAsset->sizeBytes;
+      }
     }
   }
 

Cesium3DTilesSelection/src/TileContentLoadInfo.cpp

@@ -9,6 +9,8 @@ TileContentLoadInfo::TileContentLoadInfo(
     const std::shared_ptr<IPrepareRendererResources>&
         pPrepareRendererResources_,
     const std::shared_ptr<spdlog::logger>& pLogger_,
+    const CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem>&
+        pSharedAssetSystem_,
     const TilesetContentOptions& contentOptions_,
     const Tile& tile)
     : asyncSystem(asyncSystem_),
@@ -18,6 +20,7 @@ TileContentLoadInfo::TileContentLoadInfo(
       tileID(tile.getTileID()),
       tileBoundingVolume(tile.getBoundingVolume()),
       tileContentBoundingVolume(tile.getContentBoundingVolume()),
+      pSharedAssetSystem{pSharedAssetSystem_},
       tileRefine(tile.getRefine()),
       tileGeometricError(tile.getGeometricError()),
       tileTransform(tile.getTransform()),

Cesium3DTilesSelection/src/TileContentLoadInfo.h

@@ -6,6 +6,7 @@
 #include <Cesium3DTilesSelection/TileID.h>
 #include <Cesium3DTilesSelection/TileRefine.h>
 #include <Cesium3DTilesSelection/TilesetOptions.h>
+#include <Cesium3DTilesSelection/TilesetSharedAssetSystem.h>
 #include <CesiumAsync/AsyncSystem.h>
 #include <CesiumAsync/IAssetAccessor.h>
 #include <CesiumGeometry/Axis.h>
@@ -24,6 +25,8 @@ struct TileContentLoadInfo {
       const std::shared_ptr<IPrepareRendererResources>&
           pPrepareRendererResources,
       const std::shared_ptr<spdlog::logger>& pLogger,
+      const CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem>&
+          pSharedAssetSystem,
       const TilesetContentOptions& contentOptions,
       const Tile& tile);
 
@@ -40,6 +43,7 @@ struct TileContentLoadInfo {
   BoundingVolume tileBoundingVolume;
 
   std::optional<BoundingVolume> tileContentBoundingVolume;
+  CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem> pSharedAssetSystem;
 
   TileRefine tileRefine;
 

Cesium3DTilesSelection/src/Tileset.cpp

@@ -149,6 +149,14 @@ const RasterOverlayCollection& Tileset::getOverlays() const noexcept {
   return this->_pTilesetContentManager->getRasterOverlayCollection();
 }
 
+TilesetSharedAssetSystem& Tileset::getSharedAssetSystem() noexcept {
+  return *this->_pTilesetContentManager->getSharedAssetSystem();
+}
+
+const TilesetSharedAssetSystem& Tileset::getSharedAssetSystem() const noexcept {
+  return *this->_pTilesetContentManager->getSharedAssetSystem();
+}
+
 static bool
 operator<(const FogDensityAtHeight& fogDensity, double height) noexcept {
   return fogDensity.cameraHeight < height;

Cesium3DTilesSelection/src/TilesetContentManager.cpp

@@ -49,12 +49,15 @@ struct ContentKindSetter {
 
   void operator()(CesiumGltf::Model&& model) {
     for (CesiumGltf::Image& image : model.images) {
+      if (!image.pAsset)
+        continue;
+
       // If the image size hasn't been overridden, store the pixelData
       // size now. We'll be adding this number to our total memory usage soon,
       // and remove it when the tile is later unloaded, and we must use
       // the same size in each case.
-      if (image.cesium.sizeBytes < 0) {
-        image.cesium.sizeBytes = int64_t(image.cesium.pixelData.size());
+      if (image.pAsset->sizeBytes < 0) {
+        image.pAsset->sizeBytes = int64_t(image.pAsset->pixelData.size());
       }
     }
 
@@ -562,6 +565,9 @@ postProcessContentInWorkerThread(
       tileLoadInfo.contentOptions.ktx2TranscodeTargets;
   gltfOptions.applyTextureTransform =
       tileLoadInfo.contentOptions.applyTextureTransform;
+  if (tileLoadInfo.pSharedAssetSystem) {
+    gltfOptions.pSharedAssetSystem = tileLoadInfo.pSharedAssetSystem;
+  }
 
   auto asyncSystem = tileLoadInfo.asyncSystem;
   auto pAssetAccessor = tileLoadInfo.pAssetAccessor;
@@ -599,12 +605,12 @@ postProcessContentInWorkerThread(
                 "Warning when resolving external gltf buffers from "
                 "{}:\n- {}",
                 result.pCompletedRequest->url(),
-                CesiumUtility::joinToString(gltfResult.errors, "\n- "));
+                CesiumUtility::joinToString(gltfResult.warnings, "\n- "));
           } else {
             SPDLOG_LOGGER_ERROR(
                 tileLoadInfo.pLogger,
                 "Warning resolving external glTF buffers:\n- {}",
-                CesiumUtility::joinToString(gltfResult.errors, "\n- "));
+                CesiumUtility::joinToString(gltfResult.warnings, "\n- "));
           }
         }
 
@@ -660,6 +666,7 @@ TilesetContentManager::TilesetContentManager(
       _tileLoadsInProgress{0},
       _loadedTilesCount{0},
       _tilesDataUsed{0},
+      _pSharedAssetSystem(externals.pSharedAssetSystem),
       _destructionCompletePromise{externals.asyncSystem.createPromise<void>()},
       _destructionCompleteFuture{
           this->_destructionCompletePromise.getFuture().share()},
@@ -689,6 +696,7 @@ TilesetContentManager::TilesetContentManager(
       _tileLoadsInProgress{0},
       _loadedTilesCount{0},
       _tilesDataUsed{0},
+      _pSharedAssetSystem(externals.pSharedAssetSystem),
       _destructionCompletePromise{externals.asyncSystem.createPromise<void>()},
       _destructionCompleteFuture{
           this->_destructionCompletePromise.getFuture().share()},
@@ -840,6 +848,7 @@ TilesetContentManager::TilesetContentManager(
       _tileLoadsInProgress{0},
       _loadedTilesCount{0},
       _tilesDataUsed{0},
+      _pSharedAssetSystem(externals.pSharedAssetSystem),
       _destructionCompletePromise{externals.asyncSystem.createPromise<void>()},
       _destructionCompleteFuture{
           this->_destructionCompletePromise.getFuture().share()},
@@ -985,6 +994,7 @@ void TilesetContentManager::loadTileContent(
       this->_externals.pAssetAccessor,
       this->_externals.pPrepareRendererResources,
       this->_externals.pLogger,
+      this->_pSharedAssetSystem,
       tilesetOptions.contentOptions,
       tile};
 
@@ -1227,6 +1237,11 @@ TilesetContentManager::getTilesetCredits() const noexcept {
   return this->_tilesetCredits;
 }
 
+const CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem>&
+TilesetContentManager::getSharedAssetSystem() const noexcept {
+  return this->_pSharedAssetSystem;
+}
+
 int32_t TilesetContentManager::getNumberOfTilesLoading() const noexcept {
   return this->_tileLoadsInProgress;
 }

Cesium3DTilesSelection/src/TilesetContentManager.h

@@ -18,6 +18,8 @@
 
 namespace Cesium3DTilesSelection {
 
+class TilesetSharedAssetSystem;
+
 class TilesetContentManager
     : public CesiumUtility::ReferenceCountedNonThreadSafe<
           TilesetContentManager> {
@@ -115,6 +117,9 @@ class TilesetContentManager
 
   const std::vector<CesiumUtility::Credit>& getTilesetCredits() const noexcept;
 
+  const CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem>&
+  getSharedAssetSystem() const noexcept;
+
   int32_t getNumberOfTilesLoading() const noexcept;
 
   int32_t getNumberOfTilesLoaded() const noexcept;
@@ -167,6 +172,9 @@ class TilesetContentManager
   int32_t _loadedTilesCount;
   int64_t _tilesDataUsed;
 
+  // Stores assets that might be shared between tiles.
+  CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem> _pSharedAssetSystem;
+
   CesiumAsync::Promise<void> _destructionCompletePromise;
   CesiumAsync::SharedFuture<void> _destructionCompleteFuture;
 

Cesium3DTilesSelection/src/TilesetJsonLoader.h

@@ -4,6 +4,7 @@
 
 #include <Cesium3DTilesSelection/TilesetContentLoader.h>
 #include <Cesium3DTilesSelection/TilesetExternals.h>
+#include <Cesium3DTilesSelection/TilesetSharedAssetSystem.h>
 #include <CesiumAsync/Future.h>
 #include <CesiumAsync/IAssetAccessor.h>
 
@@ -55,6 +56,7 @@ class TilesetJsonLoader : public TilesetContentLoader {
 private:
   std::string _baseUrl;
   CesiumGeospatial::Ellipsoid _ellipsoid;
+  CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem> _pSharedAssetSystem;
 
   /**
    * @brief The axis that was declared as the "up-axis" for glTF content.

Cesium3DTilesSelection/src/TilesetSharedAssetSystem.cpp

@@ -0,0 +1,32 @@
+#include <Cesium3DTilesSelection/TilesetSharedAssetSystem.h>
+
+using namespace Cesium3DTilesSelection;
+using namespace CesiumGltfReader;
+using namespace CesiumUtility;
+
+namespace {
+
+CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem> createDefault() {
+  CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem> p =
+      new TilesetSharedAssetSystem();
+
+  CesiumUtility::IntrusivePointer<GltfSharedAssetSystem> pGltf =
+      GltfSharedAssetSystem::getDefault();
+
+  p->pImage = pGltf->pImage;
+
+  return p;
+}
+
+} // namespace
+
+namespace Cesium3DTilesSelection {
+
+/*static*/ CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem>
+TilesetSharedAssetSystem::getDefault() {
+  static CesiumUtility::IntrusivePointer<TilesetSharedAssetSystem> pDefault =
+      createDefault();
+  return pDefault;
+}
+
+} // namespace Cesium3DTilesSelection

Cesium3DTilesSelection/test/SimplePrepareRendererResource.h

@@ -68,7 +68,7 @@ class SimplePrepareRendererResource
   }
 
   virtual void* prepareRasterInLoadThread(
-      CesiumGltf::ImageCesium& /*image*/,
+      CesiumGltf::ImageAsset& /*image*/,
       const std::any& /*rendererOptions*/) override {
     return new AllocationResult{totalAllocation};
   }