Added documentation to the TextureAtlas class

Raelr · Raelr · commit d1aacea975a9 · 2023-11-21T07:00:24.000+11:00
diff --git a/engine/render/renderer/Renderer.cpp b/engine/render/renderer/Renderer.cpp
@@ -123,7 +123,7 @@ void Renderer::DrawQuad(const Vec2 position,
 }
 
 void Renderer::DrawQuad(const Vec2 position,
-                        Vulkan::TextureAtlas::TextureRef texture,
+                        Vulkan::TextureAtlas::SubTextureRef texture,
                         const Vec2 scale,
                         const IColour colour,
                         float rotation,
diff --git a/engine/render/renderer/Renderer.h b/engine/render/renderer/Renderer.h
@@ -54,7 +54,7 @@ class Renderer
                   const uint8_t zIndex = 0,
                   Vulkan::Texture2D* texture = nullptr);
     void DrawQuad(const Vec2 position,
-                  Vulkan::TextureAtlas::TextureRef texture,
+                  Vulkan::TextureAtlas::SubTextureRef texture,
                   const Vec2 scale = {1.f, 1.f},
                   const IColour colour = IColour::White,
                   float rotation = 0.f,
diff --git a/engine/render/renderer/platform/vulkan/TextureAtlas.cpp b/engine/render/renderer/platform/vulkan/TextureAtlas.cpp
@@ -11,16 +11,54 @@
 
 namespace Siege::Vulkan
 {
-Texture2D& TextureAtlas::TextureRef::operator*()
+
+Texture2D& TextureAtlas::SubTextureRef::operator*()
 {
     return parentAtlas->texture;
 }
 
-TextureAtlas::TextureRef::operator bool() const
+TextureAtlas* TextureAtlas::SubTextureRef::operator->()
+{
+    return parentAtlas;
+}
+
+TextureAtlas::SubTextureRef::operator bool() const
 {
     return parentAtlas;
 }
 
+void TextureAtlas::SubTextureRef::Swap(SubTextureRef& other)
+{
+    auto tmpAtlas = parentAtlas;
+    auto tmpMinX = minX;
+    auto tmpMinY = minY;
+    auto tmpWidth = width;
+    auto tmpHeight = height;
+
+    parentAtlas = other.parentAtlas;
+    minX = other.minX;
+    minY = other.minY;
+    width = other.width;
+    height = other.height;
+
+    other.parentAtlas = tmpAtlas;
+    other.minX = tmpMinX;
+    other.minY = tmpMinY;
+    other.width = tmpWidth;
+    other.height = tmpHeight;
+}
+TextureAtlas::SubTextureRef& TextureAtlas::SubTextureRef::operator=(
+    TextureAtlas::SubTextureRef& other)
+{
+    parentAtlas = other.parentAtlas;
+    minX = other.minX;
+    minY = other.minY;
+    width = other.width;
+    height = other.height;
+
+    return *this;
+}
+
 TextureAtlas::TextureAtlas(const char* name,
                            const char* filePath,
                            Utils::Extent2DF imageExtents,
@@ -40,20 +78,25 @@ TextureAtlas::~TextureAtlas()
     fixedExtent = {};
 }
 
-TextureAtlas::TextureRef TextureAtlas::operator[](size_t index)
+TextureAtlas::SubTextureRef TextureAtlas::operator[](size_t index)
 {
+    // TODO(Aryeh): Add some level of error handling here (assert if index is higher than number of
+    //  textures)
+
+    // NOTE(Aryeh): only works for fixed size textures
     size_t elementsInRow = 1 / fixedExtent.width;
 
-    return TextureRef(this,
-                      (index % elementsInRow) * fixedExtent.width, // potentially slow code
-                      (index / elementsInRow) * fixedExtent.height,
-                      fixedExtent.width,
-                      fixedExtent.height);
+    return SubTextureRef(this,
+                         (index % elementsInRow) * fixedExtent.width, // potentially slow code
+                         (index / elementsInRow) * fixedExtent.height,
+                         fixedExtent.width,
+                         fixedExtent.height);
 }
 
-TextureAtlas* TextureAtlas::TextureRef::operator->()
+TextureAtlas& TextureAtlas::operator=(TextureAtlas&& other)
 {
-    return parentAtlas;
+    Swap(other);
+    return *this;
 }
 
 void TextureAtlas::Swap(TextureAtlas& other)
diff --git a/engine/render/renderer/platform/vulkan/TextureAtlas.h b/engine/render/renderer/platform/vulkan/TextureAtlas.h
@@ -16,86 +16,232 @@
 namespace Siege::Vulkan
 {
 
+/**
+ * A vulkan-based texture atlas class. This class contains a single texture made out of many
+ * sub-textures. Texture Atlases are a way to store multiple textures in a single space within the
+ * same memory space. Currently, the TextureAtlas supports fixed size sub-textures
+ *
+ * NOTE: Currently only supports fixed size texture atlases
+ *
+ * TODO(Aryeh): Add the ability to add sub-textures from png files
+ * TODO(Aryeh): Add the ability to manually specify the sub-texture extents
+ */
 class TextureAtlas
 {
 public:
 
-    class TextureRef
+    /**
+     * A subTextureRef is a reference to a sub-texture. These are textures which are contained
+     * within a texture atlas. These can be accessed from the TextureAtlas via indexing
+     */
+    class SubTextureRef
     {
     public:
 
         // 'Structors
-        TextureRef(TextureAtlas* parent, float minX, float minY, float width, float height) :
+
+        /**
+         * The SubTextureRef constructor
+         * @param parent the parent texture atlas this sub-texture belongs to
+         * @param minX the leftmost normalised x coordinate within the parent texture
+         * @param minY the top-most normalised y coordinate within the parent texture
+         * @param width the width of the texture
+         * @param height the height of the texture
+         */
+        inline SubTextureRef(TextureAtlas* parent,
+                             float minX,
+                             float minY,
+                             float width,
+                             float height) :
             parentAtlas {parent},
             minX {minX},
             width {width},
             minY {minY},
             height {height}
         {}
 
+        /**
+         * The SubTextureRef move constructor
+         * @param other the SubTextureRef to move information from
+         */
+        inline SubTextureRef(SubTextureRef&& other)
+        {
+            Swap(other);
+        }
+
+        /**
+         * The SubTextureRef copy constructor
+         * @param other the SubTextureRef to copy information from
+         */
+        inline SubTextureRef(SubTextureRef& other) :
+            parentAtlas {other.parentAtlas},
+            minX {other.minX},
+            width {other.width},
+            minY {other.minY},
+            height {other.height}
+        {}
+
         // Operator Overloads
 
+        /**
+         * The SubTextureRef copy assignment operator
+         * @param other the SubTextureRef to copy information from
+         * @return a reference to the SubTextureRef
+         */
+        SubTextureRef& operator=(SubTextureRef& other);
+
+        /**
+         * The SubTextureRef move assignment operator
+         * @param other the SubTextureRef to move information from
+         * @return a reference to the SubTextureRef
+         */
+        inline SubTextureRef& operator=(SubTextureRef&& other)
+        {
+            Swap(other);
+            return *this;
+        }
+
+        /**
+         * The dereference operator
+         * @return returns a reference to the stored Texture2D within the parent texture
+         */
         Texture2D& operator*();
 
+        /**
+         * The pointer arrow operator
+         * @return returns the pointer to the parentTexture for member access
+         */
         TextureAtlas* operator->();
 
+        /**
+         * A boolean operator for the SubTextureRef
+         * @return A boolean specifying if the parentAtlas exists (is not a nullptr)
+         */
         operator bool() const;
 
         // Getters and setters
 
+        /**
+         * Returns the leftmost coordinate of the sub-texture
+         * @return a float specifying the leftmost extent of the sub-texture
+         */
         inline float GetMinX() const
         {
             return minX;
         }
+        /**
+         * Returns the topmost coordinate of the sub-texture
+         * @return a float specifying the topmost coordinate of the sub-texture
+         */
         inline float GetMinY() const
         {
             return minY;
         }
+        /**
+         * Returns the width of the sub-texture
+         * @return the width of the sub-texture
+         */
         inline float GetWidth() const
         {
             return width;
         }
+        /**
+         * Returns the height of the sub-texture
+         * @return the height of the sub-texture
+         */
         inline float GetHeight() const
         {
             return height;
         }
 
     private:
 
-        // NOTE(Aryeh): Can we always guarantee that the atlas will exist?
+        // Private methods
+
+        /**
+         * Swaps the contents of two SubTextureRefs
+         * @param other the SubTextureRef to swap contents with
+         */
+        void Swap(SubTextureRef& other);
+
+        // Private member variables
+
         TextureAtlas* parentAtlas {nullptr};
         float minX, width, minY, height {0.f};
     };
 
     // 'Structors
 
+    /**
+     * The default TextureAtlas constructor (empty constructor)
+     */
     TextureAtlas() = default;
+
+    /**
+     * The file upload TextureAtlas constructor. Loads texture data from disk and stores it in the
+     * memory
+     * @param name the name of the texture
+     * @param filePath the path to the texture file
+     * @param imageExtents the width and height of the texture
+     * @param filter the scaling filter used for the texture
+     */
     TextureAtlas(const char* name,
                  const char* filePath,
                  Utils::Extent2DF imageExtents,
                  Utils::TextureFilter filter = Utils::TEXTURE_FILTER_LINEAR);
+
+    /**
+     * The TextureAtlas move constructor. Moves the contents of one TextureAtlas to another
+     * @param other the TextureAtlas to move information from
+     */
     TextureAtlas(TextureAtlas&& other);
+
+    /**
+     * The TextureAtlas Destructor. Destroys all memory stored by the TextureAtlas
+     */
     ~TextureAtlas();
 
     // Operator Overloads
 
-    TextureRef operator[](size_t index);
+    /**
+     * The TextureAtlas subscript operator. Indexes into a texture atlas and returns the SubTexture
+     * stored in that position.
+     * NOTE: So far TextureAtlases only support fixed-size textures
+     * @param index the index of the SubTexture
+     * @return the SubTextureRef stored in the specified location
+     */
+    SubTextureRef operator[](size_t index);
+
+    /**
+     * The TextureAtlas move assignment operator
+     * @param other the TextureAtlas to move information from
+     * @return a reference to the TextureAtlas
+     */
+    TextureAtlas& operator=(TextureAtlas&& other);
 
     // Getters & Setters
 
+    // TODO(Aryeh): Need a way to add new textures to the Atlas in future
+    // TODO(Aryeh): Need a way to manually specify each texture coordinate when not using fixed
+    // textures
+
+    /**
+     * Gets the Texture2D stored within the Atlas
+     * @return the atlas' texture
+     */
     inline Texture2D& GetTexture()
     {
         return texture;
     }
-    inline const Texture2D& GetTexture() const
-    {
-        return texture;
-    }
 
 private:
 
     // Private functions
 
+    /**
+     * Swaps the contents of two TextureAtlases
+     * @param other the TextureAtlas to swap contents with
+     */
     void Swap(TextureAtlas& other);
 
     // Private member variables
diff --git a/engine/render/renderer/renderer/Renderer2D.cpp b/engine/render/renderer/renderer/Renderer2D.cpp
@@ -130,7 +130,7 @@ void Renderer2D::DrawQuad(const Vec2 position,
 }
 
 void Renderer2D::DrawQuad(const Vec2 position,
-                          Vulkan::TextureAtlas::TextureRef& texture,
+                          Vulkan::TextureAtlas::SubTextureRef& texture,
                           const Vec2 scale,
                           IColour colour,
                           float rotation,
diff --git a/engine/render/renderer/renderer/Renderer2D.h b/engine/render/renderer/renderer/Renderer2D.h
@@ -36,7 +36,7 @@ class Renderer2D
                   const uint8_t zIndex = 0,
                   Vulkan::Texture2D* texture = nullptr);
     void DrawQuad(const Vec2 position,
-                  Vulkan::TextureAtlas::TextureRef& texture,
+                  Vulkan::TextureAtlas::SubTextureRef& texture,
                   const Vec2 scale = Vec2::One(),
                   const IColour colour = IColour::White,
                   float rotation = 0.f,
diff --git a/examples/tilemap/src/main.cpp b/examples/tilemap/src/main.cpp
@@ -32,16 +32,15 @@ int main()
 
     Siege::Camera camera;
 
-    camera.projection =
-        Siege::Orthographic(0.f, window.GetWidth(), window.GetHeight(), 0.f, 0.1f, 1000.f);
-    camera.view = Siege::LookAt(Siege::Vec3::Zero(), {0.f, 0.f, 1.f});
-
-    renderer.SetCamera2D(camera);
-
     while (!window.WindowShouldClose())
     {
         window.Update();
 
+        camera.projection =
+            Siege::Orthographic(0.f, window.GetWidth(), window.GetHeight(), 0.f, 0.1f, 1000.f);
+        camera.view = Siege::LookAt(Siege::Vec3::Zero(), Siege::Vec3::Forward());
+        renderer.SetCamera2D(camera);
+
         if (!renderer.StartFrame()) continue;
 
         renderer.DrawGrid2D(100.f, {.2f, .2f, .2f}, window.GetDPI());

Original file line number	Diff line number	Diff line change
`@@ -123,7 +123,7 @@ void Renderer::DrawQuad(const Vec2 position,`
`123`	`123`	`}`
`124`	`124`
`125`	`125`	`void Renderer::DrawQuad(const Vec2 position,`
`126`		`- Vulkan::TextureAtlas::TextureRef texture,`
	`126`	`+ Vulkan::TextureAtlas::SubTextureRef texture,`
`127`	`127`	`const Vec2 scale,`
`128`	`128`	`const IColour colour,`
`129`	`129`	`float rotation,`
Original file line number	Diff line number	Diff line change
`@@ -130,7 +130,7 @@ void Renderer2D::DrawQuad(const Vec2 position,`
`130`	`130`	`}`
`131`	`131`
`132`	`132`	`void Renderer2D::DrawQuad(const Vec2 position,`
`133`		`- Vulkan::TextureAtlas::TextureRef& texture,`
	`133`	`+ Vulkan::TextureAtlas::SubTextureRef& texture,`
`134`	`134`	`const Vec2 scale,`
`135`	`135`	`IColour colour,`
`136`	`136`	`float rotation,`