dri_interface.h revision 7117f1b4
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; 59typedef unsigned long __DRIid; 60typedef void __DRInativeDisplay; 61/*@}*/ 62 63 64/** 65 * \name Functions provided by the driver loader. 66 */ 67/*@{*/ 68/** 69 * Type of a pointer to \c glXGetScreenDriver, as returned by 70 * \c glXGetProcAddress. This function is used to get the name of the DRI 71 * driver for the specified screen of the specified display. The driver 72 * name is typically used with \c glXGetDriverConfig. 73 * 74 * \sa glXGetScreenDriver, glXGetProcAddress, glXGetDriverConfig 75 */ 76typedef const char * (* PFNGLXGETSCREENDRIVERPROC) (__DRInativeDisplay *dpy, int scrNum); 77 78/** 79 * Type of a pointer to \c glXGetDriverConfig, as returned by 80 * \c glXGetProcAddress. This function is used to get the XML document 81 * describing the configuration options available for the specified driver. 82 * 83 * \sa glXGetDriverConfig, glXGetProcAddress, glXGetScreenDriver 84 */ 85typedef const char * (* PFNGLXGETDRIVERCONFIGPROC) (const char *driverName); 86 87/** 88 * Type of a pointer to \c glxEnableExtension, as returned by 89 * \c __DRIinterfaceMethods::getProcAddress. This function is used to enable 90 * a GLX extension on the specified screen. 91 */ 92typedef void (* PFNGLXSCRENABLEEXTENSIONPROC) ( void *psc, const char * name ); 93/*@}*/ 94 95 96/** 97 * \name Functions and data provided by the driver. 98 */ 99/*@{*/ 100 101typedef void *(CREATENEWSCREENFUNC)(__DRInativeDisplay *dpy, int scrn, 102 __DRIscreen *psc, const __GLcontextModes * modes, 103 const __DRIversion * ddx_version, const __DRIversion * dri_version, 104 const __DRIversion * drm_version, const __DRIframebuffer * frame_buffer, 105 void * pSAREA, int fd, int internal_api_version, 106 const __DRIinterfaceMethods * interface, 107 __GLcontextModes ** driver_modes); 108typedef CREATENEWSCREENFUNC* PFNCREATENEWSCREENFUNC; 109extern CREATENEWSCREENFUNC __driCreateNewScreen_20050727; 110 111 112/** 113 * XML document describing the configuration options supported by the 114 * driver. 115 */ 116extern const char __driConfigOptions[]; 117 118/*@}*/ 119 120 121/** 122 * Stored version of some component (i.e., server-side DRI module, kernel-side 123 * DRM, etc.). 124 * 125 * \todo 126 * There are several data structures that explicitly store a major version, 127 * minor version, and patch level. These structures should be modified to 128 * have a \c __DRIversionRec instead. 129 */ 130struct __DRIversionRec { 131 int major; /**< Major version number. */ 132 int minor; /**< Minor version number. */ 133 int patch; /**< Patch-level. */ 134}; 135 136 137typedef void (*__DRIfuncPtr)(void); 138 139struct __DRIinterfaceMethodsRec { 140 /** 141 * Get pointer to named function. 142 */ 143 __DRIfuncPtr (*getProcAddress)( const char * proc_name ); 144 145 /** 146 * Create a list of \c __GLcontextModes structures. 147 */ 148 __GLcontextModes * (*createContextModes)(unsigned count, 149 size_t minimum_bytes_per_struct); 150 151 /** 152 * Destroy a list of \c __GLcontextModes structures. 153 * 154 * \todo 155 * Determine if the drivers actually need to call this. 156 */ 157 void (*destroyContextModes)( __GLcontextModes * modes ); 158 159 /** 160 * Get the \c __DRIscreen for a given display and screen number. 161 */ 162 __DRIscreen *(*getScreen)(__DRInativeDisplay *dpy, int screenNum); 163 164 165 /** 166 * \name Client/server protocol functions. 167 * 168 * These functions implement the DRI client/server protocol for 169 * context and drawable operations. Platforms that do not implement 170 * the wire protocol (e.g., EGL) will implement glorified no-op functions. 171 */ 172 /*@{*/ 173 /** 174 * Determine if the specified window ID still exists. 175 * 176 * \note 177 * Implementations may assume that the driver will only pass an ID into 178 * this function that actually corresponds to a window. On 179 * implementations where windows can only be destroyed by the DRI driver 180 * (e.g., EGL), this function is allowed to always return \c GL_TRUE. 181 */ 182 GLboolean (*windowExists)(__DRInativeDisplay *dpy, __DRIid draw); 183 184 /** 185 * Create the server-side portion of the GL context. 186 */ 187 GLboolean (* createContext)( __DRInativeDisplay *dpy, int screenNum, 188 int configID, void * contextID, drm_context_t * hw_context ); 189 190 /** 191 * Destroy the server-side portion of the GL context. 192 */ 193 GLboolean (* destroyContext)( __DRInativeDisplay *dpy, int screenNum, 194 __DRIid context ); 195 196 /** 197 * Create the server-side portion of the drawable. 198 */ 199 GLboolean (*createDrawable)( __DRInativeDisplay * ndpy, int screen, 200 __DRIid drawable, drm_drawable_t * hHWDrawable ); 201 202 /** 203 * Destroy the server-side portion of the drawable. 204 */ 205 GLboolean (*destroyDrawable)( __DRInativeDisplay * ndpy, int screen, 206 __DRIid drawable ); 207 208 /** 209 * This function is used to get information about the position, size, and 210 * clip rects of a drawable. 211 */ 212 GLboolean (* getDrawableInfo) ( __DRInativeDisplay *dpy, int scrn, 213 __DRIid draw, unsigned int * index, unsigned int * stamp, 214 int * x, int * y, int * width, int * height, 215 int * numClipRects, drm_clip_rect_t ** pClipRects, 216 int * backX, int * backY, 217 int * numBackClipRects, drm_clip_rect_t ** pBackClipRects ); 218 /*@}*/ 219 220 221 /** 222 * \name Timing related functions. 223 */ 224 /*@{*/ 225 /** 226 * Get the 64-bit unadjusted system time (UST). 227 */ 228 int (*getUST)(int64_t * ust); 229 230 /** 231 * Get the media stream counter (MSC) rate. 232 * 233 * Matching the definition in GLX_OML_sync_control, this function returns 234 * the rate of the "media stream counter". In practical terms, this is 235 * the frame refresh rate of the display. 236 */ 237 GLboolean (*getMSCRate)(__DRInativeDisplay * dpy, __DRIid drawable, 238 int32_t * numerator, int32_t * denominator); 239 /*@}*/ 240 241 /** 242 * Reports areas of the given drawable which have been modified by the 243 * driver. 244 * 245 * \param drawable which the drawing was done to. 246 * \param rects rectangles affected, with the drawable origin as the 247 * origin. 248 * \param x X offset of the drawable within the screen (used in the 249 * front_buffer case) 250 * \param y Y offset of the drawable within the screen. 251 * \param front_buffer boolean flag for whether the drawing to the 252 * drawable was actually done directly to the front buffer (instead 253 * of backing storage, for example) 254 */ 255 void (*reportDamage)(__DRInativeDisplay * dpy, int screen, 256 __DRIid drawable, 257 int x, int y, 258 drm_clip_rect_t *rects, int num_rects, 259 int front_buffer); 260}; 261 262 263/** 264 * Framebuffer information record. Used by libGL to communicate information 265 * about the framebuffer to the driver's \c __driCreateNewScreen function. 266 * 267 * In XFree86, most of this information is derrived from data returned by 268 * calling \c XF86DRIGetDeviceInfo. 269 * 270 * \sa XF86DRIGetDeviceInfo __DRIdisplayRec::createNewScreen 271 * __driUtilCreateNewScreen CallCreateNewScreen 272 * 273 * \bug This structure could be better named. 274 */ 275struct __DRIframebufferRec { 276 unsigned char *base; /**< Framebuffer base address in the CPU's 277 * address space. This value is calculated by 278 * calling \c drmMap on the framebuffer handle 279 * returned by \c XF86DRIGetDeviceInfo (or a 280 * similar function). 281 */ 282 int size; /**< Framebuffer size, in bytes. */ 283 int stride; /**< Number of bytes from one line to the next. */ 284 int width; /**< Pixel width of the framebuffer. */ 285 int height; /**< Pixel height of the framebuffer. */ 286 int dev_priv_size; /**< Size of the driver's dev-priv structure. */ 287 void *dev_priv; /**< Pointer to the driver's dev-priv structure. */ 288}; 289 290 291/** 292 * Screen dependent methods. This structure is initialized during the 293 * \c __DRIdisplayRec::createScreen call. 294 */ 295struct __DRIscreenRec { 296 /** 297 * Method to destroy the private DRI screen data. 298 */ 299 void (*destroyScreen)(__DRInativeDisplay *dpy, int scrn, void *screenPrivate); 300 301 /** 302 * Method to create the private DRI drawable data and initialize the 303 * drawable dependent methods. 304 */ 305 void *(*createNewDrawable)(__DRInativeDisplay *dpy, const __GLcontextModes *modes, 306 __DRIid draw, __DRIdrawable *pdraw, 307 int renderType, const int *attrs); 308 309 /** 310 * Method to return a pointer to the DRI drawable data. 311 */ 312 __DRIdrawable *(*getDrawable)(__DRInativeDisplay *dpy, __DRIid draw, 313 void *drawablePrivate); 314 315 /** 316 * Opaque pointer to private per screen direct rendering data. \c NULL 317 * if direct rendering is not supported on this screen. Never 318 * dereferenced in libGL. 319 */ 320 void *private; 321 322 /** 323 * Get the number of vertical refreshes since some point in time before 324 * this function was first called (i.e., system start up). 325 * 326 * \since Internal API version 20030317. 327 */ 328 int (*getMSC)( void *screenPrivate, int64_t *msc ); 329 330 /** 331 * Opaque pointer that points back to the containing 332 * \c __GLXscreenConfigs. This data structure is shared with DRI drivers 333 * but \c __GLXscreenConfigs is not. However, they are needed by some GLX 334 * functions called by DRI drivers. 335 * 336 * \since Internal API version 20030813. 337 */ 338 void *screenConfigs; 339 340 /** 341 * Functions associated with MESA_allocate_memory. 342 * 343 * \since Internal API version 20030815. 344 */ 345 /*@{*/ 346 void *(*allocateMemory)(__DRInativeDisplay *dpy, int scrn, GLsizei size, 347 GLfloat readfreq, GLfloat writefreq, 348 GLfloat priority); 349 350 void (*freeMemory)(__DRInativeDisplay *dpy, int scrn, GLvoid *pointer); 351 352 GLuint (*memoryOffset)(__DRInativeDisplay *dpy, int scrn, const GLvoid *pointer); 353 /*@}*/ 354 355 /** 356 * Method to create the private DRI context data and initialize the 357 * context dependent methods. 358 * 359 * \since Internal API version 20031201. 360 */ 361 void * (*createNewContext)(__DRInativeDisplay *dpy, const __GLcontextModes *modes, 362 int render_type, 363 void *sharedPrivate, __DRIcontext *pctx); 364 365 /** 366 * Method to override base texture image with a driver specific 'offset'. 367 * The depth passed in allows e.g. to ignore the alpha channel of texture 368 * images where the non-alpha components don't occupy a whole texel. 369 * 370 * For GLX_EXT_texture_from_pixmap with AIGLX. 371 * 372 * \since Internal API version 20070121. 373 */ 374 void (*setTexOffset)(__DRIcontext *pDRICtx, GLint texname, 375 unsigned long long offset, GLint depth, GLuint pitch); 376}; 377 378/** 379 * Context dependent methods. This structure is initialized during the 380 * \c __DRIscreenRec::createContext call. 381 */ 382struct __DRIcontextRec { 383 /** 384 * Method to destroy the private DRI context data. 385 */ 386 void (*destroyContext)(__DRInativeDisplay *dpy, int scrn, void *contextPrivate); 387 388 /** 389 * Opaque pointer to private per context direct rendering data. 390 * \c NULL if direct rendering is not supported on the display or 391 * screen used to create this context. Never dereferenced in libGL. 392 */ 393 void *private; 394 395 /** 396 * Pointer to the mode used to create this context. 397 * 398 * \since Internal API version 20040317. 399 */ 400 const __GLcontextModes * mode; 401 402 /** 403 * Method to bind a DRI drawable to a DRI graphics context. 404 * 405 * \since Internal API version 20050727. 406 */ 407 GLboolean (*bindContext)(__DRInativeDisplay *dpy, int scrn, __DRIid draw, 408 __DRIid read, __DRIcontext *ctx); 409 410 /** 411 * Method to unbind a DRI drawable from a DRI graphics context. 412 * 413 * \since Internal API version 20050727. 414 */ 415 GLboolean (*unbindContext)(__DRInativeDisplay *dpy, int scrn, __DRIid draw, 416 __DRIid read, __DRIcontext *ctx); 417}; 418 419/** 420 * Drawable dependent methods. This structure is initialized during the 421 * \c __DRIscreenRec::createDrawable call. \c createDrawable is not called 422 * by libGL at this time. It's currently used via the dri_util.c utility code 423 * instead. 424 */ 425struct __DRIdrawableRec { 426 /** 427 * Method to destroy the private DRI drawable data. 428 */ 429 void (*destroyDrawable)(__DRInativeDisplay *dpy, void *drawablePrivate); 430 431 /** 432 * Method to swap the front and back buffers. 433 */ 434 void (*swapBuffers)(__DRInativeDisplay *dpy, void *drawablePrivate); 435 436 /** 437 * Opaque pointer to private per drawable direct rendering data. 438 * \c NULL if direct rendering is not supported on the display or 439 * screen used to create this drawable. Never dereferenced in libGL. 440 */ 441 void *private; 442 443 /** 444 * Get the number of completed swap buffers for this drawable. 445 * 446 * \since Internal API version 20030317. 447 */ 448 int (*getSBC)(__DRInativeDisplay *dpy, void *drawablePrivate, int64_t *sbc ); 449 450 /** 451 * Wait for the SBC to be greater than or equal target_sbc. 452 * 453 * \since Internal API version 20030317. 454 */ 455 int (*waitForSBC)( __DRInativeDisplay * dpy, void *drawablePriv, 456 int64_t target_sbc, 457 int64_t * msc, int64_t * sbc ); 458 459 /** 460 * Wait for the MSC to equal target_msc, or, if that has already passed, 461 * the next time (MSC % divisor) is equal to remainder. If divisor is 462 * zero, the function will return as soon as MSC is greater than or equal 463 * to target_msc. 464 * 465 * \since Internal API version 20030317. 466 */ 467 int (*waitForMSC)( __DRInativeDisplay * dpy, void *drawablePriv, 468 int64_t target_msc, int64_t divisor, int64_t remainder, 469 int64_t * msc, int64_t * sbc ); 470 471 /** 472 * Like \c swapBuffers, but does NOT have an implicit \c glFlush. Once 473 * rendering is complete, waits until MSC is equal to target_msc, or 474 * if that has already passed, waits until (MSC % divisor) is equal 475 * to remainder. If divisor is zero, the swap will happen as soon as 476 * MSC is greater than or equal to target_msc. 477 * 478 * \since Internal API version 20030317. 479 */ 480 int64_t (*swapBuffersMSC)(__DRInativeDisplay *dpy, void *drawablePrivate, 481 int64_t target_msc, 482 int64_t divisor, int64_t remainder); 483 484 /** 485 * Enable or disable frame usage tracking. 486 * 487 * \since Internal API version 20030317. 488 */ 489 int (*frameTracking)(__DRInativeDisplay *dpy, void *drawablePrivate, GLboolean enable); 490 491 /** 492 * Retrieve frame usage information. 493 * 494 * \since Internal API version 20030317. 495 */ 496 int (*queryFrameTracking)(__DRInativeDisplay *dpy, void *drawablePrivate, 497 int64_t * sbc, int64_t * missedFrames, 498 float * lastMissedUsage, float * usage ); 499 500 /** 501 * Used by drivers that implement the GLX_SGI_swap_control or 502 * GLX_MESA_swap_control extension. 503 * 504 * \since Internal API version 20030317. 505 */ 506 unsigned swap_interval; 507 508 /** 509 * Used by drivers that implement the GLX_MESA_copy_sub_buffer extension. 510 * 511 * \since Internal API version 20060314. 512 */ 513 void (*copySubBuffer)(__DRInativeDisplay *dpy, void *drawablePrivate, 514 int x, int y, int w, int h); 515}; 516 517#endif 518