dri_interface.h revision 16242a8007f41ab63f9a28bb9a750857c8cdb8af
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; 58typedef struct __DRIinterfaceMethodsRec __DRIinterfaceMethods; 59 60typedef struct __DRIextensionRec __DRIextension; 61typedef struct __DRIcopySubBufferExtensionRec __DRIcopySubBufferExtension; 62typedef struct __DRIswapControlExtensionRec __DRIswapControlExtension; 63typedef struct __DRIallocateExtensionRec __DRIallocateExtension; 64typedef struct __DRIframeTrackingExtensionRec __DRIframeTrackingExtension; 65typedef struct __DRImediaStreamCounterExtensionRec __DRImediaStreamCounterExtension; 66typedef struct __DRItexOffsetExtensionRec __DRItexOffsetExtension; 67typedef struct __DRItexBufferExtensionRec __DRItexBufferExtension; 68/*@}*/ 69 70 71/** 72 * Extension struct. Drivers 'inherit' from this struct by embedding 73 * it as the first element in the extension struct. The 74 * __DRIscreen::getExtensions entry point will return a list of these 75 * structs and the loader can use the extensions it knows about by 76 * casting it to a more specific extension and optionally advertising 77 * the GLX extension. See below for examples. 78 * 79 * We never break API in for a DRI extension. If we need to change 80 * the way things work in a non-backwards compatible manner, we 81 * introduce a new extension. During a transition period, we can 82 * leave both the old and the new extension in the driver, which 83 * allows us to move to the new interface without having to update the 84 * loader(s) in lock step. 85 * 86 * However, we can add entry points to an extension over time as long 87 * as we don't break the old ones. As we add entry points to an 88 * extension, we increase the version number. The corresponding 89 * #define can be used to guard code that accesses the new entry 90 * points at compile time and the version field in the extension 91 * struct can be used at run-time to determine how to use the 92 * extension. 93 */ 94struct __DRIextensionRec { 95 const char *name; 96 int version; 97}; 98 99/** 100 * Used by drivers to indicate support for setting the read drawable. 101 */ 102#define __DRI_READ_DRAWABLE "DRI_ReadDrawable" 103#define __DRI_READ_DRAWABLE_VERSION 1 104 105/** 106 * Used by drivers that implement the GLX_MESA_copy_sub_buffer extension. 107 */ 108#define __DRI_COPY_SUB_BUFFER "DRI_CopySubBuffer" 109#define __DRI_COPY_SUB_BUFFER_VERSION 1 110struct __DRIcopySubBufferExtensionRec { 111 __DRIextension base; 112 void (*copySubBuffer)(__DRIdrawable *drawable, int x, int y, int w, int h); 113}; 114 115/** 116 * Used by drivers that implement the GLX_SGI_swap_control or 117 * GLX_MESA_swap_control extension. 118 */ 119#define __DRI_SWAP_CONTROL "DRI_SwapControl" 120#define __DRI_SWAP_CONTROL_VERSION 1 121struct __DRIswapControlExtensionRec { 122 __DRIextension base; 123 void (*setSwapInterval)(__DRIdrawable *drawable, unsigned int inteval); 124 unsigned int (*getSwapInterval)(__DRIdrawable *drawable); 125}; 126 127/** 128 * Used by drivers that implement the GLX_MESA_allocate_memory. 129 */ 130#define __DRI_ALLOCATE "DRI_Allocate" 131#define __DRI_ALLOCATE_VERSION 1 132struct __DRIallocateExtensionRec { 133 __DRIextension base; 134 135 void *(*allocateMemory)(__DRIscreen *screen, GLsizei size, 136 GLfloat readfreq, GLfloat writefreq, 137 GLfloat priority); 138 139 void (*freeMemory)(__DRIscreen *screen, GLvoid *pointer); 140 141 GLuint (*memoryOffset)(__DRIscreen *screen, const GLvoid *pointer); 142}; 143 144/** 145 * Used by drivers that implement the GLX_MESA_swap_frame_usage extension. 146 */ 147#define __DRI_FRAME_TRACKING "DRI_FrameTracking" 148#define __DRI_FRAME_TRACKING_VERSION 1 149struct __DRIframeTrackingExtensionRec { 150 __DRIextension base; 151 152 /** 153 * Enable or disable frame usage tracking. 154 * 155 * \since Internal API version 20030317. 156 */ 157 int (*frameTracking)(__DRIdrawable *drawable, GLboolean enable); 158 159 /** 160 * Retrieve frame usage information. 161 * 162 * \since Internal API version 20030317. 163 */ 164 int (*queryFrameTracking)(__DRIdrawable *drawable, 165 int64_t * sbc, int64_t * missedFrames, 166 float * lastMissedUsage, float * usage); 167}; 168 169 170/** 171 * Used by drivers that implement the GLX_SGI_video_sync extension. 172 */ 173#define __DRI_MEDIA_STREAM_COUNTER "DRI_MediaStreamCounter" 174#define __DRI_MEDIA_STREAM_COUNTER_VERSION 1 175struct __DRImediaStreamCounterExtensionRec { 176 __DRIextension base; 177 178 /** 179 * Wait for the MSC to equal target_msc, or, if that has already passed, 180 * the next time (MSC % divisor) is equal to remainder. If divisor is 181 * zero, the function will return as soon as MSC is greater than or equal 182 * to target_msc. 183 */ 184 int (*waitForMSC)(__DRIdrawable *drawable, 185 int64_t target_msc, int64_t divisor, int64_t remainder, 186 int64_t * msc, int64_t * sbc); 187 188 /** 189 * Get the number of vertical refreshes since some point in time before 190 * this function was first called (i.e., system start up). 191 */ 192 int (*getDrawableMSC)(__DRIscreen *screen, __DRIdrawable *drawable, 193 int64_t *msc); 194}; 195 196 197#define __DRI_TEX_OFFSET "DRI_TexOffset" 198#define __DRI_TEX_OFFSET_VERSION 1 199struct __DRItexOffsetExtensionRec { 200 __DRIextension base; 201 202 /** 203 * Method to override base texture image with a driver specific 'offset'. 204 * The depth passed in allows e.g. to ignore the alpha channel of texture 205 * images where the non-alpha components don't occupy a whole texel. 206 * 207 * For GLX_EXT_texture_from_pixmap with AIGLX. 208 */ 209 void (*setTexOffset)(__DRIcontext *pDRICtx, GLint texname, 210 unsigned long long offset, GLint depth, GLuint pitch); 211}; 212 213 214#define __DRI_TEX_BUFFER "DRI_TexBuffer" 215#define __DRI_TEX_BUFFER_VERSION 1 216struct __DRItexBufferExtensionRec { 217 __DRIextension base; 218 219 /** 220 * Method to override base texture image with a DRM memory manager 221 * buffer object. The depth passed in allows e.g. to ignore the 222 * alpha channel of texture images where the non-alpha components 223 * don't occupy a whole texel. 224 * 225 * For GLX_EXT_texture_from_pixmap with AIGLX. 226 */ 227 void (*setTexBuffer)(__DRIcontext *pDRICtx, 228 GLint target, unsigned long handle, 229 GLint cpp, GLuint pitch, GLuint height); 230}; 231 232 233/** 234 * Macros for building symbol and strings. Standard CPP two step... 235 */ 236 237#define __DRI_REAL_STRINGIFY(x) # x 238#define __DRI_STRINGIFY(x) __DRI_REAL_STRINGIFY(x) 239#define __DRI_REAL_MAKE_VERSION(name, version) name ## _ ## version 240#define __DRI_MAKE_VERSION(name, version) __DRI_REAL_MAKE_VERSION(name, version) 241 242/** 243 * \name Functions and data provided by the driver. 244 */ 245/*@{*/ 246 247#define __DRI_INTERFACE_VERSION 20070105 248 249typedef void *(CREATENEWSCREENFUNC)(int scr, __DRIscreen *psc, 250 const __DRIversion * ddx_version, const __DRIversion * dri_version, 251 const __DRIversion * drm_version, const __DRIframebuffer * frame_buffer, 252 void * pSAREA, int fd, int internal_api_version, 253 const __DRIinterfaceMethods * interface, 254 __GLcontextModes ** driver_modes); 255typedef CREATENEWSCREENFUNC* PFNCREATENEWSCREENFUNC; 256 257#define __DRI_CREATE_NEW_SCREEN \ 258 __DRI_MAKE_VERSION(__driCreateNewScreen, __DRI_INTERFACE_VERSION) 259 260#define __DRI_CREATE_NEW_SCREEN_STRING \ 261 __DRI_STRINGIFY(__DRI_CREATE_NEW_SCREEN) 262 263extern CREATENEWSCREENFUNC __DRI_CREATE_NEW_SCREEN; 264 265 266/* DRI2 Entry point */ 267 268typedef void *(__DRI2_CREATE_NEW_SCREEN_FUNC)(int scr, __DRIscreen *psc, 269 int fd, unsigned int sarea_handle, 270 const __DRIinterfaceMethods * interface, __GLcontextModes ** driver_modes); 271#define __DRI2_CREATE_NEW_SCREEN \ 272 __DRI_MAKE_VERSION(__dri2CreateNewScreen, __DRI_INTERFACE_VERSION) 273 274#define __DRI2_CREATE_NEW_SCREEN_STRING \ 275 __DRI_STRINGIFY(__DRI2_CREATE_NEW_SCREEN) 276 277extern __DRI2_CREATE_NEW_SCREEN_FUNC __DRI2_CREATE_NEW_SCREEN; 278 279 280/** 281 * XML document describing the configuration options supported by the 282 * driver. 283 */ 284extern const char __driConfigOptions[]; 285 286/*@}*/ 287 288 289/** 290 * Stored version of some component (i.e., server-side DRI module, kernel-side 291 * DRM, etc.). 292 * 293 * \todo 294 * There are several data structures that explicitly store a major version, 295 * minor version, and patch level. These structures should be modified to 296 * have a \c __DRIversionRec instead. 297 */ 298struct __DRIversionRec { 299 int major; /**< Major version number. */ 300 int minor; /**< Minor version number. */ 301 int patch; /**< Patch-level. */ 302}; 303 304 305typedef void (*__DRIfuncPtr)(void); 306 307struct __DRIinterfaceMethodsRec { 308 /** 309 * Create a list of \c __GLcontextModes structures. 310 */ 311 __GLcontextModes * (*createContextModes)(unsigned count, 312 size_t minimum_bytes_per_struct); 313 314 /** 315 * Destroy a list of \c __GLcontextModes structures. 316 * 317 * \todo 318 * Determine if the drivers actually need to call this. 319 */ 320 void (*destroyContextModes)( __GLcontextModes * modes ); 321 322 323 /** 324 * \name Client/server protocol functions. 325 * 326 * These functions implement the DRI client/server protocol for 327 * context and drawable operations. Platforms that do not implement 328 * the wire protocol (e.g., EGL) will implement glorified no-op functions. 329 */ 330 /*@{*/ 331 332 /** 333 * This function is used to get information about the position, size, and 334 * clip rects of a drawable. 335 */ 336 GLboolean (* getDrawableInfo) ( __DRIdrawable *drawable, 337 unsigned int * index, unsigned int * stamp, 338 int * x, int * y, int * width, int * height, 339 int * numClipRects, drm_clip_rect_t ** pClipRects, 340 int * backX, int * backY, 341 int * numBackClipRects, drm_clip_rect_t ** pBackClipRects ); 342 /*@}*/ 343 344 345 /** 346 * \name Timing related functions. 347 */ 348 /*@{*/ 349 /** 350 * Get the 64-bit unadjusted system time (UST). 351 */ 352 int (*getUST)(int64_t * ust); 353 354 /** 355 * Get the media stream counter (MSC) rate. 356 * 357 * Matching the definition in GLX_OML_sync_control, this function returns 358 * the rate of the "media stream counter". In practical terms, this is 359 * the frame refresh rate of the display. 360 */ 361 GLboolean (*getMSCRate)(__DRIdrawable *draw, 362 int32_t * numerator, int32_t * denominator); 363 /*@}*/ 364 365 /** 366 * Reports areas of the given drawable which have been modified by the 367 * driver. 368 * 369 * \param drawable which the drawing was done to. 370 * \param rects rectangles affected, with the drawable origin as the 371 * origin. 372 * \param x X offset of the drawable within the screen (used in the 373 * front_buffer case) 374 * \param y Y offset of the drawable within the screen. 375 * \param front_buffer boolean flag for whether the drawing to the 376 * drawable was actually done directly to the front buffer (instead 377 * of backing storage, for example) 378 */ 379 void (*reportDamage)(__DRIdrawable *draw, 380 int x, int y, 381 drm_clip_rect_t *rects, int num_rects, 382 GLboolean front_buffer); 383 384 /** 385 * Ping the windowing system to get it to reemit info for the 386 * specified drawable in the DRI2 event buffer. 387 * 388 * \param draw the drawable for which to request info 389 */ 390 void (*reemitDrawableInfo)(__DRIdrawable *draw); 391 392}; 393 394 395/** 396 * Framebuffer information record. Used by libGL to communicate information 397 * about the framebuffer to the driver's \c __driCreateNewScreen function. 398 * 399 * In XFree86, most of this information is derrived from data returned by 400 * calling \c XF86DRIGetDeviceInfo. 401 * 402 * \sa XF86DRIGetDeviceInfo __DRIdisplayRec::createNewScreen 403 * __driUtilCreateNewScreen CallCreateNewScreen 404 * 405 * \bug This structure could be better named. 406 */ 407struct __DRIframebufferRec { 408 unsigned char *base; /**< Framebuffer base address in the CPU's 409 * address space. This value is calculated by 410 * calling \c drmMap on the framebuffer handle 411 * returned by \c XF86DRIGetDeviceInfo (or a 412 * similar function). 413 */ 414 int size; /**< Framebuffer size, in bytes. */ 415 int stride; /**< Number of bytes from one line to the next. */ 416 int width; /**< Pixel width of the framebuffer. */ 417 int height; /**< Pixel height of the framebuffer. */ 418 int dev_priv_size; /**< Size of the driver's dev-priv structure. */ 419 void *dev_priv; /**< Pointer to the driver's dev-priv structure. */ 420}; 421 422 423/** 424 * Screen dependent methods. This structure is initialized during the 425 * \c __DRIdisplayRec::createScreen call. 426 */ 427struct __DRIscreenRec { 428 /** 429 * Method to destroy the private DRI screen data. 430 */ 431 void (*destroyScreen)(__DRIscreen *screen); 432 433 /** 434 * Method to get screen extensions. 435 */ 436 const __DRIextension **(*getExtensions)(__DRIscreen *screen); 437 438 /** 439 * Method to create the private DRI drawable data and initialize the 440 * drawable dependent methods. 441 */ 442 void *(*createNewDrawable)(__DRIscreen *screen, 443 const __GLcontextModes *modes, 444 __DRIdrawable *pdraw, 445 drm_drawable_t hwDrawable, 446 int renderType, const int *attrs); 447 448 /** 449 * Opaque pointer to private per screen direct rendering data. \c NULL 450 * if direct rendering is not supported on this screen. Never 451 * dereferenced in libGL. 452 */ 453 void *private; 454 455 /** 456 * Method to create the private DRI context data and initialize the 457 * context dependent methods. 458 * 459 * \since Internal API version 20031201. 460 */ 461 void * (*createNewContext)(__DRIscreen *screen, 462 const __GLcontextModes *modes, 463 int render_type, 464 __DRIcontext *shared, 465 drm_context_t hwContext, __DRIcontext *pctx); 466}; 467 468/** 469 * Context dependent methods. This structure is initialized during the 470 * \c __DRIscreenRec::createContext call. 471 */ 472struct __DRIcontextRec { 473 /** 474 * Method to destroy the private DRI context data. 475 */ 476 void (*destroyContext)(__DRIcontext *context); 477 478 /** 479 * Opaque pointer to private per context direct rendering data. 480 * \c NULL if direct rendering is not supported on the display or 481 * screen used to create this context. Never dereferenced in libGL. 482 */ 483 void *private; 484 485 /** 486 * Method to bind a DRI drawable to a DRI graphics context. 487 * 488 * \since Internal API version 20050727. 489 */ 490 GLboolean (*bindContext)(__DRIcontext *ctx, 491 __DRIdrawable *pdraw, 492 __DRIdrawable *pread); 493 494 /** 495 * Method to unbind a DRI drawable from a DRI graphics context. 496 * 497 * \since Internal API version 20050727. 498 */ 499 GLboolean (*unbindContext)(__DRIcontext *ctx); 500}; 501 502/** 503 * Drawable dependent methods. This structure is initialized during the 504 * \c __DRIscreenRec::createDrawable call. \c createDrawable is not called 505 * by libGL at this time. It's currently used via the dri_util.c utility code 506 * instead. 507 */ 508struct __DRIdrawableRec { 509 /** 510 * Method to destroy the private DRI drawable data. 511 */ 512 void (*destroyDrawable)(__DRIdrawable *drawable); 513 514 /** 515 * Method to swap the front and back buffers. 516 */ 517 void (*swapBuffers)(__DRIdrawable *drawable); 518 519 /** 520 * Opaque pointer to private per drawable direct rendering data. 521 * \c NULL if direct rendering is not supported on the display or 522 * screen used to create this drawable. Never dereferenced in libGL. 523 */ 524 void *private; 525}; 526 527#endif 528