gallium: add PIPE_FLUSH_ASYNC and PIPE_FLUSH_HINT_FINISH

Also document some subtleties of pipe_context::flush.

Reviewed-by: Marek Olšák <[email protected]>

3 files changed, 18 insertions, 1 deletions

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index ba7fef8301d..81822203728 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -521,6 +521,15 @@ and the context is still unflushed, and the ctx parameter of fence_finish is
 equal to the context where the fence was created, fence_finish will flush
 the context.
 
+PIPE_FLUSH_ASYNC: The flush is allowed to be asynchronous. Unlike
+``PIPE_FLUSH_DEFERRED``, the driver must still ensure that the returned fence
+will finish in finite time. However, subsequent operations in other contexts of
+the same screen are no longer guaranteed to happen after the flush. Drivers
+which use this flag must implement pipe_context::fence_server_sync.
+
+PIPE_FLUSH_HINT_FINISH: Hints to the driver that the caller will immediately
+wait for the returned fence.
+
 
 ``flush_resource``
 
diff --git a/src/gallium/include/pipe/p_context.h b/src/gallium/include/pipe/p_context.h
index 087836d1c0c..d9228e4fc92 100644
--- a/src/gallium/include/pipe/p_context.h
+++ b/src/gallium/include/pipe/p_context.h
@@ -469,7 +469,13 @@ struct pipe_context {
                         int clear_value_size);
 
    /**
-    * Flush draw commands
+    * Flush draw commands.
+    *
+    * This guarantees that the new fence (if any) will finish in finite time,
+    * unless PIPE_FLUSH_DEFERRED is used.
+    *
+    * Subsequent operations on other contexts of the same screen are guaranteed
+    * to execute after the flushed commands, unless PIPE_FLUSH_ASYNC is used.
     *
     * NOTE: use screen->fence_reference() (or equivalent) to transfer
     * new fence ref to **fence, to ensure that previous fence is unref'd
diff --git a/src/gallium/include/pipe/p_defines.h b/src/gallium/include/pipe/p_defines.h
index ddc951464b9..776a879e0a6 100644
--- a/src/gallium/include/pipe/p_defines.h
+++ b/src/gallium/include/pipe/p_defines.h
@@ -352,6 +352,8 @@ enum pipe_flush_flags
    PIPE_FLUSH_END_OF_FRAME = (1 << 0),
    PIPE_FLUSH_DEFERRED = (1 << 1),
    PIPE_FLUSH_FENCE_FD = (1 << 2),
+   PIPE_FLUSH_ASYNC = (1 << 3),
+   PIPE_FLUSH_HINT_FINISH = (1 << 4),
 };
 
 /**