Mesa (master): util: add comments to u_upload_mgr and u_inlines

[Marek Olšák]

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

Author: Marek Olšák <maraeo at gmail.com>
Date:   Thu Jan  6 00:26:02 2011 +0100

util: add comments to u_upload_mgr and u_inlines

---

 src/gallium/auxiliary/util/u_inlines.h    |   10 +++++++++
 src/gallium/auxiliary/util/u_upload_mgr.c |   32 +++++++++++++++-------------
 src/gallium/auxiliary/util/u_upload_mgr.h |   11 ++++++++++
 3 files changed, 38 insertions(+), 15 deletions(-)

diff --git a/src/gallium/auxiliary/util/u_inlines.h b/src/gallium/auxiliary/util/u_inlines.h
index 8aaf7a7..b4870bc 100644
--- a/src/gallium/auxiliary/util/u_inlines.h
+++ b/src/gallium/auxiliary/util/u_inlines.h
@@ -400,6 +400,12 @@ static INLINE boolean util_get_offset(
    }
 }
 
+/**
+ * This function is used to copy an array of pipe_vertex_buffer structures,
+ * while properly referencing the pipe_vertex_buffer::buffer member.
+ *
+ * \sa util_copy_framebuffer_state
+ */
 static INLINE void util_copy_vertex_buffers(struct pipe_vertex_buffer *dst,
                                             unsigned *dst_count,
                                             const struct pipe_vertex_buffer *src,
@@ -407,13 +413,17 @@ static INLINE void util_copy_vertex_buffers(struct pipe_vertex_buffer *dst,
 {
    unsigned i;
 
+   /* Reference the buffers of 'src' in 'dst'. */
    for (i = 0; i < src_count; i++) {
       pipe_resource_reference(&dst[i].buffer, src[i].buffer);
    }
+   /* Unreference the rest of the buffers in 'dst'. */
    for (; i < *dst_count; i++) {
       pipe_resource_reference(&dst[i].buffer, NULL);
    }
 
+   /* Update the size of 'dst' and copy over the other members
+    * of pipe_vertex_buffer. */
    *dst_count = src_count;
    memcpy(dst, src, src_count * sizeof(struct pipe_vertex_buffer));
 }
diff --git a/src/gallium/auxiliary/util/u_upload_mgr.c b/src/gallium/auxiliary/util/u_upload_mgr.c
index 80c9b63..3b3d5b4 100644
--- a/src/gallium/auxiliary/util/u_upload_mgr.c
+++ b/src/gallium/auxiliary/util/u_upload_mgr.c
@@ -41,17 +41,16 @@
 struct u_upload_mgr {
    struct pipe_context *pipe;
 
-   unsigned default_size;
-   unsigned alignment;
-   unsigned bind;
-
-   /* The active buffer:
-    */
-   struct pipe_resource *buffer;
-   struct pipe_transfer *transfer;
-   uint8_t *map;
-   unsigned size;
-   unsigned offset;
+   unsigned default_size;  /* Minimum size of the upload buffer, in bytes. */
+   unsigned alignment;     /* Alignment of each sub-allocation. */
+   unsigned bind;          /* Bitmask of PIPE_BIND_* flags. */
+
+   struct pipe_resource *buffer;   /* Upload buffer. */
+   struct pipe_transfer *transfer; /* Transfer object for the upload buffer. */
+   uint8_t *map;    /* Pointer to the mapped upload buffer. */
+   unsigned size;   /* Actual size of the upload buffer. */
+   unsigned offset; /* Aligned offset to the upload buffer, pointing
+                     * at the first unused byte. */
 };
 
 
@@ -84,6 +83,7 @@ struct u_upload_mgr *u_upload_create( struct pipe_context *pipe,
  */
 void u_upload_flush( struct u_upload_mgr *upload )
 {
+   /* Unmap and unreference the upload buffer. */
    if (upload->transfer) {
       pipe_transfer_unmap(upload->pipe, upload->transfer);
       upload->transfer = NULL;
@@ -106,7 +106,7 @@ u_upload_alloc_buffer( struct u_upload_mgr *upload,
 {
    unsigned size;
 
-   /* Release old buffer, if present:
+   /* Release the old buffer, if present:
     */
    u_upload_flush( upload );
 
@@ -120,6 +120,7 @@ u_upload_alloc_buffer( struct u_upload_mgr *upload,
    if (upload->buffer == NULL) 
       goto fail;
 
+   /* Map the new buffer. */
    upload->map = pipe_buffer_map(upload->pipe, upload->buffer,
                                  PIPE_TRANSFER_WRITE, &upload->transfer);
    
@@ -147,6 +148,8 @@ enum pipe_error u_upload_alloc( struct u_upload_mgr *upload,
    unsigned alloc_offset = align(min_out_offset, upload->alignment);
    unsigned offset;
 
+   /* Make sure we have enough space in the upload buffer
+    * for the sub-allocation. */
    if (MAX2(upload->offset, alloc_offset) + alloc_size > upload->size) {
       enum pipe_error ret = u_upload_alloc_buffer(upload,
                                                   alloc_offset + alloc_size);
@@ -164,12 +167,11 @@ enum pipe_error u_upload_alloc( struct u_upload_mgr *upload,
    assert(offset + size <= upload->buffer->width0);
    assert(size);
 
+   /* Emit the return values: */
    *ptr = upload->map + offset;
-
-   /* Emit the return values:
-    */
    pipe_resource_reference( outbuf, upload->buffer );
    *out_offset = offset;
+
    upload->offset = offset + alloc_size;
    return PIPE_OK;
 }
diff --git a/src/gallium/auxiliary/util/u_upload_mgr.h b/src/gallium/auxiliary/util/u_upload_mgr.h
index fc8f4d3..c9a2ffe 100644
--- a/src/gallium/auxiliary/util/u_upload_mgr.h
+++ b/src/gallium/auxiliary/util/u_upload_mgr.h
@@ -38,11 +38,22 @@ struct pipe_context;
 struct pipe_resource;
 
 
+/**
+ * Create the upload manager.
+ *
+ * \param pipe          Pipe driver.
+ * \param default_size  Minimum size of the upload buffer, in bytes.
+ * \param alignment     Alignment of each suballocation in the upload buffer.
+ * \param bind          Bitmask of PIPE_BIND_* flags.
+ */
 struct u_upload_mgr *u_upload_create( struct pipe_context *pipe,
                                       unsigned default_size,
                                       unsigned alignment,
                                       unsigned bind );
 
+/**
+ * Destroy the upload manager.
+ */
 void u_upload_destroy( struct u_upload_mgr *upload );
 
 /* Unmap and release old buffer.