1 /* 2 * Copyright 1998-1999 Precision Insight, Inc., Cedar Park, Texas. 3 * Copyright 2007-2008 Red Hat, Inc. 4 * (C) Copyright IBM Corporation 2004 5 * All Rights Reserved. 6 * 7 * Permission is hereby granted, free of charge, to any person obtaining a 8 * copy of this software and associated documentation files (the "Software"), 9 * to deal in the Software without restriction, including without limitation 10 * on the rights to use, copy, modify, merge, publish, distribute, sub 11 * license, and/or sell copies of the Software, and to permit persons to whom 12 * the Software is furnished to do so, subject to the following conditions: 13 * 14 * The above copyright notice and this permission notice (including the next 15 * paragraph) shall be included in all copies or substantial portions of the 16 * Software. 17 * 18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 20 * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL 21 * THE COPYRIGHT HOLDERS AND/OR THEIR SUPPLIERS BE LIABLE FOR ANY CLAIM, 22 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR 23 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE 24 * USE OR OTHER DEALINGS IN THE SOFTWARE. 25 */ 26 27 /** 28 * \file dri_interface.h 29 * 30 * This file contains all the types and functions that define the interface 31 * between a DRI driver and driver loader. Currently, the most common driver 32 * loader is the XFree86 libGL.so. However, other loaders do exist, and in 33 * the future the server-side libglx.a will also be a loader. 34 * 35 * \author Kevin E. Martin <[email protected]> 36 * \author Ian Romanick <[email protected]> 37 * \author Kristian Høgsberg <[email protected]> 38 */ 39 40 #ifndef DRI_INTERFACE_H 41 #define DRI_INTERFACE_H 42 43 #include <stdbool.h> 44 #include <stdint.h> 45 46 /** 47 * \name DRI interface structures 48 * 49 * The following structures define the interface between the GLX client 50 * side library and the DRI (direct rendering infrastructure). 51 */ 52 /*@{*/ 53 typedef struct __DRIdisplayRec __DRIdisplay; 54 typedef struct __DRIscreenRec __DRIscreen; 55 typedef struct __DRIcontextRec __DRIcontext; 56 typedef struct __DRIdrawableRec __DRIdrawable; 57 typedef struct __DRIconfigRec __DRIconfig; 58 typedef struct __DRIframebufferRec __DRIframebuffer; 59 typedef struct __DRIversionRec __DRIversion; 60 61 typedef struct __DRIcoreExtensionRec __DRIcoreExtension; 62 typedef struct __DRIextensionRec __DRIextension; 63 typedef struct __DRIcopySubBufferExtensionRec __DRIcopySubBufferExtension; 64 typedef struct __DRIswapControlExtensionRec __DRIswapControlExtension; 65 typedef struct __DRIframeTrackingExtensionRec __DRIframeTrackingExtension; 66 typedef struct __DRImediaStreamCounterExtensionRec __DRImediaStreamCounterExtension; 67 typedef struct __DRItexOffsetExtensionRec __DRItexOffsetExtension; 68 typedef struct __DRItexBufferExtensionRec __DRItexBufferExtension; 69 typedef struct __DRIlegacyExtensionRec __DRIlegacyExtension; /* DRI1, structures of which have been deleted from the tree */ 70 typedef struct __DRIswrastExtensionRec __DRIswrastExtension; 71 typedef struct __DRIbufferRec __DRIbuffer; 72 typedef struct __DRIdri2ExtensionRec __DRIdri2Extension; 73 typedef struct __DRIdri2LoaderExtensionRec __DRIdri2LoaderExtension; 74 typedef struct __DRI2flushExtensionRec __DRI2flushExtension; 75 typedef struct __DRI2throttleExtensionRec __DRI2throttleExtension; 76 typedef struct __DRI2fenceExtensionRec __DRI2fenceExtension; 77 typedef struct __DRI2interopExtensionRec __DRI2interopExtension; 78 typedef struct __DRI2blobExtensionRec __DRI2blobExtension; 79 typedef struct __DRI2bufferDamageExtensionRec __DRI2bufferDamageExtension; 80 81 typedef struct __DRIimageLoaderExtensionRec __DRIimageLoaderExtension; 82 typedef struct __DRIimageDriverExtensionRec __DRIimageDriverExtension; 83 84 /*@}*/ 85 86 87 /** 88 * Extension struct. Drivers 'inherit' from this struct by embedding 89 * it as the first element in the extension struct. 90 * 91 * We never break API in for a DRI extension. If we need to change 92 * the way things work in a non-backwards compatible manner, we 93 * introduce a new extension. During a transition period, we can 94 * leave both the old and the new extension in the driver, which 95 * allows us to move to the new interface without having to update the 96 * loader(s) in lock step. 97 * 98 * However, we can add entry points to an extension over time as long 99 * as we don't break the old ones. As we add entry points to an 100 * extension, we increase the version number. The corresponding 101 * #define can be used to guard code that accesses the new entry 102 * points at compile time and the version field in the extension 103 * struct can be used at run-time to determine how to use the 104 * extension. 105 */ 106 struct __DRIextensionRec { 107 const char *name; 108 int version; 109 }; 110 111 /** 112 * The first set of extension are the screen extensions, returned by 113 * __DRIcore::getExtensions(). This entry point will return a list of 114 * extensions and the loader can use the ones it knows about by 115 * casting them to more specific extensions and advertising any GLX 116 * extensions the DRI extensions enables. 117 */ 118 119 /** 120 * Used by drivers to indicate support for setting the read drawable. 121 */ 122 #define __DRI_READ_DRAWABLE "DRI_ReadDrawable" 123 #define __DRI_READ_DRAWABLE_VERSION 1 124 125 /** 126 * Used by drivers that implement the GLX_MESA_copy_sub_buffer extension. 127 * 128 * Used by the X server in swrast mode. 129 */ 130 #define __DRI_COPY_SUB_BUFFER "DRI_CopySubBuffer" 131 #define __DRI_COPY_SUB_BUFFER_VERSION 1 132 struct __DRIcopySubBufferExtensionRec { 133 __DRIextension base; 134 void (*copySubBuffer)(__DRIdrawable *drawable, int x, int y, int w, int h); 135 }; 136 137 /** 138 * Used by drivers that implement the GLX_SGI_swap_control or 139 * GLX_MESA_swap_control extension. 140 * 141 * Used by the X server. 142 */ 143 #define __DRI_SWAP_CONTROL "DRI_SwapControl" 144 #define __DRI_SWAP_CONTROL_VERSION 1 145 struct __DRIswapControlExtensionRec { 146 __DRIextension base; 147 void (*setSwapInterval)(__DRIdrawable *drawable, unsigned int inteval); 148 unsigned int (*getSwapInterval)(__DRIdrawable *drawable); 149 }; 150 151 /** 152 * Used by drivers that implement the GLX_SGI_video_sync extension. 153 * 154 * Not used by the X server. 155 */ 156 #define __DRI_MEDIA_STREAM_COUNTER "DRI_MediaStreamCounter" 157 #define __DRI_MEDIA_STREAM_COUNTER_VERSION 1 158 struct __DRImediaStreamCounterExtensionRec { 159 __DRIextension base; 160 161 /** 162 * Wait for the MSC to equal target_msc, or, if that has already passed, 163 * the next time (MSC % divisor) is equal to remainder. If divisor is 164 * zero, the function will return as soon as MSC is greater than or equal 165 * to target_msc. 166 */ 167 int (*waitForMSC)(__DRIdrawable *drawable, 168 int64_t target_msc, int64_t divisor, int64_t remainder, 169 int64_t * msc, int64_t * sbc); 170 171 /** 172 * Get the number of vertical refreshes since some point in time before 173 * this function was first called (i.e., system start up). 174 */ 175 int (*getDrawableMSC)(__DRIscreen *screen, __DRIdrawable *drawable, 176 int64_t *msc); 177 }; 178 179 /* Valid values for format in the setTexBuffer2 function below. These 180 * values match the GLX tokens for compatibility reasons, but we 181 * define them here since the DRI interface can't depend on GLX. */ 182 #define __DRI_TEXTURE_FORMAT_NONE 0x20D8 183 #define __DRI_TEXTURE_FORMAT_RGB 0x20D9 184 #define __DRI_TEXTURE_FORMAT_RGBA 0x20DA 185 186 #define __DRI_TEX_BUFFER "DRI_TexBuffer" 187 #define __DRI_TEX_BUFFER_VERSION 3 188 struct __DRItexBufferExtensionRec { 189 __DRIextension base; 190 191 /** 192 * Method to override base texture image with the contents of a 193 * __DRIdrawable. 194 * 195 * For GLX_EXT_texture_from_pixmap with AIGLX. Deprecated in favor of 196 * setTexBuffer2 in version 2 of this interface. Not used by post-2011 X. 197 */ 198 void (*setTexBuffer)(__DRIcontext *pDRICtx, 199 int target, 200 __DRIdrawable *pDraw); 201 202 /** 203 * Method to override base texture image with the contents of a 204 * __DRIdrawable, including the required texture format attribute. 205 * 206 * For GLX_EXT_texture_from_pixmap with AIGLX. Used by the X server since 207 * 2011. 208 * 209 * \since 2 210 */ 211 void (*setTexBuffer2)(__DRIcontext *pDRICtx, 212 int target, 213 int format, 214 __DRIdrawable *pDraw); 215 /** 216 * Called from glXReleaseTexImageEXT(). 217 * 218 * This was used by i965 in 24952160fde9 ("i965: Use finish_external instead 219 * of make_shareable in setTexBuffer2") to note when the user mis-used the 220 * interface in a way that would produce rendering bugs, and try to recover 221 * from them. This has only ever been used from inside the Mesa tree and 222 * was never used by the X server. 223 * 224 * \since 3 225 */ 226 void (*releaseTexBuffer)(__DRIcontext *pDRICtx, 227 int target, 228 __DRIdrawable *pDraw); 229 }; 230 231 /** 232 * Used by drivers that implement DRI2. Version 3 is used by the X server. 233 */ 234 #define __DRI2_FLUSH "DRI2_Flush" 235 #define __DRI2_FLUSH_VERSION 4 236 237 #define __DRI2_FLUSH_DRAWABLE (1 << 0) /* the drawable should be flushed. */ 238 #define __DRI2_FLUSH_CONTEXT (1 << 1) /* glFlush should be called */ 239 #define __DRI2_FLUSH_INVALIDATE_ANCILLARY (1 << 2) 240 241 enum __DRI2throttleReason { 242 __DRI2_THROTTLE_SWAPBUFFER, 243 __DRI2_THROTTLE_COPYSUBBUFFER, 244 __DRI2_THROTTLE_FLUSHFRONT, 245 __DRI2_NOTHROTTLE_SWAPBUFFER, 246 }; 247 248 struct __DRI2flushExtensionRec { 249 __DRIextension base; 250 void (*flush)(__DRIdrawable *drawable); 251 252 /** 253 * Ask the driver to call getBuffers/getBuffersWithFormat before 254 * it starts rendering again. 255 * 256 * \param drawable the drawable to invalidate 257 * 258 * \since 3 259 */ 260 void (*invalidate)(__DRIdrawable *drawable); 261 262 /** 263 * This function reduces the number of flushes in the driver by combining 264 * several operations into one call. 265 * 266 * It can: 267 * - throttle 268 * - flush a drawable 269 * - flush a context 270 * 271 * \param context the context 272 * \param drawable the drawable to flush 273 * \param flags a combination of _DRI2_FLUSH_xxx flags 274 * \param throttle_reason the reason for throttling, 0 = no throttling 275 * 276 * \since 4 277 */ 278 void (*flush_with_flags)(__DRIcontext *ctx, 279 __DRIdrawable *drawable, 280 unsigned flags, 281 enum __DRI2throttleReason throttle_reason); 282 }; 283 284 285 /** 286 * Extension that the driver uses to request 287 * throttle callbacks. 288 * 289 * Not used by the X server. 290 */ 291 292 #define __DRI2_THROTTLE "DRI2_Throttle" 293 #define __DRI2_THROTTLE_VERSION 1 294 295 struct __DRI2throttleExtensionRec { 296 __DRIextension base; 297 void (*throttle)(__DRIcontext *ctx, 298 __DRIdrawable *drawable, 299 enum __DRI2throttleReason reason); 300 }; 301 302 /** 303 * Extension for EGL_ANDROID_blob_cache 304 * * 305 * Not used by the X server. 306 */ 307 308 #define __DRI2_BLOB "DRI2_Blob" 309 #define __DRI2_BLOB_VERSION 1 310 311 typedef void 312 (*__DRIblobCacheSet) (const void *key, signed long keySize, 313 const void *value, signed long valueSize); 314 315 typedef signed long 316 (*__DRIblobCacheGet) (const void *key, signed long keySize, 317 void *value, signed long valueSize); 318 319 struct __DRI2blobExtensionRec { 320 __DRIextension base; 321 322 /** 323 * Set cache functions for setting and getting cache entries. 324 */ 325 void (*set_cache_funcs) (__DRIscreen *screen, 326 __DRIblobCacheSet set, __DRIblobCacheGet get); 327 }; 328 329 /** 330 * Extension for fences / synchronization objects. 331 * * 332 * Not used by the X server. 333 */ 334 335 #define __DRI2_FENCE "DRI2_Fence" 336 #define __DRI2_FENCE_VERSION 2 337 338 #define __DRI2_FENCE_TIMEOUT_INFINITE 0xffffffffffffffffull 339 340 #define __DRI2_FENCE_FLAG_FLUSH_COMMANDS (1 << 0) 341 342 /** 343 * \name Capabilities that might be returned by __DRI2fenceExtensionRec::get_capabilities 344 */ 345 /*@{*/ 346 #define __DRI_FENCE_CAP_NATIVE_FD 1 347 /*@}*/ 348 349 struct __DRI2fenceExtensionRec { 350 __DRIextension base; 351 352 /** 353 * Create and insert a fence into the command stream of the context. 354 */ 355 void *(*create_fence)(__DRIcontext *ctx); 356 357 /** 358 * Get a fence associated with the OpenCL event object. 359 * This can be NULL, meaning that OpenCL interoperability is not supported. 360 */ 361 void *(*get_fence_from_cl_event)(__DRIscreen *screen, intptr_t cl_event); 362 363 /** 364 * Destroy a fence. 365 */ 366 void (*destroy_fence)(__DRIscreen *screen, void *fence); 367 368 /** 369 * This function waits and doesn't return until the fence is signalled 370 * or the timeout expires. It returns true if the fence has been signaled. 371 * 372 * \param ctx the context where commands are flushed 373 * \param fence the fence 374 * \param flags a combination of __DRI2_FENCE_FLAG_xxx flags 375 * \param timeout the timeout in ns or __DRI2_FENCE_TIMEOUT_INFINITE 376 */ 377 unsigned char (*client_wait_sync)(__DRIcontext *ctx, void *fence, 378 unsigned flags, uint64_t timeout); 379 380 /** 381 * This function enqueues a wait command into the command stream of 382 * the context and then returns. When the execution reaches the wait 383 * command, no further execution will be done in the context until 384 * the fence is signaled. This is a no-op if the device doesn't support 385 * parallel execution of contexts. 386 * 387 * \param ctx the context where the waiting is done 388 * \param fence the fence 389 * \param flags a combination of __DRI2_FENCE_FLAG_xxx flags that make 390 * sense with this function (right now there are none) 391 */ 392 void (*server_wait_sync)(__DRIcontext *ctx, void *fence, unsigned flags); 393 394 /** 395 * Query for general capabilities of the driver that concern fences. 396 * Returns a bitmask of __DRI_FENCE_CAP_x 397 * 398 * \since 2 399 */ 400 unsigned (*get_capabilities)(__DRIscreen *screen); 401 402 /** 403 * Create an fd (file descriptor) associated fence. If the fence fd 404 * is -1, this behaves similarly to create_fence() except that when 405 * rendering is flushed the driver creates a fence fd. Otherwise, 406 * the driver wraps an existing fence fd. 407 * 408 * This is used to implement the EGL_ANDROID_native_fence_sync extension. 409 * 410 * \since 2 411 * 412 * \param ctx the context associated with the fence 413 * \param fd the fence fd or -1 414 */ 415 void *(*create_fence_fd)(__DRIcontext *ctx, int fd); 416 417 /** 418 * For fences created with create_fence_fd(), after rendering is flushed, 419 * this retrieves the native fence fd. Caller takes ownership of the 420 * fd and will close() it when it is no longer needed. 421 * 422 * \since 2 423 * 424 * \param screen the screen associated with the fence 425 * \param fence the fence 426 */ 427 int (*get_fence_fd)(__DRIscreen *screen, void *fence); 428 }; 429 430 431 /** 432 * Extension for API interop. 433 * See GL/mesa_glinterop.h. 434 * * 435 * Not used by the X server. 436 */ 437 438 #define __DRI2_INTEROP "DRI2_Interop" 439 #define __DRI2_INTEROP_VERSION 2 440 441 struct mesa_glinterop_device_info; 442 struct mesa_glinterop_export_in; 443 struct mesa_glinterop_export_out; 444 struct mesa_glinterop_flush_out; 445 typedef struct __GLsync *GLsync; 446 447 struct __DRI2interopExtensionRec { 448 __DRIextension base; 449 450 /** Same as MesaGLInterop*QueryDeviceInfo. */ 451 int (*query_device_info)(__DRIcontext *ctx, 452 struct mesa_glinterop_device_info *out); 453 454 /** Same as MesaGLInterop*ExportObject. */ 455 int (*export_object)(__DRIcontext *ctx, 456 struct mesa_glinterop_export_in *in, 457 struct mesa_glinterop_export_out *out); 458 459 /** 460 * Same as MesaGLInterop*FlushObjects. 461 * 462 * \since 2 463 */ 464 int (*flush_objects)(__DRIcontext *ctx, 465 unsigned count, struct mesa_glinterop_export_in *objects, 466 struct mesa_glinterop_flush_out *out); 467 }; 468 469 470 /** 471 * Extension for limiting window system back buffer rendering to user-defined 472 * scissor region. 473 * 474 * Not used by the X server. 475 */ 476 477 #define __DRI2_BUFFER_DAMAGE "DRI2_BufferDamage" 478 #define __DRI2_BUFFER_DAMAGE_VERSION 1 479 480 struct __DRI2bufferDamageExtensionRec { 481 __DRIextension base; 482 483 /** 484 * Provides an array of rectangles representing an overriding scissor region 485 * for rendering operations performed to the specified drawable. These 486 * rectangles do not replace client API scissor regions or draw 487 * co-ordinates, but instead inform the driver of the overall bounds of all 488 * operations which will be issued before the next flush. 489 * 490 * Any rendering operations writing pixels outside this region to the 491 * drawable will have an undefined effect on the entire drawable. 492 * 493 * This entrypoint may only be called after the drawable has either been 494 * newly created or flushed, and before any rendering operations which write 495 * pixels to the drawable. Calling this entrypoint at any other time will 496 * have an undefined effect on the entire drawable. 497 * 498 * Calling this entrypoint with @nrects 0 and @rects NULL will reset the 499 * region to the buffer's full size. This entrypoint may be called once to 500 * reset the region, followed by a second call with a populated region, 501 * before a rendering call is made. 502 * 503 * Used to implement EGL_KHR_partial_update. 504 * 505 * \param drawable affected drawable 506 * \param nrects number of rectangles provided 507 * \param rects the array of rectangles, lower-left origin 508 */ 509 void (*set_damage_region)(__DRIdrawable *drawable, unsigned int nrects, 510 int *rects); 511 }; 512 513 /*@}*/ 514 515 /** 516 * The following extensions describe loader features that the DRI 517 * driver can make use of. Some of these are mandatory, such as the 518 * getDrawableInfo extension for DRI and the DRI Loader extensions for 519 * DRI2, while others are optional, and if present allow the driver to 520 * expose certain features. The loader pass in a NULL terminated 521 * array of these extensions to the driver in the createNewScreen 522 * constructor. 523 */ 524 525 typedef struct __DRIgetDrawableInfoExtensionRec __DRIgetDrawableInfoExtension; 526 typedef struct __DRIsystemTimeExtensionRec __DRIsystemTimeExtension; 527 typedef struct __DRIdamageExtensionRec __DRIdamageExtension; 528 typedef struct __DRIloaderExtensionRec __DRIloaderExtension; 529 typedef struct __DRIswrastLoaderExtensionRec __DRIswrastLoaderExtension; 530 531 /** 532 * Callback to get system time for media stream counter extensions. 533 * 534 * Not used by the X server. 535 */ 536 #define __DRI_SYSTEM_TIME "DRI_SystemTime" 537 #define __DRI_SYSTEM_TIME_VERSION 1 538 struct __DRIsystemTimeExtensionRec { 539 __DRIextension base; 540 541 /** 542 * Get the 64-bit unadjusted system time (UST). 543 */ 544 int (*getUST)(int64_t * ust); 545 546 /** 547 * Get the media stream counter (MSC) rate. 548 * 549 * Matching the definition in GLX_OML_sync_control, this function returns 550 * the rate of the "media stream counter". In practical terms, this is 551 * the frame refresh rate of the display. 552 */ 553 unsigned char (*getMSCRate)(__DRIdrawable *draw, 554 int32_t * numerator, int32_t * denominator, 555 void *loaderPrivate); 556 }; 557 558 #define __DRI_SWRAST_IMAGE_OP_DRAW 1 559 #define __DRI_SWRAST_IMAGE_OP_CLEAR 2 560 #define __DRI_SWRAST_IMAGE_OP_SWAP 3 561 562 /** 563 * SWRast Loader extension. 564 * 565 * Version 1 is advertised by the X server. 566 */ 567 #define __DRI_SWRAST_LOADER "DRI_SWRastLoader" 568 #define __DRI_SWRAST_LOADER_VERSION 6 569 struct __DRIswrastLoaderExtensionRec { 570 __DRIextension base; 571 572 /* 573 * Drawable position and size 574 */ 575 void (*getDrawableInfo)(__DRIdrawable *drawable, 576 int *x, int *y, int *width, int *height, 577 void *loaderPrivate); 578 579 /** 580 * Put image to drawable 581 */ 582 void (*putImage)(__DRIdrawable *drawable, int op, 583 int x, int y, int width, int height, 584 char *data, void *loaderPrivate); 585 586 /** 587 * Get image from readable 588 */ 589 void (*getImage)(__DRIdrawable *readable, 590 int x, int y, int width, int height, 591 char *data, void *loaderPrivate); 592 593 /** 594 * Put image to drawable 595 * 596 * \since 2 597 */ 598 void (*putImage2)(__DRIdrawable *drawable, int op, 599 int x, int y, int width, int height, int stride, 600 char *data, void *loaderPrivate); 601 602 /** 603 * Put image to drawable 604 * 605 * \since 3 606 */ 607 void (*getImage2)(__DRIdrawable *readable, 608 int x, int y, int width, int height, int stride, 609 char *data, void *loaderPrivate); 610 611 /** 612 * Put shm image to drawable 613 * 614 * \since 4 615 */ 616 void (*putImageShm)(__DRIdrawable *drawable, int op, 617 int x, int y, int width, int height, int stride, 618 int shmid, char *shmaddr, unsigned offset, 619 void *loaderPrivate); 620 /** 621 * Get shm image from readable 622 * 623 * \since 4 624 */ 625 void (*getImageShm)(__DRIdrawable *readable, 626 int x, int y, int width, int height, 627 int shmid, void *loaderPrivate); 628 629 /** 630 * Put shm image to drawable (v2) 631 * 632 * The original version fixes srcx/y to 0, and expected 633 * the offset to be adjusted. This version allows src x,y 634 * to not be included in the offset. This is needed to 635 * avoid certain overflow checks in the X server, that 636 * result in lost rendering. 637 * 638 * \since 5 639 */ 640 void (*putImageShm2)(__DRIdrawable *drawable, int op, 641 int x, int y, 642 int width, int height, int stride, 643 int shmid, char *shmaddr, unsigned offset, 644 void *loaderPrivate); 645 646 /** 647 * get shm image to drawable (v2) 648 * 649 * There are some cases where GLX can't use SHM, but DRI 650 * still tries, we need to get a return type for when to 651 * fallback to the non-shm path. 652 * 653 * \since 6 654 */ 655 unsigned char (*getImageShm2)(__DRIdrawable *readable, 656 int x, int y, int width, int height, 657 int shmid, void *loaderPrivate); 658 }; 659 660 /** 661 * Invalidate loader extension. The presence of this extension 662 * indicates to the DRI driver that the loader will call invalidate in 663 * the __DRI2_FLUSH extension, whenever the needs to query for new 664 * buffers. This means that the DRI driver can drop the polling in 665 * glViewport(). 666 * 667 * The extension doesn't provide any functionality, it's only use to 668 * indicate to the driver that it can use the new semantics. A DRI 669 * driver can use this to switch between the different semantics or 670 * just refuse to initialize if this extension isn't present. 671 * 672 * Advertised by the X server. 673 */ 674 #define __DRI_USE_INVALIDATE "DRI_UseInvalidate" 675 #define __DRI_USE_INVALIDATE_VERSION 1 676 677 typedef struct __DRIuseInvalidateExtensionRec __DRIuseInvalidateExtension; 678 struct __DRIuseInvalidateExtensionRec { 679 __DRIextension base; 680 }; 681 682 /** 683 * Dead, do not use; kept only to allow old Xserver to compile since 684 * this file is a public API. 685 */ 686 #define __DRI_DRIVER_EXTENSIONS "__driDriverExtensions" 687 688 /** 689 * This symbol replaces the __DRI_DRIVER_EXTENSIONS symbol, and will be 690 * suffixed by "_drivername", allowing multiple drivers to be built into one 691 * library, and also giving the driver the chance to return a variable driver 692 * extensions struct depending on the driver name being loaded or any other 693 * system state. 694 * 695 * The function prototype is: 696 * 697 * const __DRIextension **__driDriverGetExtensions_drivername(void); 698 */ 699 #define __DRI_DRIVER_GET_EXTENSIONS "__driDriverGetExtensions" 700 701 /** 702 * Tokens for __DRIconfig attribs. A number of attributes defined by 703 * GLX or EGL standards are not in the table, as they must be provided 704 * by the loader. For example, FBConfig ID or visual ID, drawable type. 705 */ 706 707 #define __DRI_ATTRIB_BUFFER_SIZE 1 708 #define __DRI_ATTRIB_LEVEL 2 709 #define __DRI_ATTRIB_RED_SIZE 3 710 #define __DRI_ATTRIB_GREEN_SIZE 4 711 #define __DRI_ATTRIB_BLUE_SIZE 5 712 #define __DRI_ATTRIB_LUMINANCE_SIZE 6 713 #define __DRI_ATTRIB_ALPHA_SIZE 7 714 #define __DRI_ATTRIB_ALPHA_MASK_SIZE 8 715 #define __DRI_ATTRIB_DEPTH_SIZE 9 716 #define __DRI_ATTRIB_STENCIL_SIZE 10 717 #define __DRI_ATTRIB_ACCUM_RED_SIZE 11 718 #define __DRI_ATTRIB_ACCUM_GREEN_SIZE 12 719 #define __DRI_ATTRIB_ACCUM_BLUE_SIZE 13 720 #define __DRI_ATTRIB_ACCUM_ALPHA_SIZE 14 721 #define __DRI_ATTRIB_SAMPLE_BUFFERS 15 722 #define __DRI_ATTRIB_SAMPLES 16 723 #define __DRI_ATTRIB_RENDER_TYPE 17 724 #define __DRI_ATTRIB_CONFIG_CAVEAT 18 725 #define __DRI_ATTRIB_CONFORMANT 19 726 #define __DRI_ATTRIB_DOUBLE_BUFFER 20 727 #define __DRI_ATTRIB_STEREO 21 728 #define __DRI_ATTRIB_AUX_BUFFERS 22 729 #define __DRI_ATTRIB_TRANSPARENT_TYPE 23 730 #define __DRI_ATTRIB_TRANSPARENT_INDEX_VALUE 24 731 #define __DRI_ATTRIB_TRANSPARENT_RED_VALUE 25 732 #define __DRI_ATTRIB_TRANSPARENT_GREEN_VALUE 26 733 #define __DRI_ATTRIB_TRANSPARENT_BLUE_VALUE 27 734 #define __DRI_ATTRIB_TRANSPARENT_ALPHA_VALUE 28 735 #define __DRI_ATTRIB_FLOAT_MODE 29 736 #define __DRI_ATTRIB_RED_MASK 30 737 #define __DRI_ATTRIB_GREEN_MASK 31 738 #define __DRI_ATTRIB_BLUE_MASK 32 739 #define __DRI_ATTRIB_ALPHA_MASK 33 740 #define __DRI_ATTRIB_MAX_PBUFFER_WIDTH 34 741 #define __DRI_ATTRIB_MAX_PBUFFER_HEIGHT 35 742 #define __DRI_ATTRIB_MAX_PBUFFER_PIXELS 36 743 #define __DRI_ATTRIB_OPTIMAL_PBUFFER_WIDTH 37 744 #define __DRI_ATTRIB_OPTIMAL_PBUFFER_HEIGHT 38 745 #define __DRI_ATTRIB_VISUAL_SELECT_GROUP 39 746 #define __DRI_ATTRIB_SWAP_METHOD 40 // Parsed by the X server when our visuals return it as an attrib. 747 #define __DRI_ATTRIB_MAX_SWAP_INTERVAL 41 748 #define __DRI_ATTRIB_MIN_SWAP_INTERVAL 42 749 #define __DRI_ATTRIB_BIND_TO_TEXTURE_RGB 43 750 #define __DRI_ATTRIB_BIND_TO_TEXTURE_RGBA 44 751 #define __DRI_ATTRIB_BIND_TO_MIPMAP_TEXTURE 45 752 #define __DRI_ATTRIB_BIND_TO_TEXTURE_TARGETS 46 753 #define __DRI_ATTRIB_YINVERTED 47 754 #define __DRI_ATTRIB_FRAMEBUFFER_SRGB_CAPABLE 48 755 #define __DRI_ATTRIB_MUTABLE_RENDER_BUFFER 49 /* EGL_MUTABLE_RENDER_BUFFER_BIT_KHR */ 756 #define __DRI_ATTRIB_RED_SHIFT 50 757 #define __DRI_ATTRIB_GREEN_SHIFT 51 758 #define __DRI_ATTRIB_BLUE_SHIFT 52 759 #define __DRI_ATTRIB_ALPHA_SHIFT 53 760 #define __DRI_ATTRIB_MAX 54 761 762 /* __DRI_ATTRIB_RENDER_TYPE */ 763 #define __DRI_ATTRIB_RGBA_BIT 0x01 764 #define __DRI_ATTRIB_COLOR_INDEX_BIT 0x02 765 #define __DRI_ATTRIB_LUMINANCE_BIT 0x04 766 #define __DRI_ATTRIB_FLOAT_BIT 0x08 767 #define __DRI_ATTRIB_UNSIGNED_FLOAT_BIT 0x10 768 769 /* __DRI_ATTRIB_CONFIG_CAVEAT */ 770 #define __DRI_ATTRIB_SLOW_BIT 0x01 771 #define __DRI_ATTRIB_NON_CONFORMANT_CONFIG 0x02 772 773 /* __DRI_ATTRIB_TRANSPARENT_TYPE */ 774 #define __DRI_ATTRIB_TRANSPARENT_RGB 0x00 775 #define __DRI_ATTRIB_TRANSPARENT_INDEX 0x01 776 777 /* __DRI_ATTRIB_BIND_TO_TEXTURE_TARGETS */ 778 #define __DRI_ATTRIB_TEXTURE_1D_BIT 0x01 779 #define __DRI_ATTRIB_TEXTURE_2D_BIT 0x02 780 #define __DRI_ATTRIB_TEXTURE_RECTANGLE_BIT 0x04 781 782 /* __DRI_ATTRIB_SWAP_METHOD */ 783 /* Note that with the exception of __DRI_ATTRIB_SWAP_NONE, we need to define 784 * the same tokens as GLX. This is because old and current X servers will 785 * transmit the driconf value grabbed from the AIGLX driver untranslated as 786 * the GLX fbconfig value. These defines are kept for X Server suorce compatibility, 787 * since Mesa no longer exposes GLX_OML_swap_method. 788 */ 789 #define __DRI_ATTRIB_SWAP_NONE 0x0000 790 #define __DRI_ATTRIB_SWAP_EXCHANGE 0x8061 791 #define __DRI_ATTRIB_SWAP_COPY 0x8062 792 #define __DRI_ATTRIB_SWAP_UNDEFINED 0x8063 793 794 /** 795 * This extension defines the core DRI functionality. It was introduced when 796 * DRI2 and AIGLX were added. 797 * 798 * Version >= 2 indicates that getConfigAttrib with __DRI_ATTRIB_SWAP_METHOD 799 * returns a reliable value. The X server requires v1 and uses v2. 800 */ 801 #define __DRI_CORE "DRI_Core" 802 #define __DRI_CORE_VERSION 3 803 804 struct __DRIcoreExtensionRec { 805 __DRIextension base; 806 807 /* Not used by the X server. */ 808 __DRIscreen *(*createNewScreen)(int screen, int fd, 809 unsigned int sarea_handle, 810 const __DRIextension **extensions, 811 const __DRIconfig ***driverConfigs, 812 void *loaderPrivate); 813 814 void (*destroyScreen)(__DRIscreen *screen); 815 816 const __DRIextension **(*getExtensions)(__DRIscreen *screen); 817 818 /* Not used by the X server. */ 819 int (*getConfigAttrib)(const __DRIconfig *config, 820 unsigned int attrib, 821 unsigned int *value); 822 823 /* Not used by the X server. */ 824 int (*indexConfigAttrib)(const __DRIconfig *config, int index, 825 unsigned int *attrib, unsigned int *value); 826 827 /* Not used by the X server. */ 828 __DRIdrawable *(*createNewDrawable)(__DRIscreen *screen, 829 const __DRIconfig *config, 830 unsigned int drawable_id, 831 unsigned int head, 832 void *loaderPrivate); 833 834 /* Used by the X server */ 835 void (*destroyDrawable)(__DRIdrawable *drawable); 836 837 /* Used by the X server in swrast mode. */ 838 void (*swapBuffers)(__DRIdrawable *drawable); 839 840 /* Used by the X server in swrast mode. */ 841 __DRIcontext *(*createNewContext)(__DRIscreen *screen, 842 const __DRIconfig *config, 843 __DRIcontext *shared, 844 void *loaderPrivate); 845 846 /* Used by the X server. */ 847 int (*copyContext)(__DRIcontext *dest, 848 __DRIcontext *src, 849 unsigned long mask); 850 851 /* Used by the X server. */ 852 void (*destroyContext)(__DRIcontext *context); 853 854 /* Used by the X server. */ 855 int (*bindContext)(__DRIcontext *ctx, 856 __DRIdrawable *pdraw, 857 __DRIdrawable *pread); 858 859 /* Used by the X server. */ 860 int (*unbindContext)(__DRIcontext *ctx); 861 862 void (*swapBuffersWithDamage)(__DRIdrawable *drawable, int nrects, const int *rects); 863 }; 864 865 /** 866 * Stored version of some component (i.e., server-side DRI module, kernel-side 867 * DRM, etc.). 868 * 869 * \todo 870 * There are several data structures that explicitly store a major version, 871 * minor version, and patch level. These structures should be modified to 872 * have a \c __DRIversionRec instead. 873 * 874 * Not used by the X server since DRI1 was deleted. 875 */ 876 struct __DRIversionRec { 877 int major; /**< Major version number. */ 878 int minor; /**< Minor version number. */ 879 int patch; /**< Patch-level. */ 880 }; 881 882 /** 883 * Framebuffer information record. Used by libGL to communicate information 884 * about the framebuffer to the driver's \c __driCreateNewScreen function. 885 * 886 * In XFree86, most of this information is derrived from data returned by 887 * calling \c XF86DRIGetDeviceInfo. 888 * 889 * \sa XF86DRIGetDeviceInfo __DRIdisplayRec::createNewScreen 890 * __driUtilCreateNewScreen CallCreateNewScreen 891 * 892 * \bug This structure could be better named. 893 * 894 * Not used by the X server since DRI1 was deleted. 895 */ 896 struct __DRIframebufferRec { 897 unsigned char *base; /**< Framebuffer base address in the CPU's 898 * address space. This value is calculated by 899 * calling \c drmMap on the framebuffer handle 900 * returned by \c XF86DRIGetDeviceInfo (or a 901 * similar function). 902 */ 903 int size; /**< Framebuffer size, in bytes. */ 904 int stride; /**< Number of bytes from one line to the next. */ 905 int width; /**< Pixel width of the framebuffer. */ 906 int height; /**< Pixel height of the framebuffer. */ 907 int dev_priv_size; /**< Size of the driver's dev-priv structure. */ 908 void *dev_priv; /**< Pointer to the driver's dev-priv structure. */ 909 }; 910 911 912 /** 913 * This extension provides alternative screen, drawable and context constructors 914 * for swrast DRI functionality. This is used in conjunction with the core 915 * extension. Version 1 is required by the X server, and version 3 is used. 916 */ 917 #define __DRI_SWRAST "DRI_SWRast" 918 #define __DRI_SWRAST_VERSION 6 919 920 struct __DRIswrastExtensionRec { 921 __DRIextension base; 922 923 __DRIscreen *(*createNewScreen)(int screen, 924 const __DRIextension **extensions, 925 const __DRIconfig ***driver_configs, 926 void *loaderPrivate); 927 928 __DRIdrawable *(*createNewDrawable)(__DRIscreen *screen, 929 const __DRIconfig *config, 930 void *loaderPrivate); 931 932 /* Since version 2 */ 933 __DRIcontext *(*createNewContextForAPI)(__DRIscreen *screen, 934 int api, 935 const __DRIconfig *config, 936 __DRIcontext *shared, 937 void *data); 938 939 /** 940 * Create a context for a particular API with a set of attributes 941 * 942 * \since version 3 943 * 944 * \sa __DRIdri2ExtensionRec::createContextAttribs 945 */ 946 __DRIcontext *(*createContextAttribs)(__DRIscreen *screen, 947 int api, 948 const __DRIconfig *config, 949 __DRIcontext *shared, 950 unsigned num_attribs, 951 const uint32_t *attribs, 952 unsigned *error, 953 void *loaderPrivate); 954 955 /** 956 * createNewScreen() with the driver extensions passed in. 957 * 958 * \since version 4 959 */ 960 __DRIscreen *(*createNewScreen2)(int screen, 961 const __DRIextension **loader_extensions, 962 const __DRIextension **driver_extensions, 963 const __DRIconfig ***driver_configs, 964 void *loaderPrivate); 965 /** 966 * \since version 5 967 */ 968 int (*queryBufferAge)(__DRIdrawable *drawable); 969 970 /** 971 * createNewScreen() with the driver extensions passed in and driver_name_is_inferred load flag. 972 * 973 * \since version 6 974 */ 975 __DRIscreen *(*createNewScreen3)(int screen, 976 const __DRIextension **loader_extensions, 977 const __DRIextension **driver_extensions, 978 const __DRIconfig ***driver_configs, 979 bool driver_name_is_inferred, 980 void *loaderPrivate); 981 982 }; 983 984 /** Common DRI function definitions, shared among DRI2 and Image extensions 985 */ 986 987 typedef __DRIscreen * 988 (*__DRIcreateNewScreen2Func)(int screen, int fd, 989 const __DRIextension **extensions, 990 const __DRIextension **driver_extensions, 991 const __DRIconfig ***driver_configs, 992 void *loaderPrivate); 993 typedef __DRIscreen * 994 (*__DRIcreateNewScreen3Func)(int screen, int fd, 995 const __DRIextension **extensions, 996 const __DRIextension **driver_extensions, 997 const __DRIconfig ***driver_configs, 998 bool driver_name_is_inferred, 999 void *loaderPrivate); 1000 1001 typedef __DRIdrawable * 1002 (*__DRIcreateNewDrawableFunc)(__DRIscreen *screen, 1003 const __DRIconfig *config, 1004 void *loaderPrivate); 1005 1006 typedef __DRIcontext * 1007 (*__DRIcreateContextAttribsFunc)(__DRIscreen *screen, 1008 int api, 1009 const __DRIconfig *config, 1010 __DRIcontext *shared, 1011 unsigned num_attribs, 1012 const uint32_t *attribs, 1013 unsigned *error, 1014 void *loaderPrivate); 1015 1016 typedef unsigned int 1017 (*__DRIgetAPIMaskFunc)(__DRIscreen *screen); 1018 1019 /** 1020 * DRI2 Loader extension. 1021 */ 1022 #define __DRI_BUFFER_FRONT_LEFT 0 1023 #define __DRI_BUFFER_BACK_LEFT 1 1024 #define __DRI_BUFFER_FRONT_RIGHT 2 1025 #define __DRI_BUFFER_BACK_RIGHT 3 1026 #define __DRI_BUFFER_DEPTH 4 1027 #define __DRI_BUFFER_STENCIL 5 1028 #define __DRI_BUFFER_ACCUM 6 1029 #define __DRI_BUFFER_FAKE_FRONT_LEFT 7 1030 #define __DRI_BUFFER_FAKE_FRONT_RIGHT 8 1031 #define __DRI_BUFFER_DEPTH_STENCIL 9 /**< Only available with DRI2 1.1 */ 1032 #define __DRI_BUFFER_HIZ 10 1033 1034 /* Inofficial and for internal use. Increase when adding a new buffer token. */ 1035 #define __DRI_BUFFER_COUNT 11 1036 1037 /* Used by the X server. */ 1038 struct __DRIbufferRec { 1039 unsigned int attachment; 1040 unsigned int name; 1041 unsigned int pitch; 1042 unsigned int cpp; 1043 unsigned int flags; 1044 }; 1045 1046 /* The X server implements up to version 3 of the DRI2 loader. */ 1047 #define __DRI_DRI2_LOADER "DRI_DRI2Loader" 1048 #define __DRI_DRI2_LOADER_VERSION 5 1049 1050 enum dri_loader_cap { 1051 /* Whether the loader handles RGBA channel ordering correctly. If not, 1052 * only BGRA ordering can be exposed. 1053 */ 1054 DRI_LOADER_CAP_RGBA_ORDERING, 1055 DRI_LOADER_CAP_FP16, 1056 }; 1057 1058 struct __DRIdri2LoaderExtensionRec { 1059 __DRIextension base; 1060 1061 __DRIbuffer *(*getBuffers)(__DRIdrawable *driDrawable, 1062 int *width, int *height, 1063 unsigned int *attachments, int count, 1064 int *out_count, void *loaderPrivate); 1065 1066 /** 1067 * Flush pending front-buffer rendering 1068 * 1069 * Any rendering that has been performed to the 1070 * \c __DRI_BUFFER_FAKE_FRONT_LEFT will be flushed to the 1071 * \c __DRI_BUFFER_FRONT_LEFT. 1072 * 1073 * \param driDrawable Drawable whose front-buffer is to be flushed 1074 * \param loaderPrivate Loader's private data that was previously passed 1075 * into __DRIdri2ExtensionRec::createNewDrawable 1076 * 1077 * \since 2 1078 */ 1079 void (*flushFrontBuffer)(__DRIdrawable *driDrawable, void *loaderPrivate); 1080 1081 1082 /** 1083 * Get list of buffers from the server 1084 * 1085 * Gets a list of buffer for the specified set of attachments. Unlike 1086 * \c ::getBuffers, this function takes a list of attachments paired with 1087 * opaque \c unsigned \c int value describing the format of the buffer. 1088 * It is the responsibility of the caller to know what the service that 1089 * allocates the buffers will expect to receive for the format. 1090 * 1091 * \param driDrawable Drawable whose buffers are being queried. 1092 * \param width Output where the width of the buffers is stored. 1093 * \param height Output where the height of the buffers is stored. 1094 * \param attachments List of pairs of attachment ID and opaque format 1095 * requested for the drawable. 1096 * \param count Number of attachment / format pairs stored in 1097 * \c attachments. 1098 * \param loaderPrivate Loader's private data that was previously passed 1099 * into __DRIdri2ExtensionRec::createNewDrawable. 1100 * 1101 * \since 3 1102 */ 1103 __DRIbuffer *(*getBuffersWithFormat)(__DRIdrawable *driDrawable, 1104 int *width, int *height, 1105 unsigned int *attachments, int count, 1106 int *out_count, void *loaderPrivate); 1107 1108 /** 1109 * Return a loader capability value. If the loader doesn't know the enum, 1110 * it will return 0. 1111 * 1112 * \param loaderPrivate The last parameter of createNewScreen or 1113 * createNewScreen2. 1114 * \param cap See the enum. 1115 * 1116 * \since 4 1117 */ 1118 unsigned (*getCapability)(void *loaderPrivate, enum dri_loader_cap cap); 1119 1120 /** 1121 * Clean up any loader state associated with an image. 1122 * 1123 * \param loaderPrivate Loader's private data that was previously passed 1124 * into a __DRIimageExtensionRec::createImage function 1125 * \since 5 1126 */ 1127 void (*destroyLoaderImageState)(void *loaderPrivate); 1128 }; 1129 1130 /** 1131 * This extension provides alternative screen, drawable and context 1132 * constructors for DRI2. The X server uses up to version 4. 1133 */ 1134 #define __DRI_DRI2 "DRI_DRI2" 1135 #define __DRI_DRI2_VERSION 5 1136 1137 #define __DRI_API_OPENGL 0 /**< OpenGL compatibility profile */ 1138 #define __DRI_API_GLES 1 /**< OpenGL ES 1.x */ 1139 #define __DRI_API_GLES2 2 /**< OpenGL ES 2.x */ 1140 #define __DRI_API_OPENGL_CORE 3 /**< OpenGL 3.2+ core profile */ 1141 #define __DRI_API_GLES3 4 /**< OpenGL ES 3.x */ 1142 1143 #define __DRI_CTX_ATTRIB_MAJOR_VERSION 0 1144 #define __DRI_CTX_ATTRIB_MINOR_VERSION 1 1145 1146 /* These must alias the GLX/EGL values. */ 1147 #define __DRI_CTX_ATTRIB_FLAGS 2 1148 #define __DRI_CTX_FLAG_DEBUG 0x00000001 1149 #define __DRI_CTX_FLAG_FORWARD_COMPATIBLE 0x00000002 1150 #define __DRI_CTX_FLAG_ROBUST_BUFFER_ACCESS 0x00000004 1151 #define __DRI_CTX_FLAG_NO_ERROR 0x00000008 /* Deprecated, do not use */ 1152 /* Not yet implemented but placed here to reserve the alias with GLX */ 1153 #define __DRI_CTX_FLAG_RESET_ISOLATION 0x00000008 1154 1155 #define __DRI_CTX_ATTRIB_RESET_STRATEGY 3 1156 #define __DRI_CTX_RESET_NO_NOTIFICATION 0 1157 #define __DRI_CTX_RESET_LOSE_CONTEXT 1 1158 1159 /** 1160 * \name Context priority levels. 1161 */ 1162 #define __DRI_CTX_ATTRIB_PRIORITY 4 1163 #define __DRI_CTX_PRIORITY_LOW 0 1164 #define __DRI_CTX_PRIORITY_MEDIUM 1 1165 #define __DRI_CTX_PRIORITY_HIGH 2 1166 1167 #define __DRI_CTX_ATTRIB_RELEASE_BEHAVIOR 5 1168 #define __DRI_CTX_RELEASE_BEHAVIOR_NONE 0 1169 #define __DRI_CTX_RELEASE_BEHAVIOR_FLUSH 1 1170 1171 #define __DRI_CTX_ATTRIB_NO_ERROR 6 1172 1173 /** 1174 * \requires __DRI2_RENDER_HAS_PROTECTED_CONTEXT. 1175 * 1176 */ 1177 #define __DRI_CTX_ATTRIB_PROTECTED 7 1178 1179 1180 #define __DRI_CTX_NUM_ATTRIBS 8 1181 1182 /** 1183 * \name Reasons that __DRIdri2Extension::createContextAttribs might fail 1184 */ 1185 /*@{*/ 1186 /** Success! */ 1187 #define __DRI_CTX_ERROR_SUCCESS 0 1188 1189 /** Memory allocation failure */ 1190 #define __DRI_CTX_ERROR_NO_MEMORY 1 1191 1192 /** Client requested an API (e.g., OpenGL ES 2.0) that the driver can't do. */ 1193 #define __DRI_CTX_ERROR_BAD_API 2 1194 1195 /** Client requested an API version that the driver can't do. */ 1196 #define __DRI_CTX_ERROR_BAD_VERSION 3 1197 1198 /** Client requested a flag or combination of flags the driver can't do. */ 1199 #define __DRI_CTX_ERROR_BAD_FLAG 4 1200 1201 /** Client requested an attribute the driver doesn't understand. */ 1202 #define __DRI_CTX_ERROR_UNKNOWN_ATTRIBUTE 5 1203 1204 /** Client requested a flag the driver doesn't understand. */ 1205 #define __DRI_CTX_ERROR_UNKNOWN_FLAG 6 1206 /*@}*/ 1207 1208 struct __DRIdri2ExtensionRec { 1209 __DRIextension base; 1210 1211 __DRIscreen *(*createNewScreen)(int screen, int fd, 1212 const __DRIextension **extensions, 1213 const __DRIconfig ***driver_configs, 1214 void *loaderPrivate); 1215 1216 __DRIcreateNewDrawableFunc createNewDrawable; 1217 __DRIcontext *(*createNewContext)(__DRIscreen *screen, 1218 const __DRIconfig *config, 1219 __DRIcontext *shared, 1220 void *loaderPrivate); 1221 1222 /* Since version 2 */ 1223 __DRIgetAPIMaskFunc getAPIMask; 1224 1225 __DRIcontext *(*createNewContextForAPI)(__DRIscreen *screen, 1226 int api, 1227 const __DRIconfig *config, 1228 __DRIcontext *shared, 1229 void *data); 1230 1231 __DRIbuffer *(*allocateBuffer)(__DRIscreen *screen, 1232 unsigned int attachment, 1233 unsigned int format, 1234 int width, 1235 int height); 1236 void (*releaseBuffer)(__DRIscreen *screen, 1237 __DRIbuffer *buffer); 1238 1239 /** 1240 * Create a context for a particular API with a set of attributes 1241 * 1242 * \since version 3 1243 * 1244 * \sa __DRIswrastExtensionRec::createContextAttribs 1245 */ 1246 __DRIcreateContextAttribsFunc createContextAttribs; 1247 1248 /** 1249 * createNewScreen with the driver's extension list passed in. 1250 * 1251 * \since version 4 1252 */ 1253 __DRIcreateNewScreen2Func createNewScreen2; 1254 1255 /** 1256 * createNewScreen with the driver's extension list passed in and driver_name_is_inferred load flag. 1257 * 1258 * \since version 5 1259 */ 1260 __DRIcreateNewScreen3Func createNewScreen3; 1261 }; 1262 1263 1264 /** 1265 * This extension provides functionality to enable various EGLImage 1266 * extensions. 1267 */ 1268 #define __DRI_IMAGE "DRI_IMAGE" 1269 #define __DRI_IMAGE_VERSION 22 1270 1271 /* __DRI_IMAGE_FORMAT_* tokens are no longer exported */ 1272 1273 #define __DRI_IMAGE_USE_SHARE 0x0001 1274 #define __DRI_IMAGE_USE_SCANOUT 0x0002 1275 #define __DRI_IMAGE_USE_CURSOR 0x0004 /* Deprecated */ 1276 #define __DRI_IMAGE_USE_LINEAR 0x0008 1277 /* The buffer will only be read by an external process after SwapBuffers, 1278 * in contrary to gbm buffers, front buffers and fake front buffers, which 1279 * could be read after a flush." 1280 */ 1281 #define __DRI_IMAGE_USE_BACKBUFFER 0x0010 1282 #define __DRI_IMAGE_USE_PROTECTED 0x0020 1283 #define __DRI_IMAGE_USE_PRIME_BUFFER 0x0040 1284 #define __DRI_IMAGE_USE_FRONT_RENDERING 0x0080 1285 1286 1287 #define __DRI_IMAGE_TRANSFER_READ 0x1 1288 #define __DRI_IMAGE_TRANSFER_WRITE 0x2 1289 #define __DRI_IMAGE_TRANSFER_READ_WRITE \ 1290 (__DRI_IMAGE_TRANSFER_READ | __DRI_IMAGE_TRANSFER_WRITE) 1291 1292 /** 1293 * Extra fourcc formats used internally to Mesa with createImageFromNames. 1294 * The externally-available fourccs are defined by drm_fourcc.h (DRM_FORMAT_*) 1295 * and WL_DRM_FORMAT_* from wayland_drm.h. 1296 * 1297 * \since 5 1298 */ 1299 1300 #define __DRI_IMAGE_FOURCC_SARGB8888 0x83324258 1301 #define __DRI_IMAGE_FOURCC_SABGR8888 0x84324258 1302 #define __DRI_IMAGE_FOURCC_SXRGB8888 0x85324258 1303 1304 /** 1305 * Queryable on images created by createImageFromNames. 1306 * 1307 * RGB and RGBA might be usable directly as images, but it's still 1308 * recommended to call fromPlanar with plane == 0. 1309 * 1310 * Y_U_V, Y_UV,Y_XUXV and Y_UXVX all requires call to fromPlanar to create 1311 * usable sub-images, sampling from images return raw YUV data and 1312 * color conversion needs to be done in the shader. 1313 * 1314 * \since 5 1315 */ 1316 1317 #define __DRI_IMAGE_COMPONENTS_RGB 0x3001 1318 #define __DRI_IMAGE_COMPONENTS_RGBA 0x3002 1319 #define __DRI_IMAGE_COMPONENTS_Y_U_V 0x3003 1320 #define __DRI_IMAGE_COMPONENTS_Y_UV 0x3004 1321 #define __DRI_IMAGE_COMPONENTS_Y_XUXV 0x3005 1322 #define __DRI_IMAGE_COMPONENTS_Y_UXVX 0x3008 1323 #define __DRI_IMAGE_COMPONENTS_AYUV 0x3009 1324 #define __DRI_IMAGE_COMPONENTS_XYUV 0x300A 1325 #define __DRI_IMAGE_COMPONENTS_R 0x3006 1326 #define __DRI_IMAGE_COMPONENTS_RG 0x3007 1327 1328 1329 /** 1330 * queryImage attributes 1331 */ 1332 1333 #define __DRI_IMAGE_ATTRIB_STRIDE 0x2000 1334 #define __DRI_IMAGE_ATTRIB_HANDLE 0x2001 1335 #define __DRI_IMAGE_ATTRIB_NAME 0x2002 1336 #define __DRI_IMAGE_ATTRIB_FORMAT 0x2003 /* available in versions 3+ */ 1337 #define __DRI_IMAGE_ATTRIB_WIDTH 0x2004 /* available in versions 4+ */ 1338 #define __DRI_IMAGE_ATTRIB_HEIGHT 0x2005 1339 #define __DRI_IMAGE_ATTRIB_COMPONENTS 0x2006 /* available in versions 5+ */ 1340 #define __DRI_IMAGE_ATTRIB_FD 0x2007 /* available in versions 1341 * 7+. Each query will return a 1342 * new fd. */ 1343 #define __DRI_IMAGE_ATTRIB_FOURCC 0x2008 /* available in versions 11 */ 1344 #define __DRI_IMAGE_ATTRIB_NUM_PLANES 0x2009 /* available in versions 11 */ 1345 1346 #define __DRI_IMAGE_ATTRIB_OFFSET 0x200A /* available in versions 13 */ 1347 #define __DRI_IMAGE_ATTRIB_MODIFIER_LOWER 0x200B /* available in versions 14 */ 1348 #define __DRI_IMAGE_ATTRIB_MODIFIER_UPPER 0x200C /* available in versions 14 */ 1349 #define __DRI_IMAGE_ATTRIB_COMPRESSION_RATE 0x200D /* available in versions 22 */ 1350 1351 enum __DRIYUVColorSpace { 1352 __DRI_YUV_COLOR_SPACE_UNDEFINED = 0, 1353 __DRI_YUV_COLOR_SPACE_ITU_REC601 = 0x327F, 1354 __DRI_YUV_COLOR_SPACE_ITU_REC709 = 0x3280, 1355 __DRI_YUV_COLOR_SPACE_ITU_REC2020 = 0x3281 1356 }; 1357 1358 enum __DRISampleRange { 1359 __DRI_YUV_RANGE_UNDEFINED = 0, 1360 __DRI_YUV_FULL_RANGE = 0x3282, 1361 __DRI_YUV_NARROW_RANGE = 0x3283 1362 }; 1363 1364 enum __DRIChromaSiting { 1365 __DRI_YUV_CHROMA_SITING_UNDEFINED = 0, 1366 __DRI_YUV_CHROMA_SITING_0 = 0x3284, 1367 __DRI_YUV_CHROMA_SITING_0_5 = 0x3285 1368 }; 1369 1370 enum __DRIFixedRateCompression { 1371 __DRI_FIXED_RATE_COMPRESSION_NONE = 0x34B1, 1372 __DRI_FIXED_RATE_COMPRESSION_DEFAULT = 0x34B2, 1373 1374 __DRI_FIXED_RATE_COMPRESSION_1BPC = 0x34B4, 1375 __DRI_FIXED_RATE_COMPRESSION_2BPC = 0x34B5, 1376 __DRI_FIXED_RATE_COMPRESSION_3BPC = 0x34B6, 1377 __DRI_FIXED_RATE_COMPRESSION_4BPC = 0x34B7, 1378 __DRI_FIXED_RATE_COMPRESSION_5BPC = 0x34B8, 1379 __DRI_FIXED_RATE_COMPRESSION_6BPC = 0x34B9, 1380 __DRI_FIXED_RATE_COMPRESSION_7BPC = 0x34BA, 1381 __DRI_FIXED_RATE_COMPRESSION_8BPC = 0x34BB, 1382 __DRI_FIXED_RATE_COMPRESSION_9BPC = 0x34BC, 1383 __DRI_FIXED_RATE_COMPRESSION_10BPC = 0x34BD, 1384 __DRI_FIXED_RATE_COMPRESSION_11BPC = 0x34BE, 1385 __DRI_FIXED_RATE_COMPRESSION_12BPC = 0x34BF, 1386 }; 1387 1388 /** 1389 * \name Reasons that __DRIimageExtensionRec::createImageFromTexture or 1390 * __DRIimageExtensionRec::createImageFromDmaBufs might fail 1391 */ 1392 /*@{*/ 1393 /** Success! */ 1394 #define __DRI_IMAGE_ERROR_SUCCESS 0 1395 1396 /** Memory allocation failure */ 1397 #define __DRI_IMAGE_ERROR_BAD_ALLOC 1 1398 1399 /** Client requested an invalid attribute */ 1400 #define __DRI_IMAGE_ERROR_BAD_MATCH 2 1401 1402 /** Client requested an invalid texture object */ 1403 #define __DRI_IMAGE_ERROR_BAD_PARAMETER 3 1404 1405 /** Client requested an invalid pitch and/or offset */ 1406 #define __DRI_IMAGE_ERROR_BAD_ACCESS 4 1407 /*@}*/ 1408 1409 /** 1410 * \name Capabilities that might be returned by __DRIimageExtensionRec::getCapabilities 1411 */ 1412 /*@{*/ 1413 #define __DRI_IMAGE_CAP_GLOBAL_NAMES 1 1414 /*@}*/ 1415 1416 /** 1417 * blitImage flags 1418 */ 1419 1420 #define __BLIT_FLAG_FLUSH 0x0001 1421 #define __BLIT_FLAG_FINISH 0x0002 1422 1423 /** 1424 * Flags for createImageFromDmaBufs3 and createImageFromFds2 1425 */ 1426 #define __DRI_IMAGE_PROTECTED_CONTENT_FLAG 0x00000001 1427 #define __DRI_IMAGE_PRIME_LINEAR_BUFFER 0x00000002 1428 1429 /** 1430 * queryDmaBufFormatModifierAttribs attributes 1431 */ 1432 1433 /* Available in version 16 */ 1434 #define __DRI_IMAGE_FORMAT_MODIFIER_ATTRIB_PLANE_COUNT 0x0001 1435 1436 typedef struct __DRIimageRec __DRIimage; 1437 typedef struct __DRIimageExtensionRec __DRIimageExtension; 1438 struct __DRIimageExtensionRec { 1439 __DRIextension base; 1440 1441 __DRIimage *(*createImageFromName)(__DRIscreen *screen, 1442 int width, int height, int format, 1443 int name, int pitch, 1444 void *loaderPrivate); 1445 1446 /* Deprecated since version 17; see createImageFromRenderbuffer2 */ 1447 __DRIimage *(*createImageFromRenderbuffer)(__DRIcontext *context, 1448 int renderbuffer, 1449 void *loaderPrivate); 1450 1451 void (*destroyImage)(__DRIimage *image); 1452 1453 __DRIimage *(*createImage)(__DRIscreen *screen, 1454 int width, int height, int format, 1455 unsigned int use, 1456 void *loaderPrivate); 1457 1458 unsigned char (*queryImage)(__DRIimage *image, int attrib, int *value); 1459 1460 /** 1461 * The new __DRIimage will share the content with the old one, see dup(2). 1462 */ 1463 __DRIimage *(*dupImage)(__DRIimage *image, void *loaderPrivate); 1464 1465 /** 1466 * Validate that a __DRIimage can be used a certain way. 1467 * 1468 * \since 2 1469 */ 1470 unsigned char (*validateUsage)(__DRIimage *image, unsigned int use); 1471 1472 /** 1473 * Unlike createImageFromName __DRI_IMAGE_FORMAT is not used but instead 1474 * DRM_FORMAT_*, and strides are in bytes not pixels. Stride is 1475 * also per block and not per pixel (for non-RGB, see gallium blocks). 1476 * 1477 * \since 5 1478 */ 1479 __DRIimage *(*createImageFromNames)(__DRIscreen *screen, 1480 int width, int height, int fourcc, 1481 int *names, int num_names, 1482 int *strides, int *offsets, 1483 void *loaderPrivate); 1484 1485 /** 1486 * Create an image out of a sub-region of a parent image. This 1487 * entry point lets us create individual __DRIimages for different 1488 * planes in a planar buffer (typically yuv), for example. While a 1489 * sub-image shares the underlying buffer object with the parent 1490 * image and other sibling sub-images, the life times of parent and 1491 * sub-images are not dependent. Destroying the parent or a 1492 * sub-image doesn't affect other images. The underlying buffer 1493 * object is free when no __DRIimage remains that references it. 1494 * 1495 * Sub-images may overlap, but rendering to overlapping sub-images 1496 * is undefined. 1497 * 1498 * \since 5 1499 */ 1500 __DRIimage *(*fromPlanar)(__DRIimage *image, int plane, 1501 void *loaderPrivate); 1502 1503 /** 1504 * Create image from texture. 1505 * 1506 * \since 6 1507 */ 1508 __DRIimage *(*createImageFromTexture)(__DRIcontext *context, 1509 int target, 1510 unsigned texture, 1511 int depth, 1512 int level, 1513 unsigned *error, 1514 void *loaderPrivate); 1515 /** 1516 * Like createImageFromNames, but takes a prime fd instead. 1517 * 1518 * \since 7 1519 */ 1520 __DRIimage *(*createImageFromFds)(__DRIscreen *screen, 1521 int width, int height, int fourcc, 1522 int *fds, int num_fds, 1523 int *strides, int *offsets, 1524 void *loaderPrivate); 1525 1526 /** 1527 * Like createImageFromFds, but takes additional attributes. 1528 * 1529 * For EGL_EXT_image_dma_buf_import. 1530 * 1531 * \since 8 1532 */ 1533 __DRIimage *(*createImageFromDmaBufs)(__DRIscreen *screen, 1534 int width, int height, int fourcc, 1535 int *fds, int num_fds, 1536 int *strides, int *offsets, 1537 enum __DRIYUVColorSpace color_space, 1538 enum __DRISampleRange sample_range, 1539 enum __DRIChromaSiting horiz_siting, 1540 enum __DRIChromaSiting vert_siting, 1541 unsigned *error, 1542 void *loaderPrivate); 1543 1544 /** 1545 * Blit a part of a __DRIimage to another and flushes 1546 * 1547 * flush_flag: 1548 * 0: no flush 1549 * __BLIT_FLAG_FLUSH: flush after the blit operation 1550 * __BLIT_FLAG_FINISH: flush and wait the blit finished 1551 * 1552 * \since 9 1553 */ 1554 void (*blitImage)(__DRIcontext *context, __DRIimage *dst, __DRIimage *src, 1555 int dstx0, int dsty0, int dstwidth, int dstheight, 1556 int srcx0, int srcy0, int srcwidth, int srcheight, 1557 int flush_flag); 1558 1559 /** 1560 * Query for general capabilities of the driver that concern 1561 * buffer sharing and image importing. 1562 * 1563 * \since 10 1564 */ 1565 int (*getCapabilities)(__DRIscreen *screen); 1566 1567 /** 1568 * Returns a map of the specified region of a __DRIimage for the specified usage. 1569 * 1570 * flags may include __DRI_IMAGE_TRANSFER_READ, which will populate the 1571 * mapping with the current buffer content. If __DRI_IMAGE_TRANSFER_READ 1572 * is not included in the flags, the buffer content at map time is 1573 * undefined. Users wanting to modify the mapping must include 1574 * __DRI_IMAGE_TRANSFER_WRITE; if __DRI_IMAGE_TRANSFER_WRITE is not 1575 * included, behaviour when writing the mapping is undefined. 1576 * 1577 * Returns the byte stride in *stride, and an opaque pointer to data 1578 * tracking the mapping in **data, which must be passed to unmapImage(). 1579 * 1580 * \since 12 1581 */ 1582 void *(*mapImage)(__DRIcontext *context, __DRIimage *image, 1583 int x0, int y0, int width, int height, 1584 unsigned int flags, int *stride, void **data); 1585 1586 /** 1587 * Unmap a previously mapped __DRIimage 1588 * 1589 * \since 12 1590 */ 1591 void (*unmapImage)(__DRIcontext *context, __DRIimage *image, void *data); 1592 1593 1594 /** 1595 * Creates an image with implementation's favorite modifiers. 1596 * 1597 * This acts like createImage except there is a list of modifiers passed in 1598 * which the implementation may selectively use to create the DRIimage. The 1599 * result should be the implementation selects one modifier (perhaps it would 1600 * hold on to a few and later pick). 1601 * 1602 * The created image should be destroyed with destroyImage(). 1603 * 1604 * Returns the new DRIimage. The chosen modifier can be obtained later on 1605 * and passed back to things like the kernel's AddFB2 interface. 1606 * 1607 * \sa __DRIimageRec::createImage 1608 * 1609 * \since 14 1610 */ 1611 __DRIimage *(*createImageWithModifiers)(__DRIscreen *screen, 1612 int width, int height, int format, 1613 const uint64_t *modifiers, 1614 const unsigned int modifier_count, 1615 void *loaderPrivate); 1616 1617 /* 1618 * Like createImageFromDmaBufs, but takes also format modifiers. 1619 * 1620 * For EGL_EXT_image_dma_buf_import_modifiers. 1621 * 1622 * \since 15 1623 */ 1624 __DRIimage *(*createImageFromDmaBufs2)(__DRIscreen *screen, 1625 int width, int height, int fourcc, 1626 uint64_t modifier, 1627 int *fds, int num_fds, 1628 int *strides, int *offsets, 1629 enum __DRIYUVColorSpace color_space, 1630 enum __DRISampleRange sample_range, 1631 enum __DRIChromaSiting horiz_siting, 1632 enum __DRIChromaSiting vert_siting, 1633 unsigned *error, 1634 void *loaderPrivate); 1635 1636 /* 1637 * dmabuf format query to support EGL_EXT_image_dma_buf_import_modifiers. 1638 * 1639 * \param max Maximum number of formats that can be accomodated into 1640 * \param formats. If zero, no formats are returned - 1641 * instead, the driver returns the total number of 1642 * supported dmabuf formats in \param count. 1643 * \param formats Buffer to fill formats into. 1644 * \param count Count of formats returned, or, total number of 1645 * supported formats in case \param max is zero. 1646 * 1647 * Returns true on success. 1648 * 1649 * \since 15 1650 */ 1651 bool (*queryDmaBufFormats)(__DRIscreen *screen, int max, int *formats, 1652 int *count); 1653 1654 /* 1655 * dmabuf format modifier query for a given format to support 1656 * EGL_EXT_image_dma_buf_import_modifiers. 1657 * 1658 * \param fourcc The format to query modifiers for. If this format 1659 * is not supported by the driver, return false. 1660 * \param max Maximum number of modifiers that can be accomodated in 1661 * \param modifiers. If zero, no modifiers are returned - 1662 * instead, the driver returns the total number of 1663 * modifiers for \param format in \param count. 1664 * \param modifiers Buffer to fill modifiers into. 1665 * \param count Count of the modifiers returned, or, total number of 1666 * supported modifiers for \param fourcc in case 1667 * \param max is zero. 1668 * 1669 * Returns true upon success. 1670 * 1671 * \since 15 1672 */ 1673 bool (*queryDmaBufModifiers)(__DRIscreen *screen, int fourcc, int max, 1674 uint64_t *modifiers, 1675 unsigned int *external_only, int *count); 1676 1677 /** 1678 * dmabuf format modifier attribute query for a given format and modifier. 1679 * 1680 * \param fourcc The format to query. If this format is not supported by 1681 * the driver, return false. 1682 * \param modifier The modifier to query. If this format+modifier is not 1683 * supported by the driver, return false. 1684 * \param attrib The __DRI_IMAGE_FORMAT_MODIFIER_ATTRIB to query. 1685 * \param value A pointer to where to store the result of the query. 1686 * 1687 * Returns true upon success. 1688 * 1689 * \since 16 1690 */ 1691 bool (*queryDmaBufFormatModifierAttribs)(__DRIscreen *screen, 1692 uint32_t fourcc, uint64_t modifier, 1693 int attrib, uint64_t *value); 1694 1695 /** 1696 * Create a DRI image from the given renderbuffer. 1697 * 1698 * \param context the current DRI context 1699 * \param renderbuffer the GL name of the renderbuffer 1700 * \param loaderPrivate for callbacks into the loader related to the image 1701 * \param error will be set to one of __DRI_IMAGE_ERROR_xxx 1702 * \return the newly created image on success, or NULL otherwise 1703 * 1704 * \since 17 1705 */ 1706 __DRIimage *(*createImageFromRenderbuffer2)(__DRIcontext *context, 1707 int renderbuffer, 1708 void *loaderPrivate, 1709 unsigned *error); 1710 1711 /* 1712 * Like createImageFromDmaBufs2, but with an added flags parameter. 1713 * 1714 * See __DRI_IMAGE_*_FLAG for valid definitions of flags. 1715 * 1716 * \since 18 1717 */ 1718 __DRIimage *(*createImageFromDmaBufs3)(__DRIscreen *screen, 1719 int width, int height, int fourcc, 1720 uint64_t modifier, 1721 int *fds, int num_fds, 1722 int *strides, int *offsets, 1723 enum __DRIYUVColorSpace color_space, 1724 enum __DRISampleRange sample_range, 1725 enum __DRIChromaSiting horiz_siting, 1726 enum __DRIChromaSiting vert_siting, 1727 uint32_t flags, 1728 unsigned *error, 1729 void *loaderPrivate); 1730 1731 /** 1732 * Creates an image with implementation's favorite modifiers and the 1733 * provided usage flags. 1734 * 1735 * This acts like createImageWithModifiers except usage is also specified. 1736 * 1737 * The created image should be destroyed with destroyImage(). 1738 * 1739 * Returns the new DRIimage. The chosen modifier can be obtained later on 1740 * and passed back to things like the kernel's AddFB2 interface. 1741 * 1742 * \sa __DRIimageRec::createImage 1743 * 1744 * \since 19 1745 */ 1746 __DRIimage *(*createImageWithModifiers2)(__DRIscreen *screen, 1747 int width, int height, int format, 1748 const uint64_t *modifiers, 1749 const unsigned int modifier_count, 1750 unsigned int use, 1751 void *loaderPrivate); 1752 1753 /** 1754 * Like createImageFromFds, but with an added flag parameter. 1755 * 1756 * See __DRI_IMAGE_*_FLAG for valid definitions of flags. 1757 * 1758 * \since 20 1759 */ 1760 __DRIimage *(*createImageFromFds2)(__DRIscreen *screen, 1761 int width, int height, int fourcc, 1762 int *fds, int num_fds, 1763 uint32_t flags, 1764 int *strides, int *offsets, 1765 void *loaderPrivate); 1766 1767 /** 1768 * Set an in-fence-fd on the image. If a fence-fd is already set 1769 * (but not yet consumed), the existing and new fence will be merged 1770 * 1771 * This does *not* take ownership of the fd. The fd does not need 1772 * to be kept alive once the call has returned. 1773 * 1774 * \since 21 1775 */ 1776 void (*setInFenceFd)(__DRIimage *image, int fd); 1777 1778 /* 1779 * Query supported compression rates for a given format for 1780 * EGL_EXT_surface_compression. 1781 * 1782 * \param config Config for which to query the supported compression 1783 * rates. 1784 * \param max Maximum number of rates that can be accomodated into 1785 * \param rates. If zero, no rates are returned - 1786 * instead, the driver returns the total number of 1787 * supported compression rates in \param count. 1788 * \param rates Buffer to fill rates into. 1789 * \param count Count of rates returned, or, total number of 1790 * supported rates in case \param max is zero. 1791 * 1792 * Returns true on success. 1793 * 1794 * \since 22 1795 */ 1796 bool (*queryCompressionRates)(__DRIscreen *screen, const __DRIconfig *config, 1797 int max, enum __DRIFixedRateCompression *rates, 1798 int *count); 1799 1800 /* 1801 * Query list of modifiers that are associated with given fixed-rate 1802 * compression bitrate. 1803 * 1804 * \param format The format to query 1805 * \param rate Compression rate to query for 1806 * \param max Maximum number of modifiers that can be accomodated in 1807 * \param modifiers. If zero, no modifiers are returned - 1808 * instead, the driver returns the total number of 1809 * modifiers for \param format in \param count. 1810 * \param modifiers Buffer to fill modifiers into. 1811 * \param count Count of the modifiers returned, or, total number of 1812 * supported modifiers for \param fourcc in case 1813 * \param max is zero. 1814 * 1815 * Returns true on success. 1816 * 1817 * \since 22 1818 */ 1819 bool (*queryCompressionModifiers)(__DRIscreen *screen, uint32_t format, 1820 enum __DRIFixedRateCompression rate, 1821 int max, uint64_t *modifiers, int *count); 1822 }; 1823 1824 1825 /** 1826 * This extension must be implemented by the loader and passed to the 1827 * driver at screen creation time. The EGLImage entry points in the 1828 * various client APIs take opaque EGLImage handles and use this 1829 * extension to map them to a __DRIimage. At version 1, this 1830 * extensions allows mapping EGLImage pointers to __DRIimage pointers, 1831 * but future versions could support other EGLImage-like, opaque types 1832 * with new lookup functions. 1833 */ 1834 #define __DRI_IMAGE_LOOKUP "DRI_IMAGE_LOOKUP" 1835 #define __DRI_IMAGE_LOOKUP_VERSION 2 1836 1837 typedef struct __DRIimageLookupExtensionRec __DRIimageLookupExtension; 1838 struct __DRIimageLookupExtensionRec { 1839 __DRIextension base; 1840 1841 /** 1842 * Lookup EGLImage without validated. Equivalent to call 1843 * validateEGLImage() then lookupEGLImageValidated(). 1844 * 1845 * \since 1 1846 */ 1847 __DRIimage *(*lookupEGLImage)(__DRIscreen *screen, void *image, 1848 void *loaderPrivate); 1849 1850 /** 1851 * Check if EGLImage is associated with the EGL display before lookup with 1852 * lookupEGLImageValidated(). It will hold EGLDisplay.Mutex, so is separated 1853 * out from lookupEGLImage() to avoid deadlock. 1854 * 1855 * \since 2 1856 */ 1857 unsigned char (*validateEGLImage)(void *image, void *loaderPrivate); 1858 1859 /** 1860 * Lookup EGLImage after validateEGLImage(). No lock in this function. 1861 * 1862 * \since 2 1863 */ 1864 __DRIimage *(*lookupEGLImageValidated)(void *image, void *loaderPrivate); 1865 }; 1866 1867 /** 1868 * This extension allows for common DRI2 options 1869 */ 1870 #define __DRI2_CONFIG_QUERY "DRI_CONFIG_QUERY" 1871 #define __DRI2_CONFIG_QUERY_VERSION 2 1872 1873 typedef struct __DRI2configQueryExtensionRec __DRI2configQueryExtension; 1874 struct __DRI2configQueryExtensionRec { 1875 __DRIextension base; 1876 1877 int (*configQueryb)(__DRIscreen *screen, const char *var, unsigned char *val); 1878 int (*configQueryi)(__DRIscreen *screen, const char *var, int *val); 1879 int (*configQueryf)(__DRIscreen *screen, const char *var, float *val); 1880 int (*configQuerys)(__DRIscreen *screen, const char *var, char **val); 1881 }; 1882 1883 /** 1884 * Robust context driver extension. 1885 * 1886 * Existence of this extension means the driver can accept the 1887 * \c __DRI_CTX_FLAG_ROBUST_BUFFER_ACCESS flag and the 1888 * \c __DRI_CTX_ATTRIB_RESET_STRATEGY attribute in 1889 * \c __DRIdri2ExtensionRec::createContextAttribs. 1890 * 1891 * Used by the X server. 1892 */ 1893 #define __DRI2_ROBUSTNESS "DRI_Robustness" 1894 #define __DRI2_ROBUSTNESS_VERSION 1 1895 1896 typedef struct __DRIrobustnessExtensionRec __DRIrobustnessExtension; 1897 struct __DRIrobustnessExtensionRec { 1898 __DRIextension base; 1899 }; 1900 1901 /** 1902 * No-error context driver extension (deprecated). 1903 * 1904 * Existence of this extension means the driver can accept the 1905 * __DRI_CTX_FLAG_NO_ERROR flag. 1906 * 1907 * This extension is deprecated, and modern Mesa knows that it's always 1908 * supported. 1909 * 1910 * Not used by the X server. 1911 */ 1912 #define __DRI2_NO_ERROR "DRI_NoError" 1913 #define __DRI2_NO_ERROR_VERSION 1 1914 1915 typedef struct __DRInoErrorExtensionRec { 1916 __DRIextension base; 1917 } __DRInoErrorExtension; 1918 1919 /* 1920 * Flush control driver extension. 1921 * 1922 * Existence of this extension means the driver can accept the 1923 * \c __DRI_CTX_ATTRIB_RELEASE_BEHAVIOR attribute in 1924 * \c __DRIdri2ExtensionRec::createContextAttribs. 1925 * 1926 * Used by the X server. 1927 */ 1928 #define __DRI2_FLUSH_CONTROL "DRI_FlushControl" 1929 #define __DRI2_FLUSH_CONTROL_VERSION 1 1930 1931 typedef struct __DRI2flushControlExtensionRec __DRI2flushControlExtension; 1932 struct __DRI2flushControlExtensionRec { 1933 __DRIextension base; 1934 }; 1935 1936 /** 1937 * DRI config options extension. 1938 * 1939 * This extension provides the XML string containing driver options for use by 1940 * the loader in supporting the driconf application. 1941 * 1942 * v2: 1943 * - Add the getXml getter function which allows the driver more flexibility in 1944 * how the XML is provided. 1945 * - Deprecate the direct xml pointer. It is only provided as a fallback for 1946 * older versions of libGL and must not be used by clients that are aware of 1947 * the newer version. Future driver versions may set it to NULL. 1948 */ 1949 #define __DRI_CONFIG_OPTIONS "DRI_ConfigOptions" 1950 #define __DRI_CONFIG_OPTIONS_VERSION 2 1951 1952 typedef struct __DRIconfigOptionsExtensionRec { 1953 __DRIextension base; 1954 const char *xml; /**< deprecated since v2, use getXml instead */ 1955 1956 /** 1957 * Get an XML string that describes available driver options for use by a 1958 * config application. 1959 * 1960 * The returned string must be heap-allocated. The caller is responsible for 1961 * freeing it. 1962 */ 1963 char *(*getXml)(const char *driver_name); 1964 } __DRIconfigOptionsExtension; 1965 1966 /** 1967 * Query renderer driver extension 1968 * 1969 * This allows the window system layer (either EGL or GLX) to query aspects of 1970 * hardware and driver support without creating a context. 1971 */ 1972 #define __DRI2_RENDERER_QUERY "DRI_RENDERER_QUERY" 1973 #define __DRI2_RENDERER_QUERY_VERSION 1 1974 1975 #define __DRI2_RENDERER_VENDOR_ID 0x0000 1976 #define __DRI2_RENDERER_DEVICE_ID 0x0001 1977 #define __DRI2_RENDERER_VERSION 0x0002 1978 #define __DRI2_RENDERER_ACCELERATED 0x0003 1979 #define __DRI2_RENDERER_VIDEO_MEMORY 0x0004 1980 #define __DRI2_RENDERER_UNIFIED_MEMORY_ARCHITECTURE 0x0005 1981 #define __DRI2_RENDERER_PREFERRED_PROFILE 0x0006 1982 #define __DRI2_RENDERER_OPENGL_CORE_PROFILE_VERSION 0x0007 1983 #define __DRI2_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION 0x0008 1984 #define __DRI2_RENDERER_OPENGL_ES_PROFILE_VERSION 0x0009 1985 #define __DRI2_RENDERER_OPENGL_ES2_PROFILE_VERSION 0x000a 1986 1987 #define __DRI2_RENDERER_PREFER_BACK_BUFFER_REUSE 0x000f 1988 1989 typedef struct __DRI2rendererQueryExtensionRec __DRI2rendererQueryExtension; 1990 struct __DRI2rendererQueryExtensionRec { 1991 __DRIextension base; 1992 1993 int (*queryInteger)(__DRIscreen *screen, int attribute, unsigned int *val); 1994 int (*queryString)(__DRIscreen *screen, int attribute, const char **val); 1995 }; 1996 1997 /** 1998 * Image Loader extension. Drivers use this to allocate color buffers 1999 */ 2000 2001 /** 2002 * See __DRIimageLoaderExtensionRec::getBuffers::buffer_mask. 2003 */ 2004 enum __DRIimageBufferMask { 2005 __DRI_IMAGE_BUFFER_BACK = (1 << 0), 2006 __DRI_IMAGE_BUFFER_FRONT = (1 << 1), 2007 2008 /** 2009 * A buffer shared between application and compositor. The buffer may be 2010 * simultaneously accessed by each. 2011 * 2012 * A shared buffer is equivalent to an EGLSurface whose EGLConfig contains 2013 * EGL_MUTABLE_RENDER_BUFFER_BIT_KHR and whose active EGL_RENDER_BUFFER (as 2014 * opposed to any pending, requested change to EGL_RENDER_BUFFER) is 2015 * EGL_SINGLE_BUFFER. 2016 * 2017 * If buffer_mask contains __DRI_IMAGE_BUFFER_SHARED, then must contains no 2018 * other bits. As a corollary, a __DRIdrawable that has a "shared" buffer 2019 * has no front nor back buffer. 2020 * 2021 * The loader returns __DRI_IMAGE_BUFFER_SHARED in buffer_mask if and only 2022 * if: 2023 * - The loader supports __DRI_MUTABLE_RENDER_BUFFER_LOADER. 2024 * - The driver supports __DRI_MUTABLE_RENDER_BUFFER_DRIVER. 2025 * - The EGLConfig of the drawable EGLSurface contains 2026 * EGL_MUTABLE_RENDER_BUFFER_BIT_KHR. 2027 * - The EGLContext's EGL_RENDER_BUFFER is EGL_SINGLE_BUFFER. 2028 * Equivalently, the EGLSurface's active EGL_RENDER_BUFFER (as 2029 * opposed to any pending, requested change to EGL_RENDER_BUFFER) is 2030 * EGL_SINGLE_BUFFER. (See the EGL 1.5 and 2031 * EGL_KHR_mutable_render_buffer spec for details about "pending" vs 2032 * "active" EGL_RENDER_BUFFER state). 2033 * 2034 * A shared buffer is similar to a front buffer in that all rendering to the 2035 * buffer should appear promptly on the screen. It is different from 2036 * a front buffer in that its behavior is independent from the 2037 * GL_DRAW_BUFFER state. Specifically, if GL_DRAW_FRAMEBUFFER is 0 and the 2038 * __DRIdrawable's buffer_mask is __DRI_IMAGE_BUFFER_SHARED, then all 2039 * rendering should appear promptly on the screen if GL_DRAW_BUFFER is not 2040 * GL_NONE. 2041 * 2042 * The difference between a shared buffer and a front buffer is motivated 2043 * by the constraints of Android and OpenGL ES. OpenGL ES does not support 2044 * front-buffer rendering. Android's SurfaceFlinger protocol provides the 2045 * EGL driver only a back buffer and no front buffer. The shared buffer 2046 * mode introduced by EGL_KHR_mutable_render_buffer is a backdoor though 2047 * EGL that allows Android OpenGL ES applications to render to what is 2048 * effectively the front buffer, a backdoor that required no change to the 2049 * OpenGL ES API and little change to the SurfaceFlinger API. 2050 */ 2051 __DRI_IMAGE_BUFFER_SHARED = (1 << 2), 2052 }; 2053 2054 struct __DRIimageList { 2055 uint32_t image_mask; 2056 __DRIimage *back; 2057 __DRIimage *front; 2058 }; 2059 2060 #define __DRI_IMAGE_LOADER "DRI_IMAGE_LOADER" 2061 #define __DRI_IMAGE_LOADER_VERSION 4 2062 2063 struct __DRIimageLoaderExtensionRec { 2064 __DRIextension base; 2065 2066 /** 2067 * Allocate color buffers. 2068 * 2069 * \param driDrawable 2070 * \param width Width of allocated buffers 2071 * \param height Height of allocated buffers 2072 * \param format one of __DRI_IMAGE_FORMAT_* 2073 * \param stamp Address of variable to be updated when 2074 * getBuffers must be called again 2075 * \param loaderPrivate The loaderPrivate for driDrawable 2076 * \param buffer_mask Set of buffers to allocate. A bitmask of 2077 * __DRIimageBufferMask. 2078 * \param buffers Returned buffers 2079 */ 2080 int (*getBuffers)(__DRIdrawable *driDrawable, 2081 unsigned int format, 2082 uint32_t *stamp, 2083 void *loaderPrivate, 2084 uint32_t buffer_mask, 2085 struct __DRIimageList *buffers); 2086 2087 /** 2088 * Flush pending front-buffer rendering 2089 * 2090 * Any rendering that has been performed to the 2091 * fake front will be flushed to the front 2092 * 2093 * \param driDrawable Drawable whose front-buffer is to be flushed 2094 * \param loaderPrivate Loader's private data that was previously passed 2095 * into __DRIdri2ExtensionRec::createNewDrawable 2096 */ 2097 void (*flushFrontBuffer)(__DRIdrawable *driDrawable, void *loaderPrivate); 2098 2099 /** 2100 * Return a loader capability value. If the loader doesn't know the enum, 2101 * it will return 0. 2102 * 2103 * \since 2 2104 */ 2105 unsigned (*getCapability)(void *loaderPrivate, enum dri_loader_cap cap); 2106 2107 /** 2108 * Flush swap buffers 2109 * 2110 * Make sure any outstanding swap buffers have been submitted to the 2111 * device. 2112 * 2113 * \param driDrawable Drawable whose swaps need to be flushed 2114 * \param loaderPrivate Loader's private data that was previously passed 2115 * into __DRIdri2ExtensionRec::createNewDrawable 2116 * 2117 * \since 3 2118 */ 2119 void (*flushSwapBuffers)(__DRIdrawable *driDrawable, void *loaderPrivate); 2120 2121 /** 2122 * Clean up any loader state associated with an image. 2123 * 2124 * \param loaderPrivate Loader's private data that was previously passed 2125 * into a __DRIimageExtensionRec::createImage function 2126 * \since 4 2127 */ 2128 void (*destroyLoaderImageState)(void *loaderPrivate); 2129 }; 2130 2131 /** 2132 * Main DRI3 interface extension. 2133 * 2134 * Not used by the X server. 2135 */ 2136 2137 #define __DRI_IMAGE_DRIVER "DRI_IMAGE_DRIVER" 2138 #define __DRI_IMAGE_DRIVER_VERSION 2 2139 2140 struct __DRIimageDriverExtensionRec { 2141 __DRIextension base; 2142 2143 /* Common DRI functions, shared with DRI2 */ 2144 __DRIcreateNewScreen2Func createNewScreen2; 2145 __DRIcreateNewDrawableFunc createNewDrawable; 2146 __DRIcreateContextAttribsFunc createContextAttribs; 2147 __DRIgetAPIMaskFunc getAPIMask; 2148 __DRIcreateNewScreen3Func createNewScreen3; 2149 }; 2150 2151 /** 2152 * Background callable loader extension. 2153 * 2154 * Loaders expose this extension to indicate to drivers that they are capable 2155 * of handling callbacks from the driver's background drawing threads. 2156 */ 2157 #define __DRI_BACKGROUND_CALLABLE "DRI_BackgroundCallable" 2158 #define __DRI_BACKGROUND_CALLABLE_VERSION 1 2159 2160 typedef struct __DRIbackgroundCallableExtensionRec __DRIbackgroundCallableExtension; 2161 struct __DRIbackgroundCallableExtensionRec { 2162 __DRIextension base; 2163 2164 /** 2165 * Indicate that this thread is being used by the driver as a background 2166 * drawing thread which may make callbacks to the loader. 2167 * 2168 * \param loaderPrivate is the value that was passed to to the driver when 2169 * the context was created. This can be used by the loader to identify 2170 * which context any callbacks are associated with. 2171 * 2172 * If this function is called more than once from any given thread, each 2173 * subsequent call overrides the loaderPrivate data that was passed in the 2174 * previous call. The driver can take advantage of this to re-use a 2175 * background thread to perform drawing on behalf of multiple contexts. 2176 * 2177 * It is permissible for the driver to call this function from a 2178 * non-background thread (i.e. a thread that has already been bound to a 2179 * context using __DRIcoreExtensionRec::bindContext()); when this happens, 2180 * the \c loaderPrivate pointer must be equal to the pointer that was 2181 * passed to the driver when the currently bound context was created. 2182 * 2183 * This call should execute quickly enough that the driver can call it with 2184 * impunity whenever a background thread starts performing drawing 2185 * operations (e.g. it should just set a thread-local variable). 2186 */ 2187 void (*setBackgroundContext)(void *loaderPrivate); 2188 2189 /** 2190 * Indicate that it is multithread safe to use glthread. For GLX/EGL 2191 * platforms using Xlib, that involves calling XInitThreads, before 2192 * opening an X display. 2193 * 2194 * Note: only supported if extension version is at least 2. 2195 * 2196 * \param loaderPrivate is the value that was passed to to the driver when 2197 * the context was created. This can be used by the loader to identify 2198 * which context any callbacks are associated with. 2199 */ 2200 unsigned char (*isThreadSafe)(void *loaderPrivate); 2201 }; 2202 2203 /** 2204 * The driver portion of EGL_KHR_mutable_render_buffer. 2205 * 2206 * If the driver creates a __DRIconfig with 2207 * __DRI_ATTRIB_MUTABLE_RENDER_BUFFER, then it must support this extension. 2208 * 2209 * To support this extension: 2210 * 2211 * - The driver should create at least one __DRIconfig with 2212 * __DRI_ATTRIB_MUTABLE_RENDER_BUFFER. This is strongly recommended but 2213 * not required. 2214 * 2215 * - The driver must be able to handle __DRI_IMAGE_BUFFER_SHARED if 2216 * returned by __DRIimageLoaderExtension:getBuffers(). 2217 * 2218 * - When rendering to __DRI_IMAGE_BUFFER_SHARED, it must call 2219 * __DRImutableRenderBufferLoaderExtension::displaySharedBuffer() in 2220 * response to glFlush and glFinish. (This requirement is not documented 2221 * in EGL_KHR_mutable_render_buffer, but is a de-facto requirement in the 2222 * Android ecosystem. Android applications expect that glFlush will 2223 * immediately display the buffer when in shared buffer mode, and Android 2224 * drivers comply with this expectation). It :may: call 2225 * displaySharedBuffer() more often than required. 2226 * 2227 * - When rendering to __DRI_IMAGE_BUFFER_SHARED, it must ensure that the 2228 * buffer is always in a format compatible for display because the 2229 * display engine (usually SurfaceFlinger or hwcomposer) may display the 2230 * image at any time, even concurrently with 3D rendering. For example, 2231 * display hardware and the GL hardware may be able to access the buffer 2232 * simultaneously. In particular, if the buffer is compressed then take 2233 * care that SurfaceFlinger and hwcomposer can consume the compression 2234 * format. 2235 * 2236 * Not used by the X server. 2237 * 2238 * \see __DRI_IMAGE_BUFFER_SHARED 2239 * \see __DRI_ATTRIB_MUTABLE_RENDER_BUFFER 2240 * \see __DRI_MUTABLE_RENDER_BUFFER_LOADER 2241 */ 2242 #define __DRI_MUTABLE_RENDER_BUFFER_DRIVER "DRI_MutableRenderBufferDriver" 2243 #define __DRI_MUTABLE_RENDER_BUFFER_DRIVER_VERSION 1 2244 2245 typedef struct __DRImutableRenderBufferDriverExtensionRec __DRImutableRenderBufferDriverExtension; 2246 struct __DRImutableRenderBufferDriverExtensionRec { 2247 __DRIextension base; 2248 }; 2249 2250 /** 2251 * The loader portion of EGL_KHR_mutable_render_buffer. 2252 * 2253 * Requires loader extension DRI_IMAGE_LOADER, through which the loader sends 2254 * __DRI_IMAGE_BUFFER_SHARED to the driver. 2255 * 2256 * Not used by the X server. 2257 * 2258 * \see __DRI_MUTABLE_RENDER_BUFFER_DRIVER 2259 */ 2260 #define __DRI_MUTABLE_RENDER_BUFFER_LOADER "DRI_MutableRenderBufferLoader" 2261 #define __DRI_MUTABLE_RENDER_BUFFER_LOADER_VERSION 1 2262 2263 typedef struct __DRImutableRenderBufferLoaderExtensionRec __DRImutableRenderBufferLoaderExtension; 2264 struct __DRImutableRenderBufferLoaderExtensionRec { 2265 __DRIextension base; 2266 2267 /** 2268 * Inform the display engine (that is, SurfaceFlinger and/or hwcomposer) 2269 * that the __DRIdrawable has new content. 2270 * 2271 * The display engine may ignore this call, for example, if it continually 2272 * refreshes and displays the buffer on every frame, as in 2273 * EGL_ANDROID_front_buffer_auto_refresh. On the other extreme, the display 2274 * engine may refresh and display the buffer only in frames in which the 2275 * driver calls this. 2276 * 2277 * If the fence_fd is not -1, then the display engine will display the 2278 * buffer only after the fence signals. 2279 * 2280 * The drawable's current __DRIimageBufferMask, as returned by 2281 * __DRIimageLoaderExtension::getBuffers(), must be 2282 * __DRI_IMAGE_BUFFER_SHARED. 2283 */ 2284 void (*displaySharedBuffer)(__DRIdrawable *drawable, int fence_fd, 2285 void *loaderPrivate); 2286 }; 2287 2288 #endif 2289