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