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;
60 typedef struct __DRIextensionRec __DRIextension;
61 typedef struct __DRIcopySubBufferExtensionRec __DRIcopySubBufferExtension;
62 typedef struct __DRIswapControlExtensionRec __DRIswapControlExtension;
63 typedef struct __DRIallocateExtensionRec __DRIallocateExtension;
64 typedef struct __DRIframeTrackingExtensionRec __DRIframeTrackingExtension;
65 typedef struct __DRImediaStreamCounterExtensionRec __DRImediaStreamCounterExtension;
66 typedef struct __DRItexOffsetExtensionRec __DRItexOffsetExtension;
71 * Extension struct. Drivers 'inherit' from this struct by embedding
72 * it as the first element in the extension struct. The
73 * __DRIscreen::getExtensions entry point will return a list of these
74 * structs and the loader can use the extensions it knows about by
75 * casting it to a more specific extension and optionally advertising
76 * the GLX extension. See below for examples.
78 * We never break API in for a DRI extension. If we need to change
79 * the way things work in a non-backwards compatible manner, we
80 * introduce a new extension. During a transition period, we can
81 * leave both the old and the new extension in the driver, which
82 * allows us to move to the new interface without having to update the
83 * loader(s) in lock step.
85 * However, we can add entry points to an extension over time as long
86 * as we don't break the old ones. As we add entry points to an
87 * extension, we increase the version number. The corresponding
88 * #define can be used to guard code that accesses the new entry
89 * points at compile time and the version field in the extension
90 * struct can be used at run-time to determine how to use the
93 struct __DRIextensionRec {
99 * Used by drivers to indicate support for setting the read drawable.
101 #define __DRI_READ_DRAWABLE "DRI_ReadDrawable"
102 #define __DRI_READ_DRAWABLE_VERSION 1
105 * Used by drivers that implement the GLX_MESA_copy_sub_buffer extension.
107 #define __DRI_COPY_SUB_BUFFER "DRI_CopySubBuffer"
108 #define __DRI_COPY_SUB_BUFFER_VERSION 1
109 struct __DRIcopySubBufferExtensionRec {
111 void (*copySubBuffer)(__DRIdrawable *drawable, int x, int y, int w, int h);
115 * Used by drivers that implement the GLX_SGI_swap_control or
116 * GLX_MESA_swap_control extension.
118 #define __DRI_SWAP_CONTROL "DRI_SwapControl"
119 #define __DRI_SWAP_CONTROL_VERSION 1
120 struct __DRIswapControlExtensionRec {
122 void (*setSwapInterval)(__DRIdrawable *drawable, unsigned int inteval);
123 unsigned int (*getSwapInterval)(__DRIdrawable *drawable);
127 * Used by drivers that implement the GLX_MESA_allocate_memory.
129 #define __DRI_ALLOCATE "DRI_Allocate"
130 #define __DRI_ALLOCATE_VERSION 1
131 struct __DRIallocateExtensionRec {
134 void *(*allocateMemory)(__DRIscreen *screen, GLsizei size,
135 GLfloat readfreq, GLfloat writefreq,
138 void (*freeMemory)(__DRIscreen *screen, GLvoid *pointer);
140 GLuint (*memoryOffset)(__DRIscreen *screen, const GLvoid *pointer);
144 * Used by drivers that implement the GLX_MESA_swap_frame_usage extension.
146 #define __DRI_FRAME_TRACKING "DRI_FrameTracking"
147 #define __DRI_FRAME_TRACKING_VERSION 1
148 struct __DRIframeTrackingExtensionRec {
152 * Enable or disable frame usage tracking.
154 * \since Internal API version 20030317.
156 int (*frameTracking)(__DRIdrawable *drawable, GLboolean enable);
159 * Retrieve frame usage information.
161 * \since Internal API version 20030317.
163 int (*queryFrameTracking)(__DRIdrawable *drawable,
164 int64_t * sbc, int64_t * missedFrames,
165 float * lastMissedUsage, float * usage);
170 * Used by drivers that implement the GLX_SGI_video_sync extension.
172 #define __DRI_MEDIA_STREAM_COUNTER "DRI_MediaStreamCounter"
173 #define __DRI_MEDIA_STREAM_COUNTER_VERSION 2
174 struct __DRImediaStreamCounterExtensionRec {
178 * Get the number of vertical refreshes since some point in time before
179 * this function was first called (i.e., system start up).
181 int (*getMSC)(__DRIscreen *screen, int64_t *msc);
184 * Wait for the MSC to equal target_msc, or, if that has already passed,
185 * the next time (MSC % divisor) is equal to remainder. If divisor is
186 * zero, the function will return as soon as MSC is greater than or equal
189 int (*waitForMSC)(__DRIdrawable *drawable,
190 int64_t target_msc, int64_t divisor, int64_t remainder,
191 int64_t * msc, int64_t * sbc);
194 * Like the screen version of getMSC, but also takes a drawable so that
195 * the appropriate pipe's counter can be retrieved.
197 * Get the number of vertical refreshes since some point in time before
198 * this function was first called (i.e., system start up).
200 * \since Internal API version 2
202 int (*getDrawableMSC)(__DRIscreen *screen, void *drawablePrivate,
207 #define __DRI_TEX_OFFSET "DRI_TexOffset"
208 #define __DRI_TEX_OFFSET_VERSION 1
209 struct __DRItexOffsetExtensionRec {
213 * Method to override base texture image with a driver specific 'offset'.
214 * The depth passed in allows e.g. to ignore the alpha channel of texture
215 * images where the non-alpha components don't occupy a whole texel.
217 * For GLX_EXT_texture_from_pixmap with AIGLX.
219 void (*setTexOffset)(__DRIcontext *pDRICtx, GLint texname,
220 unsigned long long offset, GLint depth, GLuint pitch);
225 * Macros for building symbol and strings. Standard CPP two step...
228 #define __DRI_REAL_STRINGIFY(x) # x
229 #define __DRI_STRINGIFY(x) __DRI_REAL_STRINGIFY(x)
230 #define __DRI_REAL_MAKE_VERSION(name, version) name ## _ ## version
231 #define __DRI_MAKE_VERSION(name, version) __DRI_REAL_MAKE_VERSION(name, version)
233 #define __DRI_CREATE_NEW_SCREEN \
234 __DRI_MAKE_VERSION(__driCreateNewScreen, __DRI_INTERFACE_VERSION)
236 #define __DRI_CREATE_NEW_SCREEN_STRING \
237 __DRI_STRINGIFY(__DRI_CREATE_NEW_SCREEN)
240 * \name Functions and data provided by the driver.
244 #define __DRI_INTERFACE_VERSION 20070105
246 typedef void *(CREATENEWSCREENFUNC)(int scr, __DRIscreen *psc,
247 const __DRIversion * ddx_version, const __DRIversion * dri_version,
248 const __DRIversion * drm_version, const __DRIframebuffer * frame_buffer,
249 void * pSAREA, int fd, int internal_api_version,
250 const __DRIinterfaceMethods * interface,
251 __GLcontextModes ** driver_modes);
252 typedef CREATENEWSCREENFUNC* PFNCREATENEWSCREENFUNC;
253 extern CREATENEWSCREENFUNC __DRI_CREATE_NEW_SCREEN;
258 * XML document describing the configuration options supported by the
261 extern const char __driConfigOptions[];
267 * Stored version of some component (i.e., server-side DRI module, kernel-side
271 * There are several data structures that explicitly store a major version,
272 * minor version, and patch level. These structures should be modified to
273 * have a \c __DRIversionRec instead.
275 struct __DRIversionRec {
276 int major; /**< Major version number. */
277 int minor; /**< Minor version number. */
278 int patch; /**< Patch-level. */
282 typedef void (*__DRIfuncPtr)(void);
284 struct __DRIinterfaceMethodsRec {
286 * Create a list of \c __GLcontextModes structures.
288 __GLcontextModes * (*createContextModes)(unsigned count,
289 size_t minimum_bytes_per_struct);
292 * Destroy a list of \c __GLcontextModes structures.
295 * Determine if the drivers actually need to call this.
297 void (*destroyContextModes)( __GLcontextModes * modes );
301 * \name Client/server protocol functions.
303 * These functions implement the DRI client/server protocol for
304 * context and drawable operations. Platforms that do not implement
305 * the wire protocol (e.g., EGL) will implement glorified no-op functions.
310 * This function is used to get information about the position, size, and
311 * clip rects of a drawable.
313 GLboolean (* getDrawableInfo) ( __DRIdrawable *drawable,
314 unsigned int * index, unsigned int * stamp,
315 int * x, int * y, int * width, int * height,
316 int * numClipRects, drm_clip_rect_t ** pClipRects,
317 int * backX, int * backY,
318 int * numBackClipRects, drm_clip_rect_t ** pBackClipRects );
323 * \name Timing related functions.
327 * Get the 64-bit unadjusted system time (UST).
329 int (*getUST)(int64_t * ust);
332 * Get the media stream counter (MSC) rate.
334 * Matching the definition in GLX_OML_sync_control, this function returns
335 * the rate of the "media stream counter". In practical terms, this is
336 * the frame refresh rate of the display.
338 GLboolean (*getMSCRate)(__DRIdrawable *draw,
339 int32_t * numerator, int32_t * denominator);
343 * Reports areas of the given drawable which have been modified by the
346 * \param drawable which the drawing was done to.
347 * \param rects rectangles affected, with the drawable origin as the
349 * \param x X offset of the drawable within the screen (used in the
351 * \param y Y offset of the drawable within the screen.
352 * \param front_buffer boolean flag for whether the drawing to the
353 * drawable was actually done directly to the front buffer (instead
354 * of backing storage, for example)
356 void (*reportDamage)(__DRIdrawable *draw,
358 drm_clip_rect_t *rects, int num_rects,
359 GLboolean front_buffer);
364 * Framebuffer information record. Used by libGL to communicate information
365 * about the framebuffer to the driver's \c __driCreateNewScreen function.
367 * In XFree86, most of this information is derrived from data returned by
368 * calling \c XF86DRIGetDeviceInfo.
370 * \sa XF86DRIGetDeviceInfo __DRIdisplayRec::createNewScreen
371 * __driUtilCreateNewScreen CallCreateNewScreen
373 * \bug This structure could be better named.
375 struct __DRIframebufferRec {
376 unsigned char *base; /**< Framebuffer base address in the CPU's
377 * address space. This value is calculated by
378 * calling \c drmMap on the framebuffer handle
379 * returned by \c XF86DRIGetDeviceInfo (or a
382 int size; /**< Framebuffer size, in bytes. */
383 int stride; /**< Number of bytes from one line to the next. */
384 int width; /**< Pixel width of the framebuffer. */
385 int height; /**< Pixel height of the framebuffer. */
386 int dev_priv_size; /**< Size of the driver's dev-priv structure. */
387 void *dev_priv; /**< Pointer to the driver's dev-priv structure. */
392 * Screen dependent methods. This structure is initialized during the
393 * \c __DRIdisplayRec::createScreen call.
395 struct __DRIscreenRec {
397 * Method to destroy the private DRI screen data.
399 void (*destroyScreen)(__DRIscreen *screen);
402 * Method to get screen extensions.
404 const __DRIextension **(*getExtensions)(__DRIscreen *screen);
407 * Method to create the private DRI drawable data and initialize the
408 * drawable dependent methods.
410 void *(*createNewDrawable)(__DRIscreen *screen,
411 const __GLcontextModes *modes,
412 __DRIdrawable *pdraw,
413 drm_drawable_t hwDrawable,
414 int renderType, const int *attrs);
417 * Opaque pointer to private per screen direct rendering data. \c NULL
418 * if direct rendering is not supported on this screen. Never
419 * dereferenced in libGL.
424 * Method to create the private DRI context data and initialize the
425 * context dependent methods.
427 * \since Internal API version 20031201.
429 void * (*createNewContext)(__DRIscreen *screen,
430 const __GLcontextModes *modes,
432 __DRIcontext *shared,
433 drm_context_t hwContext, __DRIcontext *pctx);
437 * Context dependent methods. This structure is initialized during the
438 * \c __DRIscreenRec::createContext call.
440 struct __DRIcontextRec {
442 * Method to destroy the private DRI context data.
444 void (*destroyContext)(__DRIcontext *context);
447 * Opaque pointer to private per context direct rendering data.
448 * \c NULL if direct rendering is not supported on the display or
449 * screen used to create this context. Never dereferenced in libGL.
454 * Method to bind a DRI drawable to a DRI graphics context.
456 * \since Internal API version 20050727.
458 GLboolean (*bindContext)(__DRIcontext *ctx,
459 __DRIdrawable *pdraw,
460 __DRIdrawable *pread);
463 * Method to unbind a DRI drawable from a DRI graphics context.
465 * \since Internal API version 20050727.
467 GLboolean (*unbindContext)(__DRIcontext *ctx);
471 * Drawable dependent methods. This structure is initialized during the
472 * \c __DRIscreenRec::createDrawable call. \c createDrawable is not called
473 * by libGL at this time. It's currently used via the dri_util.c utility code
476 struct __DRIdrawableRec {
478 * Method to destroy the private DRI drawable data.
480 void (*destroyDrawable)(__DRIdrawable *drawable);
483 * Method to swap the front and back buffers.
485 void (*swapBuffers)(__DRIdrawable *drawable);
488 * Opaque pointer to private per drawable direct rendering data.
489 * \c NULL if direct rendering is not supported on the display or
490 * screen used to create this drawable. Never dereferenced in libGL.