include/GL/internal/dri_interface.h

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