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      * 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  */
 275 struct __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  */
 295 struct __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  */
 382 struct __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  */
 425 struct __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