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