From: Brian Paul <brian.paul@tungstengraphics.com>
Date: Wed, 2 Mar 2005 16:37:24 +0000 (+0000)
Subject: Added a bunch of new comments, minor code clean-ups.
X-Git-Tag: mesa-7.8~9560
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=b960c14cbb4eb701ea500f54695aec1c5948d3f1;p=platform%2Fupstream%2Fmesa.git

Added a bunch of new comments, minor code clean-ups.
---

diff --git a/src/mesa/tnl/t_vb_light.c b/src/mesa/tnl/t_vb_light.c
index d286129..9cf0032 100644
--- a/src/mesa/tnl/t_vb_light.c
+++ b/src/mesa/tnl/t_vb_light.c
@@ -46,13 +46,20 @@ typedef void (*light_func)( GLcontext *ctx,
 			    struct tnl_pipeline_stage *stage,
 			    GLvector4f *input );
 
+/**
+ * Information for updating current material attributes from vertex color,
+ * for GL_COLOR_MATERIAL.
+ */
 struct material_cursor {
-   const GLfloat *ptr;
-   GLuint stride;
-   GLfloat *current;
-   GLuint size;  /* 1, 2, 3 or 4 */
+   const GLfloat *ptr;    /* points to src vertex color (in VB array) */
+   GLuint stride;         /* stride to next vertex color (bytes) */
+   GLfloat *current;      /* points to material attribute to update */
+   GLuint size;           /* vertex/color size: 1, 2, 3 or 4 */
 };
 
+/**
+ * Data private to this pipeline stage.
+ */
 struct light_stage_data {
    GLvector4f Input;
    GLvector4f LitColor[2];
@@ -70,55 +77,75 @@ struct light_stage_data {
 
 
 
-/* In the case of colormaterial, the effected material attributes
+/**
+ * In the case of colormaterial, the effected material attributes
  * should already have been bound to point to the incoming color data,
  * prior to running the pipeline.
+ * This function copies the vertex's color to the material attributes
+ * which are tracking glColor.
+ * It's called per-vertex in the lighting loop.
  */
-static void update_materials( GLcontext *ctx,
-			      struct light_stage_data *store )
+static void
+update_materials(GLcontext *ctx, struct light_stage_data *store)
 {
    GLuint i;
 
    for (i = 0 ; i < store->mat_count ; i++) {
+      /* update the material */
       COPY_CLEAN_4V(store->mat[i].current, store->mat[i].size, store->mat[i].ptr);
+      /* increment src vertex color pointer */
       STRIDE_F(store->mat[i].ptr, store->mat[i].stride);
    }
       
+   /* recompute derived light/material values */
    _mesa_update_material( ctx, store->mat_bitmask );
+   /* XXX we should only call this if we're tracking/changing the specular
+    * exponent.
+    */
    _mesa_validate_all_lighting_tables( ctx );
 }
 
-static GLuint prepare_materials( GLcontext *ctx,
-				 struct vertex_buffer *VB,
-				 struct light_stage_data *store )
+
+/**
+ * Prepare things prior to running the lighting stage.
+ * Return number of material attributes which will track vertex color.
+ */
+static GLuint
+prepare_materials(GLcontext *ctx,
+                  struct vertex_buffer *VB, struct light_stage_data *store)
 {
    GLuint i;
    
    store->mat_count = 0;
    store->mat_bitmask = 0;
 
-   /* If ColorMaterial enabled, overwrite affected AttrPtr's with
-    * the color pointer.  This could be done earlier.
+   /* Examine the ColorMaterialBitmask to determine which materials
+    * track vertex color.  Override the material attribute's pointer
+    * with the color pointer for each one.
     */
    if (ctx->Light.ColorMaterialEnabled) {
-      GLuint bitmask = ctx->Light.ColorMaterialBitmask;
+      const GLuint bitmask = ctx->Light.ColorMaterialBitmask;
       for (i = 0 ; i < MAT_ATTRIB_MAX ; i++)
 	 if (bitmask & (1<<i))
 	    VB->AttribPtr[_TNL_ATTRIB_MAT_FRONT_AMBIENT + i] = VB->ColorPtr[0];
    }
 
+   /* Now, for each material attribute that's tracking vertex color, save
+    * some values (ptr, stride, size, current) that we'll need in
+    * update_materials(), above, that'll actually copy the vertex color to
+    * the material attribute(s).
+    */
    for (i = _TNL_ATTRIB_MAT_FRONT_AMBIENT ; i < _TNL_ATTRIB_INDEX ; i++) {
       if (VB->AttribPtr[i]->stride) {
-	 GLuint j = store->mat_count++;
-	 GLuint attr = i - _TNL_ATTRIB_MAT_FRONT_AMBIENT;
+	 const GLuint j = store->mat_count++;
+	 const GLuint attr = i - _TNL_ATTRIB_MAT_FRONT_AMBIENT;
 	 store->mat[j].ptr    = VB->AttribPtr[i]->start;
 	 store->mat[j].stride = VB->AttribPtr[i]->stride;
-         store->mat[j].size   = VB->AttribPtr[i]->size;
+	 store->mat[j].size   = VB->AttribPtr[i]->size;
 	 store->mat[j].current = ctx->Light.Material.Attrib[attr];
 	 store->mat_bitmask |= (1<<attr);
       }
    }
-   
 
    /* FIXME: Is this already done?
     */
@@ -353,7 +380,7 @@ static void dtr( struct tnl_pipeline_stage *stage )
 const struct tnl_pipeline_stage _tnl_lighting_stage =
 {
    "lighting",			/* name */
-   _NEW_LIGHT|_NEW_PROGRAM,			/* recheck */
+   _NEW_LIGHT|_NEW_PROGRAM,	/* recheck */
    _NEW_LIGHT|_NEW_MODELVIEW,	/* recalc -- modelview dependency
 				 * otherwise not captured by inputs
 				 * (which may be _TNL_BIT_POS) */