[Mesa-dev] [PATCH 2/3] gallium: define the behavior of PIPE_USAGE_* flags properly

[Brian Paul]

On 02/04/2014 04:26 PM, Marek Olšák wrote:
> From: Marek Olšák <marek.olsak at amd.com>
>
> STATIC will be removed in the following commit.
> ---
>   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 c26f98c..5932e3b 100644
> --- a/src/gallium/docs/source/screen.rst
> +++ b/src/gallium/docs/source/screen.rst
> @@ -343,12 +343,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 after the first upload.

How about "mapped or changed"?  For example, an immutable resource 
probably shouldn't be the dest of a blit.


> +* ``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 52c12df..1c550f8 100644
> --- a/src/gallium/include/pipe/p_defines.h
> +++ b/src/gallium/include/pipe/p_defines.h
> @@ -382,13 +382,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 */
>
>
>   /**
>

Otherwise, the series LGTM.

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