llvmpipe: add a bunch of comments

4 files changed, 54 insertions, 13 deletions

diff --git a/src/gallium/drivers/llvmpipe/lp_rast.c b/src/gallium/drivers/llvmpipe/lp_rast.c
index 32cd5e09f54..09495f6288e 100644
--- a/src/gallium/drivers/llvmpipe/lp_rast.c
+++ b/src/gallium/drivers/llvmpipe/lp_rast.c
@@ -51,6 +51,10 @@ struct lp_rasterizer *lp_rast_create( struct pipe_screen *screen )
 }
 
 
+/**
+ * Begin the rasterization phase.
+ * Map the framebuffer surfaces.  Initialize the 'rast' state.
+ */
 boolean lp_rast_begin( struct lp_rasterizer *rast,
                        struct pipe_surface *cbuf,
                        struct pipe_surface *zsbuf,
@@ -95,6 +99,10 @@ boolean lp_rast_begin( struct lp_rasterizer *rast,
 }
 
 
+/**
+ * Finish the rasterization phase.
+ * Unmap framebuffer surfaces.
+ */
 void lp_rast_end( struct lp_rasterizer *rast )
 {
    struct pipe_screen *screen = rast->screen;
@@ -120,7 +128,10 @@ void lp_rast_end( struct lp_rasterizer *rast )
 
 
 
-/* Begining of each tile:
+/**
+ * Begining rasterization of a tile.
+ * \param x  window X position of the tile, in pixels
+ * \param y  window Y position of the tile, in pixels
  */
 void lp_rast_start_tile( struct lp_rasterizer *rast,
 			 unsigned x,
@@ -132,6 +143,10 @@ void lp_rast_start_tile( struct lp_rasterizer *rast,
    rast->y = y;
 }
 
+
+/**
+ * Clear the rasterizer's current color tile.
+ */
 void lp_rast_clear_color( struct lp_rasterizer *rast,
                           const union lp_rast_cmd_arg arg )
 {
@@ -157,6 +172,10 @@ void lp_rast_clear_color( struct lp_rasterizer *rast,
    }
 }
 
+
+/**
+ * Clear the rasterizer's current z/stencil tile.
+ */
 void lp_rast_clear_zstencil( struct lp_rasterizer *rast,
                              const union lp_rast_cmd_arg arg)
 {
@@ -307,6 +326,9 @@ void lp_rast_shade_quads( struct lp_rasterizer *rast,
  */
 
 
+/**
+ * Write the rasterizer's color tile to the framebuffer.
+ */
 static void lp_rast_store_color( struct lp_rasterizer *rast )
 {
    const unsigned x = rast->x;
@@ -331,6 +353,9 @@ static void lp_rast_store_color( struct lp_rasterizer *rast )
 }
 
 
+/**
+ * Write the rasterizer's z/stencil tile to the framebuffer.
+ */
 static void lp_rast_store_zstencil( struct lp_rasterizer *rast )
 {
    RAST_DEBUG("%s\n", __FUNCTION__);
@@ -339,6 +364,9 @@ static void lp_rast_store_zstencil( struct lp_rasterizer *rast )
 }
 
 
+/**
+ * Write the rasterizer's tiles to the framebuffer.
+ */
 void lp_rast_end_tile( struct lp_rasterizer *rast )
 {
    RAST_DEBUG("%s\n", __FUNCTION__);
diff --git a/src/gallium/drivers/llvmpipe/lp_rast.h b/src/gallium/drivers/llvmpipe/lp_rast.h
index 282b9a46d1b..a50b73b27f6 100644
--- a/src/gallium/drivers/llvmpipe/lp_rast.h
+++ b/src/gallium/drivers/llvmpipe/lp_rast.h
@@ -79,6 +79,7 @@ struct lp_rast_shader_inputs {
  * plus inputs to run the shader:
  */
 struct lp_rast_triangle {
+   /* bounding box of tri (in pixels) */
    int minx;
    int maxx;
    int miny;
@@ -94,12 +95,12 @@ struct lp_rast_triangle {
    int eo2;
    int eo3;
 
-   /* y deltas for vertex pairs */
+   /* y deltas for vertex pairs (in fixed pt) */
    int dy12;
    int dy23;
    int dy31;
 
-   /* x deltas for vertex pairs */
+   /* x deltas for vertex pairs (in fixed pt) */
    int dx12;
    int dx23;
    int dx31;
diff --git a/src/gallium/drivers/llvmpipe/lp_setup_context.h b/src/gallium/drivers/llvmpipe/lp_setup_context.h
index 938f6ce262d..3209e41c01f 100644
--- a/src/gallium/drivers/llvmpipe/lp_setup_context.h
+++ b/src/gallium/drivers/llvmpipe/lp_setup_context.h
@@ -87,6 +87,7 @@ struct setup_context {
    struct cmd_block_list tile[TILES_X][TILES_Y];
    struct data_block_list data;
 
+   /* size of framebuffer, in tiles */
    unsigned tiles_x;
    unsigned tiles_y;
    
@@ -154,6 +155,11 @@ void lp_setup_choose_point( struct setup_context *setup );
 void lp_setup_new_data_block( struct data_block_list *list );
 void lp_setup_new_cmd_block( struct cmd_block_list *list );
 
+
+/**
+ * Allocate space for a command/data in the given block list.
+ * Grow the block list if needed.
+ */
 static INLINE void *get_data( struct data_block_list *list,
                               unsigned size)
 {
diff --git a/src/gallium/drivers/llvmpipe/lp_setup_tri.c b/src/gallium/drivers/llvmpipe/lp_setup_tri.c
index f2665c11df3..cf862554067 100644
--- a/src/gallium/drivers/llvmpipe/lp_setup_tri.c
+++ b/src/gallium/drivers/llvmpipe/lp_setup_tri.c
@@ -230,6 +230,11 @@ static inline int subpixel_snap( float a )
 #define MIN3(a,b,c) MIN2(MIN2(a,b),c)
 #define MAX3(a,b,c) MAX2(MAX2(a,b),c)
 
+/**
+ * Do basic setup for triangle rasterization and determine which
+ * framebuffer tiles are touched.  Put the triangle in the bins for the
+ * tiles which we overlap.
+ */
 static void 
 do_triangle_ccw(struct setup_context *setup,
 		const float (*v1)[4],
@@ -237,15 +242,14 @@ do_triangle_ccw(struct setup_context *setup,
 		const float (*v3)[4],
 		boolean frontfacing )
 {
-
+   /* x/y positions in fixed point */
+   const int x1 = subpixel_snap(v1[0][0]);
+   const int x2 = subpixel_snap(v2[0][0]);
+   const int x3 = subpixel_snap(v3[0][0]);
    const int y1 = subpixel_snap(v1[0][1]);
    const int y2 = subpixel_snap(v2[0][1]);
    const int y3 = subpixel_snap(v3[0][1]);
 
-   const int x1 = subpixel_snap(v1[0][0]);
-   const int x2 = subpixel_snap(v2[0][0]);
-   const int x3 = subpixel_snap(v3[0][0]);
-   
    struct lp_rast_triangle *tri = get_data( &setup->data, sizeof *tri );
    float area;
    int minx, maxx, miny, maxy;
@@ -270,7 +274,7 @@ do_triangle_ccw(struct setup_context *setup,
       return;
    }
 
-   // Bounding rectangle
+   /* Bounding rectangle (in pixels) */
    tri->minx = (MIN3(x1, x2, x3) + 0xf) >> FIXED_ORDER;
    tri->maxx = (MAX3(x1, x2, x3) + 0xf) >> FIXED_ORDER;
    tri->miny = (MIN3(y1, y2, y3) + 0xf) >> FIXED_ORDER;
@@ -372,13 +376,14 @@ do_triangle_ccw(struct setup_context *setup,
       }
    }
 
+   /* Convert to tile coordinates:
+    */
    minx = tri->minx / TILE_SIZE;
    miny = tri->miny / TILE_SIZE;
    maxx = tri->maxx / TILE_SIZE;
    maxy = tri->maxy / TILE_SIZE;
 
-
-   /* Convert to tile coordinates:
+   /* Determine which tile(s) intersect the triangle's bounding box
     */
    if (miny == maxy && minx == maxx)
    {
@@ -442,8 +447,9 @@ do_triangle_ccw(struct setup_context *setup,
 		     cx3 + ei3 > 0) 
 	    {
 	       in = 1;
-               /* shade whole tile */
-               bin_command( &setup->tile[x][y], lp_rast_shade_tile,
+               /* triangle covers the whole tile- shade whole tile */
+               bin_command( &setup->tile[x][y],
+                            lp_rast_shade_tile,
                             lp_rast_arg_inputs(&tri->inputs) );
 	    }
 	    else