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