include/GL/mesa_glinterop.h

   1 /*
   2  * Mesa 3-D graphics library
   3  *
   4  * Copyright 2016 Advanced Micro Devices, Inc.
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a
   7  * copy of this software and associated documentation files (the "Software"),
   8  * to deal in the Software without restriction, including without limitation
   9  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  10  * and/or sell copies of the Software, and to permit persons to whom the
  11  * Software is furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included
  14  * in all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  17  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  19  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
  20  * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  21  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  22  * OTHER DEALINGS IN THE SOFTWARE.
  23  */
  24
  25 /* Mesa OpenGL inter-driver interoperability interface designed for but not
  26  * limited to OpenCL.
  27  *
  28  * This is a driver-agnostic, backward-compatible interface. The structures
  29  * are only allowed to grow. They can never shrink and their members can
  30  * never be removed, renamed, or redefined.
  31  *
  32  * The interface doesn't return a lot of static texture parameters like
  33  * width, height, etc. It mainly returns mutable buffer and texture view
  34  * parameters that can't be part of the texture allocation (because they are
  35  * mutable). If drivers want to return more data or want to return static
  36  * allocation parameters, they can do it in one of these two ways:
  37  * - attaching the data to the DMABUF handle in a driver-specific way
  38  * - passing the data via "out_driver_data" in the "in" structure.
  39  *
  40  * Mesa is expected to do a lot of error checking on behalf of OpenCL, such
  41  * as checking the target, miplevel, and texture completeness.
  42  *
  43  * OpenCL, on the other hand, needs to check if the display+context combo
  44  * is compatible with the OpenCL driver by querying the device information.
  45  * It also needs to check if the texture internal format and channel ordering
  46  * (returned in a driver-specific way) is supported by OpenCL, among other
  47  * things.
  48  */
  49
  50 #ifndef MESA_GLINTEROP_H
  51 #define MESA_GLINTEROP_H
  52
  53 #include <GL/glx.h>
  54 #include <EGL/egl.h>
  55
  56 #ifdef __cplusplus
  57 extern "C" {
  58 #endif
  59
  60 /** Returned error codes. */
  61 enum {
  62    MESA_GLINTEROP_SUCCESS = 0,
  63    MESA_GLINTEROP_OUT_OF_RESOURCES,
  64    MESA_GLINTEROP_OUT_OF_HOST_MEMORY,
  65    MESA_GLINTEROP_INVALID_OPERATION,
  66    MESA_GLINTEROP_INVALID_VALUE,
  67    MESA_GLINTEROP_INVALID_DISPLAY,
  68    MESA_GLINTEROP_INVALID_CONTEXT,
  69    MESA_GLINTEROP_INVALID_TARGET,
  70    MESA_GLINTEROP_INVALID_OBJECT,
  71    MESA_GLINTEROP_INVALID_MIP_LEVEL,
  72    MESA_GLINTEROP_UNSUPPORTED
  73 };
  74
  75 /** Access flags. */
  76 enum {
  77    MESA_GLINTEROP_ACCESS_READ_WRITE = 0,
  78    MESA_GLINTEROP_ACCESS_READ_ONLY,
  79    MESA_GLINTEROP_ACCESS_WRITE_ONLY
  80 };
  81
  82 #define MESA_GLINTEROP_DEVICE_INFO_VERSION 1
  83
  84 /**
  85  * Device information returned by Mesa.
  86  */
  87 typedef struct _mesa_glinterop_device_info {
  88    /* The caller should set this to: MESA_GLINTEROP_DEVICE_INFO_VERSION */
  89    uint32_t struct_version;
  90
  91    /* PCI location */
  92    uint32_t pci_segment_group;
  93    uint32_t pci_bus;
  94    uint32_t pci_device;
  95    uint32_t pci_function;
  96
  97    /* Device identification */
  98    uint32_t vendor_id;
  99    uint32_t device_id;
 100
 101    /* The interop version determines what behavior the caller should expect
 102     * out of all functions.
 103     *
 104     * Interop version 1:
 105     * - mesa_glinterop_export_in is not read beyond "out_driver_data"
 106     * - mesa_glinterop_export_out is not written beyond "out_driver_data_written"
 107     * - mesa_glinterop_device_info is not written beyond "interop_version"
 108     */
 109    uint32_t interop_version;
 110    /* Structure version 1 ends here. */
 111 } mesa_glinterop_device_info;
 112
 113 #define MESA_GLINTEROP_EXPORT_IN_VERSION 1
 114
 115 /**
 116  * Input parameters to Mesa interop export functions.
 117  */
 118 typedef struct _mesa_glinterop_export_in {
 119    /* The caller should set this to: MESA_GLINTEROP_EXPORT_IN_VERSION */
 120    uint32_t struct_version;
 121
 122    /* One of the following:
 123     * - GL_TEXTURE_BUFFER
 124     * - GL_TEXTURE_1D
 125     * - GL_TEXTURE_2D
 126     * - GL_TEXTURE_3D
 127     * - GL_TEXTURE_RECTANGLE
 128     * - GL_TEXTURE_1D_ARRAY
 129     * - GL_TEXTURE_2D_ARRAY
 130     * - GL_TEXTURE_CUBE_MAP_ARRAY
 131     * - GL_TEXTURE_CUBE_MAP
 132     * - GL_TEXTURE_CUBE_MAP_POSITIVE_X
 133     * - GL_TEXTURE_CUBE_MAP_NEGATIVE_X
 134     * - GL_TEXTURE_CUBE_MAP_POSITIVE_Y
 135     * - GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
 136     * - GL_TEXTURE_CUBE_MAP_POSITIVE_Z
 137     * - GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
 138     * - GL_TEXTURE_2D_MULTISAMPLE
 139     * - GL_TEXTURE_2D_MULTISAMPLE_ARRAY
 140     * - GL_TEXTURE_EXTERNAL_OES
 141     * - GL_RENDERBUFFER
 142     * - GL_ARRAY_BUFFER
 143     */
 144    GLenum target;
 145
 146    /* If target is GL_ARRAY_BUFFER, it's a buffer object.
 147     * If target is GL_RENDERBUFFER, it's a renderbuffer object.
 148     * If target is GL_TEXTURE_*, it's a texture object.
 149     */
 150    GLuint obj;
 151
 152    /* Mipmap level. Ignored for non-texture objects. */
 153    GLuint miplevel;
 154
 155    /* One of MESA_GLINTEROP_ACCESS_* flags. This describes how the exported
 156     * object is going to be used.
 157     */
 158    uint32_t access;
 159
 160    /* Size of memory pointed to by out_driver_data. */
 161    uint32_t out_driver_data_size;
 162
 163    /* If the caller wants to query driver-specific data about the OpenGL
 164     * object, this should point to the memory where that data will be stored.
 165     * This is expected to be a temporary staging memory. The pointer is not
 166     * allowed to be saved for later use by Mesa.
 167     */
 168    void *out_driver_data;
 169    /* Structure version 1 ends here. */
 170 } mesa_glinterop_export_in;
 171
 172 #define MESA_GLINTEROP_EXPORT_OUT_VERSION 1
 173
 174 /**
 175  * Outputs of Mesa interop export functions.
 176  */
 177 typedef struct _mesa_glinterop_export_out {
 178    /* The caller should set this to: MESA_GLINTEROP_EXPORT_OUT_VERSION */
 179    uint32_t struct_version;
 180
 181    /* The DMABUF handle. It must be closed by the caller using the POSIX
 182     * close() function when it's not needed anymore. Mesa is not responsible
 183     * for closing the handle.
 184     *
 185     * Not closing the handle by the caller will lead to a resource leak,
 186     * will prevent releasing the GPU buffer, and may prevent creating new
 187     * DMABUF handles within the process.
 188     */
 189    int dmabuf_fd;
 190
 191    /* The mutable OpenGL internal format specified by glTextureView or
 192     * glTexBuffer. If the object is not one of those, the original internal
 193     * format specified by glTexStorage, glTexImage, or glRenderbufferStorage
 194     * will be returned.
 195     */
 196    GLenum internalformat;
 197
 198    /* Buffer offset and size for GL_ARRAY_BUFFER and GL_TEXTURE_BUFFER.
 199     * This allows interop with suballocations (a buffer allocated within
 200     * a larger buffer).
 201     *
 202     * Parameters specified by glTexBufferRange for GL_TEXTURE_BUFFER are
 203     * applied to these and can shrink the range further.
 204     */
 205    GLintptr buf_offset;
 206    GLsizeiptr buf_size;
 207
 208    /* Parameters specified by glTextureView. If the object is not a texture
 209     * view, default parameters covering the whole texture will be returned.
 210     */
 211    GLuint view_minlevel;
 212    GLuint view_numlevels;
 213    GLuint view_minlayer;
 214    GLuint view_numlayers;
 215
 216    /* The number of bytes written to out_driver_data. */
 217    uint32_t out_driver_data_written;
 218    /* Structure version 1 ends here. */
 219 } mesa_glinterop_export_out;
 220
 221
 222 /**
 223  * Query device information.
 224  *
 225  * \param dpy        GLX display
 226  * \param context    GLX context
 227  * \param out        where to return the information
 228  *
 229  * \return MESA_GLINTEROP_SUCCESS or MESA_GLINTEROP_* != 0 on error
 230  */
 231 GLAPI int GLAPIENTRY
 232 MesaGLInteropGLXQueryDeviceInfo(Display *dpy, GLXContext context,
 233                                 mesa_glinterop_device_info *out);
 234
 235
 236 /**
 237  * Same as MesaGLInteropGLXQueryDeviceInfo except that it accepts EGLDisplay
 238  * and EGLContext.
 239  */
 240 GLAPI int GLAPIENTRY
 241 MesaGLInteropEGLQueryDeviceInfo(EGLDisplay dpy, EGLContext context,
 242                                 mesa_glinterop_device_info *out);
 243
 244
 245 /**
 246  * Create and return a DMABUF handle corresponding to the given OpenGL
 247  * object, and return other parameters about the OpenGL object.
 248  *
 249  * \param dpy        GLX display
 250  * \param context    GLX context
 251  * \param in         input parameters
 252  * \param out        return values
 253  *
 254  * \return MESA_GLINTEROP_SUCCESS or MESA_GLINTEROP_* != 0 on error
 255  */
 256 GLAPI int GLAPIENTRY
 257 MesaGLInteropGLXExportObject(Display *dpy, GLXContext context,
 258                              const mesa_glinterop_export_in *in,
 259                              mesa_glinterop_export_out *out);
 260
 261
 262 /**
 263  * Same as MesaGLInteropGLXExportObject except that it accepts
 264  * EGLDisplay and EGLContext.
 265  */
 266 GLAPI int GLAPIENTRY
 267 MesaGLInteropEGLExportObject(EGLDisplay dpy, EGLContext context,
 268                              const mesa_glinterop_export_in *in,
 269                              mesa_glinterop_export_out *out);
 270
 271
 272 typedef int (APIENTRYP PFNMESAGLINTEROPGLXQUERYDEVICEINFOPROC)(Display *dpy, GLXContext context,
 273                                                                mesa_glinterop_device_info *out);
 274 typedef int (APIENTRYP PFNMESAGLINTEROPEGLQUERYDEVICEINFOPROC)(EGLDisplay dpy, EGLContext context,
 275                                                                mesa_glinterop_device_info *out);
 276 typedef int (APIENTRYP PFNMESAGLINTEROPGLXEXPORTOBJECTPROC)(Display *dpy, GLXContext context,
 277                                                             const mesa_glinterop_export_in *in,
 278                                                             mesa_glinterop_export_out *out);
 279 typedef int (APIENTRYP PFNMESAGLINTEROPEGLEXPORTOBJECTPROC)(EGLDisplay dpy, EGLContext context,
 280                                                             const mesa_glinterop_export_in *in,
 281                                                             mesa_glinterop_export_out *out);
 282
 283 #ifdef __cplusplus
 284 }
 285 #endif
 286
 287 #endif /* MESA_GLINTEROP_H */