1XDGA(3) Library Functions Manual XDGA(3)
2
6 XDGA - Client library for the XFree86-DGA extension.
7
9 #include <X11/extensions/xf86dga.h>
10 Bool XDGAQueryExtension(
12 Display *dpy,
13 int *eventBase,
14 int *errorBase)
15 Bool XDGAQueryVersion(
17 Display *dpy,
18 int *majorVersion,
19 int *minorVersion)
20 XDGAMode *XDGAQueryModes(
22 Display *dpy,
23 int screen,
24 int *num)
25 XDGADevice *XDGASetMode(
27 Display *dpy,
28 int screen,
29 int mode)
30 Bool XDGAOpenFramebuffer(
32 Display *dpy,
33 int screen)
34 void XDGACloseFramebuffer(
36 Display *dpy,
37 int screen)
38 void XDGASetViewport(
40 Display *dpy,
41 int screen,
42 int x,
43 int y,
44 int flags)
45 void XDGAInstallColormap(
47 Display *dpy,
48 int screen,
49 Colormap cmap)
50 Colormap XDGACreateColormap(
52 Display *dpy,
53 int screen,
54 XDGADevice *device,
55 int alloc)
56 void XDGASelectInput(
58 Display *dpy,
59 int screen,
60 long event_mask)
61 void XDGAFillRectangle(
63 Display *dpy,
64 int screen,
65 int x,
66 int y,
67 unsigned int width,
68 unsigned int height,
69 unsigned long color)
70 void XDGACopyArea(
72 Display *dpy,
73 int screen,
74 int srcx,
75 int srcy,
76 unsigned int width,
77 unsigned int height,
78 int dstx,
79 int dsty)
80 void XDGACopyTransparentArea(
82 Display *dpy,
83 int screen,
84 int srcx,
85 int srcy,
86 unsigned int width,
87 unsigned int height,
88 int dstx,
89 int dsty,
90 unsigned long key)
91 int XDGAGetViewportStatus(
93 Display *dpy,
94 int screen)
95 void XDGASync(
97 Display *dpy,
98 int screen)
99 Bool XDGASetClientVersion(
101 Display *dpy)
102 void XDGAChangePixmapMode(
104 Display *dpy,
105 int screen,
106 int *x,
107 int *y,
108 int mode)
109 void XDGAKeyEventToXKeyEvent(
111 XDGAKeyEvent *dk,
112 XKeyEvent *xk)
113
116 The XFree86-DGA extension is an X server extension for allowing client
117 programs direct access to the video frame buffer. This is a brief
118 description of the programming interface for version 2.0 of the
119 XFree86-DGA extension.
120 XFree86-DGA is not intended as a direct rendering API, but rather, as a
122 mechanism to "get the X Server out of the way" so that some other
123 direct rendering API can have full access to the hardware. With this
124 in mind, DGA does provide clients some direct access to the hardware
125 without requiring a separate rendering API, but this access is limited
126 to direct linear framebuffer access.
127 Most of the reasons for the XFree86-DGA extension's existence are now
129 better served in other ways. Further development of this extension is
130 not expected, and it may be deprecated in a future release. The fea‐
131 tures that continue to be useful will either be provided through other
132 existing mechanisms, or through an extension that address those needs
133 more specifically.
134 XFree86-DGA is initialized by passing a number corresponding to a valid
136 XDGAMode to XDGASetMode(). Clients can get a list of valid modes from
137 XDGAQueryModes(). Each XDGAMode corresponds to a different framebuffer
138 layout.
139 XDGAQueryModes() returns a pointer to an array of XDGAModes which are
141 valid for the given screen. num is the number of elements in the
142 array. The returned array can be freed with XFree(3). The XDGAMode
143 structure is as follows:
144 typedef struct {
146 int num;
147 char *name;
148 float verticalRefresh;
149 int flags;
150 int imageWidth;
151 int imageHeight;
152 int pixmapWidth;
153 int pixmapHeight;
154 int bytesPerScanline;
155 int byteOrder;
156 int depth;
157 int bitsPerPixel;
158 unsigned long redMask;
159 unsigned long greenMask;
160 unsigned long blueMask;
161 short visualClass;
162 int viewportWidth;
163 int viewportHeight;
164 int xViewportStep;
165 int yViewportStep;
166 int maxViewportX;
167 int maxViewportY;
168 int viewportFlags;
169 int reserved1;
170 int reserved2;
171 } XDGAMode;
172 num A unique identifying number (num > 0) for the mode. This is
174 the number referenced when initializing the mode.
175 name The name of the corresponding modeline as given in the
177 xorg.conf file.
178 verticalRefresh
180 The vertical refresh rate for the modeline (in Hz).
181 flags Any of the following may be OR'd together:
183 XDGAConcurrentAccess
185 Indicates that concurrent client/server access to the
186 framebuffer is possible. If this flag is not set it is
187 very important to call XDGASync() before directly accessing
188 the framebuffer if a call to XDGAFillRectangle(), XDGACopy‐
189 Area() or XDGACopyTransparentArea() or any Xlib rendering
190 function has been made prior to such accesses.
191 XDGASolidFillRect
193 Indicates that XDGAFillRectangle() is supported.
194 XDGABlitRect
196 Indicates that XDGACopyArea() is supported.
197 XDGABlitTransRect
199 Indicates that XDGACopyTransparentArea() is supported.
200 XDGAPixmap
202 Indicates that a Pixmap will be returned when the mode is
203 initialized. This means that rendering with Xlib is possi‐
204 ble for this mode.
205 XDGAInterlaced
207 XDGADoublescan
209 Indicates that the mode is an interlaced or doublescan
210 mode.
211 imageWidth
213 imageHeight
215 The width and height of the framebuffer area accessible by the
216 client. This rectangle is always justified to the upper left-
217 hand corner.
218 pixmapWidth
220 pixmapHeight
222 The width and height of the framebuffer area accessible by
223 Xlib. This rectangle is always justified to the upper left-
224 hand corner. These fields are only valid if the XDGAPixmap
225 flag is set in the flags field.
226 bytesPerScanline
228 The pitch of the framebuffer in bytes.
229 byteOrder
231 MSBFirst or LSBFirst.
232 depth The number of bits in each pixel which contain usable data.
234 bitsPerPixel
236 The number of bits taken up by each pixel.
237 redMask
239 greenMask
241 blueMask
243 The RGB masks. These do not apply to color-indexed modes.
244 visualClass
246 TrueColor, PseudoColor, DirectColor, etc.
247 viewportWidth
249 viewportHeight
251 The dimensions of the portion of the framebuffer which will be
252 displayed on the screen.
253 xViewportStep
255 yViewportStep
257 The granularity of the x,y viewport positioning possible with
258 the XDGASetViewport() function.
259 maxViewportX
261 maxViewportY
263 The maximum x and y positions possible with the XDGASetView‐
264 port() function.
265 viewportFlags
267 Any of the following may be OR'd together
268 XDGAFlipRetrace
270 Indicates that the hardware can switch viewports during the
271 vertical retrace.
272 XDGAFlipImmediate
274 Indicates that the hardware can switch viewports immedi‐
275 ately without waiting for the vertical retrace.
276 XDGASetMode() initialises the XDGAMode corresponding to num. To exit
278 DGA mode and return to normal server operation, call XDGASetMode() with
279 num set to zero. XDGASetMode() returns a pointer to an XDGADevice if
280 successful. The XDGADevice can be freed with XFree(3). The XDGADevice
281 structure is as follows:
282 typedef struct {
284 XDGAMode mode;
285 unsigned char *data;
286 Pixmap pixmap;
287 } XDGADevice;
288 mode The XDGAMode structure, identical to the information returned
290 by XDGAQueryModes().
291 data If direct framebuffer access is desired and possible, this
293 field will contain a pointer to the mapped framebuffer memory.
294 Generally, this field will be zero unless a call to XDGAOpen‐
295 Framebuffer() is made prior to initialization of the mode.
296 pixmap If the mode supports Xlib rendering as indicated by XDGAPixmap
298 in the flags field, this will contain a Pixmap handle suitable
299 for passing as the drawable argument to Xlib functions. This
300 field will be zero if Xlib rendering is not supported.
301 XDGAQueryExtension() checks for the presence of the extension and
303 returns the event and error bases.
304 XDGAQueryVersion() returns the XFree86-DGA major and minor version num‐
306 bers.
307 XDGAOpenFramebuffer() maps the framebuffer memory. The client needs
309 sufficient privileges to be able to do this. XDGAOpenFramebuffer()
310 should be called prior to initializing a DGA mode if direct framebuffer
311 access is desired for that mode. XDGAOpenFramebuffer() does not need
312 to be called if direct framebuffer access is not required. If the
313 framebuffer is opened,
314 XDGACloseFramebuffer() should be called prior to client exit to unmap
316 the memory.
317 XDGAChangePixmapMode() can be used to change between two pixmap sizes
319 in cases where a Pixmap is available for Xlib rendering. The following
320 values for the mode parameter are available:
321 XDGAPixmapModeLarge
323 The pixmap size is defined by the pixmapWidth and
324 pixmapHeight fields in the XDGAMode structure. The x and y
325 values are ignored in this case.
326 XDGAPixmapModeSmall
328 The pixmap size is defined by the viewportWidth and view‐
329 portHeight fields in the XDGAMode structure. In this mode,
330 the x and y values specify where in the framebuffer this
331 pixmap rectangle is located. It may be placed anywhere
332 within the Xlib renderable region described by the pixmap‐
333 Width and pixmapHeight fields in the XDGAMode. The x and y
334 values returned are the resultant location of the pixmap
335 and may be different from the requested x,y location due to
336 platform specific alignment constraints. All Xlib render‐
337 ing is clipped to this pixmap rectangle.
338 XDGASetViewport() sets the upper left-hand corner of the rectangle of
340 framebuffer that is to be displayed on the screen. Not all locations
341 may be supported by the hardware and requested locations will be
342 adjusted according to the xViewportStep and yViewportStep fields in the
343 XDGAMode.
344 flags can be XDGAFlipRetrace or XDGAFlipImmediate to adjust the view‐
346 port location at the next vertical retrace or immediately. Values
347 other than the supported values advertised in the mode's viewportFlags
348 field will result in hardware-specific default behavior. XDGAFlipImme‐
349 diate will block until the flip is completed. XDGAFlipRetrace will
350 generally NOT block so it is necessary to monitor the viewport status
351 with XDGAGetViewportStatus(). XDGAFlipImmediate requests during pend‐
352 ing XDGAFlipRetrace requests will be ignored.
353 XDGAGetViewportStatus() keeps track of the XDGASetViewport() requests
355 still pending. The return value of the function will have consecutive
356 bits set (LSB justified), each bit representing a pending viewport
357 change. For example:
358 while(XDGAGetViewportStatus(dpy, screen));
360 waits for all pending viewport changes to finish.
362 while(0x2 & XDGAGetViewportStatus(dpy, screen));
364 waits until all but the last viewport changes have completed.
366 XDGACreateColormap() is similar to the Xlib function XCreateColormap(3)
368 except that it takes an XDGADevice as an argument instead of a Window
369 and Visual. Though XCreateColormap(3) may create usable colormaps in
370 some cases, XDGACreateColormap() is the preferred method for creating
371 colormaps in DGA since there may not be an advertised visual compatible
372 with the DGA device.
373 XDGAInstallColormap() must be used to install colormaps in DGA mode.
375 XInstallColormap(3) will not work.
376 XDGASelectInput() enables DGA's own event mechanism. This function is
378 similar to XSelectInput(3), and all Xlib Key, Button and Motion masks
379 are supported. The following DGA events are defined:
380 typedef struct {
382 int type; /∗ ButtonPress or ButtonRelease + the DGA event base*/
383 unsigned long serial; /∗ # or last request processed by the server */
384 Display *display; /∗ Display the event was read from */
385 int screen; /∗ The screen number the event came from */
386 Time time; /∗ milliseconds */
387 unsigned int state; /∗ key or button mask */
388 unsigned int button; /∗ detail */
389 } XDGAButtonEvent;
390 typedef struct {
392 int type; /∗ KeyPress or KeyRelease + the DGA event base*/
393 unsigned long serial; /∗ # or last request processed by the server */
394 Display *display; /∗ Display the event was read from */
395 int screen; /∗ The screen number the event came from */
396 Time time; /∗ milliseconds */
397 unsigned int state; /∗ key or button mask */
398 unsigned int keycode; /∗ detail */
399 } XDGAKeyEvent;
400 typedef struct {
402 int type; /∗ MotionNotify + the DGA event base*/
403 unsigned long serial; /∗ # or last request processed by the server */
404 Display *display; /∗ Display the event was read from */
405 int screen; /∗ The screen number the event came from */
406 Time time; /∗ milliseconds */
407 unsigned int state; /∗ key or button mask */
408 int dx; /∗ relative pointer motion */
409 int dy; /∗ relative pointer motion */
410 } XDGAMotionEvent;
411 XDGAKeyEventToXKeyEvent() is a helper function to translate
413 XDGAKeyEvents into XKeyEvents suitable for use with XLookupKeysym(3).
414 XDGAFillRectangle(), XDGACopyArea(), and XDGACopyTransparentArea() are
416 included with some reservation since DGA is not intended as a rendering
417 API. These are merely convenience routines and are optionally sup‐
418 ported. The associated flags will be set in the XDGAMode's flags field
419 if these functions are supported. These functions will be no-ops oth‐
420 erwise. they do not provide direct access to the hardware, but are sim‐
421 ply context-less operations performed by the server.
422 XDGASync() blocks until all server rendering to the framebuffer com‐
424 pletes. If Xlib or the 3 rendering functions above are used,
425 XDGASync() must be called before the client directly accesses the
426 framebuffer as the server rendering is asynchronous with the client and
427 may have not completed. This is especially important if the XDGACon‐
428 currentAccess flag is not set in the XDGAMode's flags field since con‐
429 current access by the server and client may result in a system lockup.
430
432 Xorg(1), xorg.conf(5)
433
435 XFree86-DGA version 2 was written by Mark Vojkovich. Version 1 was
436 written by Jon Tombs, Harm Hanemaayer, Mark Vojkovich.
437X Version 11 libXxf86dga 1.1.4 XDGA(3)