1XDGA(3)                    Library Functions Manual                    XDGA(3)
2
3
4

NAME

6       XDGA - Client library for the XFree86-DGA extension.
7

SYNOPSIS

9       #include <X11/extensions/xf86dga.h>
10
11       Bool XDGAQueryExtension(
12              Display *dpy,
13              int *eventBase,
14              int *errorBase)
15
16       Bool XDGAQueryVersion(
17              Display *dpy,
18              int *majorVersion,
19              int *minorVersion)
20
21       XDGAMode *XDGAQueryModes(
22              Display *dpy,
23              int screen,
24              int *num)
25
26       XDGADevice *XDGASetMode(
27              Display *dpy,
28              int screen,
29              int mode)
30
31       Bool XDGAOpenFramebuffer(
32              Display *dpy,
33              int screen)
34
35       void XDGACloseFramebuffer(
36              Display *dpy,
37              int screen)
38
39       void XDGASetViewport(
40              Display *dpy,
41              int screen,
42              int x,
43              int y,
44              int flags)
45
46       void XDGAInstallColormap(
47              Display *dpy,
48              int screen,
49              Colormap cmap)
50
51       Colormap XDGACreateColormap(
52              Display *dpy,
53              int screen,
54              XDGADevice *device,
55              int alloc)
56
57       void XDGASelectInput(
58              Display *dpy,
59              int screen,
60              long event_mask)
61
62       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
71       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
81       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
92       int XDGAGetViewportStatus(
93              Display *dpy,
94              int screen)
95
96       void XDGASync(
97              Display *dpy,
98              int screen)
99
100       Bool XDGASetClientVersion(
101              Display *dpy)
102
103       void XDGAChangePixmapMode(
104              Display *dpy,
105              int screen,
106              int *x,
107              int *y,
108              int mode)
109
110       void XDGAKeyEventToXKeyEvent(
111              XDGAKeyEvent *dk,
112              XKeyEvent *xk)
113
114

DESCRIPTION

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
121       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
128       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
135       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
140       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
145       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
173       num     A unique identifying number (num > 0) for the  mode.   This  is
174               the number referenced when initializing the mode.
175
176       name    The  name  of  the  corresponding  modeline  as  given  in  the
177               xorg.conf file.
178
179       verticalRefresh
180               The vertical refresh rate for the modeline (in Hz).
181
182       flags   Any of the following may be OR'd together:
183
184               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
192               XDGASolidFillRect
193                   Indicates that XDGAFillRectangle() is supported.
194
195               XDGABlitRect
196                   Indicates that XDGACopyArea() is supported.
197
198               XDGABlitTransRect
199                   Indicates that XDGACopyTransparentArea() is supported.
200
201               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
206               XDGAInterlaced
207
208               XDGADoublescan
209                   Indicates  that  the  mode  is  an interlaced or doublescan
210                   mode.
211
212       imageWidth
213
214       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
219       pixmapWidth
220
221       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
227       bytesPerScanline
228               The pitch of the framebuffer in bytes.
229
230       byteOrder
231               MSBFirst or LSBFirst.
232
233       depth   The number of bits in each pixel which contain usable data.
234
235       bitsPerPixel
236               The number of bits taken up by each pixel.
237
238       redMask
239
240       greenMask
241
242       blueMask
243               The RGB masks.  These do not apply to color-indexed modes.
244
245       visualClass
246               TrueColor, PseudoColor, DirectColor, etc.
247
248       viewportWidth
249
250       viewportHeight
251               The  dimensions of the portion of the framebuffer which will be
252               displayed on the screen.
253
254       xViewportStep
255
256       yViewportStep
257               The granularity of the x,y viewport positioning  possible  with
258               the XDGASetViewport() function.
259
260       maxViewportX
261
262       maxViewportY
263               The  maximum  x  and y positions possible with the XDGASetView‐
264               port() function.
265
266       viewportFlags
267               Any of the following may be OR'd together
268
269               XDGAFlipRetrace
270                   Indicates that the hardware can switch viewports during the
271                   vertical retrace.
272
273               XDGAFlipImmediate
274                   Indicates  that  the  hardware can switch viewports immedi‐
275                   ately without waiting for the vertical retrace.
276
277       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
283       typedef struct {
284          XDGAMode mode;
285          unsigned char *data;
286          Pixmap pixmap;
287       } XDGADevice;
288
289       mode    The XDGAMode structure, identical to the  information  returned
290               by XDGAQueryModes().
291
292       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
297       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
302       XDGAQueryExtension()  checks  for  the  presence  of  the extension and
303       returns the event and error bases.
304
305       XDGAQueryVersion() returns the XFree86-DGA major and minor version num‐
306       bers.
307
308       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
315       XDGACloseFramebuffer() should be called prior to client exit  to  unmap
316       the memory.
317
318       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
322               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
327               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
339       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
345       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
354       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
359            while(XDGAGetViewportStatus(dpy, screen));
360
361       waits for all pending viewport changes to finish.
362
363            while(0x2 & XDGAGetViewportStatus(dpy, screen));
364
365       waits until all but the last viewport changes have completed.
366
367       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
374       XDGAInstallColormap()  must  be  used to install colormaps in DGA mode.
375       XInstallColormap(3) will not work.
376
377       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
381       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
391       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
401       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
412       XDGAKeyEventToXKeyEvent()   is   a   helper   function   to   translate
413       XDGAKeyEvents into XKeyEvents suitable for use with XLookupKeysym(3).
414
415       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
423       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

SEE ALSO

432       Xorg(1), xorg.conf(5)
433

AUTHORS

435       XFree86-DGA  version  2  was  written by Mark Vojkovich.  Version 1 was
436       written by Jon Tombs, Harm Hanemaayer, Mark Vojkovich.
437
438
439
440
441X Version 11                   libXxf86dga 1.1.5                       XDGA(3)
Impressum