Unload content of external tilesets to save memory usage

Cesium3DTilesSelection/include/Cesium3DTilesSelection/Tile.h

@@ -188,6 +188,11 @@ class CESIUM3DTILESSELECTION_API Tile final {
     return gsl::span<const Tile>(this->_children);
   }
 
+  /**
+   * Clears the list of this tile's children.
+   */
+  void clearChildren() { this->_children.clear(); }
+
   /**
    * @brief Assigns the given child tiles to this tile.
    *
@@ -475,6 +480,16 @@ class CESIUM3DTILESSELECTION_API Tile final {
    */
   bool isEmptyContent() const noexcept;
 
+  /**
+   * @brief Determines if this tile has unknown content.
+   */
+  bool isUnknownContent() const noexcept;
+
+  /**
+   * Determines if this tile and all of its children are ready to unload.
+   */
+  bool isReadyToUnload() const noexcept;
+
   /**
    * @brief get the loader that is used to load the tile content.
    */
@@ -535,6 +550,7 @@ class CESIUM3DTILESSELECTION_API Tile final {
   std::vector<RasterMappedTo3DTile> _rasterTiles;
 
   friend class TilesetContentManager;
+  friend class Tileset;
   friend class MockTilesetContentManagerTestFixture;
 
 public:

Cesium3DTilesSelection/include/Cesium3DTilesSelection/Tileset.h

@@ -416,6 +416,7 @@ class CESIUM3DTILESSELECTION_API Tileset final {
 
   void _unloadCachedTiles(double timeBudget) noexcept;
   void _markTileVisited(Tile& tile) noexcept;
+  void _unloadPendingChildren(Tile& tile) noexcept;
 
   void _updateLodTransitions(
       const FrameState& frameState,
@@ -485,6 +486,7 @@ class CESIUM3DTILESSELECTION_API Tileset final {
   std::vector<TileLoadTask> _workerThreadLoadQueue;
 
   Tile::LoadedLinkedList _loadedTiles;
+  Tile::LoadedLinkedList _externalTilesPendingClear;
 
   // Holds computed distances, to avoid allocating them on the heap during tile
   // selection.

Cesium3DTilesSelection/src/Tile.cpp

@@ -217,6 +217,26 @@ bool Tile::isEmptyContent() const noexcept {
   return this->_content.isEmptyContent();
 }
 
+bool Tile::isUnknownContent() const noexcept {
+  return this->_content.isUnknownContent();
+}
+
+bool Tile::isReadyToUnload() const noexcept {
+  if (this->getState() != TileLoadState::ContentLoaded &&
+      this->getState() != TileLoadState::Done &&
+      this->getState() != TileLoadState::Unloaded) {
+    return false;
+  }
+
+  for (const Tile& child : this->_children) {
+    if (!child.isReadyToUnload()) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
 TilesetContentLoader* Tile::getLoader() const noexcept {
   return this->_pLoader;
 }

Cesium3DTilesSelection/src/Tileset.cpp

@@ -48,6 +48,7 @@ Tileset::Tileset(
           _externals,
           _options,
           RasterOverlayCollection{_loadedTiles, externals},
+          _loadedTiles,
           std::vector<CesiumAsync::IAssetAccessor::THeader>{},
           std::move(pCustomLoader),
           std::move(pRootTile))} {}
@@ -66,6 +67,7 @@ Tileset::Tileset(
           _externals,
           _options,
           RasterOverlayCollection{_loadedTiles, externals},
+          _loadedTiles,
           url)} {}
 
 Tileset::Tileset(
@@ -84,12 +86,12 @@ Tileset::Tileset(
           _externals,
           _options,
           RasterOverlayCollection{_loadedTiles, externals},
+          _loadedTiles,
           ionAssetID,
           ionAccessToken,
           ionAssetEndpointUrl)} {}
 
 Tileset::~Tileset() noexcept {
-  this->_pTilesetContentManager->unloadAll();
   if (this->_externals.pTileOcclusionProxyPool) {
     this->_externals.pTileOcclusionProxyPool->destroyPool();
   }
@@ -1461,7 +1463,30 @@ void Tileset::_processMainThreadLoadQueue() {
   this->_mainThreadLoadQueue.clear();
 }
 
+void Tileset::_unloadPendingChildren(Tile& tile) noexcept {
+  for (Tile& childTile : tile.getChildren()) {
+    this->_externalTilesPendingClear.remove(childTile);
+    childTile.setState(TileLoadState::Unloaded);
+    this->_unloadPendingChildren(childTile);
+  }
+}
+
 void Tileset::_unloadCachedTiles(double timeBudget) noexcept {
+  // Clear children of external tilesets unloaded last frame
+  Tile* pPendingExternalTile;
+  while ((pPendingExternalTile = this->_externalTilesPendingClear.head()) !=
+         nullptr) {
+    this->_externalTilesPendingClear.remove(*pPendingExternalTile);
+    // We need to remove children recursively, as children of this tile might
+    // also be in the _externalTilesPendingClear list
+    this->_unloadPendingChildren(*pPendingExternalTile);
+    pPendingExternalTile->setState(TileLoadState::Unloaded);
+    pPendingExternalTile->clearChildren();
+  }
+
+  // Clear list of pending external tiles
+  this->_externalTilesPendingClear = Tile::LoadedLinkedList();
+
   const int64_t maxBytes = this->getOptions().maximumCachedBytes;
 
   const Tile* pRootTile = this->_pTilesetContentManager->getRootTile();
@@ -1492,10 +1517,18 @@ void Tileset::_unloadCachedTiles(double timeBudget) noexcept {
 
     Tile* pNext = this->_loadedTiles.next(*pTile);
 
+    // Check for external content before unloading, as an unloaded tile will
+    // always have Unknown content set
+    const bool wasExternalTile = pTile->isExternalContent();
     const bool removed =
         this->_pTilesetContentManager->unloadTileContent(*pTile);
     if (removed) {
       this->_loadedTiles.remove(*pTile);
+      if (wasExternalTile) {
+        // The Unreal implementation, at the least, requires a frame between a
+        // tile being unloaded and its pointers becoming invalidated.
+        this->_externalTilesPendingClear.insertAtTail(*pTile);
+      }
     }
 
     pTile = pNext;

Cesium3DTilesSelection/src/TilesetContentManager.cpp

@@ -72,15 +72,6 @@ struct ContentKindSetter {
   void* pRenderResources;
 };
 
-void unloadTileRecursively(
-    Tile& tile,
-    TilesetContentManager& tilesetContentManager) {
-  tilesetContentManager.unloadTileContent(tile);
-  for (Tile& child : tile.getChildren()) {
-    unloadTileRecursively(child, tilesetContentManager);
-  }
-}
-
 bool anyRasterOverlaysNeedLoading(const Tile& tile) noexcept {
   for (const RasterMappedTo3DTile& mapped : tile.getMappedRasterTiles()) {
     const RasterOverlayTile* pLoading = mapped.getLoadingTile();
@@ -599,6 +590,7 @@ TilesetContentManager::TilesetContentManager(
     const TilesetExternals& externals,
     const TilesetOptions& tilesetOptions,
     RasterOverlayCollection&& overlayCollection,
+    Tile::LoadedLinkedList& loadedTiles,
     std::vector<CesiumAsync::IAssetAccessor::THeader>&& requestHeaders,
     std::unique_ptr<TilesetContentLoader>&& pLoader,
     std::unique_ptr<Tile>&& pRootTile)
@@ -616,6 +608,7 @@ TilesetContentManager::TilesetContentManager(
       _overlayCollection{std::move(overlayCollection)},
       _tileLoadsInProgress{0},
       _loadedTilesCount{0},
+      _loadedTiles(loadedTiles),
       _tilesDataUsed{0},
       _destructionCompletePromise{externals.asyncSystem.createPromise<void>()},
       _destructionCompleteFuture{
@@ -630,6 +623,7 @@ TilesetContentManager::TilesetContentManager(
     const TilesetExternals& externals,
     const TilesetOptions& tilesetOptions,
     RasterOverlayCollection&& overlayCollection,
+    Tile::LoadedLinkedList& loadedTiles,
     const std::string& url)
     : _externals{externals},
       _requestHeaders{},
@@ -645,6 +639,7 @@ TilesetContentManager::TilesetContentManager(
       _overlayCollection{std::move(overlayCollection)},
       _tileLoadsInProgress{0},
       _loadedTilesCount{0},
+      _loadedTiles(loadedTiles),
       _tilesDataUsed{0},
       _destructionCompletePromise{externals.asyncSystem.createPromise<void>()},
       _destructionCompleteFuture{
@@ -767,6 +762,7 @@ TilesetContentManager::TilesetContentManager(
     const TilesetExternals& externals,
     const TilesetOptions& tilesetOptions,
     RasterOverlayCollection&& overlayCollection,
+    Tile::LoadedLinkedList& loadedTiles,
     int64_t ionAssetID,
     const std::string& ionAccessToken,
     const std::string& ionAssetEndpointUrl)
@@ -784,6 +780,7 @@ TilesetContentManager::TilesetContentManager(
       _overlayCollection{std::move(overlayCollection)},
       _tileLoadsInProgress{0},
       _loadedTilesCount{0},
+      _loadedTiles(loadedTiles),
       _tilesDataUsed{0},
       _destructionCompletePromise{externals.asyncSystem.createPromise<void>()},
       _destructionCompleteFuture{
@@ -1026,6 +1023,27 @@ void TilesetContentManager::updateTileContent(
   }
 }
 
+bool TilesetContentManager::handleUpsampledTileChildren(Tile& tile) {
+  for (Tile& child : tile.getChildren()) {
+    if (child.getState() == TileLoadState::ContentLoading &&
+        std::holds_alternative<CesiumGeometry::UpsampledQuadtreeNode>(
+            child.getTileID())) {
+      // Yes, a child is upsampling from this tile, so it may be using the
+      // tile's content from another thread via lambda capture. We can't unload
+      // it right now. So mark the tile as in the process of unloading and stop
+      // here.
+      tile.setState(TileLoadState::Unloading);
+      return false;
+    }
+
+    if (!this->handleUpsampledTileChildren(child)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
 bool TilesetContentManager::unloadTileContent(Tile& tile) {
   TileLoadState state = tile.getState();
   if (state == TileLoadState::Unloaded) {
@@ -1037,9 +1055,16 @@ bool TilesetContentManager::unloadTileContent(Tile& tile) {
   }
 
   TileContent& content = tile.getContent();
+  bool isReadyToUnload = tile.isReadyToUnload();
+  bool isExternalContent = tile.isExternalContent();
+
+  // don't unload external or empty tile while children are still loading
+  if ((isExternalContent || content.isEmptyContent()) && !isReadyToUnload) {
+    return false;
+  }
 
-  // don't unload external or empty tile
-  if (content.isExternalContent() || content.isEmptyContent()) {
+  // Don't unload this tile if children are still upsampling
+  if (!this->handleUpsampledTileChildren(tile)) {
     return false;
   }
 
@@ -1050,46 +1075,50 @@ bool TilesetContentManager::unloadTileContent(Tile& tile) {
   }
   tile.getMappedRasterTiles().clear();
 
-  // Unload the renderer resources and clear any raster overlay tiles. We can do
-  // this even if the tile can't be fully unloaded because this tile's geometry
-  // is being using by an async upsample operation (checked below).
-  switch (state) {
-  case TileLoadState::ContentLoaded:
-    unloadContentLoadedState(tile);
-    break;
-  case TileLoadState::Done:
-    unloadDoneState(tile);
-    break;
-  default:
-    break;
+  if (!tile.isEmptyContent() && !tile.isUnknownContent()) {
+    // Unload the renderer resources and clear any raster overlay tiles. We can
+    // do this even if the tile can't be fully unloaded because this tile's
+    // geometry is being using by an async upsample operation (checked below).
+    switch (state) {
+    case TileLoadState::ContentLoaded:
+      unloadContentLoadedState(tile);
+      break;
+    case TileLoadState::Done:
+      unloadDoneState(tile);
+      break;
+    default:
+      break;
+    }
   }
 
-  // Are any children currently being upsampled from this tile?
-  for (const Tile& child : tile.getChildren()) {
-    if (child.getState() == TileLoadState::ContentLoading &&
-        std::holds_alternative<CesiumGeometry::UpsampledQuadtreeNode>(
-            child.getTileID())) {
-      // Yes, a child is upsampling from this tile, so it may be using the
-      // tile's content from another thread via lambda capture. We can't unload
-      // it right now. So mark the tile as in the process of unloading and stop
-      // here.
-      tile.setState(TileLoadState::Unloading);
-      return false;
+  if (isReadyToUnload) {
+    // Make sure we unload all children
+    gsl::span<Cesium3DTilesSelection::Tile> children = tile.getChildren();
+    for (Tile& child : children) {
+      this->unloadTileContent(child);
     }
   }
 
   // If we make it this far, the tile's content will be fully unloaded.
   notifyTileUnloading(&tile);
   content.setContentKind(TileUnknownContent{});
-  tile.setState(TileLoadState::Unloaded);
+  if (isExternalContent) {
+    // We don't want to set external tilesets as Unloaded quite yet, because
+    // then they might get reloaded before we've had a chance to clear their
+    // children and cause an error. They'll get their children cleared and their
+    // state set to Unloaded before next clean up
+    tile.setState(TileLoadState::Done);
+  } else {
+    tile.setState(TileLoadState::Unloaded);
+  }
   return true;
 }
 
 void TilesetContentManager::unloadAll() {
   // TODO: use the linked-list of loaded tiles instead of walking the entire
   // tile tree.
   if (this->_pRootTile) {
-    unloadTileRecursively(*this->_pRootTile, *this);
+    this->unloadTileContent(*this->_pRootTile);
   }
 }
 
@@ -1424,7 +1453,10 @@ void TilesetContentManager::updateDoneState(
 void TilesetContentManager::unloadContentLoadedState(Tile& tile) {
   TileContent& content = tile.getContent();
   TileRenderContent* pRenderContent = content.getRenderContent();
-  assert(pRenderContent && "Tile must have render content to be unloaded");
+  if (pRenderContent == nullptr) {
+    // No resources we need to clean up
+    return;
+  }
 
   void* pWorkerRenderResources = pRenderContent->getRenderResources();
   this->_externals.pPrepareRendererResources->free(
@@ -1437,7 +1469,10 @@ void TilesetContentManager::unloadContentLoadedState(Tile& tile) {
 void TilesetContentManager::unloadDoneState(Tile& tile) {
   TileContent& content = tile.getContent();
   TileRenderContent* pRenderContent = content.getRenderContent();
-  assert(pRenderContent && "Tile must have render content to be unloaded");
+  if (pRenderContent == nullptr) {
+    // No resources to clean up
+    return;
+  }
 
   void* pMainThreadRenderResources = pRenderContent->getRenderResources();
   this->_externals.pPrepareRendererResources->free(