Add support for selecting tiles for multiple independent views

CHANGES.md

@@ -2,10 +2,39 @@
 
 ### ? - ?
 
-##### Additions
+##### Breaking Changes :mega:
+
+- Removed `addCreditToFrame`, `startNextFrame`, `getCreditsToShowThisFrame`, and `getCreditsToNoLongerShowThisFrame` from `CreditSystem`. `CreditSystem` no longer has a notion of a "frame". Instead, credits are included and excluded by calling `addCreditReference` and `removeCreditReference`. A snaphot of the current state can be obtained by calling `getSnapshot`, and it includes both the current set of active credits as well as the credits that were removed since the last snapshot.
+- Removed the following from `Cesium3DTilesSelection::Tile`:
+  - `getLastSelectionState` and `setLastSelectionState`. Use `TilesetViewGroup::getTraversalState` instead.
+  - `Tile::LoadedLinkedList`. Use `LoadedTileEnumerator` instead.
+- The `RasterOverlayCollection` constructor now takes a `LoadedTileEnumerator` instead of a `Tile::LoadedLinkedList`.
+- `TileSelectionState` no longer uses or requires a frame number. This parameter has been removed from its various methods.
+- Derived `TilesetContentLoader` classes that aggregate other loaders must now implement `setOwnerOfNestedLoaders` to pass the owner through.
+- `DebugTileStateDatabase::recordAllTileStates` and `recordTileState` now must be given a `TilesetViewGroup` indicating which view group to record states for.
+
+##### Additions :tada:
 
 - Added `convertAccessorTypeToPropertyType` and `convertPropertyTypeToAccessorType` to `CesiumGltf::PropertyType`.
 - Added support for building in `vcpkg` manifest mode.
+- Added `TilesetViewGroup`. View groups select tiles independently from other any other view group. This is useful for applications with multiple viewports to allow them to show different levels-of-detail for the same area.
+- Added `CreditReferencer` which makes it easy to track credits in a frame-oriented fashion similar to how `CreditSystem::addCreditToFrame` worked in previous releases.
+- Added a `std::hash` implementation for `IntrusivePointer` that simply hashes the underlying pointer.
+- Added `Math::GoldenRatio`.
+- Added `TreeTraversalState` to `CesiumUtility`. It can be used to associate arbitrary data with individual nodes during a depth-first tree traversal and access that data in a later traversal.
+- Added `LoadedTileEnumerator` to enumerate the loaded tiles in a `Tile` subtree.
+- Added `RasterOverlayCollection::setLoadedTileEnumerator`.
+- Added `TileLoadRequester`, which allows influence over which tiles in a `Cesium3DTilesSelection::Tileset` are loaded. This is the base class for `TilesetViewGroup` and `TilesetHeightRequest`.
+- Added `TileLoadTask`, `TileLoadPriorityGroup`, and `TilesetFrameState`. Previously these types were private.
+- Added the following to `Cesium3DTilesSelection::Tileset`:
+  - `getUserCredit` - Reflects the `Credit` passed as a string into `TilesetOptions::credit`.
+  - `loadedTiles`- Allows enumeration of the tileset's loaded tiles.
+  - `getDefaultViewGroup` - Gets the default view group that is used when `updateView` is called.
+  - `updateViewGroup` - Updates the set of tiles to render for a `TilesetViewGroup`, as well as the set of tiles that the view group would like to load.
+  - `loadTiles` - Loads tiles that have been identified as required across all `TilesetViewGroup` and `TilesetHeightRequest` instances, up to limits specified in `TilesetOptions`.
+- `TilesetContentLoader` instances now know the `TilesetContentManager` that owns them. This is managed with new `getOwner` and `setOwner` methods.
+
+##### Fixes :wrench:
 
 ### v0.46.0 - 2025-04-01
 

Cesium3DTilesContent/include/Cesium3DTilesContent/ImplicitTilingUtilities.h

@@ -115,7 +115,7 @@ class QuadtreeChildren {
 
   /** @brief Returns an iterator starting at the first child. */
   iterator begin() const noexcept;
-  /** @brief Returns an iterator starting at the last child. */
+  /** @brief Returns an iterator starting after the last child. */
   iterator end() const noexcept;
   /**
    * @brief Returns the total number of \ref CesiumGeometry::QuadtreeTileID
@@ -217,7 +217,7 @@ class OctreeChildren {
       : _tileID(tileID) {}
   /** @brief Returns an iterator starting at the first child. */
   iterator begin() const noexcept;
-  /** @brief Returns an iterator starting at the last child. */
+  /** @brief Returns an iterator starting after the last child. */
   iterator end() const noexcept;
   /**
    * @brief Returns the total number of \ref CesiumGeometry::OctreeTileID

Cesium3DTilesSelection/include/Cesium3DTilesSelection/DebugTileStateDatabase.h

@@ -1,12 +1,17 @@
 #pragma once
 
+#include <Cesium3DTilesSelection/TileSelectionState.h>
+#include <CesiumUtility/IntrusivePointer.h>
+
 #include <memory>
 #include <string>
+#include <unordered_map>
 
 namespace Cesium3DTilesSelection {
 
 class Tile;
 class Tileset;
+class TilesetViewGroup;
 
 /**
  * @brief Helps debug the tile selection algorithm by recording the state of
@@ -27,18 +32,50 @@ class DebugTileStateDatabase {
    * @brief Records the state of all tiles that are currently loaded by the
    * given tileset.
    *
+   * The state is obtained from the view group's
+   * {@link TilesetViewGroup::getTraversalState} by calling
+   * {@link CesiumUtility::TreeTraversalState::slowlyGetPreviousStates}.
+   *
    * @param frameNumber The current frame number.
    * @param tileset The tileset.
+   * @param viewGroup The view group.
    */
-  void recordAllTileStates(int32_t frameNumber, const Tileset& tileset);
+  void recordAllTileStates(
+      int32_t frameNumber,
+      const Tileset& tileset,
+      const TilesetViewGroup& viewGroup);
 
   /**
    * @brief Records the state of a given tile.
    *
+   * The state is obtained from the view group's
+   * {@link TilesetViewGroup::getTraversalState} by calling
+   * {@link CesiumUtility::TreeTraversalState::slowlyGetPreviousStates}.
+   *
+   * @param frameNumber The current frame number.
+   * @param viewGroup The view group.
+   * @param tile The tile.
+   */
+  void recordTileState(
+      int32_t frameNumber,
+      const TilesetViewGroup& viewGroup,
+      const Tile& tile);
+
+  /**
+   * @brief Records the state of a given tile.
+   *
+   * The state is obtained from the provided map.
+   *
    * @param frameNumber The current frame number.
    * @param tile The tile.
+   * @param states The lookup table for tile states.
    */
-  void recordTileState(int32_t frameNumber, const Tile& tile);
+  void recordTileState(
+      int32_t frameNumber,
+      const Tile& tile,
+      const std::unordered_map<
+          CesiumUtility::IntrusivePointer<const Tile>,
+          TileSelectionState>& states);
 
 private:
   struct Impl;

Cesium3DTilesSelection/include/Cesium3DTilesSelection/LoadedTileEnumerator.h

@@ -0,0 +1,198 @@
+#pragma once
+
+#include <iterator>
+#include <vector>
+
+namespace Cesium3DTilesSelection {
+
+class Tile;
+class TilesetContentManager;
+
+// The LoadedConstTileEnumerator and LoadedTileEnumerator could probably be
+// replaced with ranges, except that we need to support Android and range
+// support prior to NDK r26 is shaky. Unreal Engine 5.5 uses r25b and Unity
+// 2022.3 uses r23b. See here: https://github.com/android/ndk/issues/1530
+
+/**
+ * @brief A "virtual collection" that allows enumeration through the loaded
+ * tiles in a subtree rooted at a given {@link Tile}.
+ *
+ * For the purposes of this enumeration, a loaded tile is one that is in a
+ * {@link TileLoadState} other than {@link TileLoadState::Unloaded}, or that
+ * has any children (or other descendants) that meet this criteria. We check the
+ * latter criteria by looking at {@link Tile::getDoNotUnloadSubtreeCount}.
+ */
+class LoadedConstTileEnumerator {
+public:
+  /**
+   * @brief An iterator over constant {@link Tile} instances.
+   */
+  class const_iterator {
+  public:
+    /**
+     * @brief The iterator category tag denoting this is a forward iterator.
+     */
+    using iterator_category = std::forward_iterator_tag;
+    /**
+     * @brief The type of value that is being iterated over.
+     */
+    using value_type = const Tile;
+    /**
+     * @brief The type used to identify distance between iterators.
+     *
+     * This is `void` because there is no meaningful measure of distance between
+     * tiles.
+     */
+    using difference_type = void;
+    /**
+     * @brief A pointer to the type being iterated over.
+     */
+    using pointer = const Tile*;
+    /**
+     * @brief A reference to the type being iterated over.
+     */
+    using reference = const Tile&;
+
+    /**
+     * @brief Returns a reference to the current item being iterated.
+     */
+    const Tile& operator*() const noexcept;
+    /**
+     * @brief Returns a pointer to the current item being iterated.
+     */
+    const Tile* operator->() const noexcept;
+
+    /**
+     * @brief Advances the iterator to the next item (pre-incrementing).
+     */
+    const_iterator& operator++() noexcept;
+    /**
+     * @brief Advances the iterator to the next item (post-incrementing).
+     */
+    const_iterator operator++(int) noexcept;
+
+    /** @brief Checks if two iterators are at the same item. */
+    bool operator==(const const_iterator& rhs) const noexcept;
+    /** @brief Checks if two iterators are not at the same item. */
+    bool operator!=(const const_iterator& rhs) const noexcept;
+
+  private:
+    explicit const_iterator(const Tile* pRootTile) noexcept;
+
+    std::vector<const Tile*> _traversalStack;
+
+    friend class LoadedTileEnumerator;
+    friend class LoadedConstTileEnumerator;
+  };
+
+  /**
+   * @brief Creates a new instance to enumerate loaded tiles in the subtree
+   * rooted at `pRootTile`.
+   *
+   * If `pRootTile` is `nullptr`, then the iteration is empty (`begin==end`).
+   * Otherwise, the iteration will include at least `pRootTile`, even if it is
+   * not loaded.
+   *
+   * @param pRootTile The root tile of the subtree.
+   */
+  explicit LoadedConstTileEnumerator(const Tile* pRootTile) noexcept;
+
+  /** @brief Returns an iterator starting at the first tile. */
+  const_iterator begin() const noexcept;
+  /** @brief Returns an iterator starting after the last tile. */
+  const_iterator end() const noexcept;
+
+private:
+  const Tile* _pRootTile;
+
+  template <typename TIterator> static TIterator& increment(TIterator& it);
+  friend class LoadedTileEnumerator;
+};
+
+/** @copydoc LoadedConstTileEnumerator */
+class LoadedTileEnumerator {
+public:
+  /**
+   * @brief An iterator over constant {@link Tile} instances.
+   */
+  using const_iterator = LoadedConstTileEnumerator::const_iterator;
+
+  /**
+   * @brief An iterator over {@link Tile} instances.
+   */
+  class iterator {
+  public:
+    /**
+     * @brief The iterator category tag denoting this is a forward iterator.
+     */
+    using iterator_category = std::forward_iterator_tag;
+    /**
+     * @brief The type of value that is being iterated over.
+     */
+    using value_type = Tile;
+    /**
+     * @brief The type used to identify distance between iterators.
+     *
+     * This is `void` because there is no meaningful measure of distance between
+     * tiles.
+     */
+    using difference_type = void;
+    /**
+     * @brief A pointer to the type being iterated over.
+     */
+    using pointer = Tile*;
+    /**
+     * @brief A reference to the type being iterated over.
+     */
+    using reference = Tile&;
+
+    /**
+     * @brief Returns a reference to the current item being iterated.
+     */
+    Tile& operator*() const noexcept;
+    /**
+     * @brief Returns a pointer to the current item being iterated.
+     */
+    Tile* operator->() const noexcept;
+
+    /**
+     * @brief Advances the iterator to the next item (pre-incrementing).
+     */
+    iterator& operator++() noexcept;
+    /**
+     * @brief Advances the iterator to the next item (post-incrementing).
+     */
+    iterator operator++(int) noexcept;
+
+    /** @brief Checks if two iterators are at the same item. */
+    bool operator==(const iterator& rhs) const noexcept;
+    /** @brief Checks if two iterators are not at the same item. */
+    bool operator!=(const iterator& rhs) const noexcept;
+
+  private:
+    explicit iterator(Tile* pRootTile) noexcept;
+
+    std::vector<Tile*> _traversalStack;
+
+    friend class LoadedTileEnumerator;
+    friend class LoadedConstTileEnumerator;
+  };
+
+  /** @copydoc LoadedConstTileEnumerator::LoadedConstTileEnumerator */
+  explicit LoadedTileEnumerator(Tile* pRootTile) noexcept;
+
+  /** @brief Returns an iterator starting at the first tile. */
+  const_iterator begin() const noexcept;
+  /** @brief Returns an iterator starting after the last tile. */
+  const_iterator end() const noexcept;
+
+  /** @brief Returns an iterator starting at the first tile. */
+  iterator begin() noexcept;
+  /** @brief Returns an iterator starting after the last tile. */
+  iterator end() noexcept;
+
+private:
+  Tile* _pRootTile;
+};
+
+} // namespace Cesium3DTilesSelection

Cesium3DTilesSelection/include/Cesium3DTilesSelection/RasterOverlayCollection.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <Cesium3DTilesSelection/Library.h>
+#include <Cesium3DTilesSelection/LoadedTileEnumerator.h>
 #include <Cesium3DTilesSelection/TilesetExternals.h>
 #include <CesiumGeospatial/Ellipsoid.h>
 #include <CesiumRasterOverlays/RasterOverlay.h>
@@ -15,6 +16,8 @@
 
 namespace Cesium3DTilesSelection {
 
+class LoadedTileEnumerator;
+
 /**
  * @brief A collection of {@link CesiumRasterOverlays::RasterOverlay} instances that are associated
  * with a {@link Tileset}.
@@ -31,18 +34,31 @@ class CESIUM3DTILESSELECTION_API RasterOverlayCollection final {
   /**
    * @brief Creates a new instance.
    *
-   * @param loadedTiles The list of loaded tiles. The collection does not own
-   * this list, so the list needs to be kept alive as long as the collection's
-   * lifetime
+   * @param loadedTiles An enumerator for the loaded tiles. The raster overlay
+   * collection will copy this enumerator, and the copy must remain valid for
+   * the lifetime of the overlay collection or until \ref
+   * setLoadedTileEnumerator is called with a new enumerator.
    * @param externals A collection of loading system to load a raster overlay
    * @param ellipsoid The {@link CesiumGeospatial::Ellipsoid}.
    */
   RasterOverlayCollection(
-      Tile::LoadedLinkedList& loadedTiles,
+      const LoadedTileEnumerator& loadedTiles,
       const TilesetExternals& externals,
       const CesiumGeospatial::Ellipsoid& ellipsoid
           CESIUM_DEFAULT_ELLIPSOID) noexcept;
 
+  /**
+   * @brief Provides a new \ref LoadedTileEnumerator to use to update
+   * loaded tiles when a raster overlay is added or removed.
+   *
+   * The raster overlay collection will copy this enumerator, and the copy must
+   * remain valid for the lifetime of the overlay collection or until \ref
+   * setLoadedTileEnumerator is called with a new enumerator.
+   *
+   * @param loadedTiles The new loaded tile enumerator.
+   */
+  void setLoadedTileEnumerator(const LoadedTileEnumerator& loadedTiles);
+
   /**
    * @brief Deleted Copy constructor.
    *
@@ -206,7 +222,7 @@ class CESIUM3DTILESSELECTION_API RasterOverlayCollection final {
         placeholders{};
   };
 
-  Tile::LoadedLinkedList* _pLoadedTiles;
+  LoadedTileEnumerator _loadedTiles;
   TilesetExternals _externals;
   CesiumGeospatial::Ellipsoid _ellipsoid;
   CesiumUtility::IntrusivePointer<OverlayList> _pOverlays;