DynamicAtlasManager: updated documentation

Also don't use auto where unnecessary

Author: TheMostDiligent

Graphics/GraphicsAccessories/interface/DynamicAtlasManager.hpp

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2022 Diligent Graphics LLC
+ *  Copyright 2019-2025 Diligent Graphics LLC
  *  Copyright 2015-2019 Egor Yusov
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
@@ -41,15 +41,30 @@ namespace Diligent
 {
 
 /// Dynamic 2D atlas manager
+
+/// This class manages a 2D atlas of regions. It allows allocating and freeing
+/// rectangular regions of the atlas. The regions are represented by the
+/// Region structure, which contains the x and y coordinates of the top-left
+/// corner, as well as the width and height of the region.
+///
+/// \warning The class is not thread-safe. All operations on the atlas must be
+///          must be protected by a mutex or other synchronization mechanism.
 class DynamicAtlasManager
 {
 public:
+    /// Structure representing a rectangular region in the atlas.
     struct Region
     {
+        /// x coordinate of the top-left corner of the region
         Uint32 x = 0;
+
+        /// y coordinate of the top-left corner of the region
         Uint32 y = 0;
 
-        Uint32 width  = 0;
+        /// width of the region
+        Uint32 width = 0;
+
+        /// height of the region
         Uint32 height = 0;
 
         Region() = default;
@@ -70,6 +85,7 @@ class DynamicAtlasManager
         // clang-format on
         {}
 
+        /// Checks if the region is empty (width or height is zero).
         bool IsEmpty() const
         {
             return width == 0 || height == 0;
@@ -108,19 +124,43 @@ class DynamicAtlasManager
     DynamicAtlasManager& operator = (      DynamicAtlasManager&&) = delete;
     // clang-format on
 
+
+    /// Allocates a rectangular region in the atlas.
+
+    /// \param Width  - Width of the region to allocate.
+    /// \param Height - Height of the region to allocate.
+    /// \return         The allocated region.
+    ///
+    /// If the requested region cannot be allocated, an empty region is returned.
     Region Allocate(Uint32 Width, Uint32 Height);
-    void   Free(Region&& R);
 
+
+    /// Frees a previously allocated region in the atlas.
+
+    /// \param R - The region to free.
+    void Free(Region&& R);
+
+
+    /// Returns the number of free regions in the atlas.
     Uint32 GetFreeRegionCount() const
     {
         VERIFY_EXPR(m_FreeRegionsByWidth.size() == m_FreeRegionsByHeight.size());
         return static_cast<Uint32>(m_FreeRegionsByWidth.size());
     }
 
+    /// Returns the atlas width.
     Uint32 GetWidth() const { return m_Width; }
+
+    /// Returns the atlas height.
     Uint32 GetHeight() const { return m_Height; }
+
+    /// Returns the total free area of the atlas.
+
+    /// The total free area is the sum of the areas of all free regions in the atlas,
+    /// and thus may be fragmented.
     Uint64 GetTotalFreeArea() const { return m_TotalFreeArea; }
 
+    /// Checks if the atlas is empty, i.e. if there are no allocated regions.
     bool IsEmpty() const
     {
         VERIFY_EXPR(m_AllocatedRegions.empty() && (m_TotalFreeArea == Uint64{m_Width} * Uint64{m_Height}) ||

Graphics/GraphicsAccessories/src/DynamicAtlasManager.cpp

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2022 Diligent Graphics LLC
+ *  Copyright 2019-2025 Diligent Graphics LLC
  *  Copyright 2015-2019 Egor Yusov
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
@@ -46,7 +46,7 @@ void DynamicAtlasManager::Node::Validate() const
         Uint32 Area = 0;
         for (Uint32 i = 0; i < NumChildren; ++i)
         {
-            const auto& R0 = Child(i).R;
+            const Region& R0 = Child(i).R;
 
             VERIFY(!R0.IsEmpty(), "Region must not be empty");
             VERIFY(R0.x >= R.x && R0.x + R0.width <= R.x + R.width && R0.y >= R.y && R0.y + R0.height <= R.y + R.height,
@@ -57,7 +57,7 @@ void DynamicAtlasManager::Node::Validate() const
 
             for (Uint32 j = i + 1; j < NumChildren; ++j)
             {
-                const auto& R1 = Child(j).R;
+                const Region& R1 = Child(j).R;
                 if (CheckBox2DBox2DOverlap<false>(uint2{R0.x, R0.y}, uint2{R0.x + R0.width, R0.y + R0.height},
                                                   uint2{R1.x, R1.y}, uint2{R1.x + R1.width, R1.y + R1.height}))
                 {
@@ -79,7 +79,7 @@ void DynamicAtlasManager::Node::Split(const std::initializer_list<Region>& Regio
 
     Children.reset(new Node[Regions.size()]);
     NumChildren = 0;
-    for (const auto& ChildR : Regions)
+    for (const Region& ChildR : Regions)
     {
         Children[NumChildren].Parent = this;
         Children[NumChildren].R      = ChildR;
@@ -194,8 +194,8 @@ DynamicAtlasManager::Region DynamicAtlasManager::Allocate(Uint32 Width, Uint32 H
         ++it_h;
     VERIFY_EXPR(it_h == m_FreeRegionsByHeight.end() || (it_h->first.width >= Width && it_h->first.height >= Height));
 
-    const auto AreaW = it_w != m_FreeRegionsByWidth.end() ? it_w->first.width * it_w->first.height : 0;
-    const auto AreaH = it_h != m_FreeRegionsByHeight.end() ? it_h->first.width * it_h->first.height : 0;
+    const Uint32 AreaW = it_w != m_FreeRegionsByWidth.end() ? it_w->first.width * it_w->first.height : 0;
+    const Uint32 AreaH = it_h != m_FreeRegionsByHeight.end() ? it_h->first.width * it_h->first.height : 0;
     VERIFY_EXPR(AreaW == 0 || AreaW >= Width * Height);
     VERIFY_EXPR(AreaH == 0 || AreaH >= Width * Height);
 
@@ -220,7 +220,7 @@ DynamicAtlasManager::Region DynamicAtlasManager::Allocate(Uint32 Width, Uint32 H
 
     UnregisterNode(*pSrcNode);
 
-    auto R = pSrcNode->R;
+    Region R = pSrcNode->R;
     if (R.width > Width && R.height > Height)
     {
         if (R.width > R.height)
@@ -341,7 +341,7 @@ void DynamicAtlasManager::Free(Region&& R)
     }
 
     VERIFY_EXPR(node_it->first == R && node_it->second->R == R);
-    auto* N = node_it->second;
+    Node* N = node_it->second;
     VERIFY_EXPR(N->IsAllocated && !N->HasChildren());
     UnregisterNode(*N);
     N->IsAllocated = false;