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
  60 typedef struct __DRIextensionRec        __DRIextension;
  61 typedef struct __DRIcopySubBufferExtensionRec   __DRIcopySubBufferExtension;
  62 typedef struct __DRIswapControlExtensionRec     __DRIswapControlExtension;
  63 /*@}*/
  64
  65
  66 /**
  67  * Extension struct.  Drivers 'inherit' from this struct by embedding
  68  * it as the first element in the extension struct.  The
  69  * __DRIscreen::getExtensions entry point will return a list of these
  70  * structs and the loader can use the extensions it knows about by
  71  * casting it to a more specific extension and optionally advertising
  72  * the GLX extension.  See below for examples.
  73  */
  74 struct __DRIextensionRec {
  75     const char *name;
  76 };
  77
  78 /**
  79  * Used by drivers that implement the GLX_MESA_copy_sub_buffer extension.
  80  */
  81 #define __DRI_COPY_SUB_BUFFER "DRI_CopySubBuffer"
  82 struct __DRIcopySubBufferExtensionRec {
  83     __DRIextension base;
  84     void (*copySubBuffer)(__DRIdrawable *drawable, int x, int y, int w, int h);
  85 };
  86
  87 /**
  88  * Used by drivers that implement the GLX_SGI_swap_control or
  89  * GLX_MESA_swap_control extension.
  90  */
  91 #define __DRI_SWAP_CONTROL "DRI_SwapControl"
  92 struct __DRIswapControlExtensionRec {
  93     __DRIextension base;
  94     void (*setSwapInterval)(__DRIdrawable *drawable, unsigned int inteval);
  95     unsigned int (*getSwapInterval)(__DRIdrawable *drawable);
  96 };
  97
  98 /**
  99  * \name Functions provided by the driver loader.
 100  */
 101 /*@{*/
 102 /**
 103  * Type of a pointer to \c glXGetScreenDriver, as returned by
 104  * \c glXGetProcAddress.  This function is used to get the name of the DRI
 105  * driver for the specified screen of the specified display.  The driver
 106  * name is typically used with \c glXGetDriverConfig.
 107  *
 108  * \sa glXGetScreenDriver, glXGetProcAddress, glXGetDriverConfig
 109  */
 110 typedef const char * (* PFNGLXGETSCREENDRIVERPROC) (__DRIscreen *screen);
 111
 112 /**
 113  * Type of a pointer to \c glXGetDriverConfig, as returned by
 114  * \c glXGetProcAddress.  This function is used to get the XML document
 115  * describing the configuration options available for the specified driver.
 116  *
 117  * \sa glXGetDriverConfig, glXGetProcAddress, glXGetScreenDriver
 118  */
 119 typedef const char * (* PFNGLXGETDRIVERCONFIGPROC) (const char *driverName);
 120
 121 /**
 122  * Type of a pointer to \c glxEnableExtension, as returned by
 123  * \c __DRIinterfaceMethods::getProcAddress.  This function is used to enable
 124  * a GLX extension on the specified screen.
 125  */
 126 typedef void (* PFNGLXSCRENABLEEXTENSIONPROC) (__DRIscreen *screen,
 127                                                const char *name);
 128 /*@}*/
 129
 130
 131 /**
 132  * Macros for building symbol and strings.  Standard CPP two step...
 133  */
 134
 135 #define __DRI_REAL_STRINGIFY(x) # x
 136 #define __DRI_STRINGIFY(x) __DRI_REAL_STRINGIFY(x)
 137 #define __DRI_REAL_MAKE_VERSION(name, version) name ## _ ## version
 138 #define __DRI_MAKE_VERSION(name, version) __DRI_REAL_MAKE_VERSION(name, version)
 139
 140 #define __DRI_CREATE_NEW_SCREEN \
 141     __DRI_MAKE_VERSION(__driCreateNewScreen, __DRI_INTERFACE_VERSION)
 142
 143 #define __DRI_CREATE_NEW_SCREEN_STRING \
 144     __DRI_STRINGIFY(__DRI_CREATE_NEW_SCREEN)
 145
 146 /**
 147  * \name Functions and data provided by the driver.
 148  */
 149 /*@{*/
 150
 151 #define __DRI_INTERFACE_VERSION 20070105
 152
 153 typedef void *(CREATENEWSCREENFUNC)(int scr, __DRIscreen *psc,
 154     const __DRIversion * ddx_version, const __DRIversion * dri_version,
 155     const __DRIversion * drm_version, const __DRIframebuffer * frame_buffer,
 156     void * pSAREA, int fd, int internal_api_version,
 157     const __DRIinterfaceMethods * interface,
 158     __GLcontextModes ** driver_modes);
 159 typedef CREATENEWSCREENFUNC* PFNCREATENEWSCREENFUNC;
 160 extern CREATENEWSCREENFUNC __DRI_CREATE_NEW_SCREEN;
 161
 162
 163
 164 /**
 165  * XML document describing the configuration options supported by the
 166  * driver.
 167  */
 168 extern const char __driConfigOptions[];
 169
 170 /*@}*/
 171
 172
 173 /**
 174  * Stored version of some component (i.e., server-side DRI module, kernel-side
 175  * DRM, etc.).
 176  *
 177  * \todo
 178  * There are several data structures that explicitly store a major version,
 179  * minor version, and patch level.  These structures should be modified to
 180  * have a \c __DRIversionRec instead.
 181  */
 182 struct __DRIversionRec {
 183     int    major;        /**< Major version number. */
 184     int    minor;        /**< Minor version number. */
 185     int    patch;        /**< Patch-level. */
 186 };
 187
 188
 189 typedef void (*__DRIfuncPtr)(void);
 190
 191 struct __DRIinterfaceMethodsRec {
 192     /**
 193      * Get pointer to named function.
 194      */
 195     __DRIfuncPtr (*getProcAddress)( const char * proc_name );
 196
 197     /**
 198      * Create a list of \c __GLcontextModes structures.
 199      */
 200     __GLcontextModes * (*createContextModes)(unsigned count,
 201         size_t minimum_bytes_per_struct);
 202
 203     /**
 204      * Destroy a list of \c __GLcontextModes structures.
 205      *
 206      * \todo
 207      * Determine if the drivers actually need to call this.
 208      */
 209     void (*destroyContextModes)( __GLcontextModes * modes );
 210
 211
 212     /**
 213      * \name Client/server protocol functions.
 214      *
 215      * These functions implement the DRI client/server protocol for
 216      * context and drawable operations.  Platforms that do not implement
 217      * the wire protocol (e.g., EGL) will implement glorified no-op functions.
 218      */
 219     /*@{*/
 220
 221     /**
 222      * This function is used to get information about the position, size, and
 223      * clip rects of a drawable.
 224      */
 225     GLboolean (* getDrawableInfo) ( __DRIdrawable *drawable,
 226         unsigned int * index, unsigned int * stamp,
 227         int * x, int * y, int * width, int * height,
 228         int * numClipRects, drm_clip_rect_t ** pClipRects,
 229         int * backX, int * backY,
 230         int * numBackClipRects, drm_clip_rect_t ** pBackClipRects );
 231     /*@}*/
 232
 233
 234     /**
 235      * \name Timing related functions.
 236      */
 237     /*@{*/
 238     /**
 239      * Get the 64-bit unadjusted system time (UST).
 240      */
 241     int (*getUST)(int64_t * ust);
 242
 243     /**
 244      * Get the media stream counter (MSC) rate.
 245      *
 246      * Matching the definition in GLX_OML_sync_control, this function returns
 247      * the rate of the "media stream counter".  In practical terms, this is
 248      * the frame refresh rate of the display.
 249      */
 250     GLboolean (*getMSCRate)(__DRIdrawable *draw,
 251                             int32_t * numerator, int32_t * denominator);
 252     /*@}*/
 253
 254     /**
 255      * Reports areas of the given drawable which have been modified by the
 256      * driver.
 257      *
 258      * \param drawable which the drawing was done to.
 259      * \param rects rectangles affected, with the drawable origin as the
 260      *        origin.
 261      * \param x X offset of the drawable within the screen (used in the
 262      *        front_buffer case)
 263      * \param y Y offset of the drawable within the screen.
 264      * \param front_buffer boolean flag for whether the drawing to the
 265      *        drawable was actually done directly to the front buffer (instead
 266      *        of backing storage, for example)
 267      */
 268     void (*reportDamage)(__DRIdrawable *draw,
 269                          int x, int y,
 270                          drm_clip_rect_t *rects, int num_rects,
 271                          GLboolean front_buffer);
 272 };
 273
 274
 275 /**
 276  * Framebuffer information record.  Used by libGL to communicate information
 277  * about the framebuffer to the driver's \c __driCreateNewScreen function.
 278  *
 279  * In XFree86, most of this information is derrived from data returned by
 280  * calling \c XF86DRIGetDeviceInfo.
 281  *
 282  * \sa XF86DRIGetDeviceInfo __DRIdisplayRec::createNewScreen
 283  *     __driUtilCreateNewScreen CallCreateNewScreen
 284  *
 285  * \bug This structure could be better named.
 286  */
 287 struct __DRIframebufferRec {
 288     unsigned char *base;    /**< Framebuffer base address in the CPU's
 289                              * address space.  This value is calculated by
 290                              * calling \c drmMap on the framebuffer handle
 291                              * returned by \c XF86DRIGetDeviceInfo (or a
 292                              * similar function).
 293                              */
 294     int size;               /**< Framebuffer size, in bytes. */
 295     int stride;             /**< Number of bytes from one line to the next. */
 296     int width;              /**< Pixel width of the framebuffer. */
 297     int height;             /**< Pixel height of the framebuffer. */
 298     int dev_priv_size;      /**< Size of the driver's dev-priv structure. */
 299     void *dev_priv;         /**< Pointer to the driver's dev-priv structure. */
 300 };
 301
 302
 303 /**
 304  * Screen dependent methods.  This structure is initialized during the
 305  * \c __DRIdisplayRec::createScreen call.
 306  */
 307 struct __DRIscreenRec {
 308     /**
 309      * Method to destroy the private DRI screen data.
 310      */
 311     void (*destroyScreen)(__DRIscreen *screen);
 312
 313     /**
 314      * Method to get screen extensions.
 315      */
 316     const __DRIextension **(*getExtensions)(__DRIscreen *screen);
 317
 318     /**
 319      * Method to create the private DRI drawable data and initialize the
 320      * drawable dependent methods.
 321      */
 322     void *(*createNewDrawable)(__DRIscreen *screen,
 323                                const __GLcontextModes *modes,
 324                                __DRIdrawable *pdraw,
 325                                drm_drawable_t hwDrawable,
 326                                int renderType, const int *attrs);
 327
 328     /**
 329      * Opaque pointer to private per screen direct rendering data.  \c NULL
 330      * if direct rendering is not supported on this screen.  Never
 331      * dereferenced in libGL.
 332      */
 333     void *private;
 334
 335     /**
 336      * Get the number of vertical refreshes since some point in time before
 337      * this function was first called (i.e., system start up).
 338      *
 339      * \since Internal API version 20030317.
 340      */
 341     int (*getMSC)(__DRIscreen *screen, int64_t *msc);
 342
 343     /**
 344      * Functions associated with MESA_allocate_memory.
 345      *
 346      * \since Internal API version 20030815.
 347      */
 348     /*@{*/
 349     void *(*allocateMemory)(__DRIscreen *screen, GLsizei size,
 350                             GLfloat readfreq, GLfloat writefreq,
 351                             GLfloat priority);
 352
 353     void (*freeMemory)(__DRIscreen *screen, GLvoid *pointer);
 354
 355     GLuint (*memoryOffset)(__DRIscreen *screen, const GLvoid *pointer);
 356     /*@}*/
 357
 358     /**
 359      * Method to create the private DRI context data and initialize the
 360      * context dependent methods.
 361      *
 362      * \since Internal API version 20031201.
 363      */
 364     void * (*createNewContext)(__DRIscreen *screen,
 365                                const __GLcontextModes *modes,
 366                                int render_type,
 367                                void *sharedPrivate,
 368                                drm_context_t hwContext, __DRIcontext *pctx);
 369
 370     /**
 371      * Method to override base texture image with a driver specific 'offset'.
 372      * The depth passed in allows e.g. to ignore the alpha channel of texture
 373      * images where the non-alpha components don't occupy a whole texel.
 374      *
 375      * For GLX_EXT_texture_from_pixmap with AIGLX.
 376      *
 377      * \since Internal API version 20070121.
 378      */
 379     void (*setTexOffset)(__DRIcontext *pDRICtx, GLint texname,
 380                          unsigned long long offset, GLint depth, GLuint pitch);
 381 };
 382
 383 /**
 384  * Context dependent methods.  This structure is initialized during the
 385  * \c __DRIscreenRec::createContext call.
 386  */
 387 struct __DRIcontextRec {
 388     /**
 389      * Method to destroy the private DRI context data.
 390      */
 391     void (*destroyContext)(__DRIcontext *context);
 392
 393     /**
 394      * Opaque pointer to private per context direct rendering data.
 395      * \c NULL if direct rendering is not supported on the display or
 396      * screen used to create this context.  Never dereferenced in libGL.
 397      */
 398     void *private;
 399
 400     /**
 401      * Method to bind a DRI drawable to a DRI graphics context.
 402      *
 403      * \since Internal API version 20050727.
 404      */
 405     GLboolean (*bindContext)(__DRIcontext *ctx,
 406                              __DRIdrawable *pdraw,
 407                              __DRIdrawable *pread);
 408
 409     /**
 410      * Method to unbind a DRI drawable from a DRI graphics context.
 411      *
 412      * \since Internal API version 20050727.
 413      */
 414     GLboolean (*unbindContext)(__DRIcontext *ctx);
 415 };
 416
 417 /**
 418  * Drawable dependent methods.  This structure is initialized during the
 419  * \c __DRIscreenRec::createDrawable call.  \c createDrawable is not called
 420  * by libGL at this time.  It's currently used via the dri_util.c utility code
 421  * instead.
 422  */
 423 struct __DRIdrawableRec {
 424     /**
 425      * Method to destroy the private DRI drawable data.
 426      */
 427     void (*destroyDrawable)(__DRIdrawable *drawable);
 428
 429     /**
 430      * Method to swap the front and back buffers.
 431      */
 432     void (*swapBuffers)(__DRIdrawable *drawable);
 433
 434     /**
 435      * Opaque pointer to private per drawable direct rendering data.
 436      * \c NULL if direct rendering is not supported on the display or
 437      * screen used to create this drawable.  Never dereferenced in libGL.
 438      */
 439     void *private;
 440
 441     /**
 442      * Get the number of completed swap buffers for this drawable.
 443      *
 444      * \since Internal API version 20030317.
 445      */
 446     int (*getSBC)(__DRIdrawable *drawable, int64_t *sbc);
 447
 448     /**
 449      * Wait for the SBC to be greater than or equal target_sbc.
 450      *
 451      * \since Internal API version 20030317.
 452      */
 453     int (*waitForSBC)(__DRIdrawable *drawable,
 454                       int64_t target_sbc,
 455                       int64_t * msc, int64_t * sbc);
 456
 457     /**
 458      * Wait for the MSC to equal target_msc, or, if that has already passed,
 459      * the next time (MSC % divisor) is equal to remainder.  If divisor is
 460      * zero, the function will return as soon as MSC is greater than or equal
 461      * to target_msc.
 462      *
 463      * \since Internal API version 20030317.
 464      */
 465     int (*waitForMSC)(__DRIdrawable *drawable,
 466                       int64_t target_msc, int64_t divisor, int64_t remainder,
 467                       int64_t * msc, int64_t * sbc);
 468
 469     /**
 470      * Like \c swapBuffers, but does NOT have an implicit \c glFlush.  Once
 471      * rendering is complete, waits until MSC is equal to target_msc, or
 472      * if that has already passed, waits until (MSC % divisor) is equal
 473      * to remainder.  If divisor is zero, the swap will happen as soon as
 474      * MSC is greater than or equal to target_msc.
 475      *
 476      * \since Internal API version 20030317.
 477      */
 478     int64_t (*swapBuffersMSC)(__DRIdrawable *drawable,
 479                               int64_t target_msc,
 480                               int64_t divisor, int64_t remainder);
 481
 482     /**
 483      * Enable or disable frame usage tracking.
 484      *
 485      * \since Internal API version 20030317.
 486      */
 487     int (*frameTracking)(__DRIdrawable *drawable, GLboolean enable);
 488
 489     /**
 490      * Retrieve frame usage information.
 491      *
 492      * \since Internal API version 20030317.
 493      */
 494     int (*queryFrameTracking)(__DRIdrawable *drawable,
 495                               int64_t * sbc, int64_t * missedFrames,
 496                               float * lastMissedUsage, float * usage);
 497 };
 498
 499 #endif