[Mesa-dev] [RFC PATCH] include/GL: add mesa_glinterop.h for OpenGL-OpenCL interop

[Marek Olšák]

On Tue, Mar 1, 2016 at 3:29 AM, Michel Dänzer <michel at daenzer.net> wrote:
> On 01.03.2016 03:11, Marek Olšák wrote:
>> From: Marek Olšák <marek.olsak at amd.com>
>
> [...]
>
>> +/**
>> + * Device information returned by Mesa.
>> + */
>> +typedef struct {
>> +   uint32_t size; /* size of this structure */
>> +
>> +   /* 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;
>> +} mesa_glinterop_device_info;
>> +
>> +
>> +/**
>> + * Input parameters to Mesa interop export functions.
>> + */
>> +typedef struct {
>> +   uint32_t size; /* size of this structure */
>> +
>> +   /* 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
>> +    */
>> +   GLenum 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.
>> +    */
>> +   GLuint obj;
>> +
>> +   /* Mipmap level. Ignored for non-texture objects. */
>> +   GLuint 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 dta will be stored.
>
> Typo: "dta"
>
>
>> +    */
>> +   void *out_driver_data;
>> +} mesa_glinterop_export_in;
>> +
>> +
>> +/**
>> + * Outputs of Mesa interop export functions.
>> + */
>> +typedef struct {
>> +   uint32_t size; /* size of this structure */
>> +
>> +   /* The DMABUF handle. It must closed by the caller using the POSIX close()
>> +    * function when it's not needed anymore. Mesa is not responsible for
>> +    * closing the handle.
>> +    */
>> +   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.
>> +    */
>> +   GLenum internalformat;
>> +
>> +   /* Parameters specified by glTexBufferRange for GL_TEXTURE_BUFFER. */
>> +   GLintptr buf_offset;
>> +   GLsizeiptr buf_size;
>> +
>> +   /* Parameters specified by glTextureView. If the object is not a texture
>> +    * view, default parameters covering the whole texture will be returned.
>> +    */
>> +   GLuint view_minlevel;
>> +   GLuint view_numlevels;
>> +   GLuint view_minlayer;
>> +   GLuint view_numlayers;
>> +} 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,
>> +                             mesa_glinterop_export_in *in,
>> +                             mesa_glinterop_export_out *out);
>> +
>> +
>> +/**
>> + * Same as MesaGLInteropGLXExportGLObject except that it accepts
>> + * EGLDisplay and EGLContext.
>> + */
>> +GLAPI int GLAPIENTRY
>> +MesaGLInteropEGLExportObject(EGLDisplay dpy, EGLContext context,
>> +                             mesa_glinterop_export_in *in,
>> +                             mesa_glinterop_export_out *out);
>
> The caller doesn't know how much memory it needs to allocate for the
> *out parameters. Maybe return a pointer to memory allocated by the
> callees instead.

The caller should allocate sizeof(mesa_glinterop_export_out). The
callee won't write beyond that even if the callee has a newer version
of the structure.

>
> Another issue with using only the struct size for ABI purposes is that
> either the structs can only ever grow, or there can be different
> versions of the structs with the same size. Encoding a version instead
> of the struct size avoids this.

Since this is supposed to be a driver-agnostic, backward-compatible
interface, the structs are only allowed to grow. They can never shrink
and they can never remove, rename, or redefine existing members.

I don't expect the structs to be changed. The interface also 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 resource (because they are mutable). If drivers want to
return more data or want to return immutable parameters, they can do
it in one of 2 ways:
- attaching metadata to the DMABUF handle (amdgpu only)
- passing the data via "out_driver_data" in the "in" structure.

Some parameters are accepted only to do error checking (e.g.
miplevel). The expectation is that Mesa will do a lot of error
checking on behalf of OpenCL, such as checking texture completeness.

Hopefully that clears up some things.

Marek