dri_interface.h revision dcbe215c015c8dc48440f578023c2b9d12b934e4
1/* 2 * Copyright 1998-1999 Precision Insight, Inc., Cedar Park, Texas. 3 * (C) Copyright IBM Corporation 2004 4 * All Rights Reserved. 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 * on the rights to use, copy, modify, merge, publish, distribute, sub 10 * license, and/or sell copies of the Software, and to permit persons to whom 11 * the Software is furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice (including the next 14 * paragraph) shall be included in all copies or substantial portions of the 15 * Software. 16 * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL 20 * THE COPYRIGHT HOLDERS AND/OR THEIR SUPPLIERS BE LIABLE FOR ANY CLAIM, 21 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR 22 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE 23 * USE OR OTHER DEALINGS IN THE SOFTWARE. 24 */ 25 26/** 27 * \file dri_interface.h 28 * 29 * This file contains all the types and functions that define the interface 30 * between a DRI driver and driver loader. Currently, the most common driver 31 * loader is the XFree86 libGL.so. However, other loaders do exist, and in 32 * the future the server-side libglx.a will also be a loader. 33 * 34 * \author Kevin E. Martin <kevin@precisioninsight.com> 35 * \author Ian Romanick <idr@us.ibm.com> 36 */ 37 38#ifndef DRI_INTERFACE_H 39#define DRI_INTERFACE_H 40 41#include <GL/internal/glcore.h> 42#include <drm.h> 43 44/** 45 * \name DRI interface structures 46 * 47 * The following structures define the interface between the GLX client 48 * side library and the DRI (direct rendering infrastructure). 49 */ 50/*@{*/ 51typedef struct __DRIdisplayRec __DRIdisplay; 52typedef struct __DRIscreenRec __DRIscreen; 53typedef struct __DRIcontextRec __DRIcontext; 54typedef struct __DRIdrawableRec __DRIdrawable; 55typedef struct __DRIdriverRec __DRIdriver; 56typedef struct __DRIframebufferRec __DRIframebuffer; 57typedef struct __DRIversionRec __DRIversion; 58 59typedef struct __DRIextensionRec __DRIextension; 60typedef struct __DRIcopySubBufferExtensionRec __DRIcopySubBufferExtension; 61typedef struct __DRIswapControlExtensionRec __DRIswapControlExtension; 62typedef struct __DRIallocateExtensionRec __DRIallocateExtension; 63typedef struct __DRIframeTrackingExtensionRec __DRIframeTrackingExtension; 64typedef struct __DRImediaStreamCounterExtensionRec __DRImediaStreamCounterExtension; 65typedef struct __DRItexOffsetExtensionRec __DRItexOffsetExtension; 66typedef struct __DRItexBufferExtensionRec __DRItexBufferExtension; 67/*@}*/ 68 69 70/** 71 * Extension struct. Drivers 'inherit' from this struct by embedding 72 * it as the first element in the extension struct. The 73 * __DRIscreen::getExtensions entry point will return a list of these 74 * structs and the loader can use the extensions it knows about by 75 * casting it to a more specific extension and optionally advertising 76 * the GLX extension. See below for examples. 77 * 78 * We never break API in for a DRI extension. If we need to change 79 * the way things work in a non-backwards compatible manner, we 80 * introduce a new extension. During a transition period, we can 81 * leave both the old and the new extension in the driver, which 82 * allows us to move to the new interface without having to update the 83 * loader(s) in lock step. 84 * 85 * However, we can add entry points to an extension over time as long 86 * as we don't break the old ones. As we add entry points to an 87 * extension, we increase the version number. The corresponding 88 * #define can be used to guard code that accesses the new entry 89 * points at compile time and the version field in the extension 90 * struct can be used at run-time to determine how to use the 91 * extension. 92 */ 93struct __DRIextensionRec { 94 const char *name; 95 int version; 96}; 97 98/** 99 * Used by drivers to indicate support for setting the read drawable. 100 */ 101#define __DRI_READ_DRAWABLE "DRI_ReadDrawable" 102#define __DRI_READ_DRAWABLE_VERSION 1 103 104/** 105 * Used by drivers that implement the GLX_MESA_copy_sub_buffer extension. 106 */ 107#define __DRI_COPY_SUB_BUFFER "DRI_CopySubBuffer" 108#define __DRI_COPY_SUB_BUFFER_VERSION 1 109struct __DRIcopySubBufferExtensionRec { 110 __DRIextension base; 111 void (*copySubBuffer)(__DRIdrawable *drawable, int x, int y, int w, int h); 112}; 113 114/** 115 * Used by drivers that implement the GLX_SGI_swap_control or 116 * GLX_MESA_swap_control extension. 117 */ 118#define __DRI_SWAP_CONTROL "DRI_SwapControl" 119#define __DRI_SWAP_CONTROL_VERSION 1 120struct __DRIswapControlExtensionRec { 121 __DRIextension base; 122 void (*setSwapInterval)(__DRIdrawable *drawable, unsigned int inteval); 123 unsigned int (*getSwapInterval)(__DRIdrawable *drawable); 124}; 125 126/** 127 * Used by drivers that implement the GLX_MESA_allocate_memory. 128 */ 129#define __DRI_ALLOCATE "DRI_Allocate" 130#define __DRI_ALLOCATE_VERSION 1 131struct __DRIallocateExtensionRec { 132 __DRIextension base; 133 134 void *(*allocateMemory)(__DRIscreen *screen, GLsizei size, 135 GLfloat readfreq, GLfloat writefreq, 136 GLfloat priority); 137 138 void (*freeMemory)(__DRIscreen *screen, GLvoid *pointer); 139 140 GLuint (*memoryOffset)(__DRIscreen *screen, const GLvoid *pointer); 141}; 142 143/** 144 * Used by drivers that implement the GLX_MESA_swap_frame_usage extension. 145 */ 146#define __DRI_FRAME_TRACKING "DRI_FrameTracking" 147#define __DRI_FRAME_TRACKING_VERSION 1 148struct __DRIframeTrackingExtensionRec { 149 __DRIextension base; 150 151 /** 152 * Enable or disable frame usage tracking. 153 * 154 * \since Internal API version 20030317. 155 */ 156 int (*frameTracking)(__DRIdrawable *drawable, GLboolean enable); 157 158 /** 159 * Retrieve frame usage information. 160 * 161 * \since Internal API version 20030317. 162 */ 163 int (*queryFrameTracking)(__DRIdrawable *drawable, 164 int64_t * sbc, int64_t * missedFrames, 165 float * lastMissedUsage, float * usage); 166}; 167 168 169/** 170 * Used by drivers that implement the GLX_SGI_video_sync extension. 171 */ 172#define __DRI_MEDIA_STREAM_COUNTER "DRI_MediaStreamCounter" 173#define __DRI_MEDIA_STREAM_COUNTER_VERSION 1 174struct __DRImediaStreamCounterExtensionRec { 175 __DRIextension base; 176 177 /** 178 * Wait for the MSC to equal target_msc, or, if that has already passed, 179 * the next time (MSC % divisor) is equal to remainder. If divisor is 180 * zero, the function will return as soon as MSC is greater than or equal 181 * to target_msc. 182 */ 183 int (*waitForMSC)(__DRIdrawable *drawable, 184 int64_t target_msc, int64_t divisor, int64_t remainder, 185 int64_t * msc, int64_t * sbc); 186 187 /** 188 * Get the number of vertical refreshes since some point in time before 189 * this function was first called (i.e., system start up). 190 */ 191 int (*getDrawableMSC)(__DRIscreen *screen, __DRIdrawable *drawable, 192 int64_t *msc); 193}; 194 195 196#define __DRI_TEX_OFFSET "DRI_TexOffset" 197#define __DRI_TEX_OFFSET_VERSION 1 198struct __DRItexOffsetExtensionRec { 199 __DRIextension base; 200 201 /** 202 * Method to override base texture image with a driver specific 'offset'. 203 * The depth passed in allows e.g. to ignore the alpha channel of texture 204 * images where the non-alpha components don't occupy a whole texel. 205 * 206 * For GLX_EXT_texture_from_pixmap with AIGLX. 207 */ 208 void (*setTexOffset)(__DRIcontext *pDRICtx, GLint texname, 209 unsigned long long offset, GLint depth, GLuint pitch); 210}; 211 212 213#define __DRI_TEX_BUFFER "DRI_TexBuffer" 214#define __DRI_TEX_BUFFER_VERSION 1 215struct __DRItexBufferExtensionRec { 216 __DRIextension base; 217 218 /** 219 * Method to override base texture image with the contents of a 220 * __DRIdrawable. 221 * 222 * For GLX_EXT_texture_from_pixmap with AIGLX. 223 */ 224 void (*setTexBuffer)(__DRIcontext *pDRICtx, 225 GLint target, 226 __DRIdrawable *pDraw); 227}; 228 229 230/** 231 * Macros for building symbol and strings. Standard CPP two step... 232 */ 233 234#define __DRI_REAL_STRINGIFY(x) # x 235#define __DRI_STRINGIFY(x) __DRI_REAL_STRINGIFY(x) 236#define __DRI_REAL_MAKE_VERSION(name, version) name ## _ ## version 237#define __DRI_MAKE_VERSION(name, version) __DRI_REAL_MAKE_VERSION(name, version) 238 239/** 240 * \name Functions and data provided by the driver. 241 */ 242/*@{*/ 243 244#define __DRI_INTERFACE_VERSION 20080310 245 246typedef void *(CREATENEWSCREENFUNC)(int scr, __DRIscreen *psc, 247 const __DRIversion * ddx_version, const __DRIversion * dri_version, 248 const __DRIversion * drm_version, const __DRIframebuffer * frame_buffer, 249 void * pSAREA, int fd, const __DRIextension ** extensions, 250 __GLcontextModes ** driver_modes); 251typedef CREATENEWSCREENFUNC* PFNCREATENEWSCREENFUNC; 252 253#define __DRI_CREATE_NEW_SCREEN \ 254 __DRI_MAKE_VERSION(__driCreateNewScreen, __DRI_INTERFACE_VERSION) 255 256#define __DRI_CREATE_NEW_SCREEN_STRING \ 257 __DRI_STRINGIFY(__DRI_CREATE_NEW_SCREEN) 258 259extern CREATENEWSCREENFUNC __DRI_CREATE_NEW_SCREEN; 260 261 262/* DRI2 Entry point */ 263 264typedef void *(__DRI2_CREATE_NEW_SCREEN_FUNC)(int scr, __DRIscreen *psc, 265 int fd, unsigned int sarea_handle, 266 const __DRIextension **extensions, __GLcontextModes ** driver_modes); 267#define __DRI2_CREATE_NEW_SCREEN \ 268 __DRI_MAKE_VERSION(__dri2CreateNewScreen, __DRI_INTERFACE_VERSION) 269 270#define __DRI2_CREATE_NEW_SCREEN_STRING \ 271 __DRI_STRINGIFY(__DRI2_CREATE_NEW_SCREEN) 272 273extern __DRI2_CREATE_NEW_SCREEN_FUNC __DRI2_CREATE_NEW_SCREEN; 274 275 276/** 277 * XML document describing the configuration options supported by the 278 * driver. 279 */ 280extern const char __driConfigOptions[]; 281 282/*@}*/ 283 284 285/** 286 * Stored version of some component (i.e., server-side DRI module, kernel-side 287 * DRM, etc.). 288 * 289 * \todo 290 * There are several data structures that explicitly store a major version, 291 * minor version, and patch level. These structures should be modified to 292 * have a \c __DRIversionRec instead. 293 */ 294struct __DRIversionRec { 295 int major; /**< Major version number. */ 296 int minor; /**< Minor version number. */ 297 int patch; /**< Patch-level. */ 298}; 299 300/** 301 * The following extensions describe loader features that the DRI 302 * driver can make use of. Some of these are mandatory, such as the 303 * getDrawableInfo extension for DRI and the coreDRI2 extensions for 304 * DRI2, while others are optional, and if present allow the driver to 305 * expose certain features. The loader pass in a NULL terminated 306 * array of these extensions to the driver in the createNewScreen 307 * constructor. 308 */ 309 310typedef struct __DRIcontextModesExtensionRec __DRIcontextModesExtension; 311typedef struct __DRIgetDrawableInfoExtensionRec __DRIgetDrawableInfoExtension; 312typedef struct __DRIsystemTimeExtensionRec __DRIsystemTimeExtension; 313typedef struct __DRIdamageExtensionRec __DRIdamageExtension; 314typedef struct __DRIcoreDRI2ExtensionRec __DRIcoreDRI2Extension; 315 316/** 317 * Memory management for __GLcontextModes 318 */ 319#define __DRI_CONTEXT_MODES "DRI_ContextModes" 320#define __DRI_CONTEXT_MODES_VERSION 1 321struct __DRIcontextModesExtensionRec { 322 __DRIextension base; 323 324 /** 325 * Create a list of \c __GLcontextModes structures. 326 */ 327 __GLcontextModes * (*createContextModes)(unsigned count, 328 size_t minimum_bytes_per_struct); 329 330 /** 331 * Destroy a list of \c __GLcontextModes structures. 332 * 333 * \todo 334 * Determine if the drivers actually need to call this. 335 */ 336 void (*destroyContextModes)( __GLcontextModes * modes ); 337}; 338 339 340/** 341 * Callback to getDrawableInfo protocol 342 */ 343#define __DRI_GET_DRAWABLE_INFO "DRI_GetDrawableInfo" 344#define __DRI_GET_DRAWABLE_INFO_VERSION 1 345struct __DRIgetDrawableInfoExtensionRec { 346 __DRIextension base; 347 348 /** 349 * This function is used to get information about the position, size, and 350 * clip rects of a drawable. 351 */ 352 GLboolean (* getDrawableInfo) ( __DRIdrawable *drawable, 353 unsigned int * index, unsigned int * stamp, 354 int * x, int * y, int * width, int * height, 355 int * numClipRects, drm_clip_rect_t ** pClipRects, 356 int * backX, int * backY, 357 int * numBackClipRects, drm_clip_rect_t ** pBackClipRects ); 358}; 359 360/** 361 * Callback to get system time for media stream counter extensions. 362 */ 363#define __DRI_SYSTEM_TIME "DRI_SystemTime" 364#define __DRI_SYSTEM_TIME_VERSION 1 365struct __DRIsystemTimeExtensionRec { 366 __DRIextension base; 367 368 /** 369 * Get the 64-bit unadjusted system time (UST). 370 */ 371 int (*getUST)(int64_t * ust); 372 373 /** 374 * Get the media stream counter (MSC) rate. 375 * 376 * Matching the definition in GLX_OML_sync_control, this function returns 377 * the rate of the "media stream counter". In practical terms, this is 378 * the frame refresh rate of the display. 379 */ 380 GLboolean (*getMSCRate)(__DRIdrawable *draw, 381 int32_t * numerator, int32_t * denominator); 382}; 383 384/** 385 * Damage reporting 386 */ 387#define __DRI_DAMAGE "DRI_Damage" 388#define __DRI_DAMAGE_VERSION 1 389struct __DRIdamageExtensionRec { 390 __DRIextension base; 391 392 /** 393 * Reports areas of the given drawable which have been modified by the 394 * driver. 395 * 396 * \param drawable which the drawing was done to. 397 * \param rects rectangles affected, with the drawable origin as the 398 * origin. 399 * \param x X offset of the drawable within the screen (used in the 400 * front_buffer case) 401 * \param y Y offset of the drawable within the screen. 402 * \param front_buffer boolean flag for whether the drawing to the 403 * drawable was actually done directly to the front buffer (instead 404 * of backing storage, for example) 405 */ 406 void (*reportDamage)(__DRIdrawable *draw, 407 int x, int y, 408 drm_clip_rect_t *rects, int num_rects, 409 GLboolean front_buffer); 410}; 411 412/** 413 * DRI2 core 414 */ 415#define __DRI_CORE_DRI2 "DRI_CoreDRI2" 416#define __DRI_CORE_DRI2_VERSION 1 417struct __DRIcoreDRI2ExtensionRec { 418 __DRIextension base; 419 420 /** 421 * Ping the windowing system to get it to reemit info for the 422 * specified drawable in the DRI2 event buffer. 423 * 424 * \param draw the drawable for which to request info 425 * \param tail the new event buffer tail pointer 426 */ 427 void (*reemitDrawableInfo)(__DRIdrawable *draw, unsigned int *tail); 428 429}; 430 431 432/** 433 * Framebuffer information record. Used by libGL to communicate information 434 * about the framebuffer to the driver's \c __driCreateNewScreen function. 435 * 436 * In XFree86, most of this information is derrived from data returned by 437 * calling \c XF86DRIGetDeviceInfo. 438 * 439 * \sa XF86DRIGetDeviceInfo __DRIdisplayRec::createNewScreen 440 * __driUtilCreateNewScreen CallCreateNewScreen 441 * 442 * \bug This structure could be better named. 443 */ 444struct __DRIframebufferRec { 445 unsigned char *base; /**< Framebuffer base address in the CPU's 446 * address space. This value is calculated by 447 * calling \c drmMap on the framebuffer handle 448 * returned by \c XF86DRIGetDeviceInfo (or a 449 * similar function). 450 */ 451 int size; /**< Framebuffer size, in bytes. */ 452 int stride; /**< Number of bytes from one line to the next. */ 453 int width; /**< Pixel width of the framebuffer. */ 454 int height; /**< Pixel height of the framebuffer. */ 455 int dev_priv_size; /**< Size of the driver's dev-priv structure. */ 456 void *dev_priv; /**< Pointer to the driver's dev-priv structure. */ 457}; 458 459 460/** 461 * Screen dependent methods. This structure is initialized during the 462 * \c __DRIdisplayRec::createScreen call. 463 */ 464struct __DRIscreenRec { 465 /** 466 * Method to destroy the private DRI screen data. 467 */ 468 void (*destroyScreen)(__DRIscreen *screen); 469 470 /** 471 * Method to get screen extensions. 472 */ 473 const __DRIextension **(*getExtensions)(__DRIscreen *screen); 474 475 /** 476 * Method to create the private DRI drawable data and initialize the 477 * drawable dependent methods. 478 */ 479 void *(*createNewDrawable)(__DRIscreen *screen, 480 const __GLcontextModes *modes, 481 __DRIdrawable *pdraw, 482 drm_drawable_t hwDrawable, 483 unsigned int head, 484 int renderType, const int *attrs); 485 486 /** 487 * Opaque pointer to private per screen direct rendering data. \c NULL 488 * if direct rendering is not supported on this screen. Never 489 * dereferenced in libGL. 490 */ 491 void *private; 492 493 /** 494 * Method to create the private DRI context data and initialize the 495 * context dependent methods. 496 * 497 * \since Internal API version 20031201. 498 */ 499 void * (*createNewContext)(__DRIscreen *screen, 500 const __GLcontextModes *modes, 501 int render_type, 502 __DRIcontext *shared, 503 drm_context_t hwContext, __DRIcontext *pctx); 504}; 505 506/** 507 * Context dependent methods. This structure is initialized during the 508 * \c __DRIscreenRec::createContext call. 509 */ 510struct __DRIcontextRec { 511 /** 512 * Method to destroy the private DRI context data. 513 */ 514 void (*destroyContext)(__DRIcontext *context); 515 516 /** 517 * Opaque pointer to private per context direct rendering data. 518 * \c NULL if direct rendering is not supported on the display or 519 * screen used to create this context. Never dereferenced in libGL. 520 */ 521 void *private; 522 523 /** 524 * Method to bind a DRI drawable to a DRI graphics context. 525 * 526 * \since Internal API version 20050727. 527 */ 528 GLboolean (*bindContext)(__DRIcontext *ctx, 529 __DRIdrawable *pdraw, 530 __DRIdrawable *pread); 531 532 /** 533 * Method to unbind a DRI drawable from a DRI graphics context. 534 * 535 * \since Internal API version 20050727. 536 */ 537 GLboolean (*unbindContext)(__DRIcontext *ctx); 538}; 539 540/** 541 * Drawable dependent methods. This structure is initialized during the 542 * \c __DRIscreenRec::createDrawable call. \c createDrawable is not called 543 * by libGL at this time. It's currently used via the dri_util.c utility code 544 * instead. 545 */ 546struct __DRIdrawableRec { 547 /** 548 * Method to destroy the private DRI drawable data. 549 */ 550 void (*destroyDrawable)(__DRIdrawable *drawable); 551 552 /** 553 * Method to swap the front and back buffers. 554 */ 555 void (*swapBuffers)(__DRIdrawable *drawable); 556 557 /** 558 * Opaque pointer to private per drawable direct rendering data. 559 * \c NULL if direct rendering is not supported on the display or 560 * screen used to create this drawable. Never dereferenced in libGL. 561 */ 562 void *private; 563}; 564 565#endif 566