Debian Codegraph @

third_party/opengl_headers/GL/mesa_glinterop.h

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