src/mesa/drivers/dri/common/dri_util.h

   1 /* $XFree86: xc/lib/GL/dri/dri_util.h,v 1.1 2002/02/22 21:32:52 dawes Exp $ */
   2 /**
   3  * \file dri_util.h
   4  * DRI utility functions definitions.
   5  *
   6  * This module acts as glue between GLX and the actual hardware driver.  A DRI
   7  * driver doesn't really \e have to use any of this - it's optional.  But, some
   8  * useful stuff is done here that otherwise would have to be duplicated in most
   9  * drivers.
  10  *
  11  * Basically, these utility functions take care of some of the dirty details of
  12  * screen initialization, context creation, context binding, DRM setup, etc.
  13  *
  14  * These functions are compiled into each DRI driver so libGL.so knows nothing
  15  * about them.
  16  *
  17  * \sa dri_util.c.
  18  *
  19  * \author Kevin E. Martin <kevin@precisioninsight.com>
  20  * \author Brian Paul <brian@precisioninsight.com>
  21  */
  22
  23 /*
  24  * Copyright 1998-1999 Precision Insight, Inc., Cedar Park, Texas.
  25  * All Rights Reserved.
  26  *
  27  * Permission is hereby granted, free of charge, to any person obtaining a
  28  * copy of this software and associated documentation files (the
  29  * "Software"), to deal in the Software without restriction, including
  30  * without limitation the rights to use, copy, modify, merge, publish,
  31  * distribute, sub license, and/or sell copies of the Software, and to
  32  * permit persons to whom the Software is furnished to do so, subject to
  33  * the following conditions:
  34  *
  35  * The above copyright notice and this permission notice (including the
  36  * next paragraph) shall be included in all copies or substantial portions
  37  * of the Software.
  38  *
  39  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  40  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  41  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  42  * IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
  43  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  44  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  45  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  46  */
  47
  48
  49 #ifndef _DRI_UTIL_H_
  50 #define _DRI_UTIL_H_
  51
  52 #include <GL/gl.h>
  53 #include "drm.h"
  54 #include "drm_sarea.h"
  55 #include "xf86drm.h"
  56 #include "GL/internal/glcore.h"
  57 #include "GL/internal/dri_interface.h"
  58
  59 #define GLX_BAD_CONTEXT                    5
  60
  61 typedef struct __DRIdisplayPrivateRec  __DRIdisplayPrivate;
  62 typedef struct __DRIscreenPrivateRec   __DRIscreenPrivate;
  63 typedef struct __DRIcontextPrivateRec  __DRIcontextPrivate;
  64 typedef struct __DRIdrawablePrivateRec __DRIdrawablePrivate;
  65 typedef struct __DRIswapInfoRec        __DRIswapInfo;
  66 typedef struct __DRIutilversionRec2    __DRIutilversion2;
  67
  68
  69 /**
  70  * Driver specific entry point.  Implemented by the driver.  Called
  71  * from the top level createNewScreen entry point to initialize the
  72  * __DRIscreenPrivate struct.
  73  */
  74 extern __GLcontextModes *__driDriverInitScreen(__DRIscreenPrivate *psp);
  75
  76 /**
  77  * Extensions.
  78  */
  79 extern const __DRIcopySubBufferExtension driCopySubBufferExtension;
  80 extern const __DRIswapControlExtension driSwapControlExtension;
  81
  82 /**
  83  * Used by DRI_VALIDATE_DRAWABLE_INFO
  84  */
  85 #define DRI_VALIDATE_DRAWABLE_INFO_ONCE(pDrawPriv)              \
  86     do {                                                        \
  87         if (*(pDrawPriv->pStamp) != pDrawPriv->lastStamp) {     \
  88             __driUtilUpdateDrawableInfo(pDrawPriv);             \
  89         }                                                       \
  90     } while (0)
  91
  92
  93 /**
  94  * Utility macro to validate the drawable information.
  95  *
  96  * See __DRIdrawablePrivate::pStamp and __DRIdrawablePrivate::lastStamp.
  97  */
  98 #define DRI_VALIDATE_DRAWABLE_INFO(psp, pdp)                            \
  99 do {                                                                    \
 100     while (*(pdp->pStamp) != pdp->lastStamp) {                          \
 101         register unsigned int hwContext = psp->pSAREA->lock.lock &      \
 102                      ~(DRM_LOCK_HELD | DRM_LOCK_CONT);                  \
 103         DRM_UNLOCK(psp->fd, &psp->pSAREA->lock, hwContext);             \
 104                                                                         \
 105         DRM_SPINLOCK(&psp->pSAREA->drawable_lock, psp->drawLockID);     \
 106         DRI_VALIDATE_DRAWABLE_INFO_ONCE(pdp);                           \
 107         DRM_SPINUNLOCK(&psp->pSAREA->drawable_lock, psp->drawLockID);   \
 108                                                                         \
 109         DRM_LIGHT_LOCK(psp->fd, &psp->pSAREA->lock, hwContext);         \
 110     }                                                                   \
 111 } while (0)
 112
 113
 114 /**
 115  * Driver callback functions.
 116  *
 117  * Each DRI driver must have one of these structures with all the pointers set
 118  * to appropriate functions within the driver.
 119  *
 120  * When glXCreateContext() is called, for example, it'll call a helper function
 121  * dri_util.c which in turn will jump through the \a CreateContext pointer in
 122  * this structure.
 123  */
 124 struct __DriverAPIRec {
 125     /**
 126      * Screen destruction callback
 127      */
 128     void (*DestroyScreen)(__DRIscreenPrivate *driScrnPriv);
 129
 130     /**
 131      * Context creation callback
 132      */
 133     GLboolean (*CreateContext)(const __GLcontextModes *glVis,
 134                                __DRIcontextPrivate *driContextPriv,
 135                                void *sharedContextPrivate);
 136
 137     /**
 138      * Context destruction callback
 139      */
 140     void (*DestroyContext)(__DRIcontextPrivate *driContextPriv);
 141
 142     /**
 143      * Buffer (drawable) creation callback
 144      */
 145     GLboolean (*CreateBuffer)(__DRIscreenPrivate *driScrnPriv,
 146                               __DRIdrawablePrivate *driDrawPriv,
 147                               const __GLcontextModes *glVis,
 148                               GLboolean pixmapBuffer);
 149
 150     /**
 151      * Buffer (drawable) destruction callback
 152      */
 153     void (*DestroyBuffer)(__DRIdrawablePrivate *driDrawPriv);
 154
 155     /**
 156      * Buffer swapping callback
 157      */
 158     void (*SwapBuffers)(__DRIdrawablePrivate *driDrawPriv);
 159
 160     /**
 161      * Context activation callback
 162      */
 163     GLboolean (*MakeCurrent)(__DRIcontextPrivate *driContextPriv,
 164                              __DRIdrawablePrivate *driDrawPriv,
 165                              __DRIdrawablePrivate *driReadPriv);
 166
 167     /**
 168      * Context unbinding callback
 169      */
 170     GLboolean (*UnbindContext)(__DRIcontextPrivate *driContextPriv);
 171
 172     /**
 173      * Retrieves statistics about buffer swap operations.  Required if
 174      * GLX_OML_sync_control or GLX_MESA_swap_frame_usage is supported.
 175      */
 176     int (*GetSwapInfo)( __DRIdrawablePrivate *dPriv, __DRIswapInfo * sInfo );
 177
 178
 179     /**
 180      * Required if GLX_SGI_video_sync or GLX_OML_sync_control is
 181      * supported.
 182      */
 183     int (*GetMSC)( __DRIscreenPrivate * priv, int64_t * count );
 184
 185     /**
 186      * These are required if GLX_OML_sync_control is supported.
 187      */
 188     /*@{*/
 189     int (*WaitForMSC)( __DRIdrawablePrivate *priv, int64_t target_msc,
 190                        int64_t divisor, int64_t remainder,
 191                        int64_t * msc );
 192     int (*WaitForSBC)( __DRIdrawablePrivate *priv, int64_t target_sbc,
 193                        int64_t * msc, int64_t * sbc );
 194
 195     int64_t (*SwapBuffersMSC)( __DRIdrawablePrivate *priv, int64_t target_msc,
 196                                int64_t divisor, int64_t remainder );
 197     /*@}*/
 198     void (*CopySubBuffer)(__DRIdrawablePrivate *driDrawPriv,
 199                           int x, int y, int w, int h);
 200
 201     /**
 202      * See corresponding field in \c __DRIscreenRec.
 203      */
 204     void (*setTexOffset)(__DRIcontext *pDRICtx, GLint texname,
 205                          unsigned long long offset, GLint depth, GLuint pitch);
 206 };
 207
 208
 209 struct __DRIswapInfoRec {
 210     /**
 211      * Number of swapBuffers operations that have been *completed*.
 212      */
 213     u_int64_t swap_count;
 214
 215     /**
 216      * Unadjusted system time of the last buffer swap.  This is the time
 217      * when the swap completed, not the time when swapBuffers was called.
 218      */
 219     int64_t   swap_ust;
 220
 221     /**
 222      * Number of swap operations that occurred after the swap deadline.  That
 223      * is if a swap happens more than swap_interval frames after the previous
 224      * swap, it has missed its deadline.  If swap_interval is 0, then the
 225      * swap deadline is 1 frame after the previous swap.
 226      */
 227     u_int64_t swap_missed_count;
 228
 229     /**
 230      * Amount of time used by the last swap that missed its deadline.  This
 231      * is calculated as (__glXGetUST() - swap_ust) / (swap_interval *
 232      * time_for_single_vrefresh)).  If the actual value of swap_interval is
 233      * 0, then 1 is used instead.  If swap_missed_count is non-zero, this
 234      * should be greater-than 1.0.
 235      */
 236     float     swap_missed_usage;
 237 };
 238
 239
 240 /**
 241  * Per-drawable private DRI driver information.
 242  */
 243 struct __DRIdrawablePrivateRec {
 244     /**
 245      * Kernel drawable handle
 246      */
 247     drm_drawable_t hHWDrawable;
 248
 249     /**
 250      * Driver's private drawable information.
 251      *
 252      * This structure is opaque.
 253      */
 254     void *driverPrivate;
 255
 256     /**
 257      * X's drawable ID associated with this private drawable.
 258      */
 259     __DRIdrawable *pdraw;
 260
 261     /**
 262      * Reference count for number of context's currently bound to this
 263      * drawable.
 264      *
 265      * Once it reaches zero, the drawable can be destroyed.
 266      *
 267      * \note This behavior will change with GLX 1.3.
 268      */
 269     int refcount;
 270
 271     /**
 272      * Index of this drawable information in the SAREA.
 273      */
 274     unsigned int index;
 275
 276     /**
 277      * Pointer to the "drawable has changed ID" stamp in the SAREA.
 278      */
 279     unsigned int *pStamp;
 280
 281     /**
 282      * Last value of the stamp.
 283      *
 284      * If this differs from the value stored at __DRIdrawablePrivate::pStamp,
 285      * then the drawable information has been modified by the X server, and the
 286      * drawable information (below) should be retrieved from the X server.
 287      */
 288     unsigned int lastStamp;
 289
 290     /**
 291      * \name Drawable
 292      *
 293      * Drawable information used in software fallbacks.
 294      */
 295     /*@{*/
 296     int x;
 297     int y;
 298     int w;
 299     int h;
 300     int numClipRects;
 301     drm_clip_rect_t *pClipRects;
 302     /*@}*/
 303
 304     /**
 305      * \name Back and depthbuffer
 306      *
 307      * Information about the back and depthbuffer where different from above.
 308      */
 309     /*@{*/
 310     int backX;
 311     int backY;
 312     int backClipRectType;
 313     int numBackClipRects;
 314     drm_clip_rect_t *pBackClipRects;
 315     /*@}*/
 316
 317     /**
 318      * Pointer to context to which this drawable is currently bound.
 319      */
 320     __DRIcontextPrivate *driContextPriv;
 321
 322     /**
 323      * Pointer to screen on which this drawable was created.
 324      */
 325     __DRIscreenPrivate *driScreenPriv;
 326
 327     /**
 328      * Called via glXSwapBuffers().
 329      */
 330     void (*swapBuffers)( __DRIdrawablePrivate *dPriv );
 331
 332     /**
 333      * Controls swap interval as used by GLX_SGI_swap_control and
 334      * GLX_MESA_swap_control.
 335      */
 336     unsigned int swap_interval;
 337 };
 338
 339 /**
 340  * Per-context private driver information.
 341  */
 342 struct __DRIcontextPrivateRec {
 343     /**
 344      * Kernel context handle used to access the device lock.
 345      */
 346     drm_context_t hHWContext;
 347
 348     /**
 349      * Device driver's private context data.  This structure is opaque.
 350      */
 351     void *driverPrivate;
 352
 353     /**
 354      * Pointer back to the \c __DRIcontext that contains this structure.
 355      */
 356     __DRIcontext *pctx;
 357
 358     /**
 359      * Pointer to drawable currently bound to this context for drawing.
 360      */
 361     __DRIdrawablePrivate *driDrawablePriv;
 362
 363     /**
 364      * Pointer to drawable currently bound to this context for reading.
 365      */
 366     __DRIdrawablePrivate *driReadablePriv;
 367
 368     /**
 369      * Pointer to screen on which this context was created.
 370      */
 371     __DRIscreenPrivate *driScreenPriv;
 372 };
 373
 374 /**
 375  * Per-screen private driver information.
 376  */
 377 struct __DRIscreenPrivateRec {
 378     /**
 379      * Current screen's number
 380      */
 381     int myNum;
 382
 383     /**
 384      * Callback functions into the hardware-specific DRI driver code.
 385      */
 386     struct __DriverAPIRec DriverAPI;
 387
 388     /**
 389      * DDX / 2D driver version information.
 390      */
 391     __DRIversion ddx_version;
 392
 393     /**
 394      * DRI X extension version information.
 395      */
 396     __DRIversion dri_version;
 397
 398     /**
 399      * DRM (kernel module) version information.
 400      */
 401     __DRIversion drm_version;
 402
 403     /**
 404      * ID used when the client sets the drawable lock.
 405      *
 406      * The X server uses this value to detect if the client has died while
 407      * holding the drawable lock.
 408      */
 409     int drawLockID;
 410
 411     /**
 412      * File descriptor returned when the kernel device driver is opened.
 413      *
 414      * Used to:
 415      *   - authenticate client to kernel
 416      *   - map the frame buffer, SAREA, etc.
 417      *   - close the kernel device driver
 418      */
 419     int fd;
 420
 421     /**
 422      * SAREA pointer
 423      *
 424      * Used to access:
 425      *   - the device lock
 426      *   - the device-independent per-drawable and per-context(?) information
 427      */
 428     drm_sarea_t *pSAREA;
 429
 430     /**
 431      * \name Direct frame buffer access information
 432      * Used for software fallbacks.
 433      */
 434     /*@{*/
 435     unsigned char *pFB;
 436     int fbSize;
 437     int fbOrigin;
 438     int fbStride;
 439     int fbWidth;
 440     int fbHeight;
 441     int fbBPP;
 442     /*@}*/
 443
 444     /**
 445      * \name Device-dependent private information (stored in the SAREA).
 446      *
 447      * This data is accessed by the client driver only.
 448      */
 449     /*@{*/
 450     void *pDevPriv;
 451     int devPrivSize;
 452     /*@}*/
 453
 454     /**
 455      * Dummy context to which drawables are bound when not bound to any
 456      * other context.
 457      *
 458      * A dummy hHWContext is created for this context, and is used by the GL
 459      * core when a hardware lock is required but the drawable is not currently
 460      * bound (e.g., potentially during a SwapBuffers request).  The dummy
 461      * context is created when the first "real" context is created on this
 462      * screen.
 463      */
 464     __DRIcontextPrivate dummyContextPriv;
 465
 466     /**
 467      * Device-dependent private information (not stored in the SAREA).
 468      *
 469      * This pointer is never touched by the DRI layer.
 470      */
 471     void *private;
 472
 473     /**
 474      * Pointer back to the \c __DRIscreen that contains this structure.
 475      */
 476     __DRIscreen *psc;
 477
 478     /**
 479      * Extensions provided by this driver.
 480      */
 481     const __DRIextension **extensions;
 482 };
 483
 484
 485 /**
 486  * Used to store a version which includes a major range instead of a single
 487  * major version number.
 488  */
 489 struct __DRIutilversionRec2 {
 490     int    major_min;    /** min allowed Major version number. */
 491     int    major_max;    /** max allowed Major version number. */
 492     int    minor;        /**< Minor version number. */
 493     int    patch;        /**< Patch-level. */
 494 };
 495
 496
 497 extern void
 498 __driUtilMessage(const char *f, ...);
 499
 500
 501 extern void
 502 __driUtilUpdateDrawableInfo(__DRIdrawablePrivate *pdp);
 503
 504
 505 extern __DRIscreenPrivate * __driUtilCreateNewScreen( int scr, __DRIscreen *psc,
 506     __GLcontextModes * modes,
 507     const __DRIversion * ddx_version, const __DRIversion * dri_version,
 508     const __DRIversion * drm_version, const __DRIframebuffer * frame_buffer,
 509     drm_sarea_t *pSAREA, int fd, int internal_api_version,
 510     const struct __DriverAPIRec *driverAPI );
 511
 512 /* Test the version of the internal GLX API.  Returns a value like strcmp. */
 513 extern int
 514 driCompareGLXAPIVersion( GLint required_version );
 515
 516 extern float
 517 driCalculateSwapUsage( __DRIdrawablePrivate *dPriv,
 518                        int64_t last_swap_ust, int64_t current_ust );
 519
 520 /**
 521  * Pointer to the \c __DRIinterfaceMethods passed to the driver by the loader.
 522  *
 523  * This pointer is set in the driver's \c __driCreateNewScreen function and
 524  * is defined in dri_util.c.
 525  */
 526 extern const __DRIinterfaceMethods * dri_interface;
 527
 528 #endif /* _DRI_UTIL_H_ */