merge XFree86 4.3.99.901 (RC1) from vendor branchXORG-RELEASE-1-BASEXEVIE-MERGEXEVIE-BASEXINERAMA_2XEVIE

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.
+