include/GL/mesa_glinterop.h

/*
 * 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 <stddef.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
    */
   unsigned 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.
    */
   unsigned obj;

   /* Mipmap level. Ignored for non-texture objects. */
   unsigned 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.
    */
   unsigned internal_format;

   /* 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.
    */
   ptrdiff_t buf_offset;
   ptrdiff_t buf_size;

   /* Parameters specified by glTextureView. If the object is not a texture
    * view, default parameters covering the whole texture will be returned.
    */
   unsigned view_minlevel;
   unsigned view_numlevels;
   unsigned view_minlayer;
   unsigned 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 */