MirOS Manual: XDGA(3), XDGAChangePixmapMode(3), XDGACloseFramebuffer(3), XDGACopyArea(3), XDGACopyTransparentArea(3), XDGACreateColormap(3), XDGAFillRectangle(3), XDGAGetViewportStatus(3), XDGAInstallColormap(3), XDGAKeyEventToXKeyEvent(3), XDGAOpenFramebuffer(3), XDGAQueryExtension(3), XDGAQueryModes(3), XDGAQueryVersion(3), XDGASelectInput(3), XDGASetClientVersion(3), XDGASetMode(3), XDGASetViewport(3), XDGASync(3), XF86DGA(3), XFree86-DGA(3)


XDGA(3)                      XFree86                      XDGA(3)

NAME

     XDGA - XFree86 DGA extension client library

SYNOPSIS

     #include <X11/extensions/xf86dga.h>

     Bool XDGAQueryExtension(
          Display *dpy,
          int *eventBase,
          int *errorBase)

     Bool XDGAQueryVersion(
          Display *dpy,
          int *majorVersion,
          int *minorVersion)

     XDGAMode *XDGAQueryModes(
          Display *dpy,
          int screen,
          int *num)

     XDGADevice *XDGASetMode(
          Display *dpy,
          int screen,
          int mode)

     Bool XDGAOpenFramebuffer(
          Display *dpy,
          int screen)

     void XDGACloseFramebuffer(
          Display *dpy,
          int screen)

     void XDGASetViewport(
          Display *dpy,
          int screen,
          int x,
          int y,
          int flags)

     void XDGAInstallColormap(
          Display *dpy,
          int screen,
          Colormap cmap)

     Colormap XDGACreateColormap(
          Display *dpy,
          int screen,
          XDGADevice *device,
          int alloc)

XFree86                   Version 4.5.0                         1

XDGA(3)                      XFree86                      XDGA(3)

     void XDGASelectInput(
          Display *dpy,
          int screen,
          long event_mask)

     void XDGAFillRectangle(
          Display *dpy,
          int screen,
          int x,
          int y,
          unsigned int width,
          unsigned int height,
          unsigned long color)

     void XDGACopyArea(
          Display *dpy,
          int screen,
          int srcx,
          int srcy,
          unsigned int width,
          unsigned int height,
          int dstx,
          int dsty)

     void XDGACopyTransparentArea(
          Display *dpy,
          int screen,
          int srcx,
          int srcy,
          unsigned int width,
          unsigned int height,
          int dstx,
          int dsty,
          unsigned long key)

     int XDGAGetViewportStatus(
          Display *dpy,
          int screen)

     void XDGASync(
          Display *dpy,
          int screen)

     Bool XDGASetClientVersion(
          Display *dpy)

     void XDGAChangePixmapMode(
          Display *dpy,
          int screen,
          int *x,
          int *y,
          int mode)

XFree86                   Version 4.5.0                         2

XDGA(3)                      XFree86                      XDGA(3)

     void XDGAKeyEventToXKeyEvent(
          XDGAKeyEvent *dk,
          XKeyEvent *xk)

DESCRIPTION

     The 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 XFree86-DGA extension.

     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.

     Most of the reasons for the 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 <devel@xfree86.org>.

     XFree86-DGA is initialized by passing a number corresponding
     to a valid XDGAMode to XDGASetMode(). Clients can get a list
     of valid modes from XDGAQueryModes(). Each XDGAMode
     corresponds to a different framebuffer layout.

     XDGAQueryModes() returns a pointer to an array of XDGAModes
     which are valid for the given screen. num is the number of
     elements in the array.  The returned array can be freed with
     XFree(3).  The XDGAMode structure is as follows:

     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;

XFree86                   Version 4.5.0                         3

XDGA(3)                      XFree86                      XDGA(3)

        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;
     } XDGAMode;

     num     A unique identifying number (num > 0) for the mode.
             This is the number referenced when initializing the
             mode.

     name    The name of the corresponding modeline as given in
             the XF86Config file.

     verticalRefresh
             The vertical refresh rate for the modeline (in Hz).

     flags   Any of the following may be OR'd together:

             XDGAConcurrentAccess
                 Indicates that concurrent client/server access
                 to the framebuffer is possible.  If this flag is
                 not set it is very important to call XDGASync()
                 before directly accessing the framebuffer if a
                 call to XDGAFillRectangle(), XDGACopyArea() or
                 XDGACopyTransparentArea() or any Xlib rendering
                 function has been made prior to such accesses.

             XDGASolidFillRect
                 Indicates that XDGAFillRectangle() is supported.

             XDGABlitRect
                 Indicates that XDGACopyArea() is supported.

             XDGABlitTransRect
                 Indicates that XDGACopyTransparentArea() is sup-
                 ported.

             XDGAPixmap
                 Indicates that a Pixmap will be returned when
                 the mode is initialized. This means that render-
                 ing with Xlib is possible for this mode.

             XDGAInterlaced

XFree86                   Version 4.5.0                         4

XDGA(3)                      XFree86                      XDGA(3)

             XDGADoublescan
                 Indicates that the mode is an interlaced or
                 doublescan mode.

     imageWidth

     imageHeight
             The width and height of the framebuffer area acces-
             sible by the client. This rectangle is always justi-
             fied to the upper left-hand corner.

     pixmapWidth

     pixmapHeight
             The width and height of the framebuffer area acces-
             sible by Xlib.  This rectangle is always justified
             to the upper left-hand corner.  These fields are
             only valid if the XDGAPixmap flag is set in the
             flags field.

     bytesPerScanline
             The pitch of the framebuffer in bytes.

     byteOrder
             MSBFirst or LSBFirst.

     depth   The number of bits in each pixel which contain
             usable data.

     bitsPerPixel
             The number of bits taken up by each pixel.

     redMask

     greenMask

     blueMask
             The RGB masks.  These do not apply to color-indexed
             modes.

     visualClass
             TrueColor, PseudoColor, DirectColor, etc.

     viewportWidth

     viewportHeight
             The dimensions of the portion of the framebuffer
             which will be displayed on the screen.

     xViewPortStep

     yViewPortStep

XFree86                   Version 4.5.0                         5

XDGA(3)                      XFree86                      XDGA(3)

             The granularity of the x,y viewport positioning pos-
             sible with the XDGASetViewport() function.

     maxViewportX

     maxViewportY
             The maximum x and y positions possible with the
             XDGASetViewport() function.

     viewportFlags
             Any of the following may be OR'd together

             XDGAFlipRetrace
                 Indicates that the hardware can switch viewports
                 during the vertical retrace.

             XDGAFlipImmediate
                 Indicates that the hardware can switch viewports
                 immediately without waiting for the vertical
                 retrace.

     XDGASetMode() initialises the XDGAMode corresponding to num.
     To exit DGA mode and return to normal server operation, call
     XDGASetMode() with num set to zero. XDGASetMode() returns a
     pointer to an XDGADevice if successful.  The XDGADevice can
     be freed with XFree(3).  The XDGADevice structure is as fol-
     lows:

     typedef struct {
        XDGAMode mode;
        unsigned char *data;
        Pixmap pixmap;
     } XDGADevice;

     mode    The XDGAMode structure, identical to the information
             returned by XDGAQueryModes().

     data    If direct framebuffer access is desired and possi-
             ble, this field will contain a pointer to the mapped
             framebuffer memory.  Generally, this field will be
             zero unless a call to XDGAOpenFramebuffer() is made
             prior to initialization of the mode.

     pixmap  If the mode supports Xlib rendering as indicated by
             XDGAPixmap in the 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.

     XDGAQueryExtension() checks for the presence of the exten-
     sion and returns the event and error bases.

XFree86                   Version 4.5.0                         6

XDGA(3)                      XFree86                      XDGA(3)

     XDGAQueryVersion() returns the XFree86-DGA major and minor
     version numbers.

     XDGAOpenFramebuffer() maps the framebuffer memory.  The
     client needs sufficient privileges to be able to do this.
     XDGAOpenFramebuffer() should be called prior to initializing
     a DGA mode if direct framebuffer access is desired for that
     mode. XDGAOpenFramebuffer() does not need to be called if
     direct framebuffer access is not required. If the frame-
     buffer is opened,

     XDGACloseFramebuffer() should be called prior to client exit
     to unmap the memory.

     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 mode parameter are
     available:

             XDGAPixmapModeLarge
                 The pixmap size is defined by the pixmapWidth
                 and pixmapHeight fields in the XDGAMode struc-
                 ture.  The x and y values are ignored in this
                 case.

             XDGAPixmapModeSmall
                 The pixmap size is defined by the viewportWidth
                 and viewportHeight fields in the XDGAMode struc-
                 ture.  In this mode, the x and 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 pix-
                 mapWidth and pixmapHeight fields in the
                 XDGAMode. The x and y values returned are the
                 resultant location of the pixmap and may be dif-
                 ferent from the requested x,y location due to
                 platform specific alignment constraints.  All
                 Xlib rendering is clipped to this pixmap rectan-
                 gle.

     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
     xViewPortStep and yViewPortStep fields in the XDGAMode.

     flags can be XDGAFlipRetrace or XDGAFlipImmediate to adjust
     the viewport location at the next vertical retrace or
     immediately.  Values other than the supported values adver-
     tised in the mode's viewportFlags field will result in
     hardware-specific default behavior. XDGAFlipImmediate will
     block until the flip is completed. XDGAFlipRetrace will

XFree86                   Version 4.5.0                         7

XDGA(3)                      XFree86                      XDGA(3)

     generally NOT block so it is necessary to monitor the
     viewport status with XDGAGetViewportStatus(). XDGAFlipIm-
     mediate requests during pending XDGAFlipRetrace requests
     will be ignored.

     XDGAGetViewportStatus() keeps track of the 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:

          while(XDGAGetViewportStatus(dpy, screen));

     waits for all pending viewport changes to finish.

          while(0x2 & XDGAGetViewportStatus(dpy, screen));

     waits until all but the last viewport changes have com-
     pleted.

     XDGACreateColormap() is similar to the Xlib function
     XCreateColormap(3) except that it takes an XDGADevice as an
     argument instead of a Window and Visual.  Though
     XCreateColormap(3) may create usable colormaps in some
     cases, XDGACreateColormap() is the preferred method for
     creating colormaps in DGA since there may not be an adver-
     tised visual compatible with the DGA device.

     XDGAInstallColormap() must be used to install colormaps in
     DGA mode.  XInstallColormap(3) will not work.

     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:

     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 */
     } XDGAButtonEvent;

     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 */

XFree86                   Version 4.5.0                         8

XDGA(3)                      XFree86                      XDGA(3)

        unsigned int keycode; /* detail */
     } XDGAKeyEvent;

     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 */
     } XDGAMotionEvent;

     XDGAKeyEventToXKeyEvent() is a helper function to translate
     XDGAKeyEvents into XKeyEvents suitable for use with
     XLookupKeysym(3).

     XDGAFillRectangle(), XDGACopyArea(), and XDGACopyTransparen-
     tArea() 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 XDGAMode's 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.

     XDGASync() blocks until all server rendering to the frame-
     buffer completes.  If Xlib or the 3 rendering functions
     above are used, 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 XDGAConcurrentAccess
     flag is not set in the XDGAMode's flags field since con-
     current access by the server and client may result in a sys-
     tem lockup.

SEE ALSO

     XFree86(1), XF86Config(5)

AUTHORS

     XFree86-DGA version 2 was written by Mark Vojkovich.  Ver-
     sion 1 was written by Jon Tombs, Harm Hanemaayer, Mark
     Vojkovich.

XFree86                   Version 4.5.0                         9

Generated on 2017-04-03 16:26:17 by $MirOS: src/scripts/roff2htm,v 1.88 2017/01/29 00:51:06 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002–2017 The MirOS Project, Germany.
This product includes material provided by mirabilos.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report — diffs preferred.