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