From a8fbde4710baa3b8b17ac16b4ffaef1ac472b71e Mon Sep 17 00:00:00 2001 From: Robert Bragg Date: Tue, 25 Oct 2011 21:45:49 +0100 Subject: [PATCH] doc: Adds some documentation for CoglIndices This adds just some basic documentation to try and explain what CoglIndices are useful for. Reviewed-by: Neil Roberts --- cogl/cogl-indices.h | 53 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/cogl/cogl-indices.h b/cogl/cogl-indices.h index 3f869b7e4..be1998c8c 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;