X-Git-Url: http://git.tdb.fi/?a=blobdiff_plain;f=source%2Fcore%2Fvertexarray.h;h=8e56ee226b599254f0876942322ee2a4dc1d6ee5;hb=f73e671dcb36c097647cddbf5b1eaaad2ffc9299;hp=60e035f9a6ad429cef54bee4aaa1832d38fb4e08;hpb=be6ffe96ecb4707599fe1a6f620c348760213d46;p=libs%2Fgl.git

diff --git a/source/core/vertexarray.h b/source/core/vertexarray.h
index 60e035f9..8e56ee22 100644
--- a/source/core/vertexarray.h
+++ b/source/core/vertexarray.h
@@ -11,14 +11,17 @@ namespace Msp {
 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
 {
@@ -39,24 +42,28 @@ private:
 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;