[docs] Various gtk-doc updates for Cogl

This hides a number of internal structs and enums from the docs, and moves
some functions to more appropriate sections as well as misc description
updates (mostly for the vertex buffer api)

1 files changed, 75 insertions, 79 deletions

diff --git a/cogl-vertex-buffer.h b/cogl-vertex-buffer.h
index 73b51e84..06ac22cb 100644
--- a/cogl-vertex-buffer.h
+++ b/cogl-vertex-buffer.h
@@ -38,44 +38,39 @@ G_BEGIN_DECLS
 /**
  * SECTION:cogl-vertex-buffer
  * @short_description: An API for submitting extensible arrays of vertex
- *		       attributes to OpenGL in a way that aims to minimise
- *		       copying or reformatting of the original data.
- *
- * The Attributes Buffer API is designed to be a fairly raw mechanism for
+ *		       attributes to be mapped into the GPU for fast
+ *		       drawing.
+ *
+ * For example to describe a textured triangle, you could create a new cogl
+ * vertex buffer with 3 vertices, and then you might add 2 attributes for each
+ * vertex:
+ * <orderedlist>
+ * <listitem>
+ * a "gl_Position" describing the (x,y,z) position for each vertex.
+ * </listitem>
+ * <listitem>
+ * a "gl_MultiTexCoord0" describing the (tx,ty) texture coordinates for each
+ * vertex.
+ * </listitem>
+ * </orderedlist>
+ *
+ * The Vertex Buffer API is designed to be a fairly raw mechanism for
  * developers to be able to submit geometry to Cogl in a format that can be
- * directly consumed by an OpenGL driver and with awareness of the specific
- * hardware being used then costly format conversion can also be avoided.
- *
- * They are designed to work on top of buffer objects and developers should
- * understand that attribute buffers are not that cheap to create but once they
- * have been submitted they can be stored in GPU addressable memory and can
- * be quickly reused.
- *
- * Although this API does allow you to modify attribute buffers after they have
- * been submitted to the GPU you must note that modification is also not that
- * cheap, so if at all possible think of tricks that let you reuse a static
- * buffer. To help with this, it is possible to enable and disable individual
- * attributes cheaply.
- *
- * Take for example attributes representing an elipse. If you were to submit
- * color attributes, texture coordinates and normals, then you would be able
- * to draw an elipses in the following different ways without modifying
- * the vertex buffer, only by changing your source material.
- * <itemizedlist>
- * <listitem>Flat colored elipse</listitem>
- * <listitem>Textured elipse</listitem>
- * <listitem>Smoothly lit textured elipse blended with the color.</listitem>
- * </itemizedlist>
- *
- * Another trick that can be used is submitting highly detailed vertices and
- * then using cogl_vertex_buffer_draw_range_elements to sample sub-sets of
- * the geometry or lower resolution geometry out from a fixed buffer.
- *
- * The API doesn't currently give you any control over the actual OpenGL buffer
- * objects that are created, but you can expect that when you first submit
- * your attributes they start off in one or more GL_STATIC_DRAW buffers.
- * If you then update some of your attributes; then these attributes will
- * normally be moved into new GL_DYNAMIC_DRAW draw buffers.
+ * directly consumed by an OpenGL driver and mapped into your GPU for fast
+ * re-use. It is designed to avoid repeated validation of the attributes by the
+ * driver; to minimize transport costs (considering indirect GLX use-cases)
+ * and to potentially avoid repeated format conversions when attributes are
+ * supplied in a format that is not natively supported by the GPU.
+ *
+ * Although this API does allow you to modify attributes after they have been
+ * submitted to the GPU you should be aware that modification is not that
+ * cheap, since it implies validating the new data and potentially the
+ * OpenGL driver will need to reformat it for the GPU.
+ *
+ * If at all possible think of tricks that let you re-use static attributes,
+ * and if you do need to repeatedly update attributes (e.g. for some kind of
+ * morphing geometry) then only update and re-submit the specific attributes
+ * that have changed.
  */
 
 /**
@@ -94,7 +89,7 @@ cogl_vertex_buffer_new (guint n_vertices);
  * @attribute_name: The name of your attribute. It should be a valid GLSL
  *		    variable name and standard attribute types must use one
  *		    of following built-in names: (Note: they correspond to the
- *		    built-in names in GLSL)
+ *		    built-in names of GLSL)
  *		    <itemizedlist>
  *		    <listitem>"gl_Color"</listitem>
  *		    <listitem>"gl_Normal"</listitem>
@@ -106,8 +101,7 @@ cogl_vertex_buffer_new (guint n_vertices);
  *		    "gl_Color::active" or "gl_Color::inactive"
  * @n_components: The number of components per attribute and must be 1,2,3 or 4
  * @gl_type: Specifies the data type of each component (GL_BYTE, GL_UNSIGNED_BYTE,
- *	     GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT or
- *	     GL_DOUBLE)
+ *	     GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT or GL_FLOAT)
  * @normalized: If GL_TRUE, this specifies that values stored in an integer
  *		format should be mapped into the range [-1.0, 1.0] or [0.1, 1.0]
  *		for unsigned values. If GL_FALSE they are converted to floats
@@ -119,32 +113,33 @@ cogl_vertex_buffer_new (guint n_vertices);
  *	    stride for both attributes is 6. The special value 0 means the
  *	    values are stored sequentially in memory.
  * @pointer: This addresses the first attribute in the vertex array. (This
- *	     must remain valid until you call cogl_vertex_buffer_submit)
+ *	     must remain valid until you call cogl_vertex_buffer_submit())
  *
  * This function lets you add an attribute to a buffer. You either use one
- * of the built-in names to add standard attributes, like positions, colors
- * and normals or you can add custom attributes for use in shaders.
+ * of the built-in names such as "gl_Vertex", or "glMultiTexCoord0" to add
+ * standard attributes, like positions, colors and normals or you can add
+ * custom attributes for use in shaders.
  *
- * Note: The number of vertices declared when first creating the vertex
- * buffer is used to determine how many attribute values will be read from the
- * supplied pointer.
+ * The number of vertices declared when calling cogl_vertex_buffer_new()
+ * determines how many attribute values will be read from the supplied pointer.
  *
- * Note: the data supplied here isn't copied anywhere until you call
- * cogl_vertex_buffer_submit, so the supplied pointer must remain valid
- * until then.
- * (This is an important optimisation since we can't create the underlying
- * OpenGL buffer object until we know about all the attributes, and repeatedly
- * copying large buffers of vertex data may be very costly) If you add
- * attributes after submitting then you will need to re-call
- * cogl_vertex_buffer_submit to commit the changes to the GPU. (Be carefull
- * to minimize the number of calls to cogl_vertex_buffer_submit though)
+ * The data for your attribute isn't copied anywhere until you call
+ * cogl_vertex_buffer_submit(), so the supplied pointer must remain valid
+ * until then. If you are updating an attribute by re-adding it then you will
+ * also need to re-call cogl_vertex_buffer_submit() to commit the changes to
+ * the GPU. (Be carefull to minimize the number of calls to
+ * cogl_vertex_buffer_submit though.)
  *
  * Note: If you are interleving attributes it is assumed that that each
  * interleaved attribute starts no farther than +- stride bytes from the other
  * attributes it is interleved with. I.e. this is ok:
+ * <programlisting>
  * |-0-0-0-0-0-0-0-0-0-0|
+ * </programlisting>
  * This is not ok:
+ * <programlisting>
  * |- - - - -0-0-0-0-0-0 0 0 0 0|
+ * </programlisting>
  * (Though you can have multiple groups of interleved attributes)
  */
 void
@@ -162,59 +157,60 @@ cogl_vertex_buffer_add (CoglHandle  handle,
  * @attribute_name: The name of a previously added attribute
  *
  * This function deletes an attribute from a buffer. You will need to
- * call cogl_vertex_buffer_submit to commit this change to the GPU.
+ * call cogl_vertex_buffer_submit() to commit this change to the GPU.
  */
 void
 cogl_vertex_buffer_delete (CoglHandle   handle,
 			   const char  *attribute_name);
 
 /**
- * cogl_vertex_buffer_enable:
+ * cogl_vertex_buffer_submit:
  * @handle: A vertex buffer handle
- * @attribute_name: The name of the attribute you want to enable
  *
- * This function enables a previosuly added attribute
+ * This function submits all the user added attributes to the GPU; once
+ * submitted the attributes can be used for drawing.
  *
- * Since it can be costly to add and remove new attributes to buffers; to make
- * individual buffers more reuseable it is possible to enable and disable
- * attributes before using a buffer for drawing.
- *
- * Note: You don't need to call cogl_vertex_buffer_submit after using this
- * function
+ * You should aim to minimize calls to this function since it implies
+ * validating your data; it potentially incurs a transport cost (especially if
+ * you are using GLX indirect rendering) and potentially a format conversion
+ * cost if the GPU doesn't natively support any of the given attribute formats.
  */
 void
-cogl_vertex_buffer_enable (CoglHandle  handle,
-			   const char *attribute_name);
+cogl_vertex_buffer_submit (CoglHandle handle);
 
 /**
- * cogl_vertex_buffer_submit:
+ * cogl_vertex_buffer_disable:
  * @handle: A vertex buffer handle
+ * @attribute_name: The name of the attribute you want to disable
  *
- * This function copies all the user added attributes into buffer objects
- * managed by the OpenGL driver.
+ * This function disables a previosuly added attribute.
  *
- * You should aim to minimize calls to this function.
+ * Since it can be costly to add and remove new attributes to buffers; to make
+ * individual buffers more reuseable it is possible to enable and disable
+ * attributes before using a buffer for drawing.
+ *
+ * You don't need to call cogl_vertex_buffer_submit() after using this function.
  */
 void
-cogl_vertex_buffer_submit (CoglHandle handle);
+cogl_vertex_buffer_disable (CoglHandle  handle,
+			    const char *attribute_name);
 
 /**
- * cogl_vertex_buffer_disable:
+ * cogl_vertex_buffer_enable:
  * @handle: A vertex buffer handle
- * @attribute_name: The name of the attribute you want to disable
+ * @attribute_name: The name of the attribute you want to enable
  *
- * This function disables a previosuly added attribute
+ * This function enables a previosuly disabled attribute.
  *
  * Since it can be costly to add and remove new attributes to buffers; to make
  * individual buffers more reuseable it is possible to enable and disable
  * attributes before using a buffer for drawing.
  *
- * Note: You don't need to call cogl_vertex_buffer_submit after using this
- * function
+ * You don't need to call cogl_vertex_buffer_submit() after using this function
  */
 void
-cogl_vertex_buffer_disable (CoglHandle  handle,
-			    const char *attribute_name);
+cogl_vertex_buffer_enable (CoglHandle  handle,
+			   const char *attribute_name);
 
 /**
  * cogl_vertex_buffer_draw: