Merge remote-tracking branch 'origin/main' into i3dm-rotation-fix

.github/workflows/build.yml

@@ -131,13 +131,13 @@ jobs:
       fail-fast: false
       matrix:
         compiler: [ gcc, clang ]
-        platform: [ ubuntu-22.04, ubuntu-20.04, macos-15 ]
+        platform: [ ubuntu-22.04, ubuntu-20.04, macos-13 ]
         build_type: [Debug, RelWithDebInfo]
         exclude:
           - compiler: clang
             platform: ubuntu-22.04
           - compiler: gcc
-            platform: macos-15
+            platform: macos-13
           - compiler: gcc
             platform: ubuntu-20.04
     name: "${{matrix.platform}} / ${{matrix.compiler}} / ${{matrix.build_type}}"
@@ -166,12 +166,12 @@ jobs:
             vcpkg-${{ env.CACHE_KEY }}-${{ hashFiles('CMakeLists.txt') }}
             vcpkg-${{ env.CACHE_KEY }}
       - name: Set CC and CXX
-        if: ${{ matrix.compiler == 'clang' && matrix.platform != 'macos-15'}}
+        if: ${{ matrix.compiler == 'clang' && matrix.platform != 'macos-13'}}
         run: |
           echo "CC=clang-12" >> "$GITHUB_ENV"
           echo "CXX=clang++-12" >> "$GITHUB_ENV"
       - name: Make more swap space available
-        if: ${{ matrix.platform != 'macos-15'}}
+        if: ${{ matrix.platform != 'macos-13'}}
         run: |
           sudo swapoff -a
           sudo fallocate -l 10G /mnt/swapfile
@@ -180,9 +180,20 @@ jobs:
           sudo swapon /mnt/swapfile
           sudo swapon --show
       - name: Set macOS cmake options
-        if: ${{ matrix.platform == 'macos-15' }}
+        if: ${{ matrix.platform == 'macos-13' }}
         run: |
-          echo "EXTRA_CMAKE_OPTIONS=-DCMAKE_OSX_DEPLOYMENT_TARGET=10.15 -DCMAKE_OSX_ARCHITECTURES=x86_64 -DCMAKE_SYSTEM_NAME=Darwin -DCMAKE_SYSTEM_PROCESSOR=x86_64" >> "$GITHUB_ENV"
+          # Use a custom triplet to target macOS 10.15.
+          mkdir -p vcpkg/triplets
+          echo "
+            set(VCPKG_CMAKE_SYSTEM_NAME Darwin)
+            set(VCPKG_CRT_LINKAGE dynamic)
+            set(VCPKG_LIBRARY_LINKAGE static)
+            set(VCPKG_OSX_DEPLOYMENT_TARGET 10.15)
+            set(VCPKG_TARGET_ARCHITECTURE x64)
+            set(VCPKG_OSX_ARCHITECTURES x86_64)
+          " > vcpkg/triplets/x64-macos-10-15.cmake
+          # Specify the overlay triplet, and also tell cesium-native to build with the same settings.
+          echo "EXTRA_CMAKE_OPTIONS=-DVCPKG_OVERLAY_TRIPLETS=$PWD/vcpkg/triplets -DVCPKG_TRIPLET=x64-macos-10-15 -DCMAKE_OSX_DEPLOYMENT_TARGET=10.15 -DCMAKE_OSX_ARCHITECTURES=x86_64 -DCMAKE_SYSTEM_NAME=Darwin -DCMAKE_SYSTEM_PROCESSOR=x86_64" >> "$GITHUB_ENV"
       - name: Compile ${{matrix.build_type}} Configuration
         run: |
           cmake -B build -S . -DCMAKE_BUILD_TYPE:STRING=${{matrix.build_type}} $EXTRA_CMAKE_OPTIONS

.github/workflows/prod.yml

@@ -3,6 +3,7 @@ on:
   push:
     branches:
       - 'cesium.com'
+      - 'cesium.com-staging'
 jobs:
   deploy-docs:
     runs-on: ubuntu-22.04
@@ -13,17 +14,42 @@ jobs:
     steps:
       - name: Install Doxygen
         run: |
-          sudo apt install -y doxygen
+          cd ~
+          wget https://github.com/doxygen/doxygen/releases/download/Release_1_12_0/doxygen-1.12.0.linux.bin.tar.gz
+          tar xzf doxygen-1.12.0.linux.bin.tar.gz
+          export PATH=$PWD/doxygen-1.12.0/bin:$PATH
+          echo "PATH=$PATH" >> "$GITHUB_ENV"
+          doxygen --version
       - name: Check out repository code
         uses: actions/checkout@v4
         with:
           submodules: recursive
+      - name: ccache
+        uses: hendrikmuhs/ccache-action@v1.2.9
+        with:
+          key: ccache-ubuntu-22.04-doxygen
+      - name: Cache vcpkg artifacts
+        uses: actions/cache@v4
+        with:
+          path: ~/.ezvcpkg
+          key:  vcpkg-ubuntu-22.04-doxygen-${{ hashFiles('CMakeLists.txt') }}
+          restore-keys: |
+            vcpkg-ubuntu-22.04-doxygen-${{ hashFiles('CMakeLists.txt') }}
+            vcpkg-ubuntu-22.04-doxygen
+      - name: Mark documentation official
+        if: ${{ github.ref_name == 'cesium.com' }}
+        run: |
+          echo "EXTRA_CONFIGURE_ARGS=-DCESIUM_PRODUCTION_DOCS" >> "$GITHUB_ENV"
       - name: Generate Documentation
         run: |
           npm install
-          cmake -B build -S .
+          cmake -B build -S . $EXTRA_CONFIGURE_ARGS
           cmake --build build --target cesium-native-docs
       - name: Deploy to cesium.com
-        if: ${{ env.AWS_ACCESS_KEY_ID != '' }}
+        if: ${{ github.ref_name == 'cesium.com' }}
         run: |
           aws s3 sync build/doc/html/ s3://cesium-website/cesium-native/ref-doc/ --cache-control "public, max-age=1800" --delete
+      - name: Deploy to cesium.com staging
+        if: ${{ github.ref_name == 'cesium.com-staging' }}
+        run: |
+          aws s3 sync build/doc/html/ s3://cesium-website/cesium-native/ref-doc-staging/ --cache-control "public, max-age=1800" --delete

CHANGES.md

@@ -2,19 +2,30 @@
 
 ### ? - ?
 
+##### Breaking Changes :mega:
+
+- Removed unused types `JsonValueMissingKey` and `JsonValueNotRealValue` from `CesiumUtility`.
+
 ##### Additions :tada:
 
 - Added `offset` getter to `AccessorView`.
 - Added `stride`, `offset`, and `data` getters to `AccessorWriter`.
 - Added `value_type` typedef to `AccessorWriter`.
 - Added `InstanceAttributeSemantics` to `CesiumGltf`.
 - Added `VertexAttributeSemantics::FEATURE_ID_n`.
+- Added a `const` version of `Tileset::forEachLoadedTile`.
+- Added `DebugTileStateDatabase`, which provides tools for debugging the tile selection algorithm using SQLite.
+- Added `CesiumAsync::SqliteHelper`, containing functions for working with SQLite.
 - Updates generated classes for `EXT_structural_metadata`. See https://github.com/CesiumGS/glTF/pull/71.
 
 ##### Fixes :wrench:
 
 - Fixed a bug in `thenPassThrough` that caused a compiler error when given a value by r-value refrence.
+- Fixed a raster overlay bug that could cause unnecessary upsampling with failed or missing overlay tiles.
 - Fixed a bug in  `SubtreeFileReader::loadBinary` that prevented valid subtrees from loading if they did not contain binary data.
+- Fixed a bug in the `Tileset` selection algorithm that could cause detail to disappear during load in some cases.
+- Improved the "kicking" mechanism in the tileset selection algorithm. The new criteria allows holes in a `Tileset`, when they do occur, to be filled with loaded tiles more incrementally.
+- Fixed a bug in `SharedAssetDepot` that could lead to crashes and other undefined behavior when an asset in the depot outlived the depot itself.
 
 ### v0.42.0 - 2024-12-02
 

CMakeGraphVizOptions.cmake

@@ -0,0 +1,7 @@
+set(GRAPHVIZ_GENERATE_PER_TARGET FALSE)
+set(GRAPHVIZ_GENERATE_DEPENDERS FALSE)
+set(GRAPHVIZ_OBJECT_LIBS FALSE)
+list(APPEND GRAPHVIZ_IGNORE_TARGETS cesium-native-tests)
+list(APPEND GRAPHVIZ_IGNORE_TARGETS "Catch2::*")
+list(APPEND GRAPHVIZ_IGNORE_TARGETS "lib*.lib")
+list(APPEND GRAPHVIZ_IGNORE_TARGETS "lib*.so")

CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contribution Guide {#contributing}
+
+<!--! \cond DOXYGEN_EXCLUDE !-->
+
+## Table of Contents
+
+- [📬Submitting an Issue](#submitting-an-issue)
+- [📝Opening a Pull Request](#opening-a-pull-request)
+  - [Contributor License Agreement (CLA)](#contributor-license-agreement-cla)
+  - [Pull Request Guidelines](#pull-request-guidelines)
+- [⚖️Code of Conduct](#️code-of-conduct)
+
+<!--! \endcond -->
+
+Community involvement in Cesium Native has been and continues to be a key part of its development. Contributing to Cesium Native can take many forms:
+<!--! [TOC] -->
+
+- Making a pull request to add features or fix issues.
+- Submitting an issue to report a bug.
+- Triaging existing issues. This can include attempting to reproduce issues or sharing additional information you have.
+- Being active on the [Cesium community forum](https://community.cesium.com/) by answering questions and providing input on Cesium's direction.
+- Writing tutorials, creating examples, and improving the reference documentation.
+- Sharing projects you've made with Cesium Native with us through the [Cesium community forum](https://community.cesium.com/) or at hello@cesium.com.
+
+More details about writing issues and pull requests is detailed below. For any other guidance you need, don't hesitate to ask on the [Cesium community forum](https://community.cesium.com/)!
+
+## 📬Submitting an Issue
+
+If you have a question, please do not submit an issue; instead, search the [Cesium community forum](https://community.cesium.com/). The forum is very active and there are years of informative archives, often with answers from the core Cesium team. If you do not find an answer to your question, start a new thread and you'll likely get a quick response!
+
+If you think you've found a bug in Cesium Native, first search the [issues](https://github.com/CesiumGS/cesium-native/issues). If an issue already exists, please add a comment expressing your interest and any additional information. This helps us prioritize issues.
+
+If a related issue does not exist, submit a new one. Please be concise and include as much of the following information as is relevant:
+
+- Minimum amount of sample code (and data).
+- Screenshot or animated .gif if appropriate (try [LICEcap](http://www.cockos.com/licecap/)). For example, see [#803](https://github.com/CesiumGS/cesium-native/issues/803). Screenshots are particularly useful for exceptions and rendering artifacts.
+- Link to the thread if this was discussed on the Cesium forum or elsewhere. For example, see [#878](https://github.com/CesiumGS/cesium-native/issues/878).
+- Your operating system and version, compiler and version, and video card. If you're using Cesium Native with an engine like Unreal or Unity, please include this information as well. Are they all up-to-date? Is the issue specific to one of them?
+- The version of Cesium Native. Did this work in a previous version?
+- Ideas for how to fix or workaround the issue. Also mention if you are willing to help fix it. If so, the Cesium team can often provide guidance and the issue may get fixed more quickly with your help.
+
+## 📝Opening a Pull Request
+
+Pull requests are a huge help in the development of Cesium Native. Following the tips in this guide will help your pull request get merged quickly.
+
+> If you plan to make a major change, please start a new thread on the [Cesium community forum](https://community.cesium.com/) first. Pull requests for small features and bug fixes can generally just be opened without discussion on the forum.
+
+### Contributor License Agreement (CLA)
+
+Before we can review a pull request, we require a signed Contributor License Agreement. There is a CLA for:
+
+- [individuals](https://docs.google.com/forms/d/e/1FAIpQLScU-yvQdcdjCFHkNXwdNeEXx5Qhu45QXuWX_uF5qiLGFSEwlA/viewform) and
+- [corporations](https://docs.google.com/forms/d/e/1FAIpQLSeYEaWlBl1tQEiegfHMuqnH9VxyfgXGyIw13C2sN7Fj3J3GVA/viewform).
+
+This only needs to be completed once, and enables contributions to all of the projects under the [CesiumGS](https://github.com/CesiumGS) organization, including Cesium Native. The CLA ensures you retain copyright to your contributions, and provides us the right to use, modify, and redistribute your contributions using the [Apache 2.0 License](LICENSE).
+
+If you have any questions, feel free to reach out to hello@cesium.com!
+
+### Pull Request Guidelines
+
+Our code is our lifeblood so maintaining Cesium Native's high code quality is important to us.
+- For an overview of our workflow see [github pull request workflows](https://cesium.com/blog/2013/10/08/github-pull-request-workflows/).
+- Pull request tips
+  - If your pull request fixes an existing issue, include a link to the issue in the description (like this: &quot;Fixes [#1](https://github.com/CesiumGS/cesium-native/issues/1)&quot;). Likewise, if your pull request fixes an issue reported on the Cesium forum, include a link to the thread.
+  - If your pull request needs additional work, include a [task list](https://github.com/blog/1375%0A-task-lists-in-gfm-issues-pulls-comments).
+  - Once you are done making new commits to address feedback, add a comment to the pull request such as `"this is ready"`.
+- Code and tests
+  - Review the [C++ Style Guide](doc/topics/style-guide.md). These guidelines help us write consistent, performant, less buggy code and improve our productivity by standardizing the decisions we make across the codebase.
+  - Verify that all tests pass, and write new tests with excellent code coverage for new code. Tests can be built and run using the `cesium-native-tests` target.
+  - Update [CHANGES.md](CHANGES.md) with a brief description of your changes.
+  - If you plan to add a third-party library, start a [GitHub issue](https://github.com/CesiumGS/cesium/issues/new) discussing it first.
+
+## ⚖️Code of Conduct
+
+To ensure an inclusive community, contributors and users in the Cesium community should follow the [code of conduct](https://github.com/CesiumGS/cesium/blob/main/CODE_OF_CONDUCT.md).

Cesium3DTiles/generated/include/Cesium3DTiles/Asset.h

@@ -13,6 +13,9 @@ namespace Cesium3DTiles {
  * @brief Metadata about the entire tileset.
  */
 struct CESIUM3DTILES_API Asset final : public CesiumUtility::ExtensibleObject {
+  /**
+   * @brief The original name of this type.
+   */
   static constexpr const char* TypeName = "Asset";
 
   /**

Cesium3DTiles/generated/include/Cesium3DTiles/Availability.h

@@ -14,15 +14,20 @@ namespace Cesium3DTiles {
  */
 struct CESIUM3DTILES_API Availability final
     : public CesiumUtility::ExtensibleObject {
+  /**
+   * @brief The original name of this type.
+   */
   static constexpr const char* TypeName = "Availability";
 
   /**
    * @brief Known values for Integer indicating whether all of the elements are
    * available (1) or all are unavailable (0).
    */
   struct Constant {
+    /** @brief UNAVAILABLE (`0`) */
     static constexpr int32_t UNAVAILABLE = 0;
 
+    /** @brief AVAILABLE (`1`) */
     static constexpr int32_t AVAILABLE = 1;
   };
 

Cesium3DTiles/generated/include/Cesium3DTiles/BoundingVolume.h

@@ -15,6 +15,9 @@ namespace Cesium3DTiles {
  */
 struct CESIUM3DTILES_API BoundingVolume final
     : public CesiumUtility::ExtensibleObject {
+  /**
+   * @brief The original name of this type.
+   */
   static constexpr const char* TypeName = "BoundingVolume";
 
   /**

Cesium3DTiles/generated/include/Cesium3DTiles/BufferSpec.h

@@ -15,6 +15,9 @@ namespace Cesium3DTiles {
  * subtree file, or an external buffer referenced by a URI.
  */
 struct CESIUM3DTILES_API BufferSpec : public CesiumUtility::ExtensibleObject {
+  /**
+   * @brief The original name of this type.
+   */
   static constexpr const char* TypeName = "Buffer";
 
   /**

Cesium3DTiles/generated/include/Cesium3DTiles/BufferView.h

@@ -15,6 +15,9 @@ namespace Cesium3DTiles {
  */
 struct CESIUM3DTILES_API BufferView final
     : public CesiumUtility::ExtensibleObject {
+  /**
+   * @brief The original name of this type.
+   */
   static constexpr const char* TypeName = "BufferView";
 
   /**

Cesium3DTiles/generated/include/Cesium3DTiles/Class.h

@@ -15,6 +15,9 @@ namespace Cesium3DTiles {
  * @brief A class containing a set of properties.
  */
 struct CESIUM3DTILES_API Class final : public CesiumUtility::ExtensibleObject {
+  /**
+   * @brief The original name of this type.
+   */
   static constexpr const char* TypeName = "Class";
 
   /**

Cesium3DTiles/generated/include/Cesium3DTiles/ClassProperty.h

@@ -16,30 +16,43 @@ namespace Cesium3DTiles {
  */
 struct CESIUM3DTILES_API ClassProperty final
     : public CesiumUtility::ExtensibleObject {
+  /**
+   * @brief The original name of this type.
+   */
   static constexpr const char* TypeName = "ClassProperty";
 
   /**
    * @brief Known values for The element type.
    */
   struct Type {
+    /** @brief `SCALAR` */
     inline static const std::string SCALAR = "SCALAR";
 
+    /** @brief `VEC2` */
     inline static const std::string VEC2 = "VEC2";
 
+    /** @brief `VEC3` */
     inline static const std::string VEC3 = "VEC3";
 
+    /** @brief `VEC4` */
     inline static const std::string VEC4 = "VEC4";
 
+    /** @brief `MAT2` */
     inline static const std::string MAT2 = "MAT2";
 
+    /** @brief `MAT3` */
     inline static const std::string MAT3 = "MAT3";
 
+    /** @brief `MAT4` */
     inline static const std::string MAT4 = "MAT4";
 
+    /** @brief `STRING` */
     inline static const std::string STRING = "STRING";
 
+    /** @brief `BOOLEAN` */
     inline static const std::string BOOLEAN = "BOOLEAN";
 
+    /** @brief `ENUM` */
     inline static const std::string ENUM = "ENUM";
   };
 
@@ -48,24 +61,34 @@ struct CESIUM3DTILES_API ClassProperty final
    * for `SCALAR`, `VECN`, and `MATN` types, and disallowed for other types.
    */
   struct ComponentType {
+    /** @brief `INT8` */
     inline static const std::string INT8 = "INT8";
 
+    /** @brief `UINT8` */
     inline static const std::string UINT8 = "UINT8";
 
+    /** @brief `INT16` */
     inline static const std::string INT16 = "INT16";
 
+    /** @brief `UINT16` */
     inline static const std::string UINT16 = "UINT16";
 
+    /** @brief `INT32` */
     inline static const std::string INT32 = "INT32";
 
+    /** @brief `UINT32` */
     inline static const std::string UINT32 = "UINT32";
 
+    /** @brief `INT64` */
     inline static const std::string INT64 = "INT64";
 
+    /** @brief `UINT64` */
     inline static const std::string UINT64 = "UINT64";
 
+    /** @brief `FLOAT32` */
     inline static const std::string FLOAT32 = "FLOAT32";
 
+    /** @brief `FLOAT64` */
     inline static const std::string FLOAT64 = "FLOAT64";
   };
 

Cesium3DTiles/generated/include/Cesium3DTiles/ClassStatistics.h

@@ -18,6 +18,9 @@ namespace Cesium3DTiles {
  */
 struct CESIUM3DTILES_API ClassStatistics final
     : public CesiumUtility::ExtensibleObject {
+  /**
+   * @brief The original name of this type.
+   */
   static constexpr const char* TypeName = "ClassStatistics";
 
   /**

Cesium3DTiles/generated/include/Cesium3DTiles/Content.h

@@ -17,6 +17,9 @@ namespace Cesium3DTiles {
  */
 struct CESIUM3DTILES_API Content final
     : public CesiumUtility::ExtensibleObject {
+  /**
+   * @brief The original name of this type.
+   */
   static constexpr const char* TypeName = "Content";
 
   /**