Update and improve documentation

[libs/gl.git] / source / core / batch.h

diff --git a/source/core/batch.h b/source/core/batch.h
index 1e0b4c4703e74b09602575b6f3fa206bfc746bdf..45101d4356672950dc9439a5401ed1a3311bc307 100644 (file)
--- a/source/core/batch.h
+++ b/source/core/batch.h
@@ -14,12 +14,12 @@ namespace GL {
 class Buffer;
 
 /**
-Stores primitive type and element indices for a single GL draw call.  Data
-type for indices is automatically chosen to accommodate the largest index in
-the Batch.
+Stores primitive type and element indices for a single draw call.
 
-This is a pretty low-level class and mainly intended to be used by the Mesh
-class.
+Data type for indices is automatically chosen to accommodate the largest
+index, but can also be manually overridden.
+
+Batches are normally contained in a Mesh.
 */
 class Batch: public BatchBackend, public Bufferable
 {
@@ -39,17 +39,32 @@ private:
        unsigned max_index;
 
 public:
-       Batch(PrimitiveType t);
+       Batch(PrimitiveType);
        ~Batch();
 
        PrimitiveType get_type() const { return prim_type; }
+
+       /** Sets the data type for indices.  Allowed types are UNSIGNED_SHORT and
+       UNSIGNED_INT.  It's an error to specify a type which can't hold the current
+       range of index values. */
        void set_index_type(DataType);
+
        DataType get_index_type() const { return index_type; }
 
+       /** Appends a single index.  The data type is automatically adjusted if the
+       index is too large for the current data type. */
        Batch &append(unsigned);
+
        Batch &append(const std::vector<unsigned> &);
+
+       /** Checks if it's possible to append another Batch with a given primitive
+       type. */
        bool can_append(PrimitiveType);
+
+       /** Appends another batch.  Additional indices may be inserted in order to
+       join the primitives. */
        Batch &append(const Batch &);
+
 private:
        void append_index(unsigned);
        virtual std::size_t get_data_size() const { return data.size(); }