Merge branch 'main' into abseil-configure-order

Author: kring

.github/workflows/build.yml

@@ -15,14 +15,19 @@ 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: Generate Documentation
         run: |
-          doxygen ./Documentation~/Doxyfile
+          npm run doxygen
       - name: Publish Documentation Artifact
         if: ${{ success() }}
         uses: actions/upload-artifact@v4

.gitmodules

@@ -11,3 +11,6 @@
 	path = native~/extern/swl-variant
 	url = https://github.com/kring/swl-variant.git
 	branch = exception-public-inheritance
+[submodule "Documentation~/doxygen-awesome-css"]
+	path = Documentation~/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git

CHANGES.md

@@ -4,6 +4,7 @@
 
 ##### Fixes :wrench:
 
+- Fixed a bug that could cause a crash or incorrect textures when multiple `Cesium3DTileset` tiles referenced the same image by URL.
 - Fixed a bug in the Abseil vcpkg overlay port that could cause linker errors on some systems.
 
 ## v1.14.0 - 2024-12-02

Documentation~/Doxyfile

@@ -48,13 +48,13 @@ PROJECT_NAME           = "Cesium for Unity"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         =
+PROJECT_NUMBER         = $(npm_package_version)
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = "Unlock the 3D geospatial ecosystem in Unity with real-world 3D content and a high accuracy full-scale WGS84 globe."
+PROJECT_BRIEF          = 
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
@@ -372,7 +372,7 @@ TOC_INCLUDE_HEADINGS   = 5
 # The default value is: DOXYGEN.
 # This tag requires that the tag MARKDOWN_SUPPORT is set to YES.
 
-MARKDOWN_ID_STYLE      = DOXYGEN
+MARKDOWN_ID_STYLE      = GITHUB
 
 # When enabled doxygen tries to link words that correspond to documented
 # classes, or namespaces to their corresponding documentation. Such a link can
@@ -390,7 +390,7 @@ AUTOLINK_SUPPORT       = YES
 # diagrams that involve STL classes more complete and accurate.
 # The default value is: NO.
 
-BUILTIN_STL_SUPPORT    = NO
+BUILTIN_STL_SUPPORT    = YES
 
 # If you use Microsoft's C++/CLI language, you should set this option to YES to
 # enable parsing support.
@@ -943,7 +943,10 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ./Runtime
+INPUT                  = ./Runtime \
+                         ./Documentation~/ \
+                         ./README.md \
+                         ./Reinterop~/README.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1093,7 +1096,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = 
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1154,7 +1157,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = ./README.md
 
 # The Fortran standard specifies that for fixed formatted Fortran code all
 # characters from position 72 are to be considered as comment. A common
@@ -1176,7 +1179,7 @@ FORTRAN_COMMENT_AFTER  = 72
 # also VERBATIM_HEADERS is set to NO.
 # The default value is: NO.
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body of functions,
 # classes and enums directly into the documentation.
@@ -1393,7 +1396,7 @@ HTML_STYLESHEET        =
 # documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_STYLESHEET  = ./Documentation~/doxygen-awesome-css/doxygen-awesome.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -1416,7 +1419,7 @@ HTML_EXTRA_FILES       =
 # The default value is: AUTO_LIGHT.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE        = AUTO_LIGHT
+HTML_COLORSTYLE        = LIGHT
 
 # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen
 # will adjust the colors in the style sheet and background images according to
@@ -1717,7 +1720,7 @@ DISABLE_INDEX          = NO
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 
 # When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the
 # FULL_SIDEBAR option determines if the side bar is limited to only the treeview
@@ -2455,14 +2458,14 @@ ALLEXTERNALS           = NO
 # listed.
 # The default value is: YES.
 
-EXTERNAL_GROUPS        = YES
+EXTERNAL_GROUPS        = NO
 
 # If the EXTERNAL_PAGES tag is set to YES, all external pages will be listed in
 # the related pages index. If set to NO, only the current project's pages will
 # be listed.
 # The default value is: YES.
 
-EXTERNAL_PAGES         = YES
+EXTERNAL_PAGES         = NO
 
 #---------------------------------------------------------------------------
 # Configuration options related to diagram generator tools

Documentation~/copy-images.js

@@ -0,0 +1,18 @@
+/**
+ * Documentation for Cesium for Unity needs to exist under the Documentation~ folder, 
+ * as folders ending in ~ are ignored by Unity. However, this causes an issue with 
+ * Doxygen, as described here: https://github.com/doxygen/doxygen/issues/11273
+ * 
+ * The solution to this is to avoid putting the images in Doxygen's `IMAGE_PATH`,
+ * which triggers the issue, instead copying them to the same relative directory as
+ * the original image path in the Markdown files. The problem is that doing this from
+ * the package.json script will cause issues with the difference between `cp` on Linux
+ * and `copy` on Windows. Instead, we use this script to perform the copy operation
+ * in a cross-platform way.
+ */
+const fs = require("fs");
+
+fs.mkdirSync("./Reference/html/Documentation~/images", { recursive: true });
+const images = fs.readdirSync("./images");
+images.forEach(img => fs.copyFileSync("./images/" + img, "./Reference/html/Documentation~/images/" + img));
+console.log(`copied ${images.length} images to Documentation~/Reference/html`);

Documentation~/creating-monobehaviours.md

@@ -1,3 +1,5 @@
+# Creating MonoBehaviours {#creating-monobehaviours}
+
 Guidelines and tips for creating MonoBehaviours in Cesium for Unity.
 
 ## Avoid implementing non-static methods in C++
@@ -25,11 +27,11 @@ If you don't need C++-specific state, static methods are _much_ more efficient.
 
 Carefully consider every field that you add to the class. In general, only the essential fields necessary to reconstruct the state of the object should by marked `[SerializeField]`. Cached and derived fields should instead be marked `[NonSerialized]`. Fields without any attribute should be extremely rare.
 
-| *Characteristic*              | *`[SerializeField]`* | *No attribute* | *`[NonSerialized]`* |
-|-------------------------------|----------------------|--------------|-------------------|
-| Saved / Loaded with the Scene | ✅                   | ❌          | ❌                |
-| Preserved on script change / AppDomain reload | ✅   | ✅          | ❌                |
-| Transfers from Edit mode to Play mode      | ✅   | ❌          | ❌                |
+| *Characteristic*                              | *`[SerializeField]`* | *No attribute* | *`[NonSerialized]`* |
+| --------------------------------------------- | -------------------- | -------------- | ------------------- |
+| Saved / Loaded with the Scene                 | ✅                    | ❌              | ❌                   |
+| Preserved on script change / AppDomain reload | ✅                    | ✅              | ❌                   |
+| Transfers from Edit mode to Play mode         | ✅                    | ❌              | ❌                   |
 
 ## Backward compatibility
 

Documentation~/developer-resources.md

@@ -0,0 +1,6 @@
+# Developer Resources {#developer-resources}
+
+- \subpage developer-setup
+- \subpage reinterop
+- \subpage creating-monobehaviours
+- \subpage release-guide

Documentation~/developer-setup.md

@@ -1,8 +1,9 @@
-# Overview
+# Developer Setup {#developer-setup}
 
 This is a summary of the setup and workflows for developers who want to modify the Cesium for Unity plugin. If you just want to use Cesium for Unity in your own applications, see the main [README](../README.md).
+<!--! [TOC] -->
 
-## :computer: Building Cesium for Unity
+## 🖥️ Building Cesium for Unity
 
 ### Prerequisites
 
@@ -38,7 +39,7 @@ git clone --recurse-submodules git@github.com:CesiumGS/cesium-unity.git com.cesi
 
 Be sure to also clone the submodules. If you forgot the `--recurse-submodules` option when you cloned, run `git submodule update --init --recursive` inside the `com.cesium.unity` folder.
 
-## Reinterop
+## Reinterop {#reinterop-guide}
 
 Reinterop is a Roslyn (C# compiler) source generator that is automatically invoked by Unity while compiling the Cesium for Unity C# code, and generates C# <-> C++ interop layer.
 

Documentation~/doxygen-awesome-css

@@ -1,6 +1,7 @@
-# Releasing a new version of Cesium for Unity
+# Releasing a new version of Cesium for Unity {#release-guide}
 
 This is the process we follow when releasing a new version of Cesium for Unity on GitHub.
+<!--! [TOC] -->
 
 ## Test the release candidate
 

Documentation~/release-guide.md

@@ -4,36 +4,36 @@ Cesium for Unity enables building 3D geospatial applications and experiences wit
 
 [Cesium for Unity Homepage](https://cesium.com/platform/cesium-for-unity?utm_source=github&utm_medium=github&utm_campaign=unity)
 
-### :rocket: Get Started
+### 🚀 Get Started
 
 **[Download Cesium for Unity Samples](https://github.com/CesiumGS/cesium-unity-samples/releases/latest)**
 
 **[Follow the Quickstart](https://cesium.com/learn/unity/unity-quickstart/)**
 
 Have questions? Ask them on the [community forum](https://community.cesium.com/c/cesium-for-unity).
 
-### :clap: Featured Demos
+### 👏 Featured Demos
 
-<a href="https://github.com/CesiumGS/cesium-unity-samples"><img src="Documentation~/images/cesium-for-unity-screenshot.jpg" width="48%" title="Cesium for Unity Samples" /></a>
+[![](Documentation~/images/cesium-for-unity-screenshot.jpg)](https://github.com/CesiumGS/cesium-unity-samples)
 
-### :house_with_garden: Cesium for Unity and the 3D Geospatial Ecosystem
+### 🏡 Cesium for Unity and the 3D Geospatial Ecosystem
 
 Cesium for Unity streams real-world 3D content such as high-resolution photogrammetry, terrain, imagery, and 3D buildings from [Cesium ion](https://cesium.com/cesium-ion) and other sources, available as optional commercial subscriptions. The plugin includes Cesium ion integration for instant access to global high-resolution 3D content ready for runtime streaming. Cesium ion users can also leverage cloud-based 3D tiling pipelines to create end-to-end workflows to transform massive heterogenous content into semantically-rich 3D Tiles, ready for streaming to Unity.
 
 Cesium for Unity supports cloud and private network content and services based on open standards and APIs. You are free to use any combination of supported content sources, standards, APIs with Cesium for Unity.
 
-![Cesium for Unity Architecture](./Documentation~/images/integration-workflow_Unity.png)
+![Cesium for Unity Architecture](Documentation~/images/integration-workflow_Unity.png)
 
-Using Cesium ion helps support Cesium for Unity development. :heart:
+Using Cesium ion helps support Cesium for Unity development. ❤️
 
-### :chains: Unity Integration
+### ⛓️ Unity Integration
 
 Cesium for Unity is tightly integrated with Unity making it possible to visualize and interact with real-world content in editor and at runtime. The plugin also has support for Unity game objects, physics, collisions, and character interaction. Leverage decades worth of cutting-edge advancements in Unity and geospatial to create cohesive, interactive, and realistic simulations and applications with Cesium for Unity.
 
-### :green_book: License
+### 📗 License
 
 [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html). Cesium for Unity is free for both commercial and non-commercial use.
 
-### :computer: Developing Cesium for Unity
+### 🖥️ Developing Cesium for Unity
 
 See the [Developer Setup Guide](Documentation~/developer-setup.md) to learn how to set up a development environment for Cesium for Unity, allowing you to compile it, customize it, and contribute to its development.

README.md

@@ -1,6 +1,7 @@
-# Reinterop
+# Reinterop {#reinterop}
 
 Reinterop generates C# and C++ code to allow a .NET library to be seamlessly used from C++ code.
+<!--! [TOC] -->
 
 **Note: Reinterop currently requires the latest preview version of Visual Studio 2022, because it uses C# 11 / .NET 7. However, the generated code can be used almost anywhere, including in Unity's version of Mono.**
 

Reinterop~/README.md

@@ -103,8 +103,8 @@ public Dictionary<String, CesiumMetadataValue> GetMetadataValuesForFeature(Int64
         /// If the feature ID is out-of-bounds, the returned dictionary will be empty.
         /// </para>
         /// </remarks>
+        /// <param name="values">The dictionary of values that will be cleared and filled by this method.</param>
         /// <param name="featureId">The ID of the feature.</param>
-        /// <returns>A dictionary of the property values mapped by property name.</returns>
         public void GetMetadataValuesForFeature(Dictionary<String, CesiumMetadataValue> values, Int64 featureId)
         {
             values.Clear();

Runtime/CesiumPropertyTable.cs

@@ -25,6 +25,7 @@ public static CesiumSimplePlanarEllipsoidCurve FromEarthCenteredEarthFixedCoordi
         /// Creates a new <see cref="CesiumSimplePlanarEllipsoidCurve"/> object from a pair of 
         /// Ellipsoid-Centered, Ellipsoid-Fixed coordinates describing the beginning and end points of the curve.
         /// </summary>
+        /// <param name="ellipsoid">The ellipsoid to use for this curve.</param>
         /// <param name="sourceEcef">The start point of the curve.</param>
         /// <param name="destinationEcef">The end point of the curve.</param>
         /// <returns>
@@ -46,6 +47,7 @@ public static CesiumSimplePlanarEllipsoidCurve FromCenteredFixedCoordinates(Cesi
         /// Creates a new <see cref="CesiumSimplePlanarEllipsoidCurve"/> object from a pair of cartographic 
         /// coordinates (Longitude, Latitude, and Height) describing the beginning and end points of the curve.
         /// </summary>
+        /// <param name="ellipsoid">The ellipsoid to use for this curve.</param>
         /// <param name="sourceLlh">The start point of the curve.</param>
         /// <param name="destinationLlh">The end point of the curve.</param>
         /// <returns>

Runtime/CesiumSimplePlanarEllipsoidCurve.cs

@@ -268,6 +268,15 @@ void generateMipMaps(
       const Sampler* pSampler =
           Model::getSafe(&pModel->samplers, pTexture->sampler);
       if (pImage && pSampler) {
+        // We currently do not support shared resources, so if this image is
+        // associated with a depot, unshare it. This is necessary to avoid a
+        // race condition where multiple threads attempt to generate mipmaps for
+        // the same shared image simultaneously.
+        if (pImage->pAsset && pImage->pAsset->getDepot()) {
+          // Copy the asset.
+          pImage->pAsset.emplace(*pImage->pAsset);
+        }
+
         switch (pSampler->minFilter.value_or(
             CesiumGltf::Sampler::MinFilter::LINEAR_MIPMAP_LINEAR)) {
         case CesiumGltf::Sampler::MinFilter::LINEAR_MIPMAP_LINEAR:

native~/Runtime/src/UnityPrepareRendererResources.cpp

@@ -11,7 +11,7 @@
     "url": "https://cesium.com"
   },
   "scripts": {
-    "doxygen": "doxygen ./Documentation~/Doxyfile"
+    "doxygen": "doxygen ./Documentation~/Doxyfile && cd Documentation~ && node copy-images.js && cd .."
   },
   "changelogUrl": "https://github.com/CesiumGS/cesium-unity/blob/main/CHANGES.md",
   "documentationUrl": "https://cesium.com/learn/unity/",