2 * Copyright 1998-1999 Precision Insight, Inc., Cedar Park, Texas.
3 * (C) Copyright IBM Corporation 2004
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:
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
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.
27 * \file dri_interface.h
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.
34 * \author Kevin E. Martin <kevin@precisioninsight.com>
35 * \author Ian Romanick <idr@us.ibm.com>
38 #ifndef DRI_INTERFACE_H
39 #define DRI_INTERFACE_H
41 #ifndef DRI_NEW_INTERFACE_ONLY
44 # include "GL/glxint.h"
47 #include <GL/internal/glcore.h>
52 * \name DRI interface structures
54 * The following structures define the interface between the GLX client
55 * side library and the DRI (direct rendering infrastructure).
58 typedef struct __DRIdisplayRec __DRIdisplay
;
59 typedef struct __DRIscreenRec __DRIscreen
;
60 typedef struct __DRIcontextRec __DRIcontext
;
61 typedef struct __DRIdrawableRec __DRIdrawable
;
62 typedef struct __DRIdriverRec __DRIdriver
;
63 typedef struct __DRIframebufferRec __DRIframebuffer
;
64 typedef struct __DRIversionRec __DRIversion
;
65 typedef unsigned long __DRIid
;
66 typedef void __DRInativeDisplay
;
71 * \name Functions provided by the driver loader.
74 extern __DRIscreen
*__glXFindDRIScreen(__DRInativeDisplay
*dpy
, int scrn
);
78 * Type of a pointer to \c __glXGetInternalVersion, as returned by
79 * \c glXGetProcAddress.
81 * \sa __glXGetInternalVersion, glXGetProcAddress
83 typedef int (* PFNGLXGETINTERNALVERSIONPROC
) ( void );
86 * Type of a pointer to \c __glXWindowExists, as returned by
87 * \c glXGetProcAddress.
89 * \sa __glXWindowExists, glXGetProcAddress
91 typedef GLboolean (* PFNGLXWINDOWEXISTSPROC
) (__DRInativeDisplay
*dpy
, __DRIid draw
);
94 * Type of a pointer to \c __glXGetUST, as returned by \c glXGetProcAddress.
96 * \sa __glXGetUST, glXGetProcAddress
98 typedef int (* PFNGLXGETUSTPROC
) ( int64_t * ust
);
101 * Type of pointer to \c __glXCreateContextModes, as returned by
102 * \c glXGetProcAddress.
104 * \sa _gl_context_modes_create, glXGetProcAddress
107 typedef __GLcontextModes
* (* PFNGLXCREATECONTEXTMODES
) ( unsigned count
,
108 size_t minimum_bytes_per_struct
);
111 * Type of a pointer to \c glXGetScreenDriver, as returned by
112 * \c glXGetProcAddress. This function is used to get the name of the DRI
113 * driver for the specified screen of the specified display. The driver
114 * name is typically used with \c glXGetDriverConfig.
116 * \sa glXGetScreenDriver, glXGetProcAddress, glXGetDriverConfig
118 typedef const char * (* PFNGLXGETSCREENDRIVERPROC
) (__DRInativeDisplay
*dpy
, int scrNum
);
121 * Type of a pointer to \c glXGetDriverConfig, as returned by
122 * \c glXGetProcAddress. This function is used to get the XML document
123 * describing the configuration options available for the specified driver.
125 * \sa glXGetDriverConfig, glXGetProcAddress, glXGetScreenDriver
127 typedef const char * (* PFNGLXGETDRIVERCONFIGPROC
) (const char *driverName
);
130 * Type of a pointer to \c __glXScrEnableExtension, as returned by
131 * \c glXGetProcAddress. This function is used to enable a GLX extension
132 * on the specified screen.
134 * \sa __glXScrEnableExtension, glXGetProcAddress
136 typedef void (* PFNGLXSCRENABLEEXTENSIONPROC
) ( void *psc
, const char * name
);
139 * Type of a pointer to \c __glXGetDrawableInfo, as returned by
140 * \c glXGetProcAddress. This function is used to get information about the
141 * position, size, and clip rects of a drawable.
143 * \sa __glXGetDrawableInfo, glXGetProcAddress
145 typedef GLboolean (* PFNGLXGETDRAWABLEINFOPROC
) ( __DRInativeDisplay
*dpy
, int scrn
,
146 __DRIid draw
, unsigned int * index
, unsigned int * stamp
,
147 int * x
, int * y
, int * width
, int * height
,
148 int * numClipRects
, drm_clip_rect_t
** pClipRects
,
149 int * backX
, int * backY
,
150 int * numBackClipRects
, drm_clip_rect_t
** pBackClipRects
);
152 extern GLboolean
XF86DRIDestroyContext( __DRInativeDisplay
*dpy
, int screen
,
153 __DRIid context_id
);
155 extern GLboolean
XF86DRICreateDrawable( __DRInativeDisplay
*dpy
, int screen
,
156 __DRIid drawable
, drm_drawable_t
*hHWDrawable
);
158 extern GLboolean
XF86DRIDestroyDrawable( __DRInativeDisplay
*dpy
, int screen
,
164 * \name Functions and data provided by the driver.
168 typedef void *(CREATENEWSCREENFUNC
)(__DRInativeDisplay
*dpy
, int scrn
,
169 __DRIscreen
*psc
, const __GLcontextModes
* modes
,
170 const __DRIversion
* ddx_version
, const __DRIversion
* dri_version
,
171 const __DRIversion
* drm_version
, const __DRIframebuffer
* frame_buffer
,
172 void * pSAREA
, int fd
, int internal_api_version
,
173 __GLcontextModes
** driver_modes
);
174 typedef CREATENEWSCREENFUNC
* PFNCREATENEWSCREENFUNC
;
175 extern CREATENEWSCREENFUNC __driCreateNewScreen
;
177 #ifndef DRI_NEW_INTERFACE_ONLY
179 extern void *__driCreateScreen(Display
*dpy
, int scrn
, __DRIscreen
*psc
,
180 int numConfigs
, __GLXvisualConfig
*config
);
182 #endif /* DRI_NEW_INTERFACE_ONLY */
186 * XML document describing the configuration options supported by the
189 extern const char __driConfigOptions
[];
195 * Stored version of some component (i.e., server-side DRI module, kernel-side
199 * There are several data structures that explicitly store a major version,
200 * minor version, and patch level. These structures should be modified to
201 * have a \c __DRIversionRec instead.
203 struct __DRIversionRec
{
204 int major
; /**< Major version number. */
205 int minor
; /**< Minor version number. */
206 int patch
; /**< Patch-level. */
210 * Framebuffer information record. Used by libGL to communicate information
211 * about the framebuffer to the driver's \c __driCreateNewScreen function.
213 * In XFree86, most of this information is derrived from data returned by
214 * calling \c XF86DRIGetDeviceInfo.
216 * \sa XF86DRIGetDeviceInfo __DRIdisplayRec::createNewScreen
217 * __driUtilCreateNewScreen CallCreateNewScreen
219 * \bug This structure could be better named.
221 struct __DRIframebufferRec
{
222 unsigned char *base
; /**< Framebuffer base address in the CPU's
223 * address space. This value is calculated by
224 * calling \c drmMap on the framebuffer handle
225 * returned by \c XF86DRIGetDeviceInfo (or a
228 int size
; /**< Framebuffer size, in bytes. */
229 int stride
; /**< Number of bytes from one line to the next. */
230 int width
; /**< Pixel width of the framebuffer. */
231 int height
; /**< Pixel height of the framebuffer. */
232 int dev_priv_size
; /**< Size of the driver's dev-priv structure. */
233 void *dev_priv
; /**< Pointer to the driver's dev-priv structure. */
238 * Screen dependent methods. This structure is initialized during the
239 * \c __DRIdisplayRec::createScreen call.
241 struct __DRIscreenRec
{
243 * Method to destroy the private DRI screen data.
245 void (*destroyScreen
)(__DRInativeDisplay
*dpy
, int scrn
, void *screenPrivate
);
248 * Method to create the private DRI context data and initialize the
249 * context dependent methods.
251 * \sa __DRIscreenRec::createNewContext driCreateContext
252 * driCreateNewContext
255 * This function has been replaced by \c __DRIscreenRec::createNewContext.
256 * New drivers will continue to export this method, but it will eventually
257 * (in the next XFree86 major relearse) go away.
259 #ifndef DRI_NEW_INTERFACE_ONLY
260 void *(*createContext
)(Display
*dpy
, XVisualInfo
*vis
, void *sharedPrivate
,
263 void * createContext
;
264 #endif /* DRI_NEW_INTERFACE_ONLY */
267 * Method to create the private DRI drawable data and initialize the
268 * drawable dependent methods.
270 void *(*createNewDrawable
)(__DRInativeDisplay
*dpy
, const __GLcontextModes
*modes
,
271 __DRIid draw
, __DRIdrawable
*pdraw
,
272 int renderType
, const int *attrs
);
275 * Method to return a pointer to the DRI drawable data.
277 __DRIdrawable
*(*getDrawable
)(__DRInativeDisplay
*dpy
, __DRIid draw
,
278 void *drawablePrivate
);
281 * Opaque pointer to private per screen direct rendering data. \c NULL
282 * if direct rendering is not supported on this screen. Never
283 * dereferenced in libGL.
288 * Get the number of vertical refreshes since some point in time before
289 * this function was first called (i.e., system start up).
291 * \since Internal API version 20030317.
293 int (*getMSC
)( void *screenPrivate
, int64_t *msc
);
296 * Opaque pointer that points back to the containing
297 * \c __GLXscreenConfigs. This data structure is shared with DRI drivers
298 * but \c __GLXscreenConfigs is not. However, they are needed by some GLX
299 * functions called by DRI drivers.
301 * \since Internal API version 20030813.
306 * Functions associated with MESA_allocate_memory.
308 * \since Internal API version 20030815.
311 void *(*allocateMemory
)(__DRInativeDisplay
*dpy
, int scrn
, GLsizei size
,
312 GLfloat readfreq
, GLfloat writefreq
,
315 void (*freeMemory
)(__DRInativeDisplay
*dpy
, int scrn
, GLvoid
*pointer
);
317 GLuint (*memoryOffset
)(__DRInativeDisplay
*dpy
, int scrn
, const GLvoid
*pointer
);
321 * Method to create the private DRI context data and initialize the
322 * context dependent methods.
324 * \since Internal API version 20031201.
326 void * (*createNewContext
)(__DRInativeDisplay
*dpy
, const __GLcontextModes
*modes
,
328 void *sharedPrivate
, __DRIcontext
*pctx
);
332 * Context dependent methods. This structure is initialized during the
333 * \c __DRIscreenRec::createContext call.
335 struct __DRIcontextRec
{
337 * Method to destroy the private DRI context data.
339 void (*destroyContext
)(__DRInativeDisplay
*dpy
, int scrn
, void *contextPrivate
);
342 * Method to bind a DRI drawable to a DRI graphics context.
344 * \deprecated Replaced by bindContext3.
346 #ifndef DRI_NEW_INTERFACE_ONLY
347 Bool (*bindContext
)(Display
*dpy
, int scrn
, GLXDrawable draw
,
351 #endif /* DRI_NEW_INTERFACE_ONLY */
354 * Method to unbind a DRI drawable to a DRI graphics context.
356 * \deprecated Replaced by unbindContext3.
358 #ifndef DRI_NEW_INTERFACE_ONLY
359 Bool (*unbindContext
)(Display
*dpy
, int scrn
, GLXDrawable draw
,
360 GLXContext gc
, int will_rebind
);
363 #endif /* DRI_NEW_INTERFACE_ONLY */
366 * Opaque pointer to private per context direct rendering data.
367 * \c NULL if direct rendering is not supported on the display or
368 * screen used to create this context. Never dereferenced in libGL.
373 * Method to bind a DRI drawable to a DRI graphics context.
375 * \since Internal API version 20030606.
376 * \deprecated Replaced by bindContext3.
378 #ifndef DRI_NEW_INTERFACE_ONLY
379 Bool (*bindContext2
)(Display
*dpy
, int scrn
, GLXDrawable draw
,
380 GLXDrawable read
, GLXContext gc
);
383 #endif /* DRI_NEW_INTERFACE_ONLY */
386 * Method to unbind a DRI drawable from a DRI graphics context.
388 * \since Internal API version 20030606.
389 * \deprecated Replaced by unbindContext3.
391 #ifndef DRI_NEW_INTERFACE_ONLY
392 Bool (*unbindContext2
)(Display
*dpy
, int scrn
, GLXDrawable draw
,
393 GLXDrawable read
, GLXContext gc
);
395 void *unbindContext2
;
396 #endif /* DRI_NEW_INTERFACE_ONLY */
399 * Pointer to the mode used to create this context.
401 * \since Internal API version 20040317.
403 const __GLcontextModes
* mode
;
406 * Method to bind a DRI drawable to a DRI graphics context.
408 * \since Internal API version 20040415.
410 GLboolean (*bindContext3
)(__DRInativeDisplay
*dpy
, int scrn
, __DRIid draw
,
411 __DRIid read
, __DRIcontext
*ctx
);
414 * Method to unbind a DRI drawable from a DRI graphics context.
416 * \since Internal API version 20040415.
418 GLboolean (*unbindContext3
)(__DRInativeDisplay
*dpy
, int scrn
, __DRIid draw
,
419 __DRIid read
, __DRIcontext
*ctx
);
423 * Drawable dependent methods. This structure is initialized during the
424 * \c __DRIscreenRec::createDrawable call. \c createDrawable is not called
425 * by libGL at this time. It's currently used via the dri_util.c utility code
428 struct __DRIdrawableRec
{
430 * Method to destroy the private DRI drawable data.
432 void (*destroyDrawable
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
);
435 * Method to swap the front and back buffers.
437 void (*swapBuffers
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
);
440 * Opaque pointer to private per drawable direct rendering data.
441 * \c NULL if direct rendering is not supported on the display or
442 * screen used to create this drawable. Never dereferenced in libGL.
447 * Get the number of completed swap buffers for this drawable.
449 * \since Internal API version 20030317.
451 int (*getSBC
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
, int64_t *sbc
);
454 * Wait for the SBC to be greater than or equal target_sbc.
456 * \since Internal API version 20030317.
458 int (*waitForSBC
)( __DRInativeDisplay
* dpy
, void *drawablePriv
,
460 int64_t * msc
, int64_t * sbc
);
463 * Wait for the MSC to equal target_msc, or, if that has already passed,
464 * the next time (MSC % divisor) is equal to remainder. If divisor is
465 * zero, the function will return as soon as MSC is greater than or equal
468 * \since Internal API version 20030317.
470 int (*waitForMSC
)( __DRInativeDisplay
* dpy
, void *drawablePriv
,
471 int64_t target_msc
, int64_t divisor
, int64_t remainder
,
472 int64_t * msc
, int64_t * sbc
);
475 * Like \c swapBuffers, but does NOT have an implicit \c glFlush. Once
476 * rendering is complete, waits until MSC is equal to target_msc, or
477 * if that has already passed, waits until (MSC % divisor) is equal
478 * to remainder. If divisor is zero, the swap will happen as soon as
479 * MSC is greater than or equal to target_msc.
481 * \since Internal API version 20030317.
483 int64_t (*swapBuffersMSC
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
,
485 int64_t divisor
, int64_t remainder
);
488 * Enable or disable frame usage tracking.
490 * \since Internal API version 20030317.
492 int (*frameTracking
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
, GLboolean enable
);
495 * Retrieve frame usage information.
497 * \since Internal API version 20030317.
499 int (*queryFrameTracking
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
,
500 int64_t * sbc
, int64_t * missedFrames
,
501 float * lastMissedUsage
, float * usage
);
504 * Used by drivers that implement the GLX_SGI_swap_control or
505 * GLX_MESA_swap_control extension.
507 * \since Internal API version 20030317.
509 unsigned swap_interval
;