2 * Mesa 3-D graphics library
4 * Copyright 2016 Advanced Micro Devices, Inc.
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:
13 * The above copyright notice and this permission notice shall be included
14 * in all copies or substantial portions of the Software.
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.
25 /* Mesa OpenGL inter-driver interoperability interface designed for but not
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.
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.
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.
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
50 #ifndef MESA_GLINTEROP_H
51 #define MESA_GLINTEROP_H
60 /* Forward declarations to avoid inclusion of GL/glx.h */
61 typedef struct _XDisplay Display
;
62 typedef struct __GLXcontextRec
*GLXContext
;
64 /* Forward declarations to avoid inclusion of EGL/egl.h */
65 typedef void *EGLDisplay
;
66 typedef void *EGLContext
;
68 /** Returned error codes. */
70 MESA_GLINTEROP_SUCCESS
= 0,
71 MESA_GLINTEROP_OUT_OF_RESOURCES
,
72 MESA_GLINTEROP_OUT_OF_HOST_MEMORY
,
73 MESA_GLINTEROP_INVALID_OPERATION
,
74 MESA_GLINTEROP_INVALID_VERSION
,
75 MESA_GLINTEROP_INVALID_DISPLAY
,
76 MESA_GLINTEROP_INVALID_CONTEXT
,
77 MESA_GLINTEROP_INVALID_TARGET
,
78 MESA_GLINTEROP_INVALID_OBJECT
,
79 MESA_GLINTEROP_INVALID_MIP_LEVEL
,
80 MESA_GLINTEROP_UNSUPPORTED
85 MESA_GLINTEROP_ACCESS_READ_WRITE
= 0,
86 MESA_GLINTEROP_ACCESS_READ_ONLY
,
87 MESA_GLINTEROP_ACCESS_WRITE_ONLY
90 #define MESA_GLINTEROP_DEVICE_INFO_VERSION 1
93 * Device information returned by Mesa.
95 typedef struct _mesa_glinterop_device_info
{
96 /* The caller should set this to the version of the struct they support */
97 /* NOTE: Do not use the MESA_GLINTEROP_DEVICE_INFO_VERSION macro */
101 uint32_t pci_segment_group
;
104 uint32_t pci_function
;
106 /* Device identification */
110 /* The interop version determines what behavior the caller should expect
111 * out of all functions.
114 * - mesa_glinterop_export_in is not read beyond "out_driver_data"
115 * - mesa_glinterop_export_out is not written beyond "out_driver_data_written"
116 * - mesa_glinterop_device_info is not written beyond "interop_version"
118 uint32_t interop_version
;
119 /* Structure version 1 ends here. */
120 } mesa_glinterop_device_info
;
122 #define MESA_GLINTEROP_EXPORT_IN_VERSION 1
125 * Input parameters to Mesa interop export functions.
127 typedef struct _mesa_glinterop_export_in
{
128 /* The caller should set this to the version of the struct they support */
129 /* NOTE: Do not use the MESA_GLINTEROP_EXPORT_IN_VERSION macro */
132 /* One of the following:
133 * - GL_TEXTURE_BUFFER
137 * - GL_TEXTURE_RECTANGLE
138 * - GL_TEXTURE_1D_ARRAY
139 * - GL_TEXTURE_2D_ARRAY
140 * - GL_TEXTURE_CUBE_MAP_ARRAY
141 * - GL_TEXTURE_CUBE_MAP
142 * - GL_TEXTURE_CUBE_MAP_POSITIVE_X
143 * - GL_TEXTURE_CUBE_MAP_NEGATIVE_X
144 * - GL_TEXTURE_CUBE_MAP_POSITIVE_Y
145 * - GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
146 * - GL_TEXTURE_CUBE_MAP_POSITIVE_Z
147 * - GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
148 * - GL_TEXTURE_2D_MULTISAMPLE
149 * - GL_TEXTURE_2D_MULTISAMPLE_ARRAY
150 * - GL_TEXTURE_EXTERNAL_OES
156 /* If target is GL_ARRAY_BUFFER, it's a buffer object.
157 * If target is GL_RENDERBUFFER, it's a renderbuffer object.
158 * If target is GL_TEXTURE_*, it's a texture object.
162 /* Mipmap level. Ignored for non-texture objects. */
165 /* One of MESA_GLINTEROP_ACCESS_* flags. This describes how the exported
166 * object is going to be used.
170 /* Size of memory pointed to by out_driver_data. */
171 uint32_t out_driver_data_size
;
173 /* If the caller wants to query driver-specific data about the OpenGL
174 * object, this should point to the memory where that data will be stored.
175 * This is expected to be a temporary staging memory. The pointer is not
176 * allowed to be saved for later use by Mesa.
178 void *out_driver_data
;
179 /* Structure version 1 ends here. */
180 } mesa_glinterop_export_in
;
182 #define MESA_GLINTEROP_EXPORT_OUT_VERSION 1
185 * Outputs of Mesa interop export functions.
187 typedef struct _mesa_glinterop_export_out
{
188 /* The caller should set this to the version of the struct they support */
189 /* NOTE: Do not use the MESA_GLINTEROP_EXPORT_OUT_VERSION macro */
192 /* The DMABUF handle. It must be closed by the caller using the POSIX
193 * close() function when it's not needed anymore. Mesa is not responsible
194 * for closing the handle.
196 * Not closing the handle by the caller will lead to a resource leak,
197 * will prevent releasing the GPU buffer, and may prevent creating new
198 * DMABUF handles within the process.
202 /* The mutable OpenGL internal format specified by glTextureView or
203 * glTexBuffer. If the object is not one of those, the original internal
204 * format specified by glTexStorage, glTexImage, or glRenderbufferStorage
207 unsigned internal_format
;
209 /* Buffer offset and size for GL_ARRAY_BUFFER and GL_TEXTURE_BUFFER.
210 * This allows interop with suballocations (a buffer allocated within
213 * Parameters specified by glTexBufferRange for GL_TEXTURE_BUFFER are
214 * applied to these and can shrink the range further.
216 ptrdiff_t buf_offset
;
219 /* Parameters specified by glTextureView. If the object is not a texture
220 * view, default parameters covering the whole texture will be returned.
222 unsigned view_minlevel
;
223 unsigned view_numlevels
;
224 unsigned view_minlayer
;
225 unsigned view_numlayers
;
227 /* The number of bytes written to out_driver_data. */
228 uint32_t out_driver_data_written
;
229 /* Structure version 1 ends here. */
230 } mesa_glinterop_export_out
;
234 * Query device information.
236 * \param dpy GLX display
237 * \param context GLX context
238 * \param out where to return the information
240 * \return MESA_GLINTEROP_SUCCESS or MESA_GLINTEROP_* != 0 on error
243 MesaGLInteropGLXQueryDeviceInfo(Display
*dpy
, GLXContext context
,
244 mesa_glinterop_device_info
*out
);
248 * Same as MesaGLInteropGLXQueryDeviceInfo except that it accepts EGLDisplay
252 MesaGLInteropEGLQueryDeviceInfo(EGLDisplay dpy
, EGLContext context
,
253 mesa_glinterop_device_info
*out
);
257 * Create and return a DMABUF handle corresponding to the given OpenGL
258 * object, and return other parameters about the OpenGL object.
260 * \param dpy GLX display
261 * \param context GLX context
262 * \param in input parameters
263 * \param out return values
265 * \return MESA_GLINTEROP_SUCCESS or MESA_GLINTEROP_* != 0 on error
268 MesaGLInteropGLXExportObject(Display
*dpy
, GLXContext context
,
269 const mesa_glinterop_export_in
*in
,
270 mesa_glinterop_export_out
*out
);
274 * Same as MesaGLInteropGLXExportObject except that it accepts
275 * EGLDisplay and EGLContext.
278 MesaGLInteropEGLExportObject(EGLDisplay dpy
, EGLContext context
,
279 const mesa_glinterop_export_in
*in
,
280 mesa_glinterop_export_out
*out
);
283 typedef int (PFNMESAGLINTEROPGLXQUERYDEVICEINFOPROC
)(Display
*dpy
, GLXContext context
,
284 mesa_glinterop_device_info
*out
);
285 typedef int (PFNMESAGLINTEROPEGLQUERYDEVICEINFOPROC
)(EGLDisplay dpy
, EGLContext context
,
286 mesa_glinterop_device_info
*out
);
287 typedef int (PFNMESAGLINTEROPGLXEXPORTOBJECTPROC
)(Display
*dpy
, GLXContext context
,
288 const mesa_glinterop_export_in
*in
,
289 mesa_glinterop_export_out
*out
);
290 typedef int (PFNMESAGLINTEROPEGLEXPORTOBJECTPROC
)(EGLDisplay dpy
, EGLContext context
,
291 const mesa_glinterop_export_in
*in
,
292 mesa_glinterop_export_out
*out
);
298 #endif /* MESA_GLINTEROP_H */