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 #include <GL/internal/glcore.h>
45 * \name DRI interface structures
47 * The following structures define the interface between the GLX client
48 * side library and the DRI (direct rendering infrastructure).
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 typedef unsigned long __DRIid
;
60 typedef void __DRInativeDisplay
;
65 * \name Functions provided by the driver loader.
69 * Type of a pointer to \c glXGetScreenDriver, as returned by
70 * \c glXGetProcAddress. This function is used to get the name of the DRI
71 * driver for the specified screen of the specified display. The driver
72 * name is typically used with \c glXGetDriverConfig.
74 * \sa glXGetScreenDriver, glXGetProcAddress, glXGetDriverConfig
76 typedef const char * (* PFNGLXGETSCREENDRIVERPROC
) (__DRInativeDisplay
*dpy
, int scrNum
);
79 * Type of a pointer to \c glXGetDriverConfig, as returned by
80 * \c glXGetProcAddress. This function is used to get the XML document
81 * describing the configuration options available for the specified driver.
83 * \sa glXGetDriverConfig, glXGetProcAddress, glXGetScreenDriver
85 typedef const char * (* PFNGLXGETDRIVERCONFIGPROC
) (const char *driverName
);
88 * Type of a pointer to \c glxEnableExtension, as returned by
89 * \c __DRIinterfaceMethods::getProcAddress. This function is used to enable
90 * a GLX extension on the specified screen.
92 typedef void (* PFNGLXSCRENABLEEXTENSIONPROC
) ( void *psc
, const char * name
);
97 * \name Functions and data provided by the driver.
101 typedef void *(CREATENEWSCREENFUNC
)(__DRInativeDisplay
*dpy
, int scrn
,
102 __DRIscreen
*psc
, const __GLcontextModes
* modes
,
103 const __DRIversion
* ddx_version
, const __DRIversion
* dri_version
,
104 const __DRIversion
* drm_version
, const __DRIframebuffer
* frame_buffer
,
105 void * pSAREA
, int fd
, int internal_api_version
,
106 const __DRIinterfaceMethods
* interface
,
107 __GLcontextModes
** driver_modes
);
108 typedef CREATENEWSCREENFUNC
* PFNCREATENEWSCREENFUNC
;
109 extern CREATENEWSCREENFUNC __driCreateNewScreen_20050727
;
113 * XML document describing the configuration options supported by the
116 extern const char __driConfigOptions
[];
122 * Stored version of some component (i.e., server-side DRI module, kernel-side
126 * There are several data structures that explicitly store a major version,
127 * minor version, and patch level. These structures should be modified to
128 * have a \c __DRIversionRec instead.
130 struct __DRIversionRec
{
131 int major
; /**< Major version number. */
132 int minor
; /**< Minor version number. */
133 int patch
; /**< Patch-level. */
137 typedef void (*__DRIfuncPtr
)(void);
139 struct __DRIinterfaceMethodsRec
{
141 * Get pointer to named function.
143 __DRIfuncPtr (*getProcAddress
)( const char * proc_name
);
146 * Create a list of \c __GLcontextModes structures.
148 __GLcontextModes
* (*createContextModes
)(unsigned count
,
149 size_t minimum_bytes_per_struct
);
152 * Destroy a list of \c __GLcontextModes structures.
155 * Determine if the drivers actually need to call this.
157 void (*destroyContextModes
)( __GLcontextModes
* modes
);
160 * Get the \c __DRIscreen for a given display and screen number.
162 __DRIscreen
*(*getScreen
)(__DRInativeDisplay
*dpy
, int screenNum
);
166 * \name Client/server protocol functions.
168 * These functions implement the DRI client/server protocol for
169 * context and drawable operations. Platforms that do not implement
170 * the wire protocol (e.g., EGL) will implement glorified no-op functions.
174 * Determine if the specified window ID still exists.
177 * Implementations may assume that the driver will only pass an ID into
178 * this function that actually corresponds to a window. On
179 * implementations where windows can only be destroyed by the DRI driver
180 * (e.g., EGL), this function is allowed to always return \c GL_TRUE.
182 GLboolean (*windowExists
)(__DRInativeDisplay
*dpy
, __DRIid draw
);
185 * Create the server-side portion of the GL context.
187 GLboolean (* createContext
)( __DRInativeDisplay
*dpy
, int screenNum
,
188 int configID
, void * contextID
, drm_context_t
* hw_context
);
191 * Destroy the server-side portion of the GL context.
193 GLboolean (* destroyContext
)( __DRInativeDisplay
*dpy
, int screenNum
,
197 * Create the server-side portion of the drawable.
199 GLboolean (*createDrawable
)( __DRInativeDisplay
* ndpy
, int screen
,
200 __DRIid drawable
, drm_drawable_t
* hHWDrawable
);
203 * Destroy the server-side portion of the drawable.
205 GLboolean (*destroyDrawable
)( __DRInativeDisplay
* ndpy
, int screen
,
209 * This function is used to get information about the position, size, and
210 * clip rects of a drawable.
212 GLboolean (* getDrawableInfo
) ( __DRInativeDisplay
*dpy
, int scrn
,
213 __DRIid draw
, unsigned int * index
, unsigned int * stamp
,
214 int * x
, int * y
, int * width
, int * height
,
215 int * numClipRects
, drm_clip_rect_t
** pClipRects
,
216 int * backX
, int * backY
,
217 int * numBackClipRects
, drm_clip_rect_t
** pBackClipRects
);
222 * \name Timing related functions.
226 * Get the 64-bit unadjusted system time (UST).
228 int (*getUST
)(int64_t * ust
);
231 * Get the media stream counter (MSC) rate.
233 * Matching the definition in GLX_OML_sync_control, this function returns
234 * the rate of the "media stream counter". In practical terms, this is
235 * the frame refresh rate of the display.
237 GLboolean (*getMSCRate
)(__DRInativeDisplay
* dpy
, __DRIid drawable
,
238 int32_t * numerator
, int32_t * denominator
);
242 * Reports areas of the given drawable which have been modified by the
245 * \param drawable which the drawing was done to.
246 * \param rects rectangles affected, with the drawable origin as the
248 * \param x X offset of the drawable within the screen (used in the
250 * \param y Y offset of the drawable within the screen.
251 * \param front_buffer boolean flag for whether the drawing to the
252 * drawable was actually done directly to the front buffer (instead
253 * of backing storage, for example)
255 void (*reportDamage
)(__DRInativeDisplay
* dpy
, int screen
,
258 drm_clip_rect_t
*rects
, int num_rects
,
264 * Framebuffer information record. Used by libGL to communicate information
265 * about the framebuffer to the driver's \c __driCreateNewScreen function.
267 * In XFree86, most of this information is derrived from data returned by
268 * calling \c XF86DRIGetDeviceInfo.
270 * \sa XF86DRIGetDeviceInfo __DRIdisplayRec::createNewScreen
271 * __driUtilCreateNewScreen CallCreateNewScreen
273 * \bug This structure could be better named.
275 struct __DRIframebufferRec
{
276 unsigned char *base
; /**< Framebuffer base address in the CPU's
277 * address space. This value is calculated by
278 * calling \c drmMap on the framebuffer handle
279 * returned by \c XF86DRIGetDeviceInfo (or a
282 int size
; /**< Framebuffer size, in bytes. */
283 int stride
; /**< Number of bytes from one line to the next. */
284 int width
; /**< Pixel width of the framebuffer. */
285 int height
; /**< Pixel height of the framebuffer. */
286 int dev_priv_size
; /**< Size of the driver's dev-priv structure. */
287 void *dev_priv
; /**< Pointer to the driver's dev-priv structure. */
292 * Screen dependent methods. This structure is initialized during the
293 * \c __DRIdisplayRec::createScreen call.
295 struct __DRIscreenRec
{
297 * Method to destroy the private DRI screen data.
299 void (*destroyScreen
)(__DRInativeDisplay
*dpy
, int scrn
, void *screenPrivate
);
302 * Method to create the private DRI drawable data and initialize the
303 * drawable dependent methods.
305 void *(*createNewDrawable
)(__DRInativeDisplay
*dpy
, const __GLcontextModes
*modes
,
306 __DRIid draw
, __DRIdrawable
*pdraw
,
307 int renderType
, const int *attrs
);
310 * Method to return a pointer to the DRI drawable data.
312 __DRIdrawable
*(*getDrawable
)(__DRInativeDisplay
*dpy
, __DRIid draw
,
313 void *drawablePrivate
);
316 * Opaque pointer to private per screen direct rendering data. \c NULL
317 * if direct rendering is not supported on this screen. Never
318 * dereferenced in libGL.
323 * Get the number of vertical refreshes since some point in time before
324 * this function was first called (i.e., system start up).
326 * \since Internal API version 20030317.
328 int (*getMSC
)( void *screenPrivate
, int64_t *msc
);
331 * Opaque pointer that points back to the containing
332 * \c __GLXscreenConfigs. This data structure is shared with DRI drivers
333 * but \c __GLXscreenConfigs is not. However, they are needed by some GLX
334 * functions called by DRI drivers.
336 * \since Internal API version 20030813.
341 * Functions associated with MESA_allocate_memory.
343 * \since Internal API version 20030815.
346 void *(*allocateMemory
)(__DRInativeDisplay
*dpy
, int scrn
, GLsizei size
,
347 GLfloat readfreq
, GLfloat writefreq
,
350 void (*freeMemory
)(__DRInativeDisplay
*dpy
, int scrn
, GLvoid
*pointer
);
352 GLuint (*memoryOffset
)(__DRInativeDisplay
*dpy
, int scrn
, const GLvoid
*pointer
);
356 * Method to create the private DRI context data and initialize the
357 * context dependent methods.
359 * \since Internal API version 20031201.
361 void * (*createNewContext
)(__DRInativeDisplay
*dpy
, const __GLcontextModes
*modes
,
363 void *sharedPrivate
, __DRIcontext
*pctx
);
367 * Context dependent methods. This structure is initialized during the
368 * \c __DRIscreenRec::createContext call.
370 struct __DRIcontextRec
{
372 * Method to destroy the private DRI context data.
374 void (*destroyContext
)(__DRInativeDisplay
*dpy
, int scrn
, void *contextPrivate
);
377 * Opaque pointer to private per context direct rendering data.
378 * \c NULL if direct rendering is not supported on the display or
379 * screen used to create this context. Never dereferenced in libGL.
384 * Pointer to the mode used to create this context.
386 * \since Internal API version 20040317.
388 const __GLcontextModes
* mode
;
391 * Method to bind a DRI drawable to a DRI graphics context.
393 * \since Internal API version 20050727.
395 GLboolean (*bindContext
)(__DRInativeDisplay
*dpy
, int scrn
, __DRIid draw
,
396 __DRIid read
, __DRIcontext
*ctx
);
399 * Method to unbind a DRI drawable from a DRI graphics context.
401 * \since Internal API version 20050727.
403 GLboolean (*unbindContext
)(__DRInativeDisplay
*dpy
, int scrn
, __DRIid draw
,
404 __DRIid read
, __DRIcontext
*ctx
);
408 * Drawable dependent methods. This structure is initialized during the
409 * \c __DRIscreenRec::createDrawable call. \c createDrawable is not called
410 * by libGL at this time. It's currently used via the dri_util.c utility code
413 struct __DRIdrawableRec
{
415 * Method to destroy the private DRI drawable data.
417 void (*destroyDrawable
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
);
420 * Method to swap the front and back buffers.
422 void (*swapBuffers
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
);
425 * Opaque pointer to private per drawable direct rendering data.
426 * \c NULL if direct rendering is not supported on the display or
427 * screen used to create this drawable. Never dereferenced in libGL.
432 * Get the number of completed swap buffers for this drawable.
434 * \since Internal API version 20030317.
436 int (*getSBC
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
, int64_t *sbc
);
439 * Wait for the SBC to be greater than or equal target_sbc.
441 * \since Internal API version 20030317.
443 int (*waitForSBC
)( __DRInativeDisplay
* dpy
, void *drawablePriv
,
445 int64_t * msc
, int64_t * sbc
);
448 * Wait for the MSC to equal target_msc, or, if that has already passed,
449 * the next time (MSC % divisor) is equal to remainder. If divisor is
450 * zero, the function will return as soon as MSC is greater than or equal
453 * \since Internal API version 20030317.
455 int (*waitForMSC
)( __DRInativeDisplay
* dpy
, void *drawablePriv
,
456 int64_t target_msc
, int64_t divisor
, int64_t remainder
,
457 int64_t * msc
, int64_t * sbc
);
460 * Like \c swapBuffers, but does NOT have an implicit \c glFlush. Once
461 * rendering is complete, waits until MSC is equal to target_msc, or
462 * if that has already passed, waits until (MSC % divisor) is equal
463 * to remainder. If divisor is zero, the swap will happen as soon as
464 * MSC is greater than or equal to target_msc.
466 * \since Internal API version 20030317.
468 int64_t (*swapBuffersMSC
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
,
470 int64_t divisor
, int64_t remainder
);
473 * Enable or disable frame usage tracking.
475 * \since Internal API version 20030317.
477 int (*frameTracking
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
, GLboolean enable
);
480 * Retrieve frame usage information.
482 * \since Internal API version 20030317.
484 int (*queryFrameTracking
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
,
485 int64_t * sbc
, int64_t * missedFrames
,
486 float * lastMissedUsage
, float * usage
);
489 * Used by drivers that implement the GLX_SGI_swap_control or
490 * GLX_MESA_swap_control extension.
492 * \since Internal API version 20030317.
494 unsigned swap_interval
;
497 * Used by drivers that implement the GLX_MESA_copy_sub_buffer extension.
499 * \since Internal API version 20060314.
501 void (*copySubBuffer
)(__DRInativeDisplay
*dpy
, void *drawablePrivate
,
502 int x
, int y
, int w
, int h
);