Update and improve documentation

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

diff --git a/source/core/mesh.h b/source/core/mesh.h
index 14b08a964cd59e2889c853cc8230afaa81a97a34..5544ed1f55e0e5cdf772cf9194d26bc9eabbd775 100644 (file)
--- a/source/core/mesh.h
+++ b/source/core/mesh.h
@@ -17,9 +17,12 @@ class Buffer;
 class Renderer;
 
 /**
-Raw mesh data, consisting of a VertexArray and one or more Batches.  Though a
-Mesh can draw itself, it's usually used as part of Renderables rather than on
-its own.
+Stores mesh data using a VertexArray and one or more Batches.
+
+Meshes can be created at runtime using the MeshBuilder class.
+
+The Object class provides a higher-level interface which associates a Mesh with
+a Technique and is usually the appropriate way to of rendering geometry.
 */
 class Mesh: public Resource
 {
@@ -79,8 +82,10 @@ public:
        Mesh(const VertexFormat &);
        ~Mesh();
 
+       /** Sets the vertex format for the mesh.  It cannot be changed once set. */
        void storage(const VertexFormat &);
 
+       /** Clears all vertices and batches.  Vertex format is retained. */
        void clear();
 private:
        void check_buffers(unsigned);
@@ -90,15 +95,25 @@ public:
        const VertexSetup &get_vertex_setup() const { return vtx_setup; }
        const Buffer *get_index_buffer() const { return ibuf; }
        std::size_t get_n_vertices() const;
+
+       /** Returns a pointer to a vertex.  Offsets of individual attributes can be
+       queried from VertexFormat. */
        char *modify_vertex(std::size_t);
 
+       /** Adds a batch to the mesh.  It may be combined with the last existing
+       batch if the primitive types are compatible. */
        void add_batch(const Batch &b);
+
        const std::vector<Batch> &get_batches() const { return batches; }
 
        void set_winding(FaceWinding);
 
        void draw(Renderer &) const;
+       
+       /** Draws multiple instances of the mesh.  The supplied VertexSetup must use
+       the mesh's vertex array. */
        void draw_instanced(Renderer &, const VertexSetup &, unsigned) const;
+
 private:
        void draw(Renderer &, const VertexSetup *, unsigned) const;
        void resize_buffers() const;