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