RFC: Cleanup/complete gallium cpu access flags

[José Fonseca-2]

Attached is a minor gallium interface change to the flags used in
texture transfers and buffer maps. It consists of:

- adds a missing flag (unsynchronize bit)

- better documents the semantics of these flags

In the future we should clearly separate the access flags from
texture/buffer usage flags for coherence and clarity. Something to
consider for the next version of gallium.

Jose

[gallium-access-flags.patch]

---

diff --git a/src/gallium/include/pipe/p_defines.h b/src/gallium/include/pipe/p_defines.h
index 6a61aea..4c5c468 100644
--- a/src/gallium/include/pipe/p_defines.h
+++ b/src/gallium/include/pipe/p_defines.h
@@ -225,9 +225,10 @@ enum pipe_transfer_usage {
 };
 
 
-/**
+/*
  * Buffer usage flags
  */
+
 #define PIPE_BUFFER_USAGE_CPU_READ  (1 << 0)
 #define PIPE_BUFFER_USAGE_CPU_WRITE (1 << 1)
 #define PIPE_BUFFER_USAGE_GPU_READ  (1 << 2)
@@ -236,9 +237,59 @@ enum pipe_transfer_usage {
 #define PIPE_BUFFER_USAGE_VERTEX    (1 << 5)
 #define PIPE_BUFFER_USAGE_INDEX     (1 << 6)
 #define PIPE_BUFFER_USAGE_CONSTANT  (1 << 7)
+
+/*
+ * CPU access flags.
+ *
+ * These flags should only be used for texture transfers or when mapping
+ * buffers.
+ *
+ * Note that the PIPE_BUFFER_USAGE_CPU_xxx flags above are also used for
+ * mapping. Either PIPE_BUFFER_USAGE_CPU_READ or PIPE_BUFFER_USAGE_CPU_WRITE
+ * must be set.
+ */
+
+/**
+ * Discards the memory within the mapped region.
+ *
+ * It should not be used with PIPE_BUFFER_USAGE_CPU_READ.
+ *
+ * @sa OpenGL's ARB_map_buffer_range extension, MAP_INVALIDATE_RANGE_BIT flag.
+ * @sa Direct3D's D3DLOCK_DISCARD flag.
+ */
 #define PIPE_BUFFER_USAGE_DISCARD   (1 << 8)
+
+/**
+ * Fail if the resource cannot be mapped immediately.
+ *
+ * @sa Direct3D's D3DLOCK_DONOTWAIT flag.
+ * @sa Mesa3D's MESA_MAP_NOWAIT_BIT flag.
+ * @sa WDDM's D3DDDICB_LOCKFLAGS.DonotWait flag.
+ */
 #define PIPE_BUFFER_USAGE_DONTBLOCK (1 << 9)
-#define PIPE_BUFFER_USAGE_FLUSH_EXPLICIT (1 << 10) /**< See pipe_screen::buffer_flush_mapped_range */
+
+/**
+ * Do not attempt to synchronize pending operations on the resource when mapping.
+ *
+ * It should not be used with PIPE_BUFFER_USAGE_CPU_READ.
+ *
+ * @sa OpenGL's ARB_map_buffer_range extension, MAP_UNSYNCHRONIZED_BIT flag.
+ * @sa Direct3D's D3DLOCK_NOOVERWRITE flag.
+ * @sa WDDM's D3DDDICB_LOCKFLAGS.IgnoreSync flag.
+ */
+#define PIPE_BUFFER_USAGE_UNSYNCHRONIZED (1 << 10)
+
+/**
+ * Written ranges will be notified later with
+ * pipe_screen::buffer_flush_mapped_range.
+ *
+ * It should not be used with PIPE_BUFFER_USAGE_CPU_READ.
+ *
+ * @sa pipe_screen::buffer_flush_mapped_range
+ * @sa OpenGL's ARB_map_buffer_range extension, MAP_FLUSH_EXPLICIT_BIT flag.
+ */
+#define PIPE_BUFFER_USAGE_FLUSH_EXPLICIT (1 << 11)
+
 /** Pipe driver custom usage flags should be greater or equal to this value */
 #define PIPE_BUFFER_USAGE_CUSTOM    (1 << 16)
 
diff --git a/src/mesa/state_tracker/st_cb_bufferobjects.c b/src/mesa/state_tracker/st_cb_bufferobjects.c
index 8e09d0b..63196af 100644
--- a/src/mesa/state_tracker/st_cb_bufferobjects.c
+++ b/src/mesa/state_tracker/st_cb_bufferobjects.c
@@ -239,6 +239,9 @@ st_bufferobj_map_range(GLcontext *ctx, GLenum target,
    if (access & GL_MAP_FLUSH_EXPLICIT_BIT)
       flags |= PIPE_BUFFER_USAGE_FLUSH_EXPLICIT;
   
+   if (access & GL_MAP_UNSYNCHRONIZED_BIT)
+      flags |= PIPE_BUFFER_USAGE_UNSYNCHRONIZED;
+
    /* ... other flags ...
     */
 

---

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now.  http://p.sf.net/sfu/bobj-july
_______________________________________________
Mesa3d-dev mailing list
Mesa3d-dev@...
https://lists.sourceforge.net/lists/listinfo/mesa3d-dev

[Keith Whitwell-3]

On Thu, 2009-11-05 at 05:26 -0800, José Fonseca wrote:

> Attached is a minor gallium interface change to the flags used in
> texture transfers and buffer maps. It consists of:
>
> - adds a missing flag (unsynchronize bit)
>
> - better documents the semantics of these flags
>
> In the future we should clearly separate the access flags from
> texture/buffer usage flags for coherence and clarity. Something to
> consider for the next version of gallium.
>
> Jose

Looks good Jose.  Go ahead and commit when it's convenient.

Keith


------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now.  http://p.sf.net/sfu/bobj-july
_______________________________________________
Mesa3d-dev mailing list
Mesa3d-dev@...
https://lists.sourceforge.net/lists/listinfo/mesa3d-dev