summaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
authorMarek Olšák <[email protected]>2016-02-26 21:21:31 +0100
committerMarek Olšák <[email protected]>2016-04-20 12:15:41 +0200
commit6eeb729490a7880f8dc17de855d205a7cce5f28c (patch)
treea78c99678410b8f065eed266482222d33385b05e /include
parent8093990ef4a65c4ba69c79263a508df0ddbecae6 (diff)
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
Diffstat (limited to 'include')
-rw-r--r--include/GL/mesa_glinterop.h287
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 00000000000..814064d8530
--- /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 */