[Mesa-dev] [PATCH 01/11] gallium: add common uploaders into pipe_context (v2)

[Marek Olšák]

From: Marek Olšák <marek.olsak at amd.com>

For lower memory usage and more efficient updates of the buffer residency
list. (e.g. if drivers keep seeing the same buffer for many consecutive
"add" calls, the calls can be turned into no-ops trivially)

v2: add const_uploader, add documentation

Reviewed-by: Nicolai Hähnle <nicolai.haehnle at amd.com> (v1)
Tested-by: Edmondo Tommasina <edmondo.tommasina at gmail.com>
---
 src/gallium/docs/source/context.rst  | 23 +++++++++++++++++++++++
 src/gallium/include/pipe/p_context.h | 11 +++++++++++
 2 files changed, 34 insertions(+)

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index d8b2560..d70e34e 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -245,20 +245,43 @@ and the clear will be unconditional.
 ``clear_texture`` clears a non-PIPE_BUFFER resource's specified level
 and bounding box with a clear value provided in that resource's native
 format.
 
 ``clear_buffer`` clears a PIPE_BUFFER resource with the specified clear value
 (which may be multiple bytes in length). Logically this is a memset with a
 multi-byte element value starting at offset bytes from resource start, going
 for size bytes. It is guaranteed that size % clear_value_size == 0.
 
 
+Uploading
+^^^^^^^^^
+
+For simple single-use uploads, use ``pipe_context::stream_uploader`` or
+``pipe_context::const_uploader``. The latter should be used for uploading
+constants, while the former should be used for uploading everything else.
+PIPE_USAGE_STREAM is implied in both cases, so don't use the uploaders
+for static allocations.
+
+Usage:
+
+Call u_upload_alloc or u_upload_data as many times as you want. After you are
+done, call u_upload_unmap. If the driver doesn't support persistent mappings,
+u_upload_unmap makes sure the previously mapped memory is unmapped.
+
+Gotchas:
+- Always fill the memory immediately after u_upload_alloc. Any following call
+to u_upload_alloc and u_upload_data can unmap memory returned by previous
+u_upload_alloc.
+- Don't interleave calls using stream_uploader and const_uploader. If you use
+one of them, do the upload, unmap, and only then can you use the other one.
+
+
 Drawing
 ^^^^^^^
 
 ``draw_vbo`` draws a specified primitive.  The primitive mode and other
 properties are described by ``pipe_draw_info``.
 
 The ``mode``, ``start``, and ``count`` fields of ``pipe_draw_info`` specify the
 the mode of the primitive and the vertices to be fetched, in the range between
 ``start`` to ``start``+``count``-1, inclusive.
 
diff --git a/src/gallium/include/pipe/p_context.h b/src/gallium/include/pipe/p_context.h
index 45098c9..49e366a 100644
--- a/src/gallium/include/pipe/p_context.h
+++ b/src/gallium/include/pipe/p_context.h
@@ -69,33 +69,44 @@ struct pipe_stream_output_target;
 struct pipe_surface;
 struct pipe_transfer;
 struct pipe_vertex_buffer;
 struct pipe_vertex_element;
 struct pipe_video_buffer;
 struct pipe_video_codec;
 struct pipe_viewport_state;
 struct pipe_compute_state;
 union pipe_color_union;
 union pipe_query_result;
+struct u_upload_mgr;
 
 /**
  * Gallium rendering context.  Basically:
  *  - state setting functions
  *  - VBO drawing functions
  *  - surface functions
  */
 struct pipe_context {
    struct pipe_screen *screen;
 
    void *priv;  /**< context private data (for DRI for example) */
    void *draw;  /**< private, for draw module (temporary?) */
 
+   /**
+    * Stream uploaders created by the driver. All drivers, state trackers, and
+    * modules should use them.
+    *
+    * Use u_upload_alloc or u_upload_data as many times as you want.
+    * Once you are done, use u_upload_unmap.
+    */
+   struct u_upload_mgr *stream_uploader; /* everything but shader constants */
+   struct u_upload_mgr *const_uploader;  /* shader constants only */
+
    void (*destroy)( struct pipe_context * );
 
    /**
     * VBO drawing
     */
    /*@{*/
    void (*draw_vbo)( struct pipe_context *pipe,
                      const struct pipe_draw_info *info );
    /*@}*/
 
-- 
2.7.4