gallium-docs: Add documentation for when using several contexts
Add documentation to explicit what can be expected and what is allowed
when using several contexts.
Signed-off-by: Axel Davy <axel.davy@ens.fr>
Reviewed-by: Marek Olšák <marek.olsak@amd.com>
diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index e190cef..35f51a0 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -707,3 +707,26 @@
since the last call or since the last notification by callback.
* ``set_device_reset_callback`` sets a callback which will be called when
a device reset is detected. The callback is only called synchronously.
+
+Using several contexts
+----------------------
+
+Several contexts from the same screen can be used at the same time. Objects
+created on one context cannot be used in another context, but the objects
+created by the screen methods can be used by all contexts.
+
+Transfers
+^^^^^^^^^
+A transfer on one context is not expected to synchronize properly with
+rendering on other contexts, thus only areas not yet used for rendering should
+be locked.
+
+A flush is required after transfer_unmap to expect other contexts to see the
+uploaded data, unless:
+
+* Using persistent mapping. Associated with coherent mapping, unmapping the
+ resource is also not required to use it in other contexts. Without coherent
+ mapping, memory_barrier(PIPE_BARRIER_MAPPED_BUFFER) should be called on the
+ context that has mapped the resource. No flush is required.
+
+* Mapping the resource with PIPE_TRANSFER_MAP_DIRECTLY.
