Mesa (master): gallium: define the behavior of PIPE_USAGE_* flags properly

[Marek Olšák]

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

Author: Marek Olšák <marek.olsak at amd.com>
Date:   Mon Feb  3 03:21:29 2014 +0100

gallium: define the behavior of PIPE_USAGE_* flags properly

STATIC will be removed in the following commit.

v2: changed the definition of IMMUTABLE

Reviewed-by: Brian Paul <brianp at vmware.com>

---

 src/gallium/docs/source/screen.rst   |   18 ++++++++++++------
 src/gallium/include/pipe/p_defines.h |   13 +++++++------
 2 files changed, 19 insertions(+), 12 deletions(-)

diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst
index ed8e832..0c9c274 100644
--- a/src/gallium/docs/source/screen.rst
+++ b/src/gallium/docs/source/screen.rst
@@ -340,12 +340,18 @@ PIPE_USAGE_*
 ^^^^^^^^^^^^
 
 The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
-
-* ``PIPE_USAGE_DEFAULT``: Expect many uploads to the resource, intermixed with draws.
-* ``PIPE_USAGE_DYNAMIC``: Expect many uploads to the resource, intermixed with draws.
-* ``PIPE_USAGE_STATIC``: Same as immutable (?)
-* ``PIPE_USAGE_IMMUTABLE``: Resource will not be changed after first upload.
-* ``PIPE_USAGE_STREAM``: Upload will be followed by draw, followed by upload, ...
+Note that drivers must always support read and write CPU access at any time
+no matter which hint they got.
+
+* ``PIPE_USAGE_DEFAULT``: Optimized for fast GPU access.
+* ``PIPE_USAGE_IMMUTABLE``: Optimized for fast GPU access and the resource is
+  not expected to be mapped or changed (even by the GPU) after the first upload.
+* ``PIPE_USAGE_DYNAMIC``: Expect frequent write-only CPU access. What is
+  uploaded is expected to be used at least several times by the GPU.
+* ``PIPE_USAGE_STATIC``: Same as PIPE_USAGE_DEFAULT.
+* ``PIPE_USAGE_STREAM``: Expect frequent write-only CPU access. What is
+  uploaded is expected to be used only once by the GPU.
+* ``PIPE_USAGE_STAGING``: Optimized for fast CPU access.
 
 
 Methods
diff --git a/src/gallium/include/pipe/p_defines.h b/src/gallium/include/pipe/p_defines.h
index 183726c..8538538 100644
--- a/src/gallium/include/pipe/p_defines.h
+++ b/src/gallium/include/pipe/p_defines.h
@@ -356,13 +356,14 @@ enum pipe_flush_flags {
 #define PIPE_RESOURCE_FLAG_ST_PRIV     (1 << 24) /* state-tracker/winsys private */
 
 /* Hint about the expected lifecycle of a resource.
+ * Sorted according to GPU vs CPU access.
  */
-#define PIPE_USAGE_DEFAULT        0 /* many uploads, draws intermixed */
-#define PIPE_USAGE_DYNAMIC        1 /* many uploads, draws intermixed */
-#define PIPE_USAGE_STATIC         2 /* same as immutable?? */
-#define PIPE_USAGE_IMMUTABLE      3 /* no change after first upload */
-#define PIPE_USAGE_STREAM         4 /* upload, draw, upload, draw */
-#define PIPE_USAGE_STAGING        5 /* supports data transfers from the GPU to the CPU */
+#define PIPE_USAGE_DEFAULT        0 /* fast GPU access */
+#define PIPE_USAGE_IMMUTABLE      1 /* fast GPU access, immutable */
+#define PIPE_USAGE_DYNAMIC        2 /* uploaded data is used multiple times */
+#define PIPE_USAGE_STREAM         3 /* uploaded data is used once */
+#define PIPE_USAGE_STAGING        4 /* fast CPU access */
+#define PIPE_USAGE_STATIC         5 /* same as DEFAULT, will be removed */
 
 
 /**