include/GL: add mesa_glinterop.h for OpenGL-OpenCL interop (v4.2)

v2: - use "enum" to define stuff
v3: - more comments, define MESA_GLINTEROP_UNSUPPORTED
v4: - add mesa_glinterop_device_info::interop_version
    - more comments
    - remove #define MESA_GLINTEROP_VERSION
    - use const for "in"
v4.1: - use version numbers for structures
      - add "out_driver_data_written"
v4.2: - buf_offset & buf_size affect GL_ARRAY_BUFFER too, this is required
        for sharing suballocations within a larger buffer

1 files changed, 287 insertions, 0 deletions

diff --git a/include/GL/mesa_glinterop.h b/include/GL/mesa_glinterop.h
new file mode 100644
index 0000000000..814064d853
--- /dev/null
+++ b/include/GL/mesa_glinterop.h
@@ -0,0 +1,287 @@
+/*
+ * Mesa 3-D graphics library
+ *
+ * Copyright 2016 Advanced Micro Devices, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+ * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/* Mesa OpenGL inter-driver interoperability interface designed for but not
+ * limited to OpenCL.
+ *
+ * This is a driver-agnostic, backward-compatible interface. The structures
+ * are only allowed to grow. They can never shrink and their members can
+ * never be removed, renamed, or redefined.
+ *
+ * The interface doesn't return a lot of static texture parameters like
+ * width, height, etc. It mainly returns mutable buffer and texture view
+ * parameters that can't be part of the texture allocation (because they are
+ * mutable). If drivers want to return more data or want to return static
+ * allocation parameters, they can do it in one of these two ways:
+ * - attaching the data to the DMABUF handle in a driver-specific way
+ * - passing the data via "out_driver_data" in the "in" structure.
+ *
+ * Mesa is expected to do a lot of error checking on behalf of OpenCL, such
+ * as checking the target, miplevel, and texture completeness.
+ *
+ * OpenCL, on the other hand, needs to check if the display+context combo
+ * is compatible with the OpenCL driver by querying the device information.
+ * It also needs to check if the texture internal format and channel ordering
+ * (returned in a driver-specific way) is supported by OpenCL, among other
+ * things.
+ */
+
+#ifndef MESA_GLINTEROP_H
+#define MESA_GLINTEROP_H
+
+#include <GL/glx.h>
+#include <EGL/egl.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Returned error codes. */
+enum {
+   MESA_GLINTEROP_SUCCESS = 0,
+   MESA_GLINTEROP_OUT_OF_RESOURCES,
+   MESA_GLINTEROP_OUT_OF_HOST_MEMORY,
+   MESA_GLINTEROP_INVALID_OPERATION,
+   MESA_GLINTEROP_INVALID_VALUE,
+   MESA_GLINTEROP_INVALID_DISPLAY,
+   MESA_GLINTEROP_INVALID_CONTEXT,
+   MESA_GLINTEROP_INVALID_TARGET,
+   MESA_GLINTEROP_INVALID_OBJECT,
+   MESA_GLINTEROP_INVALID_MIP_LEVEL,
+   MESA_GLINTEROP_UNSUPPORTED
+};
+
+/** Access flags. */
+enum {
+   MESA_GLINTEROP_ACCESS_READ_WRITE = 0,
+   MESA_GLINTEROP_ACCESS_READ_ONLY,
+   MESA_GLINTEROP_ACCESS_WRITE_ONLY
+};
+
+#define MESA_GLINTEROP_DEVICE_INFO_VERSION 1
+
+/**
+ * Device information returned by Mesa.
+ */
+typedef struct _mesa_glinterop_device_info {
+   /* The caller should set this to: MESA_GLINTEROP_DEVICE_INFO_VERSION */
+   uint32_t struct_version;
+
+   /* PCI location */
+   uint32_t pci_segment_group;
+   uint32_t pci_bus;
+   uint32_t pci_device;
+   uint32_t pci_function;
+
+   /* Device identification */
+   uint32_t vendor_id;
+   uint32_t device_id;
+
+   /* The interop version determines what behavior the caller should expect
+    * out of all functions.
+    *
+    * Interop version 1:
+    * - mesa_glinterop_export_in is not read beyond "out_driver_data"
+    * - mesa_glinterop_export_out is not written beyond "out_driver_data_written"
+    * - mesa_glinterop_device_info is not written beyond "interop_version"
+    */
+   uint32_t interop_version;
+   /* Structure version 1 ends here. */
+} mesa_glinterop_device_info;
+
+#define MESA_GLINTEROP_EXPORT_IN_VERSION 1
+
+/**
+ * Input parameters to Mesa interop export functions.
+ */
+typedef struct _mesa_glinterop_export_in {
+   /* The caller should set this to: MESA_GLINTEROP_EXPORT_IN_VERSION */
+   uint32_t struct_version;
+
+   /* One of the following:
+    * - GL_TEXTURE_BUFFER
+    * - GL_TEXTURE_1D
+    * - GL_TEXTURE_2D
+    * - GL_TEXTURE_3D
+    * - GL_TEXTURE_RECTANGLE
+    * - GL_TEXTURE_1D_ARRAY
+    * - GL_TEXTURE_2D_ARRAY
+    * - GL_TEXTURE_CUBE_MAP_ARRAY
+    * - GL_TEXTURE_CUBE_MAP
+    * - GL_TEXTURE_CUBE_MAP_POSITIVE_X
+    * - GL_TEXTURE_CUBE_MAP_NEGATIVE_X
+    * - GL_TEXTURE_CUBE_MAP_POSITIVE_Y
+    * - GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
+    * - GL_TEXTURE_CUBE_MAP_POSITIVE_Z
+    * - GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
+    * - GL_TEXTURE_2D_MULTISAMPLE
+    * - GL_TEXTURE_2D_MULTISAMPLE_ARRAY
+    * - GL_TEXTURE_EXTERNAL_OES
+    * - GL_RENDERBUFFER
+    * - GL_ARRAY_BUFFER
+    */
+   GLenum target;
+
+   /* If target is GL_ARRAY_BUFFER, it's a buffer object.
+    * If target is GL_RENDERBUFFER, it's a renderbuffer object.
+    * If target is GL_TEXTURE_*, it's a texture object.
+    */
+   GLuint obj;
+
+   /* Mipmap level. Ignored for non-texture objects. */
+   GLuint miplevel;
+
+   /* One of MESA_GLINTEROP_ACCESS_* flags. This describes how the exported
+    * object is going to be used.
+    */
+   uint32_t access;
+
+   /* Size of memory pointed to by out_driver_data. */
+   uint32_t out_driver_data_size;
+
+   /* If the caller wants to query driver-specific data about the OpenGL
+    * object, this should point to the memory where that data will be stored.
+    * This is expected to be a temporary staging memory. The pointer is not
+    * allowed to be saved for later use by Mesa.
+    */
+   void *out_driver_data;
+   /* Structure version 1 ends here. */
+} mesa_glinterop_export_in;
+
+#define MESA_GLINTEROP_EXPORT_OUT_VERSION 1
+
+/**
+ * Outputs of Mesa interop export functions.
+ */
+typedef struct _mesa_glinterop_export_out {
+   /* The caller should set this to: MESA_GLINTEROP_EXPORT_OUT_VERSION */
+   uint32_t struct_version;
+
+   /* The DMABUF handle. It must be closed by the caller using the POSIX
+    * close() function when it's not needed anymore. Mesa is not responsible
+    * for closing the handle.
+    *
+    * Not closing the handle by the caller will lead to a resource leak,
+    * will prevent releasing the GPU buffer, and may prevent creating new
+    * DMABUF handles within the process.
+    */
+   int dmabuf_fd;
+
+   /* The mutable OpenGL internal format specified by glTextureView or
+    * glTexBuffer. If the object is not one of those, the original internal
+    * format specified by glTexStorage, glTexImage, or glRenderbufferStorage
+    * will be returned.
+    */
+   GLenum internalformat;
+
+   /* Buffer offset and size for GL_ARRAY_BUFFER and GL_TEXTURE_BUFFER.
+    * This allows interop with suballocations (a buffer allocated within
+    * a larger buffer).
+    *
+    * Parameters specified by glTexBufferRange for GL_TEXTURE_BUFFER are
+    * applied to these and can shrink the range further.
+    */
+   GLintptr buf_offset;
+   GLsizeiptr buf_size;
+
+   /* Parameters specified by glTextureView. If the object is not a texture
+    * view, default parameters covering the whole texture will be returned.
+    */
+   GLuint view_minlevel;
+   GLuint view_numlevels;
+   GLuint view_minlayer;
+   GLuint view_numlayers;
+
+   /* The number of bytes written to out_driver_data. */
+   uint32_t out_driver_data_written;
+   /* Structure version 1 ends here. */
+} mesa_glinterop_export_out;
+
+
+/**
+ * Query device information.
+ *
+ * \param dpy        GLX display
+ * \param context    GLX context
+ * \param out        where to return the information
+ *
+ * \return MESA_GLINTEROP_SUCCESS or MESA_GLINTEROP_* != 0 on error
+ */
+GLAPI int GLAPIENTRY
+MesaGLInteropGLXQueryDeviceInfo(Display *dpy, GLXContext context,
+                                mesa_glinterop_device_info *out);
+
+
+/**
+ * Same as MesaGLInteropGLXQueryDeviceInfo except that it accepts EGLDisplay
+ * and EGLContext.
+ */
+GLAPI int GLAPIENTRY
+MesaGLInteropEGLQueryDeviceInfo(EGLDisplay dpy, EGLContext context,
+                                mesa_glinterop_device_info *out);
+
+
+/**
+ * Create and return a DMABUF handle corresponding to the given OpenGL
+ * object, and return other parameters about the OpenGL object.
+ *
+ * \param dpy        GLX display
+ * \param context    GLX context
+ * \param in         input parameters
+ * \param out        return values
+ *
+ * \return MESA_GLINTEROP_SUCCESS or MESA_GLINTEROP_* != 0 on error
+ */
+GLAPI int GLAPIENTRY
+MesaGLInteropGLXExportObject(Display *dpy, GLXContext context,
+                             const mesa_glinterop_export_in *in,
+                             mesa_glinterop_export_out *out);
+
+
+/**
+ * Same as MesaGLInteropGLXExportObject except that it accepts
+ * EGLDisplay and EGLContext.
+ */
+GLAPI int GLAPIENTRY
+MesaGLInteropEGLExportObject(EGLDisplay dpy, EGLContext context,
+                             const mesa_glinterop_export_in *in,
+                             mesa_glinterop_export_out *out);
+
+
+typedef int (APIENTRYP PFNMESAGLINTEROPGLXQUERYDEVICEINFOPROC)(Display *dpy, GLXContext context,
+                                                               mesa_glinterop_device_info *out);
+typedef int (APIENTRYP PFNMESAGLINTEROPEGLQUERYDEVICEINFOPROC)(EGLDisplay dpy, EGLContext context,
+                                                               mesa_glinterop_device_info *out);
+typedef int (APIENTRYP PFNMESAGLINTEROPGLXEXPORTOBJECTPROC)(Display *dpy, GLXContext context,
+                                                            const mesa_glinterop_export_in *in,
+                                                            mesa_glinterop_export_out *out);
+typedef int (APIENTRYP PFNMESAGLINTEROPEGLEXPORTOBJECTPROC)(EGLDisplay dpy, EGLContext context,
+                                                            const mesa_glinterop_export_in *in,
+                                                            mesa_glinterop_export_out *out);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* MESA_GLINTEROP_H */