Mesa (master): indices: add some comments

[Brian Paul]

Module: Mesa
Branch: master
Commit: 8b3d4efed8275b0f9ddc436a61884c8bc0171192
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=8b3d4efed8275b0f9ddc436a61884c8bc0171192

Author: Brian Paul <brianp at vmware.com>
Date:   Wed Jun 19 10:39:43 2013 -0600

indices: add some comments

This is pretty complicated code with few/any comments.  Here's a first stab.

Reviewed-by: Jose Fonseca <jfonseca at vmware.com>

---

 src/gallium/auxiliary/indices/u_indices.c          |   23 +++++++++++++++++--
 src/gallium/auxiliary/indices/u_unfilled_indices.c |    9 +++++++-
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/src/gallium/auxiliary/indices/u_indices.c b/src/gallium/auxiliary/indices/u_indices.c
index 03d7453..72c46f7 100644
--- a/src/gallium/auxiliary/indices/u_indices.c
+++ b/src/gallium/auxiliary/indices/u_indices.c
@@ -150,9 +150,26 @@ int u_index_translator( unsigned hw_mask,
 }
 
 
-
-
-
+/**
+ * If a driver does not support a particular gallium primitive type
+ * (such as PIPE_PRIM_QUAD_STRIP) this function can be used to help
+ * convert the primitive into a simpler type (like PIPE_PRIM_TRIANGLES).
+ *
+ * The generator functions generates a number of ushort or uint indexes
+ * for drawing the new type of primitive.
+ *
+ * \param hw_mask  a bitmask of (1 << PIPE_PRIM_x) values that indicates
+ *                 kind of primitives are supported by the driver.
+ * \param prim  the PIPE_PRIM_x that the user wants to draw
+ * \param start  index of first vertex to draw
+ * \param nr  number of vertices to draw
+ * \param in_pv  user's provoking vertex (PV_FIRST/LAST)
+ * \param out_pv  desired proking vertex for the hardware (PV_FIRST/LAST)
+ * \param out_prim  returns the new primitive type for the driver
+ * \param out_index_size  returns OUT_USHORT or OUT_UINT
+ * \param out_nr  returns new number of vertices to draw
+ * \param out_generate  returns pointer to the generator function
+ */
 int u_index_generator( unsigned hw_mask,
                        unsigned prim,
                        unsigned start,
diff --git a/src/gallium/auxiliary/indices/u_unfilled_indices.c b/src/gallium/auxiliary/indices/u_unfilled_indices.c
index c353717..25c61d9 100644
--- a/src/gallium/auxiliary/indices/u_unfilled_indices.c
+++ b/src/gallium/auxiliary/indices/u_unfilled_indices.c
@@ -151,7 +151,14 @@ int u_unfilled_translator( unsigned prim,
 }
 
 
-
+/**
+ * Utility for converting unfilled polygons into points, lines, triangles.
+ * Few drivers have direct support for OpenGL's glPolygonMode.
+ * This function helps with converting triangles into points or lines
+ * when the front and back fill modes are the same.  When there's
+ * different front/back fill modes, that can be handled with the
+ * 'draw' module.
+ */
 int u_unfilled_generator( unsigned prim,
                           unsigned start,
                           unsigned nr,