Mesa (master): gallium: document convention for get_handle calls on multi-planar resources

[GitLab Mirror]

Module: Mesa
Branch: master
Commit: 6ec7e0d4066488dd8dbc90ee2f747809be1f1c02
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=6ec7e0d4066488dd8dbc90ee2f747809be1f1c02

Author: Lucas Stach <l.stach at pengutronix.de>
Date:   Sat Oct 31 08:34:28 2020 +0100

gallium: document convention for get_handle calls on multi-planar resources

There are resources that may have more planes than chained resources. The
frontend has no way of figuring out which (if any) chained resource is the
right one to call resource_get_handle with and until a (now reverted)
change to the dri frontend it just always called with the first resource.

The convention of calling with the first resource of a chain allows the
pipe driver, which has the necessary information of how resources and
planes map to each other for a specific format/modifier combination, to do
the necessary walking. Document this as the official calling convention
of this function.

Signed-off-by: Lucas Stach <l.stach at pengutronix.de>
Reviewed-by: Marek Olšák <marek.olsak at amd.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/7419>

---

 src/gallium/include/pipe/p_screen.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/gallium/include/pipe/p_screen.h b/src/gallium/include/pipe/p_screen.h
index 53a192b6349..d52dbd7e5c6 100644
--- a/src/gallium/include/pipe/p_screen.h
+++ b/src/gallium/include/pipe/p_screen.h
@@ -250,6 +250,12 @@ struct pipe_screen {
     * the resource into a format compatible for sharing. The use case is
     * OpenGL-OpenCL interop. The context parameter is allowed to be NULL.
     *
+    * NOTE: for multi-planar resources (which may or may not have the planes
+    * chained through the pipe_resource next pointer) the frontend will
+    * always call this function with the first resource of the chain. It is
+    * the pipe drivers responsibility to walk the resources as needed when
+    * called with handle->plane != 0.
+    *
     * NOTE: in the case of WINSYS_HANDLE_TYPE_FD handles, the caller
     * takes ownership of the FD.  (This is consistent with
     * EGL_MESA_image_dma_buf_export)