namespace GL {
/**
-Stores vertex data.
+Stores vertex data. Each vertex has one or more attributes defined by a
+VertexFormat.
The array's contents can be modified with the append and modify methods. To
obtain the location of an individual component within the vertex, use
VertexFormat::offset.
-A higher-level interface for filling in vertex data is available in the
-VertexArrayBuilder class.
+VertexArrayBuilder provides a convenient way of filling in vertex data.
+
+Applications normally don't need to deal with VertexArrays directly. They're
+managed by the Mesh and InstanceArray classes.
*/
class VertexArray: public Bufferable
{
public:
VertexArray() = default;
- /// Construct a VertexArray and set its format.
+ /** Constructs a VertexArray and sets its format. */
VertexArray(const VertexFormat &);
- /// Sets the format of the VertexArray.
+ /** Sets the format of the VertexArray. The format cannot be changed once
+ set. */
void set_format(const VertexFormat &);
const VertexFormat &get_format() const { return format; }
- /// Clears all vertices from the array.
+ /** Clears all vertices from the array. Vertex format is retained. */
void clear();
- /// Reserve space for vertices.
+ /** Reserve space for vertices. If n is smaller than the current size,
+ nothing is done. */
void reserve(std::size_t n);
- /// Append a new vertex at the end of the array and return its location.
+ /** Append a new vertex at the end of the array and return a pointer to it.
+ The array is marked as dirty. */
char *append();
- /// Returns the location of a vertex for modification.
+ /** Returns a pointer to a vertex for modification. The array is marked as
+ dirty. */
char *modify(std::size_t);
private:
virtual std::size_t get_data_size() const;