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 <stddef.h>
  54 #include <stdint.h>
  55
  56 #ifdef __cplusplus
  57 extern "C" {
  58 #endif
  59
  60 /* Forward declarations to avoid inclusion of GL/glx.h */
  61 #ifndef GLX_H
  62 struct _XDisplay;
  63 struct __GLXcontextRec;
  64 #endif
  65
  66 /* Forward declarations to avoid inclusion of EGL/egl.h */
  67 #ifndef __egl_h_
  68 typedef void *EGLDisplay;
  69 typedef void *EGLContext;
  70 #endif
  71
  72 /** Returned error codes. */
  73 enum {
  74    MESA_GLINTEROP_SUCCESS = 0,
  75    MESA_GLINTEROP_OUT_OF_RESOURCES,
  76    MESA_GLINTEROP_OUT_OF_HOST_MEMORY,
  77    MESA_GLINTEROP_INVALID_OPERATION,
  78    MESA_GLINTEROP_INVALID_VERSION,
  79    MESA_GLINTEROP_INVALID_DISPLAY,
  80    MESA_GLINTEROP_INVALID_CONTEXT,
  81    MESA_GLINTEROP_INVALID_TARGET,
  82    MESA_GLINTEROP_INVALID_OBJECT,
  83    MESA_GLINTEROP_INVALID_MIP_LEVEL,
  84    MESA_GLINTEROP_UNSUPPORTED
  85 };
  86
  87 /** Access flags. */
  88 enum {
  89    MESA_GLINTEROP_ACCESS_READ_WRITE = 0,
  90    MESA_GLINTEROP_ACCESS_READ_ONLY,
  91    MESA_GLINTEROP_ACCESS_WRITE_ONLY
  92 };
  93
  94 #define MESA_GLINTEROP_DEVICE_INFO_VERSION 1
  95
  96 /**
  97  * Device information returned by Mesa.
  98  */
  99 struct mesa_glinterop_device_info {
 100    /* The caller should set this to the version of the struct they support */
 101    /* The callee will overwrite it if it supports a lower version.
 102     *
 103     * The caller should check the value and access up-to the version supported
 104     * by the callee.
 105     */
 106    /* NOTE: Do not use the MESA_GLINTEROP_DEVICE_INFO_VERSION macro */
 107    uint32_t version;
 108
 109    /* PCI location */
 110    uint32_t pci_segment_group;
 111    uint32_t pci_bus;
 112    uint32_t pci_device;
 113    uint32_t pci_function;
 114
 115    /* Device identification */
 116    uint32_t vendor_id;
 117    uint32_t device_id;
 118
 119    /* Structure version 1 ends here. */
 120 };
 121
 122 #define MESA_GLINTEROP_EXPORT_IN_VERSION 1
 123
 124 /**
 125  * Input parameters to Mesa interop export functions.
 126  */
 127 struct mesa_glinterop_export_in {
 128    /* The caller should set this to the version of the struct they support */
 129    /* The callee will overwrite it if it supports a lower version.
 130     *
 131     * The caller should check the value and access up-to the version supported
 132     * by the callee.
 133     */
 134    /* NOTE: Do not use the MESA_GLINTEROP_EXPORT_IN_VERSION macro */
 135    uint32_t version;
 136
 137    /* One of the following:
 138     * - GL_TEXTURE_BUFFER
 139     * - GL_TEXTURE_1D
 140     * - GL_TEXTURE_2D
 141     * - GL_TEXTURE_3D
 142     * - GL_TEXTURE_RECTANGLE
 143     * - GL_TEXTURE_1D_ARRAY
 144     * - GL_TEXTURE_2D_ARRAY
 145     * - GL_TEXTURE_CUBE_MAP_ARRAY
 146     * - GL_TEXTURE_CUBE_MAP
 147     * - GL_TEXTURE_CUBE_MAP_POSITIVE_X
 148     * - GL_TEXTURE_CUBE_MAP_NEGATIVE_X
 149     * - GL_TEXTURE_CUBE_MAP_POSITIVE_Y
 150     * - GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
 151     * - GL_TEXTURE_CUBE_MAP_POSITIVE_Z
 152     * - GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
 153     * - GL_TEXTURE_2D_MULTISAMPLE
 154     * - GL_TEXTURE_2D_MULTISAMPLE_ARRAY
 155     * - GL_TEXTURE_EXTERNAL_OES
 156     * - GL_RENDERBUFFER
 157     * - GL_ARRAY_BUFFER
 158     */
 159    unsigned target;
 160
 161    /* If target is GL_ARRAY_BUFFER, it's a buffer object.
 162     * If target is GL_RENDERBUFFER, it's a renderbuffer object.
 163     * If target is GL_TEXTURE_*, it's a texture object.
 164     */
 165    unsigned obj;
 166
 167    /* Mipmap level. Ignored for non-texture objects. */
 168    unsigned miplevel;
 169
 170    /* One of MESA_GLINTEROP_ACCESS_* flags. This describes how the exported
 171     * object is going to be used.
 172     */
 173    uint32_t access;
 174
 175    /* Size of memory pointed to by out_driver_data. */
 176    uint32_t out_driver_data_size;
 177
 178    /* If the caller wants to query driver-specific data about the OpenGL
 179     * object, this should point to the memory where that data will be stored.
 180     * This is expected to be a temporary staging memory. The pointer is not
 181     * allowed to be saved for later use by Mesa.
 182     */
 183    void *out_driver_data;
 184    /* Structure version 1 ends here. */
 185 };
 186
 187 #define MESA_GLINTEROP_EXPORT_OUT_VERSION 1
 188
 189 /**
 190  * Outputs of Mesa interop export functions.
 191  */
 192 struct mesa_glinterop_export_out {
 193    /* The caller should set this to the version of the struct they support */
 194    /* The callee will overwrite it if it supports a lower version.
 195     *
 196     * The caller should check the value and access up-to the version supported
 197     * by the callee.
 198     */
 199    /* NOTE: Do not use the MESA_GLINTEROP_EXPORT_OUT_VERSION macro */
 200    uint32_t version;
 201
 202    /* The DMABUF handle. It must be closed by the caller using the POSIX
 203     * close() function when it's not needed anymore. Mesa is not responsible
 204     * for closing the handle.
 205     *
 206     * Not closing the handle by the caller will lead to a resource leak,
 207     * will prevent releasing the GPU buffer, and may prevent creating new
 208     * DMABUF handles within the process.
 209     */
 210    int dmabuf_fd;
 211
 212    /* The mutable OpenGL internal format specified by glTextureView or
 213     * glTexBuffer. If the object is not one of those, the original internal
 214     * format specified by glTexStorage, glTexImage, or glRenderbufferStorage
 215     * will be returned.
 216     */
 217    unsigned internal_format;
 218
 219    /* Buffer offset and size for GL_ARRAY_BUFFER and GL_TEXTURE_BUFFER.
 220     * This allows interop with suballocations (a buffer allocated within
 221     * a larger buffer).
 222     *
 223     * Parameters specified by glTexBufferRange for GL_TEXTURE_BUFFER are
 224     * applied to these and can shrink the range further.
 225     */
 226    ptrdiff_t buf_offset;
 227    ptrdiff_t buf_size;
 228
 229    /* Parameters specified by glTextureView. If the object is not a texture
 230     * view, default parameters covering the whole texture will be returned.
 231     */
 232    unsigned view_minlevel;
 233    unsigned view_numlevels;
 234    unsigned view_minlayer;
 235    unsigned view_numlayers;
 236
 237    /* The number of bytes written to out_driver_data. */
 238    uint32_t out_driver_data_written;
 239    /* Structure version 1 ends here. */
 240 };
 241
 242
 243 /**
 244  * Query device information.
 245  *
 246  * \param dpy        GLX display
 247  * \param context    GLX context
 248  * \param out        where to return the information
 249  *
 250  * \return MESA_GLINTEROP_SUCCESS or MESA_GLINTEROP_* != 0 on error
 251  */
 252 int
 253 MesaGLInteropGLXQueryDeviceInfo(struct _XDisplay *dpy, struct __GLXcontextRec *context,
 254                                 struct mesa_glinterop_device_info *out);
 255
 256
 257 /**
 258  * Same as MesaGLInteropGLXQueryDeviceInfo except that it accepts EGLDisplay
 259  * and EGLContext.
 260  */
 261 int
 262 MesaGLInteropEGLQueryDeviceInfo(EGLDisplay dpy, EGLContext context,
 263                                 struct mesa_glinterop_device_info *out);
 264
 265
 266 /**
 267  * Create and return a DMABUF handle corresponding to the given OpenGL
 268  * object, and return other parameters about the OpenGL object.
 269  *
 270  * \param dpy        GLX display
 271  * \param context    GLX context
 272  * \param in         input parameters
 273  * \param out        return values
 274  *
 275  * \return MESA_GLINTEROP_SUCCESS or MESA_GLINTEROP_* != 0 on error
 276  */
 277 int
 278 MesaGLInteropGLXExportObject(struct _XDisplay *dpy, struct __GLXcontextRec *context,
 279                              struct mesa_glinterop_export_in *in,
 280                              struct mesa_glinterop_export_out *out);
 281
 282
 283 /**
 284  * Same as MesaGLInteropGLXExportObject except that it accepts
 285  * EGLDisplay and EGLContext.
 286  */
 287 int
 288 MesaGLInteropEGLExportObject(EGLDisplay dpy, EGLContext context,
 289                              struct mesa_glinterop_export_in *in,
 290                              struct mesa_glinterop_export_out *out);
 291
 292
 293 typedef int (PFNMESAGLINTEROPGLXQUERYDEVICEINFOPROC)(struct _XDisplay *dpy, struct __GLXcontextRec *context,
 294                                                      struct mesa_glinterop_device_info *out);
 295 typedef int (PFNMESAGLINTEROPEGLQUERYDEVICEINFOPROC)(EGLDisplay dpy, EGLContext context,
 296                                                      struct mesa_glinterop_device_info *out);
 297 typedef int (PFNMESAGLINTEROPGLXEXPORTOBJECTPROC)(struct _XDisplay *dpy, struct __GLXcontextRec *context,
 298                                                   struct mesa_glinterop_export_in *in,
 299                                                   struct mesa_glinterop_export_out *out);
 300 typedef int (PFNMESAGLINTEROPEGLEXPORTOBJECTPROC)(EGLDisplay dpy, EGLContext context,
 301                                                   struct mesa_glinterop_export_in *in,
 302                                                   struct mesa_glinterop_export_out *out);
 303
 304 #ifdef __cplusplus
 305 }
 306 #endif
 307
 308 #endif /* MESA_GLINTEROP_H */