dri_util.h revision efaf90b03e8b69e04909bce071f8ef6b65cc0e9d 
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
61typedef struct __DRIdisplayPrivateRec  __DRIdisplayPrivate;
62typedef struct __DRIscreenPrivateRec   __DRIscreenPrivate;
63typedef struct __DRIcontextPrivateRec  __DRIcontextPrivate;
64typedef struct __DRIdrawablePrivateRec __DRIdrawablePrivate;
65typedef struct __DRIswapInfoRec        __DRIswapInfo;
66typedef 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 */
74extern __GLcontextModes *__driDriverInitScreen(__DRIscreenPrivate *psp);
75
76/**
77 * Extensions.
78 */
79extern const __DRIcopySubBufferExtension driCopySubBufferExtension;
80extern 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)                            \
99do {                                                                    \
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 */
124struct __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
209struct __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 */
243struct __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 */
342struct __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 */
377struct __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 */
489struct __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
497extern void
498__driUtilMessage(const char *f, ...);
499
500
501extern void
502__driUtilUpdateDrawableInfo(__DRIdrawablePrivate *pdp);
503
504
505extern __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. */
513extern int
514driCompareGLXAPIVersion( GLint required_version );
515
516extern float
517driCalculateSwapUsage( __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 */
526extern const __DRIinterfaceMethods * dri_interface;
527
528#endif /* _DRI_UTIL_H_ */
529