3 * \brief DRI utility functions definitions.
5 * This module acts as glue between GLX and the actual hardware driver. A DRI
6 * driver doesn't really \e have to use any of this - it's optional. But, some
7 * useful stuff is done here that otherwise would have to be duplicated in most
10 * Basically, these utility functions take care of some of the dirty details of
11 * screen initialization, context creation, context binding, DRM setup, etc.
13 * These functions are compiled into each DRI driver so libGL.so knows nothing
16 * Look for more comments in the dri_util.c file.
18 * \author Kevin E. Martin <kevin@precisioninsight.com>
19 * \author Brian Paul <brian@precisioninsight.com>
23 * Copyright 1998-1999 Precision Insight, Inc., Cedar Park, Texas.
24 * All Rights Reserved.
26 * Permission is hereby granted, free of charge, to any person obtaining a
27 * copy of this software and associated documentation files (the
28 * "Software"), to deal in the Software without restriction, including
29 * without limitation the rights to use, copy, modify, merge, publish,
30 * distribute, sub license, and/or sell copies of the Software, and to
31 * permit persons to whom the Software is furnished to do so, subject to
32 * the following conditions:
34 * The above copyright notice and this permission notice (including the
35 * next paragraph) shall be included in all copies or substantial portions
38 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
39 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
40 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
41 * IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
42 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
43 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
44 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
52 #include "dri.h" /* public entry points */
53 #include "sarea.h" /* for XF86DRISAREAPtr */
57 typedef unsigned long CARD32
;
58 typedef int (* PFNGLXGETUSTPROC
) ( uint64_t * ust
);
60 typedef struct __DRIdisplayPrivateRec __DRIdisplayPrivate
; /**< \brief Alias for __DRIdisplayPrivateRec */
61 typedef struct __DRIscreenPrivateRec __DRIscreenPrivate
; /**< \brief Alias for __DRIscreenPrivateRec */
62 typedef struct __DRIcontextPrivateRec __DRIcontextPrivate
; /**< \brief Alias for __DRIcontextPrivateRec */
63 typedef struct __DRIdrawablePrivateRec __DRIdrawablePrivate
; /**< \brief Alias for __DRIdrawablePrivateRec */
64 typedef struct __DRIswapInfoRec __DRIswapInfo
; /**< \brief Alias for __DRIswapInfoPrivateRec */
68 * Used by DRI_VALIDATE_DRAWABLE_INFO
70 #define DRI_VALIDATE_DRAWABLE_INFO_ONCE(pDrawPriv) \
72 if (*(pDrawPriv->pStamp) != pDrawPriv->lastStamp) { \
73 __driUtilUpdateDrawableInfo(pDrawPriv); \
79 * \brief Utility macro to validate the drawable information.
81 * See __DRIdrawablePrivateRec::pStamp and __DRIdrawablePrivateRec::lastStamp.
83 #define DRI_VALIDATE_DRAWABLE_INFO(psp, pdp) \
85 DRI_VALIDATE_DRAWABLE_INFO_ONCE(pdp); \
90 * Driver callback functions.
92 * Each DRI driver must have one of these structures with all the pointers set
93 * to appropriate functions within the driver.
95 * When glXCreateContext() is called, for example, it'll call a helper function
96 * dri_util.c which in turn will jump through the \a CreateContext pointer in
99 struct __DriverAPIRec
{
101 * Driver initialization callback
103 GLboolean (*InitDriver
)(__DRIscreenPrivate
*driScrnPriv
);
106 * Screen destruction callback
108 void (*DestroyScreen
)(__DRIscreenPrivate
*driScrnPriv
);
111 * Context creation callback
113 GLboolean (*CreateContext
)(const __GLcontextModes
*glVis
,
114 __DRIcontextPrivate
*driContextPriv
,
115 void *sharedContextPrivate
);
118 * Context destruction callback
120 void (*DestroyContext
)(__DRIcontextPrivate
*driContextPriv
);
123 * Buffer (drawable) creation callback
125 GLboolean (*CreateBuffer
)(__DRIscreenPrivate
*driScrnPriv
,
126 __DRIdrawablePrivate
*driDrawPriv
,
127 const __GLcontextModes
*glVis
,
128 GLboolean pixmapBuffer
);
131 * Buffer (drawable) destruction callback
133 void (*DestroyBuffer
)(__DRIdrawablePrivate
*driDrawPriv
);
136 * Buffer swapping callback
138 void (*SwapBuffers
)(__DRIdrawablePrivate
*driDrawPriv
);
141 * Context activation callback
143 GLboolean (*MakeCurrent
)(__DRIcontextPrivate
*driContextPriv
,
144 __DRIdrawablePrivate
*driDrawPriv
,
145 __DRIdrawablePrivate
*driReadPriv
);
148 * Context unbinding callback
150 GLboolean (*UnbindContext
)(__DRIcontextPrivate
*driContextPriv
);
153 * Full screen mode opening callback.
155 * \deprecated Full screen functionality is no longer used by DRI.
156 * Drivers should simply install a function returning
157 * \c GL_TRUE for backwards compatability.
159 GLboolean (*OpenFullScreen
)(__DRIcontextPrivate
*driContextPriv
);
162 * Full screen mode closing callback.
164 * \deprecated Full screen functionality is no longer used by DRI.
165 * Drivers should simply install a function returning
166 * \c GL_TRUE for backwards compatability.
168 GLboolean (*CloseFullScreen
)(__DRIcontextPrivate
*driContextPriv
);
170 /* Retrieves statistics about buffer swap operations. Required if
171 * GLX_OML_sync_control or GLX_MESA_swap_frame_usage is supported.
173 int (*GetSwapInfo
)( __DRIdrawablePrivate
*dPriv
, __DRIswapInfo
* sInfo
);
176 /* Required if GLX_SGI_video_sync or GLX_OML_sync_control is
179 int (*GetMSC
)( __DRIscreenPrivate
* priv
, int64_t * count
);
182 * These are required if GLX_OML_sync_control is supported.
185 int (*WaitForMSC
)( __DRIdrawablePrivate
*priv
, int64_t target_msc
,
186 int64_t divisor
, int64_t remainder
,
188 int (*WaitForSBC
)( __DRIdrawablePrivate
*priv
, int64_t target_sbc
,
189 int64_t * msc
, int64_t * sbc
);
191 int64_t (*SwapBuffersMSC
)( __DRIdrawablePrivate
*priv
, int64_t target_msc
,
192 int64_t divisor
, int64_t remainder
);
197 struct __DRIswapInfoRec
{
199 * Number of swapBuffers operations that have been *completed*.
204 * Unadjusted system time of the last buffer swap. This is the time
205 * when the swap completed, not the time when swapBuffers was called.
210 * Number of swap operations that occurred after the swap deadline. That
211 * is if a swap happens more than swap_interval frames after the previous
212 * swap, it has missed its deadline. If swap_interval is 0, then the
213 * swap deadline is 1 frame after the previous swap.
215 uint64_t swap_missed_count
;
218 * Amount of time used by the last swap that missed its deadline. This
219 * is calculated as (__glXGetUST() - swap_ust) / (swap_interval *
220 * time_for_single_vrefresh)). If the actual value of swap_interval is
221 * 0, then 1 is used instead. If swap_missed_count is non-zero, this
222 * should be greater-than 1.0.
224 float swap_missed_usage
;
229 * \brief Per-drawable private DRI driver information.
232 struct __DRIdrawablePrivateRec
{
235 * \brief Public entry points
240 * \brief Kernel drawable handle
242 * \note Not currently used.
244 drmDrawable hHWDrawable
;
247 * \brief Driver's private drawable information.
249 * This structure is opaque.
254 * \brief Reference count for number of context's currently bound to this
257 * Once it reaches zero, the drawable can be destroyed.
259 * \note This behavior will change with GLX 1.3.
264 * \brief Index of this drawable information in the SAREA.
269 * \brief Pointer to the "drawable has changed ID" stamp in the SAREA.
271 unsigned int *pStamp
;
274 * \brief Last value of the stamp.
276 * If this differs from the value stored at
277 * __DRIdrawablePrivateRec::pStamp, then the drawable information has been
278 * modified by the X server, and the drawable information (below) should be
279 * retrieved from the X server.
281 unsigned int lastStamp
;
285 * Drawable information used in software fallbacks.
293 XF86DRIClipRectPtr pClipRects
;
297 * \name Back and depthbuffer
298 * Information about the back and depthbuffer where different from above.
303 int backClipRectType
;
304 int numBackClipRects
;
305 XF86DRIClipRectPtr pBackClipRects
;
309 * \brief Pointer to context to which this drawable is currently bound.
311 __DRIcontextPrivate
*driContextPriv
;
314 * \brief Pointer to screen on which this drawable was created.
316 __DRIscreenPrivate
*driScreenPriv
;
329 * \brief Called via glXSwapBuffers().
331 void (*swapBuffers
)( __DRIdrawablePrivate
*dPriv
);
335 * \brief Per-context private driver information.
337 struct __DRIcontextPrivateRec
{
339 * \brief Public entry points
344 * \brief Kernel context handle used to access the device lock.
346 drmContext hHWContext
;
349 * \brief Device driver's private context data. This structure is opaque.
354 * \brief Pointer to drawable currently bound to this context.
356 __DRIdrawablePrivate
*driDrawablePriv
;
359 * \brief Pointer to screen on which this context was created.
361 __DRIscreenPrivate
*driScreenPriv
;
365 * \brief Per-screen private driver information.
367 struct __DRIscreenPrivateRec
{
370 * \brief Public entry points
375 * \brief Callback functions into the hardware-specific DRI driver code.
377 struct __DriverAPIRec DriverAPI
;
381 * DDX / 2D driver version information.
391 * DRI X extension version information.
401 * DRM (kernel module) version information.
410 * \brief ID used when the client sets the drawable lock.
412 * The X server uses this value to detect if the client has died while
413 * holding the drawable lock.
418 * \brief File descriptor returned when the kernel device driver is opened.
421 * - authenticate client to kernel
422 * - map the frame buffer, SAREA, etc.
423 * - close the kernel device driver
428 * \brief SAREA pointer
432 * - the device-independent per-drawable and per-context(?) information
434 XF86DRISAREAPtr pSAREA
;
437 * \name Direct frame buffer access information
438 * Used for software fallbacks.
451 * \name Device-dependent private information (stored in the SAREA).
453 * This data is accessed by the client driver only.
461 * \brief Dummy context to which drawables are bound when not bound to any
464 * A dummy hHWContext is created for this context, and is used by the GL
465 * core when a hardware lock is required but the drawable is not currently
466 * bound (e.g., potentially during a SwapBuffers request). The dummy
467 * context is created when the first "real" context is created on this
470 __DRIcontextPrivate dummyContextPriv
;
473 * \brief Hash table to hold the drawable information for this screen.
478 * \brief Device-dependent private information (not stored in the SAREA).
480 * This pointer is never touched by the DRI layer.
485 * \brief Full screen mode.
487 * If we're in full screen mode (via DRIOpenFullScreen()), this points to
488 * the drawable that was bound. Otherwise, this is NULL.
490 __DRIdrawablePrivate
*fullscreen
;
494 __driUtilMessage(const char *f
, ...);
498 __driUtilUpdateDrawableInfo(__DRIdrawablePrivate
*pdp
);
501 extern __DRIscreenPrivate
*
502 __driUtilCreateScreen(struct DRIDriverRec
*driver
,
503 struct DRIDriverContextRec
*driverContext
,
504 const struct __DriverAPIRec
*driverAPI
);
507 __driUtilCreateScreenNoDRM(struct DRIDriverRec
*driver
,
508 struct DRIDriverContextRec
*driverContext
,
509 const struct __DriverAPIRec
*driverAPI
);
512 driCalculateSwapUsage( __DRIdrawablePrivate
*dPriv
,
513 int64_t last_swap_ust
, int64_t current_ust
);
515 /* Test the version of the internal GLX API. Returns a value like strcmp. */
517 driCompareGLXAPIVersion( GLuint required_version
);
519 /** This is optionally implemented in each driver */
521 __driRegisterExtensions( void );
523 #endif /* _DRI_UTIL_H_ */