[render] documentation for VertexBuffer and IndexBuffer classes

alemuntoni · alemuntoni · commit 1939666f231a · 2025-01-25T15:16:28.000+01:00
diff --git a/vclib/render/include/vclib/bgfx/buffers/index_buffer.h b/vclib/render/include/vclib/bgfx/buffers/index_buffer.h
@@ -31,44 +31,117 @@
 
 namespace vcl {
 
+/**
+ * @brief The IndexBuffer manages the lifetime of a bgfx::IndexBufferHandle.
+ *
+ * It provides an interface to set the index buffer data and bind it to the
+ * rendering pipeline. The index buffer can be used for rendering or for
+ * compute shaders.
+ *
+ * @note An IndexBuffer can be moved but not copied (a copy would require to
+ * create a new bgfx::IndexBufferHandle, that can be done only having access
+ * to the data). Any class that contains an IndexBuffer should implement the
+ * copy constructor and the copy assignment operator.
+ */
 class IndexBuffer
 {
     bgfx::IndexBufferHandle mIndexBufferHandle = BGFX_INVALID_HANDLE;
+    bool mCompute = false;
 
 public:
+    /**
+     * @brief Empty constructor.
+     *
+     * It creates an invalid IndexBuffer object.
+     */
     IndexBuffer() = default;
 
+    // Copying an IndexBuffer is not allowed
     IndexBuffer(const IndexBuffer& other) = delete;
 
+    /**
+     * @brief Move constructor.
+     *
+     * The other IndexBuffer is left in an invalid state.
+     *
+     * @param[in] other: the other IndexBuffer object.
+     */
     IndexBuffer(IndexBuffer&& other) noexcept
     {
-        mIndexBufferHandle = other.mIndexBufferHandle;
-        other.mIndexBufferHandle = BGFX_INVALID_HANDLE;
+        swap(other);
     }
 
+    /**
+     * @brief Destructor.
+     *
+     * It destroys the bgfx::IndexBufferHandle.
+     */
     ~IndexBuffer()
     {
         if (bgfx::isValid(mIndexBufferHandle))
             bgfx::destroy(mIndexBufferHandle);
     }
 
+    // Copying a IndexBuffer is not allowed
     IndexBuffer& operator=(const IndexBuffer& other) = delete;
 
+    /**
+     * @brief Move assignment operator.
+     *
+     * The other IndexBuffer is left in an invalid state.
+     *
+     * @param[in] other: the other IndexBuffer object.
+     * @return a reference to this object.
+     */
     IndexBuffer& operator=(IndexBuffer&& other) noexcept
     {
-        mIndexBufferHandle = other.mIndexBufferHandle;
-        other.mIndexBufferHandle = BGFX_INVALID_HANDLE;
+        swap(other);
         return *this;
     }
 
+    /**
+     * @brief Swap the content of this object with another IndexBuffer object.
+     *
+     * @param[in] other: the other IndexBuffer object.
+     */
     void swap(IndexBuffer& other)
     {
         using std::swap;
         swap(mIndexBufferHandle, other.mIndexBufferHandle);
+        swap(mCompute, other.mCompute);
     }
 
     friend void swap(IndexBuffer& a, IndexBuffer& b) { a.swap(b); }
 
+    /**
+     * @brief Check if the IndexBuffer is valid.
+     *
+     * @return true if the IndexBuffer is valid, false otherwise.
+     */
+    bool isValid() const { return bgfx::isValid(mIndexBufferHandle); }
+
+    /**
+     * @brief Check if the IndexBuffer is used for compute shaders.
+     *
+     * @return true if the IndexBuffer is used for compute shaders, false
+     * otherwise.
+     */
+    bool isCompute() const { return mCompute; }
+
+    /**
+     * @brief Set the index buffer data.
+     *
+     * @note The data must be available for two bgfx::frame calls, then it is
+     * safe to release the data. If you cannot guarantee this, you must provide
+     * a release function that will be called automatically when the data is no
+     * longer needed.
+     *
+     * @param[in] bufferIndices: the data to be copied in the index buffer.
+     * @param[in] bufferSize: the size of the bufferIndices.
+     * @param[in] is32Bit: if true, the bufferIndices are 32-bit integers.
+     * @param[in] releaseFn: the release function to be called when the data is
+     * no longer needed.
+     */
     void set(
         const void*     bufferIndices,
         const uint      bufferSize,
@@ -77,9 +150,26 @@ class IndexBuffer
     {
         uint64_t flags = is32Bit ? BGFX_BUFFER_INDEX32 : BGFX_BUFFER_NONE;
         uint size = is32Bit ? 4 : 2;
-        set(bgfx::makeRef(bufferIndices, bufferSize * size, releaseFn), flags);
+        set(bgfx::makeRef(bufferIndices, bufferSize * size, releaseFn),
+            false,
+            flags);
     }
 
+    /**
+     * @brief Set the index buffer data for compute shaders.
+     *
+     * @note The data must be available for two bgfx::frame calls, then it is
+     * safe to release the data. If you cannot guarantee this, you must provide
+     * a release function that will be called automatically when the data is no
+     * longer needed.
+     *
+     * @param[in] bufferIndices: the data to be copied in the index buffer.
+     * @param[in] bufferSize: the size of the bufferIndices.
+     * @param[in] type: the type of the elements.
+     * @param[in] access: the access type for the buffer.
+     * @param[in] releaseFn: the release function to be called when the data is
+     * no longer needed.
+     */
     void setForCompute(
         const void*   bufferIndices,
         const uint    bufferSize,
@@ -90,14 +180,36 @@ class IndexBuffer
         uint64_t flags = flagsForType(type);
         flags |= flagsForAccess(access);
         set(bgfx::makeRef(bufferIndices, bufferSize * sizeOf(type), releaseFn),
+            true,
             flags);
     }
 
-    void set(const bgfx::Memory* indices, uint64_t flags = BGFX_BUFFER_NONE)
+    /**
+     * @brief Set the index buffer data.
+     *
+     * @param[in] indices: the memory containing the data.
+     * @param[in] compute: if true, the buffer is used for compute shaders.
+     * @param[in] flags: the flags for the buffer.
+     */
+    void set(
+        const bgfx::Memory* indices,
+        bool                compute = false,
+        uint64_t            flags   = BGFX_BUFFER_NONE)
     {
         mIndexBufferHandle = bgfx::createIndexBuffer(indices, flags);
+        mCompute = compute;
     }
 
+    /**
+     * @brief Bind the index buffer to the rendering pipeline.
+     *
+     * If the stage is not specified, the index buffer is bound to the rendering
+     * pipeline. Otherwise, it is bound to the compute shader with the specified
+     * stage and the given access type (Read, Write, ReadWrite).
+     *
+     * @param[in] stage: the stage to which the buffer is bound.
+     * @param[in] access: the access type for the buffer.
+     */
     void bind(
         uint               stage  = UINT_NULL,
         bgfx::Access::Enum access = bgfx::Access::Read) const
diff --git a/vclib/render/include/vclib/bgfx/buffers/vertex_buffer.h b/vclib/render/include/vclib/bgfx/buffers/vertex_buffer.h
@@ -31,39 +31,79 @@
 
 namespace vcl {
 
+/**
+ * @brief The VertexBuffer manages the lifetime of a bgfx::VertexBufferHandle.
+ *
+ * It provides an interface to set the vertex buffer data and bind it to the
+ * rendering pipeline. The vertex buffer can be used for rendering or for
+ * compute shaders.
+ *
+ * @note A VertexBuffer can be moved but not copied (a copy would require to
+ * create a new bgfx::VertexBufferHandle, that can be done only having access
+ * to the data). Any class that contains a VertexBuffer should implement the
+ * copy constructor and the copy assignment operator.
+ */
 class VertexBuffer
 {
     bgfx::VertexBufferHandle mVertexBufferHandle = BGFX_INVALID_HANDLE;
     bool mCompute = false;
 
 public:
+    /**
+     * @brief Empty constructor.
+     *
+     * It creates an invalid VertexBuffer object.
+     */
     VertexBuffer() = default;
 
+    // Copying a VertexBuffer is not allowed
     VertexBuffer(const VertexBuffer& other) = delete;
 
+    /**
+     * @brief Move constructor.
+     *
+     * The other VertexBuffer is left in an invalid state.
+     *
+     * @param[in] other: the other VertexBuffer object.
+     */
     VertexBuffer(VertexBuffer&& other) noexcept
     {
-        mVertexBufferHandle = other.mVertexBufferHandle;
-        mCompute = other.mCompute;
-        other.mVertexBufferHandle = BGFX_INVALID_HANDLE;
+        swap(other);
     }
 
+    /**
+     * @brief Destructor.
+     *
+     * If the VertexBuffer is valid, the bgfx::VertexBufferHandle is destroyed.
+     */
     ~VertexBuffer()
     {
         if (bgfx::isValid(mVertexBufferHandle))
             bgfx::destroy(mVertexBufferHandle);
     }
 
+    // Copying a VertexBuffer is not allowed
     VertexBuffer& operator=(const VertexBuffer& other) = delete;
 
+    /**
+     * @brief Move assignment operator.
+     *
+     * The other VertexBuffer is left in an invalid state.
+     *
+     * @param[in] other: the other VertexBuffer object.
+     * @return a reference to this object.
+     */
     VertexBuffer& operator=(VertexBuffer&& other) noexcept
     {
-        mVertexBufferHandle = other.mVertexBufferHandle;
-        mCompute = other.mCompute;
-        other.mVertexBufferHandle = BGFX_INVALID_HANDLE;
+        swap(other);
         return *this;
     }
 
+    /**
+     * @brief Swap the content of this object with another VertexBuffer object.
+     *
+     * @param[in] other: the other VertexBuffer object.
+     */
     void swap(VertexBuffer& other)
     {
         using std::swap;
@@ -73,6 +113,38 @@ class VertexBuffer
 
     friend void swap(VertexBuffer& a, VertexBuffer& b) { a.swap(b); }
 
+    /**
+     * @brief Check if the VertexBuffer is valid.
+     *
+     * @return true if the VertexBuffer is valid, false otherwise.
+     */
+    bool isValid() const { return bgfx::isValid(mVertexBufferHandle); }
+
+    /**
+     * @brief Check if the VertexBuffer is used for compute shaders.
+     *
+     * @return true if the VertexBuffer is used for compute shaders, false
+     * otherwise.
+     */
+    bool isCompute() const { return mCompute; }
+
+    /**
+     * @brief Set the vertex buffer data for rendering.
+     *
+     * @note The data must be available for two bgfx::frame calls, then it is
+     * safe to release the data. If you cannot guarantee this, you must provide
+     * a release function that will be called automatically when the data is no
+     * longer needed.
+     *
+     * @param[in] bufferData: the data to be copied in the vertex buffer.
+     * @param[in] bufferSize: the size of the bufferData.
+     * @param[in] attrib: the attribute to which the data refers.
+     * @param[in] numElements: the number of elements for each vertex.
+     * @param[in] type: the type of the elements.
+     * @param[in] normalize: if true, the data is normalized.
+     * @param[in] releaseFn: the release function to be called when the data is
+     * no longer needed.
+     */
     void set(
         const void*        bufferData,
         const uint         bufferSize,
@@ -92,6 +164,24 @@ class VertexBuffer
                 releaseFn));
     }
 
+    /**
+     * @brief Set the vertex buffer data for compute shaders.
+     *
+     * @note The data must be available for two bgfx::frame calls, then it is
+     * safe to release the data. If you cannot guarantee this, you must provide
+     * a release function that will be called automatically when the data is no
+     * longer needed.
+     *
+     * @param[in] bufferData: the data to be copied in the vertex buffer.
+     * @param[in] bufferSize: the size of the bufferData.
+     * @param[in] attrib: the attribute to which the data refers.
+     * @param[in] numElements: the number of elements for each vertex.
+     * @param[in] type: the type of the elements.
+     * @param[in] normalize: if true, the data is normalized.
+     * @param[in] access: the access type for the buffer.
+     * @param[in] releaseFn: the release function to be called when the data is
+     * no longer needed.
+     */
     void setForCompute(
         const void*        bufferData,
         const uint         bufferSize,
@@ -116,19 +206,34 @@ class VertexBuffer
             flags);
     }
 
+    /**
+     * @brief Set the vertex buffer data.
+     *
+     * @param[in] layout: the vertex layout.
+     * @param[in] data: the memory containing the data.
+     * @param[in] compute: if true, the buffer is used for compute shaders.
+     * @param[in] flags: the flags for the buffer.
+     */
     void set(
         const bgfx::VertexLayout& layout,
-        const bgfx::Memory* vertices,
+        const bgfx::Memory* data,
         bool compute = false,
         uint64_t flags = BGFX_BUFFER_NONE)
     {
         if (bgfx::isValid(mVertexBufferHandle))
             bgfx::destroy(mVertexBufferHandle);
 
-        mVertexBufferHandle = bgfx::createVertexBuffer(vertices, layout, flags);
+        mVertexBufferHandle = bgfx::createVertexBuffer(data, layout, flags);
         mCompute = compute;
     }
 
+    /**
+     * @brief Bind the vertex buffer to the rendering pipeline.
+     *
+     * @param[in] stream: the stream (or stage, in case of compute) to which the
+     * vertex buffer is bound.
+     * @param[in] access: the access type for the buffer (only for compute).
+     */
     void bind(uint stream, bgfx::Access::Enum access = bgfx::Access::Read) const
     {
         if (bgfx::isValid(mVertexBufferHandle)) {
