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 #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 /*@{*/
  51 typedef struct __DRIdisplayRec  __DRIdisplay;
  52 typedef struct __DRIscreenRec   __DRIscreen;
  53 typedef struct __DRIcontextRec  __DRIcontext;
  54 typedef struct __DRIdrawableRec __DRIdrawable;
  55 typedef struct __DRIdriverRec   __DRIdriver;
  56 typedef struct __DRIframebufferRec __DRIframebuffer;
  57 typedef struct __DRIversionRec     __DRIversion;
  58 typedef struct __DRIinterfaceMethodsRec  __DRIinterfaceMethods;
  59 typedef unsigned long __DRIid;
  60 typedef 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  */
  76 typedef 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  */
  85 typedef 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  */
  92 typedef void (* PFNGLXSCRENABLEEXTENSIONPROC) ( void *psc, const char * name );
  93 /*@}*/
  94
  95
  96 /**
  97  * \name Functions and data provided by the driver.
  98  */
  99 /*@{*/
 100
 101 typedef 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);
 108 typedef CREATENEWSCREENFUNC* PFNCREATENEWSCREENFUNC;
 109 extern CREATENEWSCREENFUNC __driCreateNewScreen_20050727;
 110
 111
 112 /**
 113  * XML document describing the configuration options supported by the
 114  * driver.
 115  */
 116 extern 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  */
 130 struct __DRIversionRec {
 131     int    major;        /**< Major version number. */
 132     int    minor;        /**< Minor version number. */
 133     int    patch;        /**< Patch-level. */
 134 };
 135
 136
 137 typedef void (*__DRIfuncPtr)(void);
 138
 139 struct __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
 243 /**
 244  * Framebuffer information record.  Used by libGL to communicate information
 245  * about the framebuffer to the driver's \c __driCreateNewScreen function.
 246  *
 247  * In XFree86, most of this information is derrived from data returned by
 248  * calling \c XF86DRIGetDeviceInfo.
 249  *
 250  * \sa XF86DRIGetDeviceInfo __DRIdisplayRec::createNewScreen
 251  *     __driUtilCreateNewScreen CallCreateNewScreen
 252  *
 253  * \bug This structure could be better named.
 254  */
 255 struct __DRIframebufferRec {
 256     unsigned char *base;    /**< Framebuffer base address in the CPU's
 257                              * address space.  This value is calculated by
 258                              * calling \c drmMap on the framebuffer handle
 259                              * returned by \c XF86DRIGetDeviceInfo (or a
 260                              * similar function).
 261                              */
 262     int size;               /**< Framebuffer size, in bytes. */
 263     int stride;             /**< Number of bytes from one line to the next. */
 264     int width;              /**< Pixel width of the framebuffer. */
 265     int height;             /**< Pixel height of the framebuffer. */
 266     int dev_priv_size;      /**< Size of the driver's dev-priv structure. */
 267     void *dev_priv;         /**< Pointer to the driver's dev-priv structure. */
 268 };
 269
 270
 271 /**
 272  * Screen dependent methods.  This structure is initialized during the
 273  * \c __DRIdisplayRec::createScreen call.
 274  */
 275 struct __DRIscreenRec {
 276     /**
 277      * Method to destroy the private DRI screen data.
 278      */
 279     void (*destroyScreen)(__DRInativeDisplay *dpy, int scrn, void *screenPrivate);
 280
 281     /**
 282      * Method to create the private DRI drawable data and initialize the
 283      * drawable dependent methods.
 284      */
 285     void *(*createNewDrawable)(__DRInativeDisplay *dpy, const __GLcontextModes *modes,
 286                                __DRIid draw, __DRIdrawable *pdraw,
 287                                int renderType, const int *attrs);
 288
 289     /**
 290      * Method to return a pointer to the DRI drawable data.
 291      */
 292     __DRIdrawable *(*getDrawable)(__DRInativeDisplay *dpy, __DRIid draw,
 293                                   void *drawablePrivate);
 294
 295     /**
 296      * Opaque pointer to private per screen direct rendering data.  \c NULL
 297      * if direct rendering is not supported on this screen.  Never
 298      * dereferenced in libGL.
 299      */
 300     void *private;
 301
 302     /**
 303      * Get the number of vertical refreshes since some point in time before
 304      * this function was first called (i.e., system start up).
 305      *
 306      * \since Internal API version 20030317.
 307      */
 308     int (*getMSC)( void *screenPrivate, int64_t *msc );
 309
 310     /**
 311      * Opaque pointer that points back to the containing
 312      * \c __GLXscreenConfigs.  This data structure is shared with DRI drivers
 313      * but \c __GLXscreenConfigs is not. However, they are needed by some GLX
 314      * functions called by DRI drivers.
 315      *
 316      * \since Internal API version 20030813.
 317      */
 318     void *screenConfigs;
 319
 320     /**
 321      * Functions associated with MESA_allocate_memory.
 322      *
 323      * \since Internal API version 20030815.
 324      */
 325     /*@{*/
 326     void *(*allocateMemory)(__DRInativeDisplay *dpy, int scrn, GLsizei size,
 327                             GLfloat readfreq, GLfloat writefreq,
 328                             GLfloat priority);
 329
 330     void (*freeMemory)(__DRInativeDisplay *dpy, int scrn, GLvoid *pointer);
 331
 332     GLuint (*memoryOffset)(__DRInativeDisplay *dpy, int scrn, const GLvoid *pointer);
 333     /*@}*/
 334
 335     /**
 336      * Method to create the private DRI context data and initialize the
 337      * context dependent methods.
 338      *
 339      * \since Internal API version 20031201.
 340      */
 341     void * (*createNewContext)(__DRInativeDisplay *dpy, const __GLcontextModes *modes,
 342                                int render_type,
 343                                void *sharedPrivate, __DRIcontext *pctx);
 344 };
 345
 346 /**
 347  * Context dependent methods.  This structure is initialized during the
 348  * \c __DRIscreenRec::createContext call.
 349  */
 350 struct __DRIcontextRec {
 351     /**
 352      * Method to destroy the private DRI context data.
 353      */
 354     void (*destroyContext)(__DRInativeDisplay *dpy, int scrn, void *contextPrivate);
 355
 356     /**
 357      * Opaque pointer to private per context direct rendering data.
 358      * \c NULL if direct rendering is not supported on the display or
 359      * screen used to create this context.  Never dereferenced in libGL.
 360      */
 361     void *private;
 362
 363     /**
 364      * Pointer to the mode used to create this context.
 365      *
 366      * \since Internal API version 20040317.
 367      */
 368     const __GLcontextModes * mode;
 369
 370     /**
 371      * Method to bind a DRI drawable to a DRI graphics context.
 372      *
 373      * \since Internal API version 20050727.
 374      */
 375     GLboolean (*bindContext)(__DRInativeDisplay *dpy, int scrn, __DRIid draw,
 376                          __DRIid read, __DRIcontext *ctx);
 377
 378     /**
 379      * Method to unbind a DRI drawable from a DRI graphics context.
 380      *
 381      * \since Internal API version 20050727.
 382      */
 383     GLboolean (*unbindContext)(__DRInativeDisplay *dpy, int scrn, __DRIid draw,
 384                            __DRIid read, __DRIcontext *ctx);
 385 };
 386
 387 /**
 388  * Drawable dependent methods.  This structure is initialized during the
 389  * \c __DRIscreenRec::createDrawable call.  \c createDrawable is not called
 390  * by libGL at this time.  It's currently used via the dri_util.c utility code
 391  * instead.
 392  */
 393 struct __DRIdrawableRec {
 394     /**
 395      * Method to destroy the private DRI drawable data.
 396      */
 397     void (*destroyDrawable)(__DRInativeDisplay *dpy, void *drawablePrivate);
 398
 399     /**
 400      * Method to swap the front and back buffers.
 401      */
 402     void (*swapBuffers)(__DRInativeDisplay *dpy, void *drawablePrivate);
 403
 404     /**
 405      * Opaque pointer to private per drawable direct rendering data.
 406      * \c NULL if direct rendering is not supported on the display or
 407      * screen used to create this drawable.  Never dereferenced in libGL.
 408      */
 409     void *private;
 410
 411     /**
 412      * Get the number of completed swap buffers for this drawable.
 413      *
 414      * \since Internal API version 20030317.
 415      */
 416     int (*getSBC)(__DRInativeDisplay *dpy, void *drawablePrivate, int64_t *sbc );
 417
 418     /**
 419      * Wait for the SBC to be greater than or equal target_sbc.
 420      *
 421      * \since Internal API version 20030317.
 422      */
 423     int (*waitForSBC)( __DRInativeDisplay * dpy, void *drawablePriv,
 424                        int64_t target_sbc,
 425                        int64_t * msc, int64_t * sbc );
 426
 427     /**
 428      * Wait for the MSC to equal target_msc, or, if that has already passed,
 429      * the next time (MSC % divisor) is equal to remainder.  If divisor is
 430      * zero, the function will return as soon as MSC is greater than or equal
 431      * to target_msc.
 432      *
 433      * \since Internal API version 20030317.
 434      */
 435     int (*waitForMSC)( __DRInativeDisplay * dpy, void *drawablePriv,
 436                        int64_t target_msc, int64_t divisor, int64_t remainder,
 437                        int64_t * msc, int64_t * sbc );
 438
 439     /**
 440      * Like \c swapBuffers, but does NOT have an implicit \c glFlush.  Once
 441      * rendering is complete, waits until MSC is equal to target_msc, or
 442      * if that has already passed, waits until (MSC % divisor) is equal
 443      * to remainder.  If divisor is zero, the swap will happen as soon as
 444      * MSC is greater than or equal to target_msc.
 445      *
 446      * \since Internal API version 20030317.
 447      */
 448     int64_t (*swapBuffersMSC)(__DRInativeDisplay *dpy, void *drawablePrivate,
 449                               int64_t target_msc,
 450                               int64_t divisor, int64_t remainder);
 451
 452     /**
 453      * Enable or disable frame usage tracking.
 454      *
 455      * \since Internal API version 20030317.
 456      */
 457     int (*frameTracking)(__DRInativeDisplay *dpy, void *drawablePrivate, GLboolean enable);
 458
 459     /**
 460      * Retrieve frame usage information.
 461      *
 462      * \since Internal API version 20030317.
 463      */
 464     int (*queryFrameTracking)(__DRInativeDisplay *dpy, void *drawablePrivate,
 465                               int64_t * sbc, int64_t * missedFrames,
 466                               float * lastMissedUsage, float * usage );
 467
 468     /**
 469      * Used by drivers that implement the GLX_SGI_swap_control or
 470      * GLX_MESA_swap_control extension.
 471      *
 472      * \since Internal API version 20030317.
 473      */
 474     unsigned swap_interval;
 475
 476     /**
 477      * Used by drivers that implement the GLX_MESA_copy_sub_buffer extension.
 478      *
 479      * \since Internal API version 20060314.
 480      */
 481     void (*copySubBuffer)(__DRInativeDisplay *dpy, void *drawablePrivate,
 482                           int x, int y, int w, int h);
 483 };
 484
 485 #endif