dri_interface.h revision 60b0e12830310e7c05b4043857ed277b28b1c781
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#ifndef DRI_NEW_INTERFACE_ONLY 42/* FIXME: With a small amount of work, these two includes can be removed. */ 43#include <X11/Xlib.h> 44#include <GL/glx.h> 45#endif 46 47#ifndef DRI_NEW_INTERFACE_ONLY 48#include <GL/glxint.h> 49#endif 50 51#include <GL/internal/glcore.h> 52#include <xf86drm.h> 53#include <drm.h> 54 55/** 56 * \name DRI interface structures 57 * 58 * The following structures define the interface between the GLX client 59 * side library and the DRI (direct rendering infrastructure). 60 */ 61/*@{*/ 62typedef struct __DRIdisplayRec __DRIdisplay; 63typedef struct __DRIscreenRec __DRIscreen; 64typedef struct __DRIcontextRec __DRIcontext; 65typedef struct __DRIdrawableRec __DRIdrawable; 66typedef struct __DRIdriverRec __DRIdriver; 67typedef struct __DRIframebufferRec __DRIframebuffer; 68typedef struct __DRIversionRec __DRIversion; 69typedef unsigned long __DRIid; 70typedef void __DRInativeDisplay; 71/*@}*/ 72 73 74/** 75 * \name Functions provided by the driver loader. 76 */ 77/*@{*/ 78extern __DRIscreen *__glXFindDRIScreen(__DRInativeDisplay *dpy, int scrn); 79 80 81/** 82 * Type of a pointer to \c __glXGetInternalVersion, as returned by 83 * \c glXGetProcAddress. 84 * 85 * \sa __glXGetInternalVersion, glXGetProcAddress 86 */ 87typedef int (* PFNGLXGETINTERNALVERSIONPROC) ( void ); 88 89/** 90 * Type of a pointer to \c __glXWindowExists, as returned by 91 * \c glXGetProcAddress. 92 * 93 * \sa __glXWindowExists, glXGetProcAddress 94 */ 95typedef Bool (* PFNGLXWINDOWEXISTSPROC) (__DRInativeDisplay *dpy, __DRIid draw); 96 97/** 98 * Type of a pointer to \c __glXGetUST, as returned by \c glXGetProcAddress. 99 * 100 * \sa __glXGetUST, glXGetProcAddress 101 */ 102typedef int (* PFNGLXGETUSTPROC) ( int64_t * ust ); 103 104/** 105 * Type of pointer to \c __glXCreateContextModes, as returned by 106 * \c glXGetProcAddress. 107 * 108 * \sa _gl_context_modes_create, glXGetProcAddress 109 */ 110 111typedef __GLcontextModes * (* PFNGLXCREATECONTEXTMODES) ( unsigned count, 112 size_t minimum_bytes_per_struct ); 113 114/** 115 * Type of a pointer to \c glXGetScreenDriver, as returned by 116 * \c glXGetProcAddress. This function is used to get the name of the DRI 117 * driver for the specified screen of the specified display. The driver 118 * name is typically used with \c glXGetDriverConfig. 119 * 120 * \sa glXGetScreenDriver, glXGetProcAddress, glXGetDriverConfig 121 */ 122typedef const char * (* PFNGLXGETSCREENDRIVERPROC) (__DRInativeDisplay *dpy, int scrNum); 123 124/** 125 * Type of a pointer to \c glXGetDriverConfig, as returned by 126 * \c glXGetProcAddress. This function is used to get the XML document 127 * describing the configuration options available for the specified driver. 128 * 129 * \sa glXGetDriverConfig, glXGetProcAddress, glXGetScreenDriver 130 */ 131typedef const char * (* PFNGLXGETDRIVERCONFIGPROC) (const char *driverName); 132 133/** 134 * Type of a pointer to \c __glXScrEnableExtension, as returned by 135 * \c glXGetProcAddress. This function is used to enable a GLX extension 136 * on the specified screen. 137 * 138 * \sa __glXScrEnableExtension, glXGetProcAddress 139 */ 140typedef void (* PFNGLXSCRENABLEEXTENSIONPROC) ( void *psc, const char * name ); 141 142/** 143 * Type of a pointer to \c __glXGetDrawableInfo, as returned by 144 * \c glXGetProcAddress. This function is used to get information about the 145 * position, size, and clip rects of a drawable. 146 * 147 * \sa __glXGetDrawableInfo, glXGetProcAddress 148 */ 149typedef Bool (* PFNGLXGETDRAWABLEINFOPROC) ( __DRInativeDisplay *dpy, int scrn, 150 __DRIid draw, unsigned int * index, unsigned int * stamp, 151 int * x, int * y, int * width, int * height, 152 int * numClipRects, drm_clip_rect_t ** pClipRects, 153 int * backX, int * backY, 154 int * numBackClipRects, drm_clip_rect_t ** pBackClipRects ); 155/*@}*/ 156 157 158/** 159 * \name Functions and data provided by the driver. 160 */ 161/*@{*/ 162 163extern void * __driCreateNewScreen( __DRInativeDisplay *dpy, int scrn, __DRIscreen *psc, 164 const __GLcontextModes * modes, const __DRIversion * ddx_version, 165 const __DRIversion * dri_version, const __DRIversion * drm_version, 166 const __DRIframebuffer * frame_buffer, drmAddress pSAREA, int fd, 167 int internal_api_version, __GLcontextModes ** driver_modes ); 168 169#ifndef DRI_NEW_INTERFACE_ONLY 170 171extern void *__driCreateScreen(Display *dpy, int scrn, __DRIscreen *psc, 172 int numConfigs, __GLXvisualConfig *config); 173 174/** This is optionally implemented in each driver */ 175extern void __driRegisterExtensions( void ); 176 177#endif /* DRI_NEW_INTERFACE_ONLY */ 178 179 180/** 181 * XML document describing the configuration options supported by the 182 * driver. 183 */ 184extern const char __driConfigOptions[]; 185 186/*@}*/ 187 188 189/** 190 * Stored version of some component (i.e., server-side DRI module, kernel-side 191 * DRM, etc.). 192 * 193 * \todo 194 * There are several data structures that explicitly store a major version, 195 * minor version, and patch level. These structures should be modified to 196 * have a \c __DRIversionRec instead. 197 */ 198struct __DRIversionRec { 199 int major; /**< Major version number. */ 200 int minor; /**< Minor version number. */ 201 int patch; /**< Patch-level. */ 202}; 203 204/** 205 * Framebuffer information record. Used by libGL to communicate information 206 * about the framebuffer to the driver's \c __driCreateNewScreen function. 207 * 208 * In XFree86, most of this information is derrived from data returned by 209 * calling \c XF86DRIGetDeviceInfo. 210 * 211 * \sa XF86DRIGetDeviceInfo __DRIdisplayRec::createNewScreen 212 * __driUtilCreateNewScreen CallCreateNewScreen 213 * 214 * \bug This structure could be better named. 215 */ 216struct __DRIframebufferRec { 217 unsigned char *base; /**< Framebuffer base address in the CPU's 218 * address space. This value is calculated by 219 * calling \c drmMap on the framebuffer handle 220 * returned by \c XF86DRIGetDeviceInfo (or a 221 * similar function). 222 */ 223 int size; /**< Framebuffer size, in bytes. */ 224 int stride; /**< Number of bytes from one line to the next. */ 225 int width; /**< Pixel width of the framebuffer. */ 226 int height; /**< Pixel height of the framebuffer. */ 227 int dev_priv_size; /**< Size of the driver's dev-priv structure. */ 228 void *dev_priv; /**< Pointer to the driver's dev-priv structure. */ 229}; 230 231 232/** 233 * Screen dependent methods. This structure is initialized during the 234 * \c __DRIdisplayRec::createScreen call. 235 */ 236struct __DRIscreenRec { 237 /** 238 * Method to destroy the private DRI screen data. 239 */ 240 void (*destroyScreen)(__DRInativeDisplay *dpy, int scrn, void *screenPrivate); 241 242 /** 243 * Method to create the private DRI context data and initialize the 244 * context dependent methods. 245 * 246 * \sa __DRIscreenRec::createNewContext driCreateContext 247 * driCreateNewContext 248 * 249 * \deprecated 250 * This function has been replaced by \c __DRIscreenRec::createNewContext. 251 * New drivers will continue to export this method, but it will eventually 252 * (in the next XFree86 major relearse) go away. 253 */ 254#ifndef DRI_NEW_INTERFACE_ONLY 255 void *(*createContext)(Display *dpy, XVisualInfo *vis, void *sharedPrivate, 256 __DRIcontext *pctx); 257#else 258 void * createContext; 259#endif /* DRI_NEW_INTERFACE_ONLY */ 260 261 /** 262 * Method to create the private DRI drawable data and initialize the 263 * drawable dependent methods. 264 */ 265 void *(*createNewDrawable)(__DRInativeDisplay *dpy, const __GLcontextModes *modes, 266 __DRIid draw, __DRIdrawable *pdraw, 267 int renderType, const int *attrs); 268 269 /** 270 * Method to return a pointer to the DRI drawable data. 271 */ 272 __DRIdrawable *(*getDrawable)(__DRInativeDisplay *dpy, __DRIid draw, 273 void *drawablePrivate); 274 275 /** 276 * Opaque pointer to private per screen direct rendering data. \c NULL 277 * if direct rendering is not supported on this screen. Never 278 * dereferenced in libGL. 279 */ 280 void *private; 281 282 /** 283 * Get the number of vertical refreshes since some point in time before 284 * this function was first called (i.e., system start up). 285 * 286 * \since Internal API version 20030317. 287 */ 288 int (*getMSC)( void *screenPrivate, int64_t *msc ); 289 290 /** 291 * Opaque pointer that points back to the containing 292 * \c __GLXscreenConfigs. This data structure is shared with DRI drivers 293 * but \c __GLXscreenConfigs is not. However, they are needed by some GLX 294 * functions called by DRI drivers. 295 * 296 * \since Internal API version 20030813. 297 */ 298 void *screenConfigs; 299 300 /** 301 * Functions associated with MESA_allocate_memory. 302 * 303 * \since Internal API version 20030815. 304 */ 305 /*@{*/ 306 void *(*allocateMemory)(__DRInativeDisplay *dpy, int scrn, GLsizei size, 307 GLfloat readfreq, GLfloat writefreq, 308 GLfloat priority); 309 310 void (*freeMemory)(__DRInativeDisplay *dpy, int scrn, GLvoid *pointer); 311 312 GLuint (*memoryOffset)(__DRInativeDisplay *dpy, int scrn, const GLvoid *pointer); 313 /*@}*/ 314 315 /** 316 * Method to create the private DRI context data and initialize the 317 * context dependent methods. 318 * 319 * \since Internal API version 20031201. 320 */ 321 void * (*createNewContext)(__DRInativeDisplay *dpy, const __GLcontextModes *modes, 322 int render_type, 323 void *sharedPrivate, __DRIcontext *pctx); 324}; 325 326/** 327 * Context dependent methods. This structure is initialized during the 328 * \c __DRIscreenRec::createContext call. 329 */ 330struct __DRIcontextRec { 331 /** 332 * Method to destroy the private DRI context data. 333 */ 334 void (*destroyContext)(__DRInativeDisplay *dpy, int scrn, void *contextPrivate); 335 336 /** 337 * Method to bind a DRI drawable to a DRI graphics context. 338 * 339 * \deprecated Replaced by bindContext3. 340 */ 341#ifndef DRI_NEW_INTERFACE_ONLY 342 Bool (*bindContext)(Display *dpy, int scrn, GLXDrawable draw, 343 GLXContext gc); 344#else 345 void *bindContext; 346#endif /* DRI_NEW_INTERFACE_ONLY */ 347 348 /** 349 * Method to unbind a DRI drawable to a DRI graphics context. 350 * 351 * \deprecated Replaced by unbindContext3. 352 */ 353#ifndef DRI_NEW_INTERFACE_ONLY 354 Bool (*unbindContext)(Display *dpy, int scrn, GLXDrawable draw, 355 GLXContext gc, int will_rebind); 356#else 357 void *unbindContext; 358#endif /* DRI_NEW_INTERFACE_ONLY */ 359 360 /** 361 * Opaque pointer to private per context direct rendering data. 362 * \c NULL if direct rendering is not supported on the display or 363 * screen used to create this context. Never dereferenced in libGL. 364 */ 365 void *private; 366 367 /** 368 * Method to bind a DRI drawable to a DRI graphics context. 369 * 370 * \since Internal API version 20030606. 371 * \deprecated Replaced by bindContext3. 372 */ 373#ifndef DRI_NEW_INTERFACE_ONLY 374 Bool (*bindContext2)(Display *dpy, int scrn, GLXDrawable draw, 375 GLXDrawable read, GLXContext gc); 376#else 377 void *bindContext2; 378#endif /* DRI_NEW_INTERFACE_ONLY */ 379 380 /** 381 * Method to unbind a DRI drawable from a DRI graphics context. 382 * 383 * \since Internal API version 20030606. 384 * \deprecated Replaced by unbindContext3. 385 */ 386#ifndef DRI_NEW_INTERFACE_ONLY 387 Bool (*unbindContext2)(Display *dpy, int scrn, GLXDrawable draw, 388 GLXDrawable read, GLXContext gc); 389#else 390 void *unbindContext2; 391#endif /* DRI_NEW_INTERFACE_ONLY */ 392 393 /** 394 * Pointer to the mode used to create this context. 395 * 396 * \since Internal API version 20040317. 397 */ 398 const __GLcontextModes * mode; 399 400 /** 401 * Method to bind a DRI drawable to a DRI graphics context. 402 * 403 * \since Internal API version 20040415. 404 */ 405 Bool (*bindContext3)(__DRInativeDisplay *dpy, int scrn, __DRIid draw, 406 __DRIid read, __DRIcontext *ctx); 407 408 /** 409 * Method to unbind a DRI drawable from a DRI graphics context. 410 * 411 * \since Internal API version 20040415. 412 */ 413 Bool (*unbindContext3)(__DRInativeDisplay *dpy, int scrn, __DRIid draw, 414 __DRIid read, __DRIcontext *ctx); 415}; 416 417/** 418 * Drawable dependent methods. This structure is initialized during the 419 * \c __DRIscreenRec::createDrawable call. \c createDrawable is not called 420 * by libGL at this time. It's currently used via the dri_util.c utility code 421 * instead. 422 */ 423struct __DRIdrawableRec { 424 /** 425 * Method to destroy the private DRI drawable data. 426 */ 427 void (*destroyDrawable)(__DRInativeDisplay *dpy, void *drawablePrivate); 428 429 /** 430 * Method to swap the front and back buffers. 431 */ 432 void (*swapBuffers)(__DRInativeDisplay *dpy, void *drawablePrivate); 433 434 /** 435 * Opaque pointer to private per drawable direct rendering data. 436 * \c NULL if direct rendering is not supported on the display or 437 * screen used to create this drawable. Never dereferenced in libGL. 438 */ 439 void *private; 440 441 /** 442 * Get the number of completed swap buffers for this drawable. 443 * 444 * \since Internal API version 20030317. 445 */ 446 int (*getSBC)(__DRInativeDisplay *dpy, void *drawablePrivate, int64_t *sbc ); 447 448 /** 449 * Wait for the SBC to be greater than or equal target_sbc. 450 * 451 * \since Internal API version 20030317. 452 */ 453 int (*waitForSBC)( __DRInativeDisplay * dpy, void *drawablePriv, 454 int64_t target_sbc, 455 int64_t * msc, int64_t * sbc ); 456 457 /** 458 * Wait for the MSC to equal target_msc, or, if that has already passed, 459 * the next time (MSC % divisor) is equal to remainder. If divisor is 460 * zero, the function will return as soon as MSC is greater than or equal 461 * to target_msc. 462 * 463 * \since Internal API version 20030317. 464 */ 465 int (*waitForMSC)( __DRInativeDisplay * dpy, void *drawablePriv, 466 int64_t target_msc, int64_t divisor, int64_t remainder, 467 int64_t * msc, int64_t * sbc ); 468 469 /** 470 * Like \c swapBuffers, but does NOT have an implicit \c glFlush. Once 471 * rendering is complete, waits until MSC is equal to target_msc, or 472 * if that has already passed, waits until (MSC % divisor) is equal 473 * to remainder. If divisor is zero, the swap will happen as soon as 474 * MSC is greater than or equal to target_msc. 475 * 476 * \since Internal API version 20030317. 477 */ 478 int64_t (*swapBuffersMSC)(__DRInativeDisplay *dpy, void *drawablePrivate, 479 int64_t target_msc, 480 int64_t divisor, int64_t remainder); 481 482 /** 483 * Enable or disable frame usage tracking. 484 * 485 * \since Internal API version 20030317. 486 */ 487 int (*frameTracking)(__DRInativeDisplay *dpy, void *drawablePrivate, Bool enable); 488 489 /** 490 * Retrieve frame usage information. 491 * 492 * \since Internal API version 20030317. 493 */ 494 int (*queryFrameTracking)(__DRInativeDisplay *dpy, void *drawablePrivate, 495 int64_t * sbc, int64_t * missedFrames, 496 float * lastMissedUsage, float * usage ); 497 498 /** 499 * Used by drivers that implement the GLX_SGI_swap_control or 500 * GLX_MESA_swap_control extension. 501 * 502 * \since Internal API version 20030317. 503 */ 504 unsigned swap_interval; 505}; 506 507#endif 508