[cogl/wip/rib/master-next: 40/44] doc: Adds some documentation for CoglIndices

[Robert Bragg <rbragg src gnome org>]

commit 0c093b5ec00c0fd14af84255193a78566c14d2f1
Author: Robert Bragg <robert linux intel com>
Date:   Tue Oct 25 21:45:49 2011 +0100

    doc: Adds some documentation for CoglIndices
    
    This adds just some basic documentation to try and explain what
    CoglIndices are useful for.

 cogl/cogl-indices.h |   53 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 52 insertions(+), 1 deletions(-)
---
diff --git a/cogl/cogl-indices.h b/cogl/cogl-indices.h
index 3f869b7..be1998c 100644
--- a/cogl/cogl-indices.h
+++ b/cogl/cogl-indices.h
@@ -40,7 +40,58 @@ G_BEGIN_DECLS
  * @short_description: Fuctions for declaring a range of vertex indices
  *   stored in a #CoglIndexBuffer.
  *
- * FIXME
+ * Indices allow you to avoid duplicating vertices in your vertex data
+ * by virtualizing your data and instead providing a sequence of index
+ * values that tell the GPU which data should be used for each vertex.
+ *
+ * If the GPU is given a squence of indices it doesn't simply walk
+ * through each vertex of your data in order it will instead walk
+ * through the indices which can provide random access to the
+ * underlying data.
+ *
+ * Since it's very common to have duplicate vertices when describing a
+ * shape as a list of triangles it can often be a significant space
+ * saving to describe geometry using indices. Reducing the size of
+ * your models can make it cheaper to map them into the GPU by
+ * reducing the demand on memory bandwidth and may help to make better
+ * use of your GPUs internal vertex caching.
+ *
+ * For example, to describe a quadrilateral as 2 triangles for the GPU
+ * you could either provide data with 6 vertices or instead with
+ * indices you can provide vertex data for just 4 vertices and an
+ * index buffer that specfies the 6 vertices by indexing the shared
+ * vertices multiple times.
+ *
+ * |[
+ *   CoglVertex2f quad_vertices[] = {
+ *     {x0, y0}, //0 = top left
+ *     {x1, y1}, //1 = bottom left
+ *     {x2, y2}, //2 = bottom right
+ *     {x3, y3}, //3 = top right
+ *   };
+ *   //tell the gpu how to interpret the quad as 2 triangles...
+ *   unsigned char indices[] = {0, 1, 2, 0, 2, 3};
+ * ]|
+ *
+ * Even in the above illustration we see a saving of 10bytes for one
+ * quad compared to having data for 6 vertices and no indices but if
+ * you need to draw 100s or 1000s of quads then its really quite
+ * significant.
+ *
+ * Something else to consider is that often indices can be defined
+ * once and remain static while the vertex data may change for
+ * animations perhaps. That means you may be able to ignore the
+ * negligable cost of mapping your indices into the GPU if they don't
+ * ever change.
+ *
+ * The above illustration is actually a good example of static indices
+ * because it's really common that developers have quad mesh data that
+ * they need to display and we know exactly what that indices array
+ * needs to look like depending on the number of quads that need to be
+ * drawn. It doesn't matter how the quads might be animated and
+ * changed the indices will remain the same. Cogl even has a utility
+ * (cogl_get_rectangle_indices()) to get access to re-useable indices
+ * for drawing quads as above.
  */
 
 typedef struct _CoglIndices CoglIndices;