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