diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index 0ac73402422..e8e80dcbc39 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -567,7 +567,38 @@ by a single pipe_screen and is not shared with another process. (i.e. you shouldn't use it to flush caches explicitly if you want to e.g. use the resource for texturing) +Fences +^^^^^^ +``pipe_fence_handle``, and related methods, are used to synchronize +execution between multiple parties. Examples include CPU <-> GPU synchronization, +renderer <-> windowing system, multiple external APIs, etc. + +A ``pipe_fence_handle`` can either be 'one time use' or 're-usable'. A 'one time use' +fence behaves like a traditional GPU fence. Once it reaches the signaled state it +is forever considered to be signaled. + +Once a re-usable ``pipe_fence_handle`` becomes signaled, it can be reset +back into an unsignaled state. The ``pipe_fence_handle`` will be reset to +the unsignaled state by performing a wait operation on said object, i.e. +``fence_server_sync``. As a corollary to this behaviour, a re-usable +``pipe_fence_handle`` can only have one waiter. + +This behaviour is useful in producer <-> consumer chains. It helps avoid +unecessarily sharing a new ``pipe_fence_handle`` each time a new frame is +ready. Instead, the fences are exchanged once ahead of time, and access is synchronized +through GPU signaling instead of direct producer <-> consumer communication. + +``fence_server_sync`` inserts a wait command into the GPU's command stream. + +``fence_server_signal`` inserts a signal command into the GPU's command stream. + +There are no guarantees that the wait/signal commands will be flushed when +calling ``fence_server_sync`` or ``fence_server_signal``. An explicit +call to ``flush`` is required to make sure the commands are emitted to the GPU. + +The Gallium implementation may implicitly ``flush`` the command stream during a +``fence_server_sync`` or ``fence_server_signal`` call if necessary. Resource Busy Queries ^^^^^^^^^^^^^^^^^^^^^ diff --git a/src/gallium/include/pipe/p_context.h b/src/gallium/include/pipe/p_context.h index 1c7f52cfc59..c3dc5edf57d 100644 --- a/src/gallium/include/pipe/p_context.h +++ b/src/gallium/include/pipe/p_context.h @@ -525,6 +525,12 @@ struct pipe_context { void (*fence_server_sync)(struct pipe_context *pipe, struct pipe_fence_handle *fence); + /** + * Insert commands to have the GPU signal a fence. + */ + void (*fence_server_signal)(struct pipe_context *pipe, + struct pipe_fence_handle *fence); + /** * Create a view on a texture to be used by a shader stage. */