Home | History | Annotate | Download | only in GL 
      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 */
    309