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
57extern "C" {
58#endif
59
60/* Forward declarations to avoid inclusion of GL/glx.h */
61#ifndef GLX_H
62struct _XDisplay;
63struct __GLXcontextRec;
64#endif
65
66/* Forward declarations to avoid inclusion of EGL/egl.h */
67#ifndef __egl_h_
68typedef void *EGLDisplay;
69typedef void *EGLContext;
70#endif
71
72/** Returned error codes. */
73enum {
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. */
88enum {
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 */
99struct 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 */
127struct 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 */
192struct 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 */
252int
253MesaGLInteropGLXQueryDeviceInfo(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 */
261int
262MesaGLInteropEGLQueryDeviceInfo(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 */
277int
278MesaGLInteropGLXExportObject(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 */
287int
288MesaGLInteropEGLExportObject(EGLDisplay dpy, EGLContext context,
289                             struct mesa_glinterop_export_in *in,
290                             struct mesa_glinterop_export_out *out);
291
292
293typedef int (PFNMESAGLINTEROPGLXQUERYDEVICEINFOPROC)(struct _XDisplay *dpy, struct __GLXcontextRec *context,
294                                                     struct mesa_glinterop_device_info *out);
295typedef int (PFNMESAGLINTEROPEGLQUERYDEVICEINFOPROC)(EGLDisplay dpy, EGLContext context,
296                                                     struct mesa_glinterop_device_info *out);
297typedef int (PFNMESAGLINTEROPGLXEXPORTOBJECTPROC)(struct _XDisplay *dpy, struct __GLXcontextRec *context,
298                                                  struct mesa_glinterop_export_in *in,
299                                                  struct mesa_glinterop_export_out *out);
300typedef 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