VERTEX_CONTAINER documentation update

include/gal/opengl/cached_container.h

@@ -67,14 +67,12 @@ public:
     virtual void Clear() override;
 
     /**
-     * Function GetBufferHandle()
+     * Returns handle to the vertex buffer. It might be negative if the buffer is not initialized.
-     * returns handle to the vertex buffer. It might be negative if the buffer is not initialized.
      */
     virtual unsigned int GetBufferHandle() const = 0;
 
     /**
-     * Function IsMapped()
+     * Returns true if vertex buffer is currently mapped.
-     * returns true if vertex buffer is currently mapped.
      */
     virtual bool IsMapped() const = 0;
 
@@ -106,8 +104,7 @@ protected:
     unsigned int        m_chunkOffset;
 
     /**
-     * Function reallocate()
+     * Resizes the chunk that stores the current item to the given size. The current item has
-     * resizes the chunk that stores the current item to the given size. The current item has
      * its offset adjusted after the call, and the new chunk parameters are stored
      * in m_chunkOffset and m_chunkSize.
      *
@@ -117,8 +114,7 @@ protected:
     bool reallocate( unsigned int aSize );
 
     /**
-     * Function defragmentResize()
+     * Removes empty spaces between chunks and optionally resizes the container.
-     * removes empty spaces between chunks and optionally resizes the container.
      * After the operation there is continous space for storing vertices at the end of the container.
      *
      * @param aNewSize is the new size of container, expressed in number of vertices
@@ -134,15 +130,13 @@ protected:
     void defragment( VERTEX* aTarget );
 
     /**
-     * Function mergeFreeChunks()
+     * Looks for consecutive free memory chunks and merges them, decreasing fragmentation of
-     * looks for consecutive free memory chunks and merges them, decreasing fragmentation of
      * memory.
      */
     void mergeFreeChunks();
 
     /**
-     * Function getChunkSize()
+     * Returns the size of a chunk.
-     * returns size of the given chunk.
      *
      * @param aChunk is the chunk.
      */
@@ -152,8 +146,7 @@ protected:
     }
 
     /**
-     * Function getChunkOffset()
+     * Returns the offset of a chunk.
-     * returns offset of the chunk.
      *
      * @param aChunk is the chunk.
      */
@@ -163,8 +156,7 @@ protected:
     }
 
     /**
-     * Function addFreeChunk
+     * Adds a chunk marked as a free space.
-     * Adds a chunk marked as free.
      */
     void addFreeChunk( unsigned int aOffset, unsigned int aSize );
 

include/gal/opengl/noncached_container.h

@@ -62,7 +62,7 @@ public:
     virtual void Clear() override;
 
     /// @copydoc VERTEX_CONTAINER::GetSize()
-    virtual inline unsigned int GetSize() const override
+    virtual unsigned int GetSize() const override
     {
         // As the m_freePtr points to the first free space, we can safely assume
         // that this is the number of vertices stored inside

include/gal/opengl/vertex_container.h

@@ -41,7 +41,6 @@ class VERTEX_CONTAINER
 {
 public:
     /**
-     * Function MakeContainer()
      * Returns a pointer to a new container of an appropriate type.
      */
     static VERTEX_CONTAINER* MakeContainer( bool aCached );
@@ -55,35 +54,29 @@ public:
     virtual bool IsCached() const = 0;
 
     /**
-     * Function Map()
+     * Prepares the container for vertices updates.
-     * prepares the container for vertices updates.
      */
     virtual void Map() {}
 
     /**
-     * Function Unmap()
+     * Finishes the vertices updates stage.
-     * finishes the vertices updates stage.
      */
     virtual void Unmap() {}
 
     /**
-     * Function SetItem()
+     * Sets the item for the further actions.
-     * sets the item in order to modify or finishes its current modifications.
      * @param aItem is the item or NULL in case of finishing the item.
      */
     virtual void SetItem( VERTEX_ITEM* aItem ) = 0;
 
     /**
-     * Function FinishItem()
+     * Clean up after adding an item.
-     * does the cleaning after adding an item.
      */
     virtual void FinishItem() {};
 
     /**
-     * Function Allocate()
+     * Returns allocated space for the requested number of vertices associated with the
-     * returns allocated space (possibly resizing the used memory chunk or allocating a new
+     * current item (set with SetItem()). The allocated space is added at the end of the chunk
-     * chunk if it was not stored before) for the given number of vertices associated with the
-     * current item (set by SetItem()). The newly allocated space is added at the end of the chunk
      * used by the current item and may serve to store new vertices.
      * @param aSize is the number of vertices to be allocated.
      * @return Pointer to the allocated space or NULL in case of failure.
@@ -91,25 +84,20 @@ public:
     virtual VERTEX* Allocate( unsigned int aSize ) = 0;
 
     /**
-     * Function Delete()
+     * Erases the data related to an item.
-     * erases the selected item.
-     *
      * @param aItem is the item to be erased.
      */
     virtual void Delete( VERTEX_ITEM* aItem ) = 0;
 
     /**
-     * Function Clear()
+     * Removes all data stored in the container and restores its original state.
-     * removes all the data stored in the container and restores its original state.
      */
     virtual void Clear() = 0;
 
     /**
-     * Function GetAllVertices()
+     * Returns pointer to the vertices stored in the container.
-     * returns all the vertices stored in the container. It is especially useful for transferring
-     * data to the GPU memory.
      */
-    inline virtual VERTEX* GetAllVertices() const
+    VERTEX* GetAllVertices() const
     {
         return m_vertices;
     }
@@ -119,7 +107,7 @@ public:
      * returns vertices stored at the specific offset.
      * @param aOffset is the offset.
      */
-    virtual inline VERTEX* GetVertices( unsigned int aOffset ) const
+    virtual VERTEX* GetVertices( unsigned int aOffset ) const
     {
         return &m_vertices[aOffset];
     }
@@ -128,31 +116,25 @@ public:
      * Function GetSize()
      * returns amount of vertices currently stored in the container.
      */
-    virtual inline unsigned int GetSize() const
+    virtual unsigned int GetSize() const
     {
         return m_currentSize;
     }
 
     /**
-     * Function IsDirty()
+     * Returns information about the container cache state.
-     * returns information about container cache state. Clears the flag after calling the function.
+     * @return True in case the vertices have to be reuploaded.
-     * @return true in case the vertices have to be reuploaded.
      */
-    inline bool IsDirty()
+    bool IsDirty() const
     {
-        bool state = m_dirty;
+        return m_dirty;
-
-        m_dirty = false;
-
-        return state;
     }
 
     /**
-     * Function SetDirty()
+     * Sets the dirty flag, so vertices in the container are going to be reuploaded to the GPU on
-     * sets the dirty flag, so vertices in the container are going to be reuploaded to the GPU on
      * the next frame.
      */
-    inline void SetDirty()
+    void SetDirty()
     {
         m_dirty = true;
     }
@@ -168,19 +150,19 @@ public:
 protected:
     VERTEX_CONTAINER( unsigned int aSize = DEFAULT_SIZE );
 
-    ///< How many vertices we can store in the container
+    ///> Free space left in the container, expressed in vertices
     unsigned int    m_freeSpace;
 
-    ///< How big is the current container, expressed in vertices
+    ///> Current container size, expressed in vertices
     unsigned int    m_currentSize;
 
-    ///< Store the initial size, so it can be resized to this on Clear()
+    ///> Store the initial size, so it can be resized to this on Clear()
     unsigned int    m_initialSize;
 
-    ///< Actual storage memory (should be handled using malloc/realloc/free to speed up resizing)
+    ///> Actual storage memory
     VERTEX*         m_vertices;
 
-    ///< State flags
+    // Status flags
     bool            m_failed;
     bool            m_dirty;
 
@@ -189,7 +171,7 @@ protected:
      * returns size of the used memory space.
      * @return Size of the used memory space (expressed as a number of vertices).
      */
-    inline unsigned int usedSpace() const
+    unsigned int usedSpace() const
     {
         return m_currentSize - m_freeSpace;
     }