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 #ifndef _WINDEF_
  73 struct HDC__;
  74 typedef struct HDC__ *HDC;
  75 struct HGLRC__;
  76 typedef struct HGLRC__ *HGLRC;
  77 typedef void *HANDLE;
  78 #endif
  79
  80 typedef struct __GLsync *GLsync;
  81
  82 /** Returned error codes. */
  83 enum {
  84    MESA_GLINTEROP_SUCCESS = 0,
  85    MESA_GLINTEROP_OUT_OF_RESOURCES,
  86    MESA_GLINTEROP_OUT_OF_HOST_MEMORY,
  87    MESA_GLINTEROP_INVALID_OPERATION,
  88    MESA_GLINTEROP_INVALID_VERSION,
  89    MESA_GLINTEROP_INVALID_DISPLAY,
  90    MESA_GLINTEROP_INVALID_CONTEXT,
  91    MESA_GLINTEROP_INVALID_TARGET,
  92    MESA_GLINTEROP_INVALID_OBJECT,
  93    MESA_GLINTEROP_INVALID_MIP_LEVEL,
  94    MESA_GLINTEROP_UNSUPPORTED
  95 };
  96
  97 /** Access flags. */
  98 enum {
  99    MESA_GLINTEROP_ACCESS_READ_WRITE = 0,
 100    MESA_GLINTEROP_ACCESS_READ_ONLY,
 101    MESA_GLINTEROP_ACCESS_WRITE_ONLY
 102 };
 103
 104 #define MESA_GLINTEROP_DEVICE_INFO_VERSION 2
 105
 106 /**
 107  * Device information returned by Mesa.
 108  */
 109 struct mesa_glinterop_device_info {
 110    /* The caller should set this to the version of the struct they support */
 111    /* The callee will overwrite it if it supports a lower version.
 112     *
 113     * The caller should check the value and access up-to the version supported
 114     * by the callee.
 115     */
 116    /* NOTE: Do not use the MESA_GLINTEROP_DEVICE_INFO_VERSION macro */
 117    uint32_t version;
 118
 119    /* PCI location */
 120    uint32_t pci_segment_group;
 121    uint32_t pci_bus;
 122    uint32_t pci_device;
 123    uint32_t pci_function;
 124
 125    /* Device identification */
 126    uint32_t vendor_id;
 127    uint32_t device_id;
 128
 129    /* Structure version 1 ends here. */
 130
 131    /* Size of memory pointed to by out_driver_data. */
 132    uint32_t driver_data_size;
 133
 134    /* If the caller wants to query driver-specific data about the OpenGL
 135    * object, this should point to the memory where that data will be stored.
 136    * This is expected to be a temporary staging memory. The pointer is not
 137    * allowed to be saved for later use by Mesa.
 138    */
 139    void *driver_data;
 140
 141    /* Structure version 2 ends here. */
 142 };
 143
 144 #define MESA_GLINTEROP_EXPORT_IN_VERSION 1
 145
 146 /**
 147  * Input parameters to Mesa interop export functions.
 148  */
 149 struct mesa_glinterop_export_in {
 150    /* The caller should set this to the version of the struct they support */
 151    /* The callee will overwrite it if it supports a lower version.
 152     *
 153     * The caller should check the value and access up-to the version supported
 154     * by the callee.
 155     */
 156    /* NOTE: Do not use the MESA_GLINTEROP_EXPORT_IN_VERSION macro */
 157    uint32_t version;
 158
 159    /* One of the following:
 160     * - GL_TEXTURE_BUFFER
 161     * - GL_TEXTURE_1D
 162     * - GL_TEXTURE_2D
 163     * - GL_TEXTURE_3D
 164     * - GL_TEXTURE_RECTANGLE
 165     * - GL_TEXTURE_1D_ARRAY
 166     * - GL_TEXTURE_2D_ARRAY
 167     * - GL_TEXTURE_CUBE_MAP_ARRAY
 168     * - GL_TEXTURE_CUBE_MAP
 169     * - GL_TEXTURE_CUBE_MAP_POSITIVE_X
 170     * - GL_TEXTURE_CUBE_MAP_NEGATIVE_X
 171     * - GL_TEXTURE_CUBE_MAP_POSITIVE_Y
 172     * - GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
 173     * - GL_TEXTURE_CUBE_MAP_POSITIVE_Z
 174     * - GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
 175     * - GL_TEXTURE_2D_MULTISAMPLE
 176     * - GL_TEXTURE_2D_MULTISAMPLE_ARRAY
 177     * - GL_TEXTURE_EXTERNAL_OES
 178     * - GL_RENDERBUFFER
 179     * - GL_ARRAY_BUFFER
 180     */
 181    unsigned target;
 182
 183    /* If target is GL_ARRAY_BUFFER, it's a buffer object.
 184     * If target is GL_RENDERBUFFER, it's a renderbuffer object.
 185     * If target is GL_TEXTURE_*, it's a texture object.
 186     */
 187    unsigned obj;
 188
 189    /* Mipmap level. Ignored for non-texture objects. */
 190    unsigned miplevel;
 191
 192    /* One of MESA_GLINTEROP_ACCESS_* flags. This describes how the exported
 193     * object is going to be used.
 194     */
 195    uint32_t access;
 196
 197    /* Size of memory pointed to by out_driver_data. */
 198    uint32_t out_driver_data_size;
 199
 200    /* If the caller wants to query driver-specific data about the OpenGL
 201     * object, this should point to the memory where that data will be stored.
 202     * This is expected to be a temporary staging memory. The pointer is not
 203     * allowed to be saved for later use by Mesa.
 204     */
 205    void *out_driver_data;
 206    /* Structure version 1 ends here. */
 207 };
 208
 209 #define MESA_GLINTEROP_EXPORT_OUT_VERSION 1
 210
 211 /**
 212  * Outputs of Mesa interop export functions.
 213  */
 214 struct mesa_glinterop_export_out {
 215    /* The caller should set this to the version of the struct they support */
 216    /* The callee will overwrite it if it supports a lower version.
 217     *
 218     * The caller should check the value and access up-to the version supported
 219     * by the callee.
 220     */
 221    /* NOTE: Do not use the MESA_GLINTEROP_EXPORT_OUT_VERSION macro */
 222    uint32_t version;
 223
 224 #ifndef _WIN32
 225    /* The DMABUF handle. It must be closed by the caller using the POSIX
 226     * close() function when it's not needed anymore. Mesa is not responsible
 227     * for closing the handle.
 228     *
 229     * Not closing the handle by the caller will lead to a resource leak,
 230     * will prevent releasing the GPU buffer, and may prevent creating new
 231     * DMABUF handles within the process.
 232     */
 233    int dmabuf_fd;
 234 #else
 235    /* Same concept as a DMABUF, but for Windows/WDDM. It must be closed by
 236     * the caller using CloseHandle() when it's not needed anymore.
 237     */
 238    HANDLE win32_handle;
 239 #endif
 240
 241    /* The mutable OpenGL internal format specified by glTextureView or
 242     * glTexBuffer. If the object is not one of those, the original internal
 243     * format specified by glTexStorage, glTexImage, or glRenderbufferStorage
 244     * will be returned.
 245     */
 246    unsigned internal_format;
 247
 248    /* Buffer offset and size for GL_ARRAY_BUFFER and GL_TEXTURE_BUFFER.
 249     * This allows interop with suballocations (a buffer allocated within
 250     * a larger buffer).
 251     *
 252     * Parameters specified by glTexBufferRange for GL_TEXTURE_BUFFER are
 253     * applied to these and can shrink the range further.
 254     */
 255    ptrdiff_t buf_offset;
 256    ptrdiff_t buf_size;
 257
 258    /* Parameters specified by glTextureView. If the object is not a texture
 259     * view, default parameters covering the whole texture will be returned.
 260     */
 261    unsigned view_minlevel;
 262    unsigned view_numlevels;
 263    unsigned view_minlayer;
 264    unsigned view_numlayers;
 265
 266    /* The number of bytes written to out_driver_data. */
 267    uint32_t out_driver_data_written;
 268    /* Structure version 1 ends here. */
 269 };
 270
 271
 272 /**
 273  * Query device information.
 274  *
 275  * \param dpy        GLX display
 276  * \param context    GLX context
 277  * \param out        where to return the information
 278  *
 279  * \return MESA_GLINTEROP_SUCCESS or MESA_GLINTEROP_* != 0 on error
 280  */
 281 int
 282 MesaGLInteropGLXQueryDeviceInfo(struct _XDisplay *dpy, struct __GLXcontextRec *context,
 283                                 struct mesa_glinterop_device_info *out);
 284
 285
 286 /**
 287  * Same as MesaGLInteropGLXQueryDeviceInfo except that it accepts EGLDisplay
 288  * and EGLContext.
 289  */
 290 int
 291 MesaGLInteropEGLQueryDeviceInfo(EGLDisplay dpy, EGLContext context,
 292                                 struct mesa_glinterop_device_info *out);
 293
 294
 295 /**
 296 * Same as MesaGLInteropGLXQueryDeviceInfo except that it accepts HDC
 297 * and HGLRC.
 298 */
 299 int
 300 wglMesaGLInteropQueryDeviceInfo(HDC dpy, HGLRC context,
 301                                 struct mesa_glinterop_device_info *out);
 302
 303 /**
 304  * Create and return a DMABUF handle corresponding to the given OpenGL
 305  * object, and return other parameters about the OpenGL object.
 306  *
 307  * \param dpy        GLX display
 308  * \param context    GLX context
 309  * \param in         input parameters
 310  * \param out        return values
 311  *
 312  * \return MESA_GLINTEROP_SUCCESS or MESA_GLINTEROP_* != 0 on error
 313  */
 314 int
 315 MesaGLInteropGLXExportObject(struct _XDisplay *dpy, struct __GLXcontextRec *context,
 316                              struct mesa_glinterop_export_in *in,
 317                              struct mesa_glinterop_export_out *out);
 318
 319
 320 /**
 321  * Same as MesaGLInteropGLXExportObject except that it accepts
 322  * EGLDisplay and EGLContext.
 323  */
 324 int
 325 MesaGLInteropEGLExportObject(EGLDisplay dpy, EGLContext context,
 326                              struct mesa_glinterop_export_in *in,
 327                              struct mesa_glinterop_export_out *out);
 328
 329
 330 /**
 331 * Same as MesaGLInteropGLXExportObject except that it accepts
 332 * HDC and HGLRC.
 333 */
 334 int
 335 wglMesaGLInteropExportObject(HDC dpy, HGLRC context,
 336                              struct mesa_glinterop_export_in *in,
 337                              struct mesa_glinterop_export_out *out);
 338
 339
 340 /**
 341  * Prepare OpenGL resources for being accessed by OpenCL.
 342  *
 343  * \param dpy        GLX display
 344  * \param context    GLX context
 345  * \param count      number of resources
 346  * \param resources  resources to flush
 347  * \param sync       optional GLsync to map to CL event
 348  *
 349  * \return MESA_GLINTEROP_SUCCESS or MESA_GLINTEROP_* != 0 on error
 350  */
 351 int
 352 MesaGLInteropGLXFlushObjects(struct _XDisplay *dpy, struct __GLXcontextRec *context,
 353                              unsigned count, struct mesa_glinterop_export_in *resources,
 354                              GLsync *sync);
 355
 356 /**
 357 * Same as MesaGLInteropGLXFlushObjects except that it accepts
 358 * EGLDisplay and EGLContext.
 359 */
 360 int
 361 MesaGLInteropEGLFlushObjects(EGLDisplay dpy, EGLContext context,
 362                              unsigned count, struct mesa_glinterop_export_in *resources,
 363                              GLsync *sync);
 364
 365 /**
 366 * Same as MesaGLInteropGLXFlushObjects except that it accepts
 367 * HDC and HGLRC.
 368 */
 369 int
 370 wglMesaGLInteropFlushObjects(HDC dpy, HGLRC context,
 371                              unsigned count, struct mesa_glinterop_export_in *resources,
 372                              GLsync *sync);
 373
 374
 375 typedef int (PFNMESAGLINTEROPGLXQUERYDEVICEINFOPROC)(struct _XDisplay *dpy, struct __GLXcontextRec *context,
 376                                                      struct mesa_glinterop_device_info *out);
 377 typedef int (PFNMESAGLINTEROPEGLQUERYDEVICEINFOPROC)(EGLDisplay dpy, EGLContext context,
 378                                                      struct mesa_glinterop_device_info *out);
 379 typedef int (PFNWGLMESAGLINTEROPQUERYDEVICEINFOPROC)(HDC dpy, HGLRC context,
 380                                                      struct mesa_glinterop_device_info *out);
 381 typedef int (PFNMESAGLINTEROPGLXEXPORTOBJECTPROC)(struct _XDisplay *dpy, struct __GLXcontextRec *context,
 382                                                   struct mesa_glinterop_export_in *in,
 383                                                   struct mesa_glinterop_export_out *out);
 384 typedef int (PFNMESAGLINTEROPEGLEXPORTOBJECTPROC)(EGLDisplay dpy, EGLContext context,
 385                                                   struct mesa_glinterop_export_in *in,
 386                                                   struct mesa_glinterop_export_out *out);
 387 typedef int (PFNWGLMESAGLINTEROPEXPORTOBJECTPROC)(HDC dpy, HGLRC context,
 388                                                   struct mesa_glinterop_export_in *in,
 389                                                   struct mesa_glinterop_export_out *out);
 390 typedef int (PFNMESAGLINTEROPGLXFLUSHOBJECTSPROC)(struct _XDisplay *dpy, struct __GLXcontextRec *context,
 391                                                   unsigned count, struct mesa_glinterop_export_in *resources,
 392                                                   GLsync *sync);
 393 typedef int (PFNMESAGLINTEROPEGLFLUSHOBJECTSPROC)(EGLDisplay dpy, EGLContext context,
 394                                                   unsigned count, struct mesa_glinterop_export_in *resources,
 395                                                   GLsync *sync);
 396 typedef int (PFNWGLMESAGLINTEROPFLUSHOBJECTSPROC)(HDC dpy, HGLRC context,
 397                                                   unsigned count, struct mesa_glinterop_export_in *resources,
 398                                                   GLsync *sync);
 399
 400 #ifdef __cplusplus
 401 }
 402 #endif
 403
 404 #endif /* MESA_GLINTEROP_H */