diff --git a/CesiumGeometry/include/CesiumGeometry/Availability.h b/CesiumGeometry/include/CesiumGeometry/Availability.h index 4b61f0dde..2db058519 100644 --- a/CesiumGeometry/include/CesiumGeometry/Availability.h +++ b/CesiumGeometry/include/CesiumGeometry/Availability.h @@ -47,6 +47,15 @@ struct CESIUMGEOMETRY_API SubtreeBufferView { uint8_t buffer; }; +/** + * @brief A view into availability information for part of the availability + * tree. This could be either a constant boolean value or a descriptor pointing + * to a buffer in an \ref AvailabilitySubtree where the information will be + * looked up. + * + * Instead of using this type directly, \ref AvailabilityAccessor can be used to + * work with it safely. + */ typedef std::variant AvailabilityView; /** diff --git a/CesiumGeometry/include/CesiumGeometry/AxisAlignedBox.h b/CesiumGeometry/include/CesiumGeometry/AxisAlignedBox.h index f4033028d..54a1e1eb3 100644 --- a/CesiumGeometry/include/CesiumGeometry/AxisAlignedBox.h +++ b/CesiumGeometry/include/CesiumGeometry/AxisAlignedBox.h @@ -6,8 +6,16 @@ namespace CesiumGeometry { +/** + * @brief An Axis-Aligned Bounding Box (AABB), where the axes of the box are + * aligned with the axes of the coordinate system. + */ struct CESIUMGEOMETRY_API AxisAlignedBox final { + /** + * @brief Creates an empty AABB with a length, width, and height of zero, + * with the center located at (0, 0, 0). + */ constexpr AxisAlignedBox() noexcept : minimumX(0.0), minimumY(0.0), @@ -20,6 +28,16 @@ struct CESIUMGEOMETRY_API AxisAlignedBox final { lengthZ(0.0), center(0.0) {} + /** + * @brief Creates a new AABB using the range of coordinates the box covers. + * + * @param minimumX_ The minimum X coordinate within the box. + * @param minimumY_ The minimum Y coordinate within the box. + * @param minimumZ_ The minimum Z coordinate within the box. + * @param maximumX_ The maximum X coordinate within the box. + * @param maximumY_ The maximum Y coordinate within the box. + * @param maximumZ_ The maximum Z coordinate within the box. + */ constexpr AxisAlignedBox( double minimumX_, double minimumY_, @@ -91,6 +109,12 @@ struct CESIUMGEOMETRY_API AxisAlignedBox final { */ glm::dvec3 center; + /** + * @brief Checks if this AABB contains the given position. + * + * @param position The position to check. + * @returns True if this AABB contains the position, false otherwise. + */ constexpr bool contains(const glm::dvec3& position) const noexcept { return position.x >= this->minimumX && position.x <= this->maximumX && position.y >= this->minimumY && position.y <= this->maximumY && diff --git a/CesiumGeometry/include/CesiumGeometry/OctreeAvailability.h b/CesiumGeometry/include/CesiumGeometry/OctreeAvailability.h index 572147149..7f2a17bca 100644 --- a/CesiumGeometry/include/CesiumGeometry/OctreeAvailability.h +++ b/CesiumGeometry/include/CesiumGeometry/OctreeAvailability.h @@ -12,6 +12,10 @@ namespace CesiumGeometry { +/** + * @brief An availability tree for an octree, where availability can be stored + * and computed based on \ref OctreeTileID. + */ class CESIUMGEOMETRY_API OctreeAvailability final { public: /** @@ -136,6 +140,8 @@ class CESIUMGEOMETRY_API OctreeAvailability final { /** * @brief Gets the number of levels in each subtree. + * + * @returns The number of levels in each subtree. */ constexpr inline uint32_t getSubtreeLevels() const noexcept { return this->_subtreeLevels; @@ -143,6 +149,8 @@ class CESIUMGEOMETRY_API OctreeAvailability final { /** * @brief Gets the index of the maximum level in this implicit tileset. + * + * @returns The index of the maximum level. */ constexpr inline uint32_t getMaximumLevel() const noexcept { return this->_maximumLevel; @@ -150,6 +158,8 @@ class CESIUMGEOMETRY_API OctreeAvailability final { /** * @brief Gets a pointer to the root subtree node of this implicit tileset. + * + * @returns The root node of the availability tree. */ AvailabilityNode* getRootNode() noexcept { return this->_pRoot.get(); } diff --git a/CesiumGeometry/include/CesiumGeometry/QuadtreeAvailability.h b/CesiumGeometry/include/CesiumGeometry/QuadtreeAvailability.h index df787b538..f47dfde35 100644 --- a/CesiumGeometry/include/CesiumGeometry/QuadtreeAvailability.h +++ b/CesiumGeometry/include/CesiumGeometry/QuadtreeAvailability.h @@ -12,6 +12,10 @@ namespace CesiumGeometry { +/** + * @brief An availability tree for a quadtree, where availability can be stored + * and computed based on \ref QuadtreeTileID. + */ class CESIUMGEOMETRY_API QuadtreeAvailability final { public: /** diff --git a/CesiumGeospatial/include/CesiumGeospatial/BoundingRegionBuilder.h b/CesiumGeospatial/include/CesiumGeospatial/BoundingRegionBuilder.h index 3b03bf78c..4f6476f08 100644 --- a/CesiumGeospatial/include/CesiumGeospatial/BoundingRegionBuilder.h +++ b/CesiumGeospatial/include/CesiumGeospatial/BoundingRegionBuilder.h @@ -6,6 +6,10 @@ namespace CesiumGeospatial { +/** + * @brief Helper class for creating a \ref BoundingRegion or \ref GlobeRectangle + * from a set of points. + */ class CESIUMGEOSPATIAL_API BoundingRegionBuilder { public: /** diff --git a/CesiumGltf/include/CesiumGltf/PropertyArrayView.h b/CesiumGltf/include/CesiumGltf/PropertyArrayView.h index 20c1d9198..11ecd26e6 100644 --- a/CesiumGltf/include/CesiumGltf/PropertyArrayView.h +++ b/CesiumGltf/include/CesiumGltf/PropertyArrayView.h @@ -35,15 +35,29 @@ template class PropertyArrayView { PropertyArrayView(const std::span& buffer) noexcept : _values{CesiumUtility::reintepretCastSpan(buffer)} {} + /** + * @brief Accesses the element of this array at the given index. + */ const ElementType& operator[](int64_t index) const noexcept { return this->_values[index]; } + /** + * @brief The number of elements in this array. + */ int64_t size() const noexcept { return this->_values.size(); } + /** + * @brief The `begin` iterator. + */ auto begin() { return this->_values.begin(); } + /** + * @brief The `end` iterator. + */ auto end() { return this->_values.end(); } + /** @copydoc begin */ auto begin() const { return this->_values.begin(); } + /** @copydoc end */ auto end() const { return this->_values.end(); } private: @@ -125,6 +139,13 @@ template class PropertyArrayCopy { PropertyArrayView _view; }; +/** + * @brief A view on a bool array element of a {@link PropertyTableProperty} + * or {@link PropertyTextureProperty}. + * + * Provides utility to retrieve the data stored in the array of + * elements via the array index operator. + */ template <> class PropertyArrayView { public: /** @@ -146,6 +167,9 @@ template <> class PropertyArrayView { int64_t size) noexcept : _values{buffer}, _bitOffset{bitOffset}, _size{size} {} + /** + * @brief Obtains the element in the array at the given index. + */ bool operator[](int64_t index) const noexcept { index += _bitOffset; const int64_t byteIndex = index / 8; @@ -154,6 +178,9 @@ template <> class PropertyArrayView { return bitValue == 1; } + /** + * @brief The number of entries in the array. + */ int64_t size() const noexcept { return _size; } private: @@ -162,6 +189,13 @@ template <> class PropertyArrayView { int64_t _size; }; +/** + * @brief A view on a string array element of a {@link PropertyTableProperty} + * or {@link PropertyTextureProperty}. + * + * Provides utility to retrieve the data stored in the array of + * elements via the array index operator. + */ template <> class PropertyArrayView { public: /** @@ -191,6 +225,9 @@ template <> class PropertyArrayView { _stringOffsetType{stringOffsetType}, _size{size} {} + /** + * @brief Obtains an `std::string_view` for the element at the given index. + */ std::string_view operator[](int64_t index) const noexcept { const size_t currentOffset = getOffsetFromOffsetsBuffer(index, _stringOffsets, _stringOffsetType); @@ -203,6 +240,9 @@ template <> class PropertyArrayView { (nextOffset - currentOffset)); } + /** + * @brief The number of elements in this array. + */ int64_t size() const noexcept { return _size; } private: diff --git a/CesiumGltf/include/CesiumGltf/PropertyTypeTraits.h b/CesiumGltf/include/CesiumGltf/PropertyTypeTraits.h index 46df75966..66ec93f77 100644 --- a/CesiumGltf/include/CesiumGltf/PropertyTypeTraits.h +++ b/CesiumGltf/include/CesiumGltf/PropertyTypeTraits.h @@ -14,30 +14,50 @@ namespace CesiumGltf { * @brief Check if a C++ type can be represented as a scalar property type */ template struct IsMetadataScalar; +/** @copydoc IsMetadataScalar */ template struct IsMetadataScalar : std::false_type {}; +/** @copydoc IsMetadataScalar */ template <> struct IsMetadataScalar : std::true_type {}; +/** @copydoc IsMetadataScalar */ template <> struct IsMetadataScalar : std::true_type {}; +/** @copydoc IsMetadataScalar */ template <> struct IsMetadataScalar : std::true_type {}; +/** @copydoc IsMetadataScalar */ template <> struct IsMetadataScalar : std::true_type {}; +/** @copydoc IsMetadataScalar */ template <> struct IsMetadataScalar : std::true_type {}; +/** @copydoc IsMetadataScalar */ template <> struct IsMetadataScalar : std::true_type {}; +/** @copydoc IsMetadataScalar */ template <> struct IsMetadataScalar : std::true_type {}; +/** @copydoc IsMetadataScalar */ template <> struct IsMetadataScalar : std::true_type {}; +/** @copydoc IsMetadataScalar */ template <> struct IsMetadataScalar : std::true_type {}; +/** @copydoc IsMetadataScalar */ template <> struct IsMetadataScalar : std::true_type {}; /** * @brief Check if a C++ type can be represented as an integer property type */ template struct IsMetadataInteger; +/** @copydoc IsMetadataInteger */ template struct IsMetadataInteger : std::false_type {}; +/** @copydoc IsMetadataInteger */ template <> struct IsMetadataInteger : std::true_type {}; +/** @copydoc IsMetadataInteger */ template <> struct IsMetadataInteger : std::true_type {}; +/** @copydoc IsMetadataInteger */ template <> struct IsMetadataInteger : std::true_type {}; +/** @copydoc IsMetadataInteger */ template <> struct IsMetadataInteger : std::true_type {}; +/** @copydoc IsMetadataInteger */ template <> struct IsMetadataInteger : std::true_type {}; +/** @copydoc IsMetadataInteger */ template <> struct IsMetadataInteger : std::true_type {}; +/** @copydoc IsMetadataInteger */ template <> struct IsMetadataInteger : std::true_type {}; +/** @copydoc IsMetadataInteger */ template <> struct IsMetadataInteger : std::true_type {}; /** @@ -45,15 +65,20 @@ template <> struct IsMetadataInteger : std::true_type {}; * type. */ template struct IsMetadataFloating; +/** @copydoc IsMetadataFloating */ template struct IsMetadataFloating : std::false_type {}; +/** @copydoc IsMetadataFloating */ template <> struct IsMetadataFloating : std::true_type {}; +/** @copydoc IsMetadataFloating */ template <> struct IsMetadataFloating : std::true_type {}; /** * @brief Check if a C++ type can be represented as a vecN type. */ template struct IsMetadataVecN; +/** @copydoc IsMetadataVecN */ template struct IsMetadataVecN : std::false_type {}; +/** @copydoc IsMetadataVecN */ template struct IsMetadataVecN> : IsMetadataScalar {}; @@ -61,7 +86,9 @@ struct IsMetadataVecN> : IsMetadataScalar {}; * @brief Check if a C++ type can be represented as a matN type. */ template struct IsMetadataMatN; +/** @copydoc IsMetadataMatN */ template struct IsMetadataMatN : std::false_type {}; +/** @copydoc IsMetadataMatN */ template struct IsMetadataMatN> : IsMetadataScalar {}; @@ -70,6 +97,9 @@ struct IsMetadataMatN> : IsMetadataScalar {}; * a scalar / vecN / matN type. */ template struct IsMetadataNumeric; +/** + * @copydoc IsMetadataNumeric + */ template struct IsMetadataNumeric { static constexpr bool value = IsMetadataScalar::value || IsMetadataVecN::value || @@ -80,23 +110,30 @@ template struct IsMetadataNumeric { * @brief Check if a C++ type can be represented as a boolean property type */ template struct IsMetadataBoolean; +/** @copydoc IsMetadataBoolean */ template struct IsMetadataBoolean : std::false_type {}; +/** @copydoc IsMetadataBoolean */ template <> struct IsMetadataBoolean : std::true_type {}; /** * @brief Check if a C++ type can be represented as a string property type */ template struct IsMetadataString; +/** @copydoc IsMetadataString */ template struct IsMetadataString : std::false_type {}; +/** @copydoc IsMetadataString */ template <> struct IsMetadataString : std::true_type {}; /** * @brief Check if a C++ type can be represented as an array. */ template struct IsMetadataArray; +/** @copydoc IsMetadataArray */ template struct IsMetadataArray : std::false_type {}; +/** @copydoc IsMetadataArray */ template struct IsMetadataArray> : std::true_type {}; +/** @copydoc IsMetadataArray */ template struct IsMetadataArray> : std::true_type {}; @@ -105,10 +142,13 @@ struct IsMetadataArray> : std::true_type {}; * property type */ template struct IsMetadataNumericArray; +/** @copydoc IsMetadataNumericArray */ template struct IsMetadataNumericArray : std::false_type {}; +/** @copydoc IsMetadataNumericArray */ template struct IsMetadataNumericArray> { static constexpr bool value = IsMetadataNumeric::value; }; +/** @copydoc IsMetadataNumericArray */ template struct IsMetadataNumericArray> { static constexpr bool value = IsMetadataNumeric::value; }; @@ -118,7 +158,9 @@ template struct IsMetadataNumericArray> { * property type */ template struct IsMetadataBooleanArray; +/** @copydoc IsMetadataBooleanArray */ template struct IsMetadataBooleanArray : std::false_type {}; +/** @copydoc IsMetadataBooleanArray */ template <> struct IsMetadataBooleanArray> : std::true_type {}; @@ -127,7 +169,9 @@ struct IsMetadataBooleanArray> : std::true_type {}; * type */ template struct IsMetadataStringArray; +/** @copydoc IsMetadataStringArray */ template struct IsMetadataStringArray : std::false_type {}; +/** @copydoc IsMetadataStringArray */ template <> struct IsMetadataStringArray> : std::true_type {}; @@ -138,10 +182,12 @@ struct IsMetadataStringArray> template struct MetadataArrayType { using type = void; }; +/** @copydoc MetadataArrayType */ template struct MetadataArrayType> { using type = T; }; +/** @copydoc MetadataArrayType */ template struct MetadataArrayType> { using type = T; @@ -154,60 +200,70 @@ template struct TypeToPropertyType; #pragma region Scalar Property Types +/** @copydoc TypeToPropertyType */ template <> struct TypeToPropertyType { static constexpr PropertyComponentType component = PropertyComponentType::Uint8; static constexpr PropertyType value = PropertyType::Scalar; }; +/** @copydoc TypeToPropertyType */ template <> struct TypeToPropertyType { static constexpr PropertyComponentType component = PropertyComponentType::Int8; static constexpr PropertyType value = PropertyType::Scalar; }; +/** @copydoc TypeToPropertyType */ template <> struct TypeToPropertyType { static constexpr PropertyComponentType component = PropertyComponentType::Uint16; static constexpr PropertyType value = PropertyType::Scalar; }; +/** @copydoc TypeToPropertyType */ template <> struct TypeToPropertyType { static constexpr PropertyComponentType component = PropertyComponentType::Int16; static constexpr PropertyType value = PropertyType::Scalar; }; +/** @copydoc TypeToPropertyType */ template <> struct TypeToPropertyType { static constexpr PropertyComponentType component = PropertyComponentType::Uint32; static constexpr PropertyType value = PropertyType::Scalar; }; +/** @copydoc TypeToPropertyType */ template <> struct TypeToPropertyType { static constexpr PropertyComponentType component = PropertyComponentType::Int32; static constexpr PropertyType value = PropertyType::Scalar; }; +/** @copydoc TypeToPropertyType */ template <> struct TypeToPropertyType { static constexpr PropertyComponentType component = PropertyComponentType::Uint64; static constexpr PropertyType value = PropertyType::Scalar; }; +/** @copydoc TypeToPropertyType */ template <> struct TypeToPropertyType { static constexpr PropertyComponentType component = PropertyComponentType::Int64; static constexpr PropertyType value = PropertyType::Scalar; }; +/** @copydoc TypeToPropertyType */ template <> struct TypeToPropertyType { static constexpr PropertyComponentType component = PropertyComponentType::Float32; static constexpr PropertyType value = PropertyType::Scalar; }; +/** @copydoc TypeToPropertyType */ template <> struct TypeToPropertyType { static constexpr PropertyComponentType component = PropertyComponentType::Float64; @@ -217,6 +273,7 @@ template <> struct TypeToPropertyType { #pragma region Vector Property Types +/** @copydoc TypeToPropertyType */ template struct TypeToPropertyType> { static constexpr PropertyComponentType component = @@ -224,6 +281,7 @@ struct TypeToPropertyType> { static constexpr PropertyType value = PropertyType::Vec2; }; +/** @copydoc TypeToPropertyType */ template struct TypeToPropertyType> { static constexpr PropertyComponentType component = @@ -231,6 +289,7 @@ struct TypeToPropertyType> { static constexpr PropertyType value = PropertyType::Vec3; }; +/** @copydoc TypeToPropertyType */ template struct TypeToPropertyType> { static constexpr PropertyComponentType component = @@ -242,6 +301,7 @@ struct TypeToPropertyType> { #pragma region Matrix Property Types +/** @copydoc TypeToPropertyType */ template struct TypeToPropertyType> { static constexpr PropertyComponentType component = @@ -249,6 +309,7 @@ struct TypeToPropertyType> { static constexpr PropertyType value = PropertyType::Mat2; }; +/** @copydoc TypeToPropertyType */ template struct TypeToPropertyType> { static constexpr PropertyComponentType component = @@ -256,6 +317,7 @@ struct TypeToPropertyType> { static constexpr PropertyType value = PropertyType::Mat3; }; +/** @copydoc TypeToPropertyType */ template struct TypeToPropertyType> { static constexpr PropertyComponentType component = @@ -265,12 +327,14 @@ struct TypeToPropertyType> { #pragma endregion +/** @copydoc TypeToPropertyType */ template <> struct TypeToPropertyType { static constexpr PropertyComponentType component = PropertyComponentType::None; static constexpr PropertyType value = PropertyType::Boolean; }; +/** @copydoc TypeToPropertyType */ template <> struct TypeToPropertyType { static constexpr PropertyComponentType component = PropertyComponentType::None; @@ -281,22 +345,34 @@ template <> struct TypeToPropertyType { * @brief Check if a C++ type can be normalized. */ template struct CanBeNormalized; +/** @copydoc CanBeNormalized */ template struct CanBeNormalized : std::false_type {}; +/** @copydoc CanBeNormalized */ template <> struct CanBeNormalized : std::true_type {}; +/** @copydoc CanBeNormalized */ template <> struct CanBeNormalized : std::true_type {}; +/** @copydoc CanBeNormalized */ template <> struct CanBeNormalized : std::true_type {}; +/** @copydoc CanBeNormalized */ template <> struct CanBeNormalized : std::true_type {}; +/** @copydoc CanBeNormalized */ template <> struct CanBeNormalized : std::true_type {}; +/** @copydoc CanBeNormalized */ template <> struct CanBeNormalized : std::true_type {}; +/** @copydoc CanBeNormalized */ template <> struct CanBeNormalized : std::true_type {}; +/** @copydoc CanBeNormalized */ template <> struct CanBeNormalized : std::true_type {}; +/** @copydoc CanBeNormalized */ template struct CanBeNormalized> : CanBeNormalized {}; +/** @copydoc CanBeNormalized */ template struct CanBeNormalized> : CanBeNormalized {}; +/** @copydoc CanBeNormalized */ template struct CanBeNormalized> : CanBeNormalized {}; /** @@ -305,71 +381,91 @@ struct CanBeNormalized> : CanBeNormalized {}; */ template struct TypeToNormalizedType; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType { using type = double; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType { using type = double; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType { using type = double; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType { using type = double; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType { using type = double; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType { using type = double; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType { using type = double; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType { using type = double; }; +/** @copydoc TypeToNormalizedType */ template struct TypeToNormalizedType> { using type = glm::vec; }; +/** @copydoc TypeToNormalizedType */ template struct TypeToNormalizedType> { using type = glm::mat; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType> { using type = PropertyArrayView; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType> { using type = PropertyArrayView; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType> { using type = PropertyArrayView; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType> { using type = PropertyArrayView; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType> { using type = PropertyArrayView; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType> { using type = PropertyArrayView; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType> { using type = PropertyArrayView; }; +/** @copydoc TypeToNormalizedType */ template <> struct TypeToNormalizedType> { using type = PropertyArrayView; }; +/** @copydoc TypeToNormalizedType */ template struct TypeToNormalizedType>> { using type = PropertyArrayView>; }; +/** @copydoc TypeToNormalizedType */ template struct TypeToNormalizedType>> { using type = PropertyArrayView>; @@ -382,6 +478,9 @@ struct TypeToNormalizedType>> { * transforms numeric `PropertyArrayView` to `PropertyArrayCopy` because a * `PropertyArrayView` only has a pointer to the value it is viewing. * + * See \ref propertyValueViewToCopy + * + * @remarks This is the inverse of \ref PropertyValueCopyToView * @tparam T The type of the property value view. */ template @@ -390,6 +489,17 @@ using PropertyValueViewToCopy = std::conditional_t< PropertyArrayCopy::type>, T>; +/** + * @brief Transforms a property value type from a copy that owns the data it is + * viewing to a view into that data. For most property types this is an identity + * transformation, because most property types are held by value. However, it + * transforms numeric `PropertyArrayCopy` to `PropertyArrayView`. + * + * See \ref propertyValueCopyToView + * + * @remarks This is the inverse of \ref PropertyValueViewToCopy + * @tparam T The type of the property value copy. + */ template using PropertyValueCopyToView = std::conditional_t< IsMetadataNumericArray::value, @@ -399,11 +509,11 @@ using PropertyValueCopyToView = std::conditional_t< /** * @brief Creates an optional instance of a type that can be used to own a * property value from an optional instance that is only a view on that value. - * See {@link PropertyValueViewToOwner}. + * See {@link PropertyValueViewToCopy}. * - * @tparam T - * @param view - * @return std::optional> + * @tparam T The type of the view to copy. + * @param view An optional instance of a view on the value that will be copied. + * @return std::optional> */ template static std::optional> @@ -420,6 +530,14 @@ propertyValueViewToCopy(const std::optional& view) { } } +/** + * @brief Creates an instance of a type that will own a property value from a + * view on that value. See \ref PropertyValueViewToOwner. + * + * @tparam T The type of the view to copy. + * @param view A view on the value that will be copied. + * @return PropertyValueViewToCopy + */ template static PropertyValueViewToCopy propertyValueViewToCopy(const T& view) { if constexpr (IsMetadataNumericArray::value) { @@ -429,6 +547,14 @@ static PropertyValueViewToCopy propertyValueViewToCopy(const T& view) { } } +/** + * @brief Creates a view on an owned copy of a property value. See \ref + * PropertyValueCopyToView. + * + * @tparam T The type of the value to create a view from. + * @param copy The value to create a view from. + * @return PropertyValueCopyToView + */ template static PropertyValueCopyToView propertyValueCopyToView(const T& copy) { if constexpr (IsMetadataNumericArray::value) { diff --git a/CesiumGltf/include/CesiumGltf/PropertyView.h b/CesiumGltf/include/CesiumGltf/PropertyView.h index 99b80ffc2..ed730d1e4 100644 --- a/CesiumGltf/include/CesiumGltf/PropertyView.h +++ b/CesiumGltf/include/CesiumGltf/PropertyView.h @@ -782,71 +782,71 @@ template class PropertyView { public: /** - * @copydoc PropertyView::status + * @copydoc PropertyView::status */ PropertyViewStatusType status() const noexcept { return _status; } /** - * @copydoc PropertyView::name + * @copydoc PropertyView::name */ const std::optional& name() const noexcept { return _name; } /** - * @copydoc PropertyView::semantic + * @copydoc PropertyView::semantic */ const std::optional& semantic() const noexcept { return _semantic; } /** - * @copydoc PropertyView::description + * @copydoc PropertyView::description */ const std::optional& description() const noexcept { return _description; } /** - * @copydoc PropertyView::arrayCount + * @copydoc PropertyView::arrayCount */ int64_t arrayCount() const noexcept { return 0; } /** - * @copydoc PropertyView::normalized + * @copydoc PropertyView::normalized */ bool normalized() const noexcept { return true; } /** - * @copydoc PropertyView::offset + * @copydoc PropertyView::offset */ std::optional offset() const noexcept { return _offset; } /** - * @copydoc PropertyView::scale + * @copydoc PropertyView::scale */ std::optional scale() const noexcept { return _scale; } /** - * @copydoc PropertyView::max + * @copydoc PropertyView::max */ std::optional max() const noexcept { return _max; } /** - * @copydoc PropertyView::min + * @copydoc PropertyView::min */ std::optional min() const noexcept { return _min; } /** - * @copydoc PropertyView::required + * @copydoc PropertyView::required */ bool required() const noexcept { return _required; } /** - * @copydoc PropertyView::noData + * @copydoc PropertyView::noData */ std::optional noData() const noexcept { return _noData; } /** - * @copydoc PropertyView::defaultValue + * @copydoc PropertyView::defaultValue */ std::optional defaultValue() const noexcept { return _defaultValue; @@ -1015,71 +1015,71 @@ template <> class PropertyView { public: /** - * @copydoc PropertyView::status + * @copydoc PropertyView::status */ PropertyViewStatusType status() const noexcept { return _status; } /** - * @copydoc PropertyView::name + * @copydoc PropertyView::name */ const std::optional& name() const noexcept { return _name; } /** - * @copydoc PropertyView::semantic + * @copydoc PropertyView::semantic */ const std::optional& semantic() const noexcept { return _semantic; } /** - * @copydoc PropertyView::description + * @copydoc PropertyView::description */ const std::optional& description() const noexcept { return _description; } /** - * @copydoc PropertyView::arrayCount + * @copydoc PropertyView::arrayCount */ int64_t arrayCount() const noexcept { return 0; } /** - * @copydoc PropertyView::normalized + * @copydoc PropertyView::normalized */ bool normalized() const noexcept { return false; } /** - * @copydoc PropertyView::offset + * @copydoc PropertyView::offset */ std::optional offset() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::scale + * @copydoc PropertyView::scale */ std::optional scale() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::max + * @copydoc PropertyView::max */ std::optional max() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::min + * @copydoc PropertyView::min */ std::optional min() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::required + * @copydoc PropertyView::required */ bool required() const noexcept { return _required; } /** - * @copydoc PropertyView::noData + * @copydoc PropertyView::noData */ std::optional noData() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::defaultValue + * @copydoc PropertyView::defaultValue */ std::optional defaultValue() const noexcept { return _defaultValue; } @@ -1188,70 +1188,70 @@ template <> class PropertyView { public: /** - * @copydoc PropertyView::status + * @copydoc PropertyView::status */ PropertyViewStatusType status() const noexcept { return _status; } /** - * @copydoc PropertyView::name + * @copydoc PropertyView::name */ const std::optional& name() const noexcept { return _name; } /** - * @copydoc PropertyView::semantic + * @copydoc PropertyView::semantic */ const std::optional& semantic() const noexcept { return _semantic; } /** - * @copydoc PropertyView::description + * @copydoc PropertyView::description */ const std::optional& description() const noexcept { return _description; } /** - * @copydoc PropertyView::arrayCount + * @copydoc PropertyView::arrayCount */ int64_t arrayCount() const noexcept { return 0; } /** - * @copydoc PropertyView::normalized + * @copydoc PropertyView::normalized */ bool normalized() const noexcept { return false; } /** - * @copydoc PropertyView::offset + * @copydoc PropertyView::offset */ std::optional offset() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::scale + * @copydoc PropertyView::scale */ std::optional scale() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::max + * @copydoc PropertyView::max */ std::optional max() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::min + * @copydoc PropertyView::min */ std::optional min() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::required + * @copydoc PropertyView::required */ bool required() const noexcept { return _required; } /** - * @copydoc PropertyView::noData + * @copydoc PropertyView::noData */ std::optional noData() const noexcept { if (_noData) @@ -1261,7 +1261,7 @@ template <> class PropertyView { } /** - * @copydoc PropertyView::defaultValue + * @copydoc PropertyView::defaultValue */ std::optional defaultValue() const noexcept { if (_defaultValue) @@ -1434,41 +1434,41 @@ class PropertyView, false> { public: /** - * @copydoc PropertyView::status + * @copydoc PropertyView::status */ PropertyViewStatusType status() const noexcept { return _status; } /** - * @copydoc PropertyView::name + * @copydoc PropertyView::name */ const std::optional& name() const noexcept { return _name; } /** - * @copydoc PropertyView::semantic + * @copydoc PropertyView::semantic */ const std::optional& semantic() const noexcept { return _semantic; } /** - * @copydoc PropertyView::description + * @copydoc PropertyView::description */ const std::optional& description() const noexcept { return _description; } /** - * @copydoc PropertyView::arrayCount + * @copydoc PropertyView::arrayCount */ int64_t arrayCount() const noexcept { return _count; } /** - * @copydoc PropertyView::normalized + * @copydoc PropertyView::normalized */ bool normalized() const noexcept { return false; } /** - * @copydoc PropertyView::offset + * @copydoc PropertyView::offset */ std::optional> offset() const noexcept { if (!_offset) { @@ -1480,7 +1480,7 @@ class PropertyView, false> { } /** - * @copydoc PropertyView::scale + * @copydoc PropertyView::scale */ std::optional> scale() const noexcept { if (!_scale) { @@ -1492,7 +1492,7 @@ class PropertyView, false> { } /** - * @copydoc PropertyView::max + * @copydoc PropertyView::max */ std::optional> max() const noexcept { if (!_max) { @@ -1504,7 +1504,7 @@ class PropertyView, false> { } /** - * @copydoc PropertyView::min + * @copydoc PropertyView::min */ std::optional> min() const noexcept { if (!_min) { @@ -1516,12 +1516,12 @@ class PropertyView, false> { } /** - * @copydoc PropertyView::required + * @copydoc PropertyView::required */ bool required() const noexcept { return _required; } /** - * @copydoc PropertyView::noData + * @copydoc PropertyView::noData */ std::optional> noData() const noexcept { if (!_noData) { @@ -1533,7 +1533,7 @@ class PropertyView, false> { } /** - * @copydoc PropertyView::defaultValue + * @copydoc PropertyView::defaultValue */ std::optional> defaultValue() const noexcept { if (!_defaultValue) { @@ -1830,41 +1830,41 @@ class PropertyView, true> { public: /** - * @copydoc PropertyView::status + * @copydoc PropertyView::status */ PropertyViewStatusType status() const noexcept { return _status; } /** - * @copydoc PropertyView::name + * @copydoc PropertyView::name */ const std::optional& name() const noexcept { return _name; } /** - * @copydoc PropertyView::semantic + * @copydoc PropertyView::semantic */ const std::optional& semantic() const noexcept { return _semantic; } /** - * @copydoc PropertyView::description + * @copydoc PropertyView::description */ const std::optional& description() const noexcept { return _description; } /** - * @copydoc PropertyView::arrayCount + * @copydoc PropertyView::arrayCount */ int64_t arrayCount() const noexcept { return _count; } /** - * @copydoc PropertyView::normalized + * @copydoc PropertyView::normalized */ bool normalized() const noexcept { return true; } /** - * @copydoc PropertyView::offset + * @copydoc PropertyView::offset */ std::optional> offset() const noexcept { if (!_offset) { @@ -1876,7 +1876,7 @@ class PropertyView, true> { } /** - * @copydoc PropertyView::scale + * @copydoc PropertyView::scale */ std::optional> scale() const noexcept { if (!_scale) { @@ -1888,7 +1888,7 @@ class PropertyView, true> { } /** - * @copydoc PropertyView::max + * @copydoc PropertyView::max */ std::optional> max() const noexcept { if (!_max) { @@ -1900,7 +1900,7 @@ class PropertyView, true> { } /** - * @copydoc PropertyView::min + * @copydoc PropertyView::min */ std::optional> min() const noexcept { if (!_min) { @@ -1912,12 +1912,12 @@ class PropertyView, true> { } /** - * @copydoc PropertyView::required + * @copydoc PropertyView::required */ bool required() const noexcept { return _required; } /** - * @copydoc PropertyView::noData + * @copydoc PropertyView::noData */ std::optional> noData() const noexcept { if (!_noData) { @@ -1929,7 +1929,7 @@ class PropertyView, true> { } /** - * @copydoc PropertyView::defaultValue + * @copydoc PropertyView::defaultValue */ std::optional> defaultValue() const noexcept { @@ -2140,81 +2140,81 @@ template <> class PropertyView> { public: /** - * @copydoc PropertyView::status + * @copydoc PropertyView::status */ PropertyViewStatusType status() const noexcept { return _status; } /** - * @copydoc PropertyView::name + * @copydoc PropertyView::name */ const std::optional& name() const noexcept { return _name; } /** - * @copydoc PropertyView::semantic + * @copydoc PropertyView::semantic */ const std::optional& semantic() const noexcept { return _semantic; } /** - * @copydoc PropertyView::description + * @copydoc PropertyView::description */ const std::optional& description() const noexcept { return _description; } /** - * @copydoc PropertyView::arrayCount + * @copydoc PropertyView::arrayCount */ int64_t arrayCount() const noexcept { return _count; } /** - * @copydoc PropertyView::normalized + * @copydoc PropertyView::normalized */ bool normalized() const noexcept { return false; } /** - * @copydoc PropertyView::offset + * @copydoc PropertyView::offset */ std::optional> offset() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::scale + * @copydoc PropertyView::scale */ std::optional> scale() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::max + * @copydoc PropertyView::max */ std::optional> max() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::min + * @copydoc PropertyView::min */ std::optional> min() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::required + * @copydoc PropertyView::required */ bool required() const noexcept { return _required; } /** - * @copydoc PropertyView::noData + * @copydoc PropertyView::noData */ std::optional> noData() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::defaultValue + * @copydoc PropertyView::defaultValue */ std::optional> defaultValue() const noexcept { if (_size > 0) { @@ -2371,74 +2371,74 @@ template <> class PropertyView> { public: /** - * @copydoc PropertyView::status + * @copydoc PropertyView::status */ PropertyViewStatusType status() const noexcept { return _status; } /** - * @copydoc PropertyView::name + * @copydoc PropertyView::name */ const std::optional& name() const noexcept { return _name; } /** - * @copydoc PropertyView::semantic + * @copydoc PropertyView::semantic */ const std::optional& semantic() const noexcept { return _semantic; } /** - * @copydoc PropertyView::description + * @copydoc PropertyView::description */ const std::optional& description() const noexcept { return _description; } /** - * @copydoc PropertyView::arrayCount + * @copydoc PropertyView::arrayCount */ int64_t arrayCount() const noexcept { return _count; } /** - * @copydoc PropertyView::normalized + * @copydoc PropertyView::normalized */ bool normalized() const noexcept { return false; } /** - * @copydoc PropertyView::offset + * @copydoc PropertyView::offset */ std::optional> offset() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::scale + * @copydoc PropertyView::scale */ std::optional> scale() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::max + * @copydoc PropertyView::max */ std::optional> max() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::min + * @copydoc PropertyView::min */ std::optional> min() const noexcept { return std::nullopt; } /** - * @copydoc PropertyView::required + * @copydoc PropertyView::required */ bool required() const noexcept { return _required; } /** - * @copydoc PropertyView::noData + * @copydoc PropertyView::noData */ std::optional> noData() const noexcept { if (_noData.size > 0) { @@ -2455,7 +2455,7 @@ template <> class PropertyView> { } /** - * @copydoc PropertyView::defaultValue + * @copydoc PropertyView::defaultValue */ std::optional> defaultValue() const noexcept { diff --git a/CesiumGltf/include/CesiumGltf/TextureView.h b/CesiumGltf/include/CesiumGltf/TextureView.h index ef681dd74..6bbf6f8e6 100644 --- a/CesiumGltf/include/CesiumGltf/TextureView.h +++ b/CesiumGltf/include/CesiumGltf/TextureView.h @@ -92,6 +92,9 @@ enum class TextureViewStatus { ErrorInvalidBytesPerChannel, }; +/** + * @brief A view into the texture data of a single texture from a \ref Model. + */ class TextureView { public: /** diff --git a/CesiumGltfContent/include/CesiumGltfContent/ImageManipulation.h b/CesiumGltfContent/include/CesiumGltfContent/ImageManipulation.h index 2f350629b..57c2a0b72 100644 --- a/CesiumGltfContent/include/CesiumGltfContent/ImageManipulation.h +++ b/CesiumGltfContent/include/CesiumGltfContent/ImageManipulation.h @@ -37,6 +37,9 @@ struct PixelRectangle { int32_t height; }; +/** + * @brief A collection of utility functions for image manipulation operations. + */ class CESIUMGLTFCONTENT_API ImageManipulation { public: /** diff --git a/CesiumGltfContent/include/CesiumGltfContent/SkirtMeshMetadata.h b/CesiumGltfContent/include/CesiumGltfContent/SkirtMeshMetadata.h index e0dfd5aba..594be7ddf 100644 --- a/CesiumGltfContent/include/CesiumGltfContent/SkirtMeshMetadata.h +++ b/CesiumGltfContent/include/CesiumGltfContent/SkirtMeshMetadata.h @@ -5,7 +5,25 @@ #include namespace CesiumGltfContent { + +/** + * @brief Metadata obtained from a glTF that describes the skirts present on the + * mesh. + * + * @remarks Skirts are a technique for hiding cracks between adjacent tiles + * where the geometry at the edges of tiles is extended downwards, like the + * edges of a tablecloth hanging off of a table. These skirts are included in + * the glTF when they're generated, in the case of 3D Tiles, or they are + * generated by Cesium Native when terrain is loaded, in the case of Quantized + * Mesh terrain. `SkirtMeshMetadata` is attached to the glTF to allow Cesium + * Native to know which parts of the mesh are original and which contain the + * generated skirts, for operations such as creating texture coordinates for + * raster overlays. + */ struct SkirtMeshMetadata { + /** + * @brief Creates a new `SkirtMeshMetadata` with zeroes in all fields. + */ SkirtMeshMetadata() noexcept : noSkirtIndicesBegin{0}, noSkirtIndicesCount{0}, @@ -17,20 +35,78 @@ struct SkirtMeshMetadata { skirtEastHeight{0.0}, skirtNorthHeight{0.0} {} + /** + * @brief Parses `SkirtMeshMetadata` from the `extras` field of a glTF mesh, + * if present. + * + * @param extras The extras field of the glTF mesh. + * @returns An optional containing the `SkirtMeshMetadata` if it was present + * on the mesh. + */ static std::optional parseFromGltfExtras(const CesiumUtility::JsonValue::Object& extras); + /** + * @brief Creates a glTF mesh extras value from the provided + * `SkirtMeshMetadata`. + * + * This might be used when generating a glTF at runtime, in order to provide + * information on the mesh's skirts to the rest of Cesium Native. + * + * @param skirt The skirt to create the glTF extras object from. + * @returns An object representing the value of a glTF extras field containing + * the skirt metadata. + */ static CesiumUtility::JsonValue::Object createGltfExtras(const SkirtMeshMetadata& skirt); + /** + * @brief The start index of the range of a glTF mesh's indices buffer that + * should \b NOT be considered part of the skirt. + */ uint32_t noSkirtIndicesBegin; + /** + * @brief The length of the range of a glTF mesh's indices buffer that should + * \b NOT be considered part of the skirt. + * + * Any indices outside of the range `(noSkirtIndicesBegin, + * noSkirtIndicesBegin + noSkirtIndicesCount)` will be considered part of the + * skirt. + */ uint32_t noSkirtIndicesCount; + /** + * @brief The start index of the range of a glTF mesh's vertices buffer that + * should \b NOT be considered part of the skirt. + */ uint32_t noSkirtVerticesBegin; + /** + * @brief The length of the range of a glTF mesh's vertices buffer that should + * \b NOT be considered part of the skirt. + * + * Any vertices outside of the range `(noSkirtVerticesBegin, + * noSkirtVerticesBegin + noSkirtVerticesCount)` will be considered part of + * the skirt. + */ uint32_t noSkirtVerticesCount; + /** + * @brief The center coordinates of the mesh, in \ref glossary-ecef. + */ glm::dvec3 meshCenter; + /** + * @brief The height of the skirt on the western edge of the mesh. + */ double skirtWestHeight; + /** + * @brief The height of the skirt on the southern edge of the mesh. + */ double skirtSouthHeight; + /** + * @brief The height of the skirt on the eastern edge of the mesh. + */ double skirtEastHeight; + /** + * @brief The height of the skirt on the northern edge of the mesh. + */ double skirtNorthHeight; }; } // namespace CesiumGltfContent diff --git a/CesiumIonClient/include/CesiumIonClient/Assets.h b/CesiumIonClient/include/CesiumIonClient/Assets.h index dc736fa4c..4fcd3737f 100644 --- a/CesiumIonClient/include/CesiumIonClient/Assets.h +++ b/CesiumIonClient/include/CesiumIonClient/Assets.h @@ -70,6 +70,10 @@ struct Asset { int8_t percentComplete = 0; }; +/** + * @brief A page of assets obtained from the Cesium ion `v1/assets` endpoint, + * including a link to obtain the next page, if one exists. + */ struct Assets { /** * @brief An [RFC 5988](https://tools.ietf.org/html/rfc5988) formatted string diff --git a/CesiumJsonWriter/include/CesiumJsonWriter/JsonWriter.h b/CesiumJsonWriter/include/CesiumJsonWriter/JsonWriter.h index 2d70c724a..65ceccdec 100644 --- a/CesiumJsonWriter/include/CesiumJsonWriter/JsonWriter.h +++ b/CesiumJsonWriter/include/CesiumJsonWriter/JsonWriter.h @@ -12,12 +12,18 @@ #include namespace CesiumJsonWriter { +/** + * @brief Wrapper around `rapidjson::Writer` for writing objects to JSON. + */ class JsonWriter { public: JsonWriter(); virtual ~JsonWriter() {} - // rapidjson methods + /** + * @name RapidJSON methods + */ + /**@{*/ virtual bool Null(); virtual bool Bool(bool b); virtual bool Int(int i); @@ -32,8 +38,12 @@ class JsonWriter { virtual bool EndObject(); virtual bool StartArray(); virtual bool EndArray(); + /**@}*/ - // Primitive overloads + /** + * @name Primitive overloads + */ + /**@{*/ virtual void Primitive(std::int32_t value); virtual void Primitive(std::uint32_t value); virtual void Primitive(std::int64_t value); @@ -42,29 +52,48 @@ class JsonWriter { virtual void Primitive(double value); virtual void Primitive(std::nullptr_t value); virtual void Primitive(std::string_view string); + /**@}*/ - // Integral + /** + * @name Integral + */ + /**@{*/ virtual void KeyPrimitive(std::string_view keyName, std::int32_t value); virtual void KeyPrimitive(std::string_view keyName, std::uint32_t value); virtual void KeyPrimitive(std::string_view keyName, std::int64_t value); virtual void KeyPrimitive(std::string_view keyName, std::uint64_t value); + /**@}*/ - // String + /** + * @brief String + */ virtual void KeyPrimitive(std::string_view keyName, std::string_view value); - // Floating Point + /** + * @brief Floating point + */ + /**@{*/ virtual void KeyPrimitive(std::string_view keyName, float value); virtual void KeyPrimitive(std::string_view keyName, double value); + /**@}*/ - // Null + /** + * @brief Null + */ + /**@{*/ virtual void KeyPrimitive(std::string_view keyName, std::nullptr_t value); + /**@}*/ - // Array / Objects + /** + * @name Array / Objects + */ + /**@{*/ virtual void KeyArray(std::string_view keyName, std::function insideArray); virtual void KeyObject(std::string_view keyName, std::function insideObject); + /**@}*/ virtual std::string toString(); virtual std::string_view toStringView(); diff --git a/CesiumQuantizedMeshTerrain/include/CesiumQuantizedMeshTerrain/QuantizedMeshLoader.h b/CesiumQuantizedMeshTerrain/include/CesiumQuantizedMeshTerrain/QuantizedMeshLoader.h index 73cf9c14b..823234ccc 100644 --- a/CesiumQuantizedMeshTerrain/include/CesiumQuantizedMeshTerrain/QuantizedMeshLoader.h +++ b/CesiumQuantizedMeshTerrain/include/CesiumQuantizedMeshTerrain/QuantizedMeshLoader.h @@ -23,6 +23,12 @@ class IAssetRequest; namespace CesiumQuantizedMeshTerrain { +/** + * @brief The results of a \ref QuantizedMeshLoader::load operation, containing + * either the loaded model, an improved bounding region for the tile, and + * available quadtree tiles discovered, if the load succeeded - or the request + * made and the errors that were returned, if the load failed. + */ struct QuantizedMeshLoadResult { /** * @brief The glTF model to be rendered for this tile. @@ -55,11 +61,25 @@ struct QuantizedMeshLoadResult { */ std::shared_ptr pRequest; + /** + * @brief The errors and warnings reported while loading this tile. + */ CesiumUtility::ErrorList errors; }; +/** + * @brief The metadata of a Quantized Mesh tile, returned by \ref + * QuantizedMeshLoader::loadMetadata. + */ struct QuantizedMeshMetadataResult { + /** + * @brief Information about the availability of child tiles. + */ std::vector availability; + + /** + * @brief The errors and warnings reported while loading this tile, if any. + */ CesiumUtility::ErrorList errors; }; diff --git a/CesiumRasterOverlays/include/CesiumRasterOverlays/IPrepareRasterOverlayRendererResources.h b/CesiumRasterOverlays/include/CesiumRasterOverlays/IPrepareRasterOverlayRendererResources.h index 923af887e..43fb643e2 100644 --- a/CesiumRasterOverlays/include/CesiumRasterOverlays/IPrepareRasterOverlayRendererResources.h +++ b/CesiumRasterOverlays/include/CesiumRasterOverlays/IPrepareRasterOverlayRendererResources.h @@ -14,6 +14,13 @@ class RasterOverlayTile; namespace CesiumRasterOverlays { +/** + * @brief An interface between Cesium Native and the application using it, + * allowing Cesium Native to pass loaded raster overlay data to the implementing + * application in order for the application to prepare it to be used in its + * renderer of choice. This could involve creating a texture asset, uploading + * the texture data to the GPU, or any other similar tasks required. + */ class CESIUMRASTEROVERLAYS_API IPrepareRasterOverlayRendererResources { public: /** diff --git a/CesiumRasterOverlays/include/CesiumRasterOverlays/QuadtreeRasterOverlayTileProvider.h b/CesiumRasterOverlays/include/CesiumRasterOverlays/QuadtreeRasterOverlayTileProvider.h index 4f3ea98f1..4551b4217 100644 --- a/CesiumRasterOverlays/include/CesiumRasterOverlays/QuadtreeRasterOverlayTileProvider.h +++ b/CesiumRasterOverlays/include/CesiumRasterOverlays/QuadtreeRasterOverlayTileProvider.h @@ -19,6 +19,16 @@ namespace CesiumRasterOverlays { +/** + * @brief A base class used for raster overlay providers that use a + * quadtree-based tiling scheme. This includes \ref TileMapServiceRasterOverlay, + * \ref BingMapsRasterOverlay, and \ref WebMapServiceRasterOverlay. + * + * To implement a new raster overlay provider based on + * QuadtreeRasterOverlayTileProvider, use this as the base class and override + * \ref QuadtreeRasterOverlayTileProvider::loadQuadtreeTileImage + * "loadQuadtreeTileImage" with code that makes requests to your service. + */ class CESIUMRASTEROVERLAYS_API QuadtreeRasterOverlayTileProvider : public RasterOverlayTileProvider { diff --git a/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterOverlayLoadFailureDetails.h b/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterOverlayLoadFailureDetails.h index 5ea7af042..615f813d1 100644 --- a/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterOverlayLoadFailureDetails.h +++ b/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterOverlayLoadFailureDetails.h @@ -33,6 +33,9 @@ enum class RasterOverlayLoadType { TileProvider }; +/** + * @brief Details on a failure while attempting to load a raster overlay tile. + */ class RasterOverlayLoadFailureDetails { public: /** diff --git a/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterOverlayUtilities.h b/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterOverlayUtilities.h index 00db1bc26..11b8bac43 100644 --- a/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterOverlayUtilities.h +++ b/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterOverlayUtilities.h @@ -19,6 +19,10 @@ struct Model; namespace CesiumRasterOverlays { +/** + * @brief A collection of utilities useful for operations involving raster + * overlay tiles. + */ struct CESIUMRASTEROVERLAYS_API RasterOverlayUtilities { static constexpr std::string_view DEFAULT_TEXTURE_COORDINATE_BASE_NAME = "_CESIUMOVERLAY_"; diff --git a/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterizedPolygonsOverlay.h b/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterizedPolygonsOverlay.h index ad467bde3..e355a26fb 100644 --- a/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterizedPolygonsOverlay.h +++ b/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterizedPolygonsOverlay.h @@ -17,10 +17,30 @@ namespace CesiumRasterOverlays { +/** + * @brief A raster overlay made from rasterizing a set of \ref + * CesiumGeospatial::CartographicPolygon "CartographicPolygon" objects. The + * resulting overlay is monochromatic - white where pixels are inside of the + * polygons, and black where they are not. + */ class CESIUMRASTEROVERLAYS_API RasterizedPolygonsOverlay final : public RasterOverlay { public: + /** + * @brief Creates a new RasterizedPolygonsOverlay. + * + * @param name The user-given name of this polygon layer. + * @param polygons The \ref CesiumGeospatial::CartographicPolygon + * "CartographicPolygon" objects to rasterize. + * @param invertSelection If true, the overlay's colors will be inverted. The + * pixels inside of polygons will be black, and those outside will be white. + * @param ellipsoid The ellipsoid that this RasterOverlay is being generated + * for. + * @param projection The projection that this RasterOverlay is being generated + * for. + * @param overlayOptions Options to use for this RasterOverlay. + */ RasterizedPolygonsOverlay( const std::string& name, const std::vector& polygons, @@ -40,13 +60,23 @@ class CESIUMRASTEROVERLAYS_API RasterizedPolygonsOverlay final CesiumUtility::IntrusivePointer pOwner) const override; + /** + * @brief Gets the polygons that are being rasterized to create this overlay. + */ const std::vector& getPolygons() const noexcept { return this->_polygons; } + /** + * @brief Gets the value of the `invertSelection` value passed to the + * constructor. + */ bool getInvertSelection() const noexcept { return this->_invertSelection; } + /** + * @brief Gets the ellipsoid that this overlay is being generated for. + */ const CesiumGeospatial::Ellipsoid& getEllipsoid() const noexcept { return this->_ellipsoid; } diff --git a/CesiumUtility/include/CesiumUtility/JsonHelpers.h b/CesiumUtility/include/CesiumUtility/JsonHelpers.h index 508d62b6e..f5ea4526e 100644 --- a/CesiumUtility/include/CesiumUtility/JsonHelpers.h +++ b/CesiumUtility/include/CesiumUtility/JsonHelpers.h @@ -9,10 +9,28 @@ namespace CesiumUtility { +/** + * @brief A collection of helper functions to make reading JSON simpler. + */ class JsonHelpers final { public: + /** + * @brief Attempts to read the value at `key` of `tileJson` as a `double`, + * returning std::nullopt if it wasn't found or couldn't be read as a double. + * + * @param tileJson The JSON object to obtain the scalar property from. + * @param key The key of the scalar property to obtain. + */ static std::optional getScalarProperty(const rapidjson::Value& tileJson, const std::string& key); + /** + * @brief Attempts to read the value at `key` of `tileJson` as a + * `glm::dmat4x4`, returning std::nullopt if it wasn't found or couldn't be + * read as a glm::dmat4x4. + * + * @param tileJson The JSON object to obtain the transform property from. + * @param key The key of the transform property. + */ static std::optional getTransformProperty( const rapidjson::Value& tileJson, const std::string& key); @@ -36,57 +54,191 @@ class JsonHelpers final { int32_t expectedSize, const std::string& key); + /** + * @brief Attempts to obtain a string from the given key on the JSON object, + * returning a default value if this isn't possible. + * + * @param json The JSON object. + * @param key The key (property name) of the string. + * @param defaultValue The default value to return if the string property + * `key` of `json` couldn't be read. + */ static std::string getStringOrDefault( const rapidjson::Value& json, const std::string& key, const std::string& defaultValue); + /** + * @brief Attempts to read `json` as a string, returning a default value if + * this isn't possible. + * + * @param json The JSON value that might be a string. + * @param defaultValue The default value to return if `json` couldn't be read + * as a string. + */ static std::string getStringOrDefault( const rapidjson::Value& json, const std::string& defaultValue); + /** + * @brief Attempts to obtain a double from the given key on the JSON object, + * returning a default value if this isn't possible. + * + * @param json The JSON object. + * @param key The key (property name) of the double. + * @param defaultValue The default value to return if the double property + * `key` of `json` couldn't be read. + */ static double getDoubleOrDefault( const rapidjson::Value& json, const std::string& key, double defaultValue); + /** + * @brief Attempts to read `json` as a double, returning a default value if + * this isn't possible. + * + * @param json The JSON value that might be a double. + * @param defaultValue The default value to return if `json` couldn't be read + * as a double. + */ static double getDoubleOrDefault(const rapidjson::Value& json, double defaultValue); + /** + * @brief Attempts to obtain a uint32_t from the given key on the JSON object, + * returning a default value if this isn't possible. + * + * @param json The JSON object. + * @param key The key (property name) of the uint32_t. + * @param defaultValue The default value to return if the uint32_t property + * `key` of `json` couldn't be read. + */ static uint32_t getUint32OrDefault( const rapidjson::Value& json, const std::string& key, uint32_t defaultValue); + /** + * @brief Attempts to read `json` as a uint32_t, returning a default value if + * this isn't possible. + * + * @param json The JSON value that might be a uint32_t. + * @param defaultValue The default value to return if `json` couldn't be read + * as a uint32_t. + */ static uint32_t getUint32OrDefault(const rapidjson::Value& json, uint32_t defaultValue); + /** + * @brief Attempts to obtain a int32_t from the given key on the JSON object, + * returning a default value if this isn't possible. + * + * @param json The JSON object. + * @param key The key (property name) of the int32_t. + * @param defaultValue The default value to return if the int32_t property + * `key` of `json` couldn't be read. + */ static int32_t getInt32OrDefault( const rapidjson::Value& json, const std::string& key, int32_t defaultValue); + /** + * @brief Attempts to read `json` as a int32_t, returning a default value if + * this isn't possible. + * + * @param json The JSON value that might be a int32_t. + * @param defaultValue The default value to return if `json` couldn't be read + * as a int32_t. + */ static int32_t getInt32OrDefault(const rapidjson::Value& json, int32_t defaultValue); + /** + * @brief Attempts to obtain a uint64_t from the given key on the JSON object, + * returning a default value if this isn't possible. + * + * @param json The JSON object. + * @param key The key (property name) of the uint64_t. + * @param defaultValue The default value to return if the uint64_t property + * `key` of `json` couldn't be read. + */ static uint64_t getUint64OrDefault( const rapidjson::Value& json, const std::string& key, uint64_t defaultValue); + /** + * @brief Attempts to read `json` as a uint64_t, returning a default value if + * this isn't possible. + * + * @param json The JSON value that might be a uint64_t. + * @param defaultValue The default value to return if `json` couldn't be read + * as a uint64_t. + */ static uint64_t getUint64OrDefault(const rapidjson::Value& json, uint64_t defaultValue); + /** + * @brief Attempts to obtain a int64_t from the given key on the JSON object, + * returning a default value if this isn't possible. + * + * @param json The JSON object. + * @param key The key (property name) of the int64_t. + * @param defaultValue The default value to return if the int64_t property + * `key` of `json` couldn't be read. + */ static int64_t getInt64OrDefault( const rapidjson::Value& json, const std::string& key, int64_t defaultValue); + /** + * @brief Attempts to read `json` as a int64_t, returning a default value if + * this isn't possible. + * + * @param json The JSON value that might be a int64_t. + * @param defaultValue The default value to return if `json` couldn't be read + * as a int64_t. + */ static int64_t getInt64OrDefault(const rapidjson::Value& json, int64_t defaultValue); + /** + * @brief Attempts to obtain a bool from the given key on the JSON object, + * returning a default value if this isn't possible. + * + * @param json The JSON object. + * @param key The key (property name) of the bool. + * @param defaultValue The default value to return if the bool property + * `key` of `json` couldn't be read. + */ static bool getBoolOrDefault( const rapidjson::Value& json, const std::string& key, bool defaultValue); + /** + * @brief Attempts to read `json` as a bool, returning a default value if + * this isn't possible. + * + * @param json The JSON value that might be a bool. + * @param defaultValue The default value to return if `json` couldn't be read + * as a bool. + */ static bool getBoolOrDefault(const rapidjson::Value& json, bool defaultValue); + /** + * @brief Attempts to read an array of strings from the property `key` of + * `json`, returning an empty vector if this isn't possible. + * + * @param json The JSON object. + * @param key The key (property name) of the string array. + */ static std::vector getStrings(const rapidjson::Value& json, const std::string& key); + + /** + * @brief Attempts to read an int64_t array from the property `key` of + * `json`, returning an empty vector if this isn't possible. + * + * @param json The JSON object. + * @param key The key (property name) of the int64_t array. + */ static std::vector getInt64s(const rapidjson::Value& json, const std::string& key); }; diff --git a/CesiumUtility/include/CesiumUtility/ReferenceCounted.h b/CesiumUtility/include/CesiumUtility/ReferenceCounted.h index 6e4861ed4..b25bb4260 100644 --- a/CesiumUtility/include/CesiumUtility/ReferenceCounted.h +++ b/CesiumUtility/include/CesiumUtility/ReferenceCounted.h @@ -11,6 +11,7 @@ namespace CesiumUtility { +/** \cond Doxygen_Suppress */ #ifndef NDEBUG template class ThreadIdHolder; @@ -24,6 +25,7 @@ template <> class ThreadIdHolder { template <> class ThreadIdHolder {}; #endif +/** \endcond */ /** * @brief A reference-counted base class, meant to be used with diff --git a/CesiumUtility/include/CesiumUtility/Uri.h b/CesiumUtility/include/CesiumUtility/Uri.h index 1552b594f..c50bbb790 100644 --- a/CesiumUtility/include/CesiumUtility/Uri.h +++ b/CesiumUtility/include/CesiumUtility/Uri.h @@ -4,22 +4,86 @@ #include namespace CesiumUtility { +/** + * @brief A class for building and manipulating Uniform Resource Identifiers + * (URIs). + */ class Uri final { public: + /** + * @brief Attempts to resolve a relative URI using a base URI. + * + * For example, a relative URI `/v1/example` together with the base URI + * `https://api.cesium.com` would resolve to + * `https://api.cesium.com/v1/example`. + * + * @param base The base URI that the relative URI is relative to. + * @param relative The relative URI to be resolved against the base URI. + * @param useBaseQuery If true, any query parameters of the base URI will be + * retained in the resolved URI. + * @param assumeHttpsDefault If true, protocol-relative URIs (such as + * `//api.cesium.com`) will be assumed to be `https`. If false, they will be + * assumed to be `http`. + * @returns The resolved URI. + */ static std::string resolve( const std::string& base, const std::string& relative, bool useBaseQuery = false, bool assumeHttpsDefault = true); + /** + * @brief Adds the given key and value to the query string of a URI. For + * example, `addQuery("https://api.cesium.com/v1/example", "key", "value")` + * would produce the URL `https://api.cesium.com/v1/example?key=value`. + * + * @param uri The URI whose query string will be modified. + * @param key The key to be added to the query string. + * @param value The value to be added to the query string. + * @returns The modified URI including the new query string parameter. + */ static std::string addQuery( const std::string& uri, const std::string& key, const std::string& value); + /** + * @brief Obtains the value of the given key from the query string of the URI, + * if possible. + * + * If the URI can't be parsed, or the key doesn't exist in the + * query string, an empty string will be returned. + * + * @param uri The URI with a query string to obtain a value from. + * @param key The key whose value will be obtained from the URI, if possible. + * @returns The value of the given key in the query string, or an empty string + * if not found. + */ static std::string getQueryValue(const std::string& uri, const std::string& key); + /** + * @brief A callback to fill-in a placeholder value in a URL. + * + * @param placeholder The text of the placeholder. For example, if the + * placeholder was `{example}`, the value of `placeholder` will be `example`. + * @returns The value to use in place of the placeholder. + */ typedef std::string SubstitutionCallbackSignature(const std::string& placeholder); + + /** + * @brief Substitutes the placeholders in a templated URI with their + * appropriate values obtained using a specified callback function. + * + * A templated URI has placeholders in the form of `{name}`. For example, + * `https://example.com/{x}/{y}/{z}` has three placeholders, `x`, `y`, and `z`. + * The callback will be called for each placeholder and they will be replaced + * with the return value of this callback. + * + * @param templateUri The templated URI whose placeholders will be substituted + * by this method. + * @param substitutionCallback The callback that will be called for each + * placeholder in the provided URI. See \ref SubstitutionCallbackSignature. + */ static std::string substituteTemplateParameters( const std::string& templateUri, const std::function& substitutionCallback); diff --git a/doc/topics/glossary.md b/doc/topics/glossary.md new file mode 100644 index 000000000..fc24bbf2c --- /dev/null +++ b/doc/topics/glossary.md @@ -0,0 +1,9 @@ +# Glossary {#glossary} + +Terminology and jargon used throughout Cesium Native and its documentation is collected here for clarity's sake. + +## Earth-Centered, Earth-Fixed Coordinates (ECEF) {#glossary-ecef} + +\link https://en.wikipedia.org/wiki/Earth-centered,_Earth-fixed_coordinate_system Earth-Centered, Earth-Fixed (ECEF)\endlink coordinates are, as the name describes, in a 3D Cartesian coordinate system fixed to the Earth with the center at the center of the Earth's ellipsoid. As the Earth spins, the coordinate system spins with it, meaning an ECEF coordinate and its equivalent coordinate in a cartographic coordinate system (like Longitude, Latitude, Height) will remain the same. + +For example, Philadelphia, Pennsylvania is located at -75.1652215° longitude, 39.952839° latitude, at a height of 14.34m. The equivalent ECEF coordinates are (1253556.69, -4732887.41, 4073982.02). \ No newline at end of file