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