diff options
| -rw-r--r-- | man/XDGA.man | 675 |
1 files changed, 675 insertions, 0 deletions
diff --git a/man/XDGA.man b/man/XDGA.man new file mode 100644 index 0000000..d13c4bf --- /dev/null +++ b/man/XDGA.man @@ -0,0 +1,675 @@ +.\" $XFree86: xc/lib/Xxf86dga/XDGA.man,v 1.1 2003/11/22 01:33:31 dawes Exp $ +.\" +.TH XDGA 3 __vendorversion__ "XFree86" +.SH NAME +XDGA \- XFree86 DGA extension client library +.SH SYNOPSIS +.B #include <X11/extensions/xf86dga.h> +.HP +Bool +.BR XDGAQueryExtension ( +.br +.RI "Display *" dpy , +.br +.RI "int *" eventBase , +.br +.RI "int *" errorBase ) +.HP +Bool +.BR XDGAQueryVersion ( +.br +.RI "Display *" dpy , +.br +.RI "int *" majorVersion , +.br +.RI "int *" minorVersion ) +.HP +XDGAMode +.RB * XDGAQueryModes ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen , +.br +.RI "int *" num ) +.HP +XDGADevice +.RB * XDGASetMode ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen , +.br +.RI "int " mode ) +.HP +Bool +.BR XDGAOpenFramebuffer ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen ) +.HP +void +.BR XDGACloseFramebuffer ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen ) +.HP +void +.BR XDGASetViewport ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen , +.br +.RI "int " x , +.br +.RI "int " y , +.br +.RI "int " flags ) +.HP +void +.BR XDGAInstallColormap ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen , +.br +.RI "Colormap " cmap ) +.HP +Colormap +.BR XDGACreateColormap ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen , +.br +.RI "XDGADevice *" device , +.br +.RI "int " alloc ) +.HP +void +.BR XDGASelectInput ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen , +.br +.RI "long " event_mask ) +.HP +void +.BR XDGAFillRectangle ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen , +.br +.RI "int " x , +.br +.RI "int " y , +.br +.RI "unsigned int " width , +.br +.RI "unsigned int " height , +.br +.RI "unsigned long " color ) +.HP +void +.BR XDGACopyArea ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen , +.br +.RI "int " srcx , +.br +.RI "int " srcy , +.br +.RI "unsigned int " width , +.br +.RI "unsigned int " height , +.br +.RI "int " dstx , +.br +.RI "int " dsty ) +.HP +void +.BR XDGACopyTransparentArea ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen , +.br +.RI "int " srcx , +.br +.RI "int " srcy , +.br +.RI "unsigned int " width , +.br +.RI "unsigned int " height , +.br +.RI "int " dstx , +.br +.RI "int " dsty , +.br +.RI "unsigned long " key ) +.HP +int +.BR XDGAGetViewportStatus ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen ) +.HP +void +.BR XDGASync ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen ) +.HP +Bool +.BR XDGASetClientVersion ( +.br +.RI "Display *" dpy ) +.HP +void +.BR XDGAChangePixmapMode ( +.br +.RI "Display *" dpy , +.br +.RI "int " screen , +.br +.RI "int *" x , +.br +.RI "int *" y , +.br +.RI "int " mode ) +.HP +void +.BR XDGAKeyEventToXKeyEvent ( +.br +.RI "XDGAKeyEvent *" dk , +.br +.RI "XKeyEvent *" xk ) + +.SH DESCRIPTION +The +.B XFree86-DGA +extension is an X server extension for allowing client programs direct +access to the video frame buffer. This is a brief description of the +programming interface for version 2.0 of the +.B XFree86-DGA +extension. +.PP +.B XFree86-DGA +is not intended as a direct rendering API, but rather, as a mechanism +to "get the X Server out of the way" so that some other direct rendering +API can have full access to the hardware. With this in mind, DGA does +provide clients some direct access to the hardware without requiring a +separate rendering API, but this access is limited to direct linear +framebuffer access. +.PP +Most of the reasons for the +.B XFree86-DGA +extension's existence are now better served in other ways. Further +development of this extension is not expected, and it may be deprecated +in a future release. The features that continue to be useful will either +be provided through other existing mechanisms, or through an extension +that address those needs more specifically. Discussion of these issue +is encouraged in the XFree86 developer forum +.RI < devel@xfree86.org >. +.PP +.B XFree86-DGA +is initialized by passing a number corresponding to a valid +.I XDGAMode +to +.BR XDGASetMode (). +Clients can get a list of valid modes from +.BR XDGAQueryModes (). +Each +.I XDGAMode +corresponds to a different framebuffer layout. +.PP +.BR XDGAQueryModes () +returns a pointer to an array of +.IR XDGAMode s +which are valid for the given screen. +.I num +is the number of elements in the array. The returned array can be freed +with XFree(3). The +.I XDGAMode +structure is as follows: +.PP +.nf +.ta .5i 2i +typedef struct { + int num; + char *name; + float verticalRefresh; + int flags; + int imageWidth; + int imageHeight; + int pixmapWidth; + int pixmapHeight; + int bytesPerScanline; + int byteOrder; + int depth; + int bitsPerPixel; + unsigned long redMask; + unsigned long greenMask; + unsigned long blueMask; + short visualClass; + int viewportWidth; + int viewportHeight; + int xViewportStep; + int yViewportStep; + int maxViewportX; + int maxViewportY; + int viewportFlags; + int reserved1; + int reserved2; +.br +} XDGAMode; +.fi +.TP 8 +.I num +A unique identifying number +.RI ( num +> 0) for the mode. This is the number referenced when initializing the mode. +.TP 8 +.I name +The name of the corresponding modeline as given in the XF86Config file. +.TP 8 +.I verticalRefresh +The vertical refresh rate for the modeline (in Hz). +.TP 8 +.I flags +Any of the following may be OR'd together: +.RS 8 +.TP 4 +.B XDGAConcurrentAccess +Indicates that concurrent client/server access to the framebuffer is +possible. If this flag is not set it is very important to call +.BR XDGASync () +before directly accessing the framebuffer if a call to +.BR XDGAFillRectangle (), +.BR XDGACopyArea () +or +.BR XDGACopyTransparentArea () +or any Xlib rendering function has been made prior to such accesses. +.TP 4 +.B XDGASolidFillRect +Indicates that +.BR XDGAFillRectangle () +is supported. +.TP 4 +.B XDGABlitRect +Indicates that +.BR XDGACopyArea () +is supported. +.TP 4 +.B XDGABlitTransRect +Indicates that +.BR XDGACopyTransparentArea () +is supported. +.TP 4 +.B XDGAPixmap +Indicates that a Pixmap will be returned when the mode is initialized. +This means that rendering with Xlib is possible for this mode. +.TP 4 +.B XDGAInterlaced +.TP 4 +.B XDGADoublescan +Indicates that the mode is an interlaced or doublescan mode. +.RE +.TP 8 +.I imageWidth +.TP 8 +.I imageHeight +The width and height of the framebuffer area accessible by the client. +This rectangle is always justified to the upper left-hand corner. +.TP 8 +.I pixmapWidth +.TP 8 +.I pixmapHeight +The width and height of the framebuffer area accessible by Xlib. This +rectangle is always justified to the upper left-hand corner. These +fields are only valid if the +.B XDGAPixmap +flag is set in the +.I flags +field. +.TP 8 +.I bytesPerScanline +The pitch of the framebuffer in bytes. +.TP 8 +.I byteOrder +.B MSBFirst +or +.BR LSBFirst . +.TP 8 +.I depth +The number of bits in each pixel which contain usable data. +.TP 8 +.I bitsPerPixel +The number of bits taken up by each pixel. +.TP 8 +.I redMask +.TP 8 +.I greenMask +.TP 8 +.I blueMask +The RGB masks. These do not apply to color-indexed modes. +.TP 8 +.I visualClass +.BR TrueColor , +.BR PseudoColor , +.BR DirectColor , +etc. +.TP 8 +.I viewportWidth +.TP 8 +.I viewportHeight +The dimensions of the portion of the framebuffer which will be displayed +on the screen. +.TP 8 +.I xViewPortStep +.TP 8 +.I yViewPortStep +The granularity of the x,y viewport positioning possible with the +.BR XDGASetViewport () +function. +.TP 8 +.I maxViewportX +.TP 8 +.I maxViewportY +The maximum x and y positions possible with the +.BR XDGASetViewport () +function. +.TP 8 +.I viewportFlags +Any of the following may be OR'd together +.RS 8 +.TP 4 +.B XDGAFlipRetrace +Indicates that the hardware can switch viewports during the vertical +retrace. +.TP 4 +.B XDGAFlipImmediate +Indicates that the hardware can switch viewports immediately without +waiting for the vertical retrace. +.RE +.PP +.BR XDGASetMode () +initialises the +.I XDGAMode +corresponding to +.IR num . +To exit DGA mode and return to normal server operation, call +.BR XDGASetMode () +with +.I num +set to zero. +.BR XDGASetMode () +returns a pointer to an +.I XDGADevice +if successful. The XDGADevice can be freed with XFree(3). The +.I XDGADevice +structure is as follows: +.PP +.nf +.ta .5i 2i +typedef struct { + XDGAMode mode; + unsigned char *data; + Pixmap pixmap; +.br +} XDGADevice; +.fi +.TP 8 +.I mode +The +.I XDGAMode +structure, identical to the information returned by +.BR XDGAQueryModes (). +.TP 8 +.I data +If direct framebuffer access is desired and possible, this field will +contain a pointer to the mapped framebuffer memory. Generally, this +field will be zero unless a call to +.BR XDGAOpenFramebuffer () +is made prior to initialization of the mode. +.TP 8 +.I pixmap +If the mode supports Xlib rendering as indicated by +.B XDGAPixmap +in the +.I flags +field, this will contain a Pixmap handle suitable for passing as the +drawable argument to Xlib functions. This field will be zero if Xlib +rendering is not supported. +.PP +.BR XDGAQueryExtension () +checks for the presence of the extension and returns the event and error bases. +.PP +.BR XDGAQueryVersion () +returns the +.B XFree86-DGA +major and minor version numbers. +.PP +.BR XDGAOpenFramebuffer () +maps the framebuffer memory. The client needs sufficient privileges to be +able to do this. +.BR XDGAOpenFramebuffer () +should be called prior to initializing a DGA mode if direct framebuffer +access is desired for that mode. +.BR XDGAOpenFramebuffer () +does not need to be called if direct framebuffer access is not required. +If the framebuffer is opened, +.PP +.BR XDGACloseFramebuffer () +should be called prior to client exit to unmap the memory. +.PP +.BR XDGAChangePixmapMode () +can be used to change between two pixmap sizes in cases where a Pixmap is +available for Xlib rendering. The following values for the +.I mode +parameter are available: +.RS 8 +.TP 4 +.B XDGAPixmapModeLarge +The pixmap size is defined by the +.I pixmapWidth +and +.I pixmapHeight +fields in the +.I XDGAMode +structure. The +.I x +and +.I y +values are ignored in this case. +.TP 4 +.B XDGAPixmapModeSmall +The pixmap size is defined by the +.I viewportWidth +and +.I viewportHeight +fields in the +.I XDGAMode +structure. In this mode, the +.I x +and +.I y +values specify where in the framebuffer this pixmap rectangle is located. +It may be placed anywhere within the Xlib renderable region described +by the +.I pixmapWidth +and +.I pixmapHeight +fields in the +.IR XDGAMode . +The +.I x +and +.I y +values returned are the resultant location of the pixmap and may be +different from the requested x,y location due to platform specific +alignment constraints. All Xlib rendering is clipped to this pixmap +rectangle. +.RE +.PP +.BR XDGASetViewport () +sets the upper left-hand corner of the rectangle of framebuffer that is +to be displayed on the screen. Not all locations may be supported by +the hardware and requested locations will be adjusted according to the +.I xViewPortStep +and +.I yViewPortStep +fields in the +.IR XDGAMode . +.PP +.I flags +can be +.B XDGAFlipRetrace +or +.B XDGAFlipImmediate +to adjust the viewport location at the next vertical retrace or +immediately. Values other than the supported values advertised in the +mode's +.I viewportFlags +field will result in hardware-specific default behavior. +.B XDGAFlipImmediate +will block until the flip is completed. +.B XDGAFlipRetrace +will generally NOT block so it is necessary to monitor the viewport +status with +.BR XDGAGetViewportStatus (). +.B XDGAFlipImmediate +requests during pending +.B XDGAFlipRetrace +requests will be ignored. +.PP +.BR XDGAGetViewportStatus () +keeps track of the +.BR XDGASetViewport () +requests still pending. The return value of the function will have +consecutive bits set (LSB justified), each bit representing a pending +viewport change. For example: +.PP +.nf + while(XDGAGetViewportStatus(dpy, screen)); +.fi +.PP +waits for all pending viewport changes to finish. +.PP +.nf + while(0x2 & XDGAGetViewportStatus(dpy, screen)); +.fi +.PP +waits until all but the last viewport changes have completed. +.PP +.BR XDGACreateColormap () +is similar to the Xlib function XCreateColormap(3) except that it takes +an +.I XDGADevice +as an argument instead of a Window and Visual. Though XCreateColormap(3) +may create usable colormaps in some cases, +.BR XDGACreateColormap () +is the preferred method for creating colormaps in DGA since there may +not be an advertised visual compatible with the DGA device. +.PP +.BR XDGAInstallColormap () +must be used to install colormaps in DGA mode. XInstallColormap(3) will +not work. +.PP +.BR XDGASelectInput () +enables DGA's own event mechanism. This function is similar to +XSelectInput(3), and all Xlib Key, Button and Motion masks are supported. +The following DGA events are defined: +.PP +.nf +.ta .5i 2i +typedef struct { + int type; /\(** ButtonPress or ButtonRelease + the DGA event base*/ + unsigned long serial; /\(** # or last request processed by the server */ + Display *display; /\(** Display the event was read from */ + int screen; /\(** The screen number the event came from */ + Time time; /\(** milliseconds */ + unsigned int state; /\(** key or button mask */ + unsigned int button; /\(** detail */ +.br +} XDGAButtonEvent; +.fi +.PP +.nf +.ta .5i 2i +typedef struct { + int type; /\(** KeyPress or KeyRelease + the DGA event base*/ + unsigned long serial; /\(** # or last request processed by the server */ + Display *display; /\(** Display the event was read from */ + int screen; /\(** The screen number the event came from */ + Time time; /\(** milliseconds */ + unsigned int state; /\(** key or button mask */ + unsigned int keycode; /\(** detail */ +.br +} XDGAKeyEvent; +.fi +.PP +.nf +.ta .5i 2i +typedef struct { + int type; /\(** MotionNotify + the DGA event base*/ + unsigned long serial; /\(** # or last request processed by the server */ + Display *display; /\(** Display the event was read from */ + int screen; /\(** The screen number the event came from */ + Time time; /\(** milliseconds */ + unsigned int state; /\(** key or button mask */ + int dx; /\(** relative pointer motion */ + int dy; /\(** relative pointer motion */ +.br +} XDGAMotionEvent; +.fi +.PP +.BR XDGAKeyEventToXKeyEvent () +is a helper function to translate +.IR XDGAKeyEvent s +into +.IR XKeyEvent s +suitable for use with XLookupKeysym(3). +.PP +.BR XDGAFillRectangle (), +.BR XDGACopyArea (), +and +.BR XDGACopyTransparentArea () +are included with some reservation since DGA is not intended as a +rendering API. These are merely convenience routines and are optionally +supported. The associated flags will be set in the +.IR XDGAMode 's +.I flags +field if these functions are supported. These functions will be no-ops +otherwise. they do not provide direct access to the hardware, but are +simply context-less operations performed by the server. +.PP +.BR XDGASync () +blocks until all server rendering to the framebuffer completes. If Xlib +or the 3 rendering functions above are used, +.BR XDGASync () +must be called before the client directly accesses the framebuffer as +the server rendering is asynchronous with the client and may have not +completed. This is especially important if the +.B XDGAConcurrentAccess +flag is not set in the +.IR XDGAMode 's +.I flags +field since concurrent access by the server and client may result in a +system lockup. +.SH SEE ALSO +XFree86(1), XF86Config(__filemansuffix__) +.SH AUTHORS +.B XFree86-DGA +version 2 was written by Mark Vojkovich. Version 1 was written by Jon +Tombs, Harm Hanemaayer, Mark Vojkovich. + |