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