XFree86® server 4.x Design (DRAFT) : DGA Extension
Previous: DPMS Extension
Next: The XFree86 X Video Extension (Xv) Device Dependent Layer

## 15. DGA Extension

Drivers can support the XFree86 Direct Graphics Architecture (DGA) by filling out a structure of function pointers and a list of modes and passing them to DGAInit.

> `Bool DGAInit(ScreenPtr pScreen, DGAFunctionPtr funcs,
> DGAModePtr modes, int num)`

> >     /** The DGAModeRec **/

> >     typedef struct {
> >       int num;
> >       DisplayModePtr mode;
> >       int flags;
> >       int imageWidth;
> >       int imageHeight;
> >       int pixmapWidth;
> >       int pixmapHeight;
> >       int bytesPerScanline;
> >       int byteOrder;
> >       int depth;
> >       int bitsPerPixel;
> >       unsigned long red_mask;
> >       unsigned long green_mask;
> >       unsigned long blue_mask;
> >       int viewportWidth;
> >       int viewportHeight;
> >       int xViewportStep;
> >       int yViewportStep;
> >       int maxViewportX;
> >       int maxViewportY;
> >       int viewportFlags;
> >       int offset;
> >       unsigned char *address;
> >       int reserved1;
> >       int reserved2;
> >     } DGAModeRec, *DGAModePtr;

> > `num`

> > > Can be ignored. The DGA DDX will assign these numbers.

> > `mode`

> > > A pointer to the `DisplayModeRec` for this mode.

> > `flags`

> > > The following flags are defined and may be OR'd together:

> > > `DGA_CONCURRENT_ACCESS`

> > > > Indicates that the driver supports concurrent graphics accelerator and linear framebuffer access.

> > > `DGA_FILL_RECT
> > > DGA_BLIT_RECT
> > > DGA_BLIT_RECT_TRANS`

> > > > Indicates that the driver supports the FillRect, BlitRect or BlitTransRect functions in this mode.

> > > `DGA_PIXMAP_AVAILABLE`

> > > > Indicates that Xlib may be used on the framebuffer. This flag will usually be set unless the driver wishes to prohibit this for some reason.

> > > `DGA_INTERLACED
> > > DGA_DOUBLESCAN`

> > > > Indicates that these are interlaced or double scan modes.

> > `imageWidth
> > imageHeight`

> > > These are the dimensions of the linear framebuffer accessible by the client.

> > `pixmapWidth
> > pixmapHeight`

> > > These are the dimensions of the area of the framebuffer accessible by the graphics accelerator.

> > `bytesPerScanline`

> > > Pitch of the framebuffer in bytes.

> > `byteOrder`

> > > Usually the same as `pScrn->imageByteOrder`.

> > `depth`

> > > The depth of the framebuffer in this mode.

> > `bitsPerPixel`

> > > The number of bits per pixel in this mode.

> > `red_mask
> > green_mask
> > blue_mask`

> > > The RGB masks for this mode, if applicable.

> > `viewportWidth
> > viewportHeight`

> > > Dimensions of the visible part of the framebuffer. Usually `mode->HDisplay` and `mode->VDisplay`.

> > `xViewportStep
> > yViewportStep`

> > > The granularity of x and y viewport positions that the driver supports in this mode.

> > `maxViewportX
> > maxViewportY`

> > > The maximum viewport position supported by the driver in this mode.

> > `viewportFlags`

> > > The following may be OR'd together:

> > > `DGA_FLIP_IMMEDIATE`

> > > > The driver supports immediate viewport changes.

> > > `DGA_FLIP_RETRACE`

> > > > The driver supports viewport changes at retrace.

> > `offset`

> > > The offset into the linear framebuffer that corresponds to pixel (0,0) for this mode.

> > `address`

> > > The virtual address of the framebuffer as mapped by the driver. This is needed when DGA_PIXMAP_AVAILABLE is set.

> >     /** The DGAFunctionRec **/

> >     typedef struct {
> >       Bool (*OpenFramebuffer)(
> >            ScrnInfoPtr pScrn,
> >            char **name,
> >            unsigned int *mem,
> >            unsigned int *size,
> >            unsigned int *offset,
> >            unsigned int *extra
> >       );
> >       void (*CloseFramebuffer)(ScrnInfoPtr pScrn);
> >       Bool (*SetMode)(ScrnInfoPtr pScrn, DGAModePtr pMode);
> >       void (*SetViewport)(ScrnInfoPtr pScrn, int x, int y, int flags);
> >       int  (*GetViewport)(ScrnInfoPtr pScrn);
> >       void (*Sync)(ScrnInfoPtr);
> >       void (*FillRect)(
> >            ScrnInfoPtr pScrn,
> >            int x, int y, int w, int h,
> >            unsigned long color
> >       );
> >       void (*BlitRect)(
> >            ScrnInfoPtr pScrn,
> >            int srcx, int srcy,
> >            int w, int h,
> >            int dstx, int dsty
> >       );
> >       void (*BlitTransRect)(
> >            ScrnInfoPtr pScrn,
> >            int srcx, int srcy,
> >            int w, int h,
> >            int dstx, int dsty,
> >            unsigned long color
> >       );
> >     } DGAFunctionRec, *DGAFunctionPtr;

> `Bool OpenFramebuffer (pScrn, name, mem, size, offset, extra)`

> > `OpenFramebuffer()` should pass the client everything it needs to know to be able to open the framebuffer. These parameters are OS specific and their meanings are to be interpreted by an OS specific client library.

> > `name`

> > > The name of the device to open or `NULL` if there is no special device to open. A `NULL` name tells the client that it should open whatever device one would usually open to access physical memory.

> > `mem`

> > > The physical address of the start of the framebuffer, or the `mmap(2)` offset into the device designated by `name`. This is actually a pointer to two consecutive 32-bit values. Regardless of hardware architecture, the first of these is to be set to the low-order 32 bits of the address or offset, and the second is to be set to the high-order 32 bits.

> > `size`

> > > The size of the framebuffer in bytes.

> > `offset`

> > > Any offset into the device, if applicable.

> > `flags`

> > > Any additional information that the client may need. Currently, only the `DGA_NEED_ROOT` flag is defined.

> `void CloseFramebuffer (pScrn)`

> > `CloseFramebuffer()` merely informs the driver (if it even cares) that client no longer needs to access the framebuffer directly. This function is optional.

> `Bool SetMode (pScrn, pMode)`

> > `SetMode()` tells the driver to initialize the mode passed to it. If `pMode` is `NULL`, then the driver should restore the original pre-DGA mode.

> `void SetViewport (pScrn, x, y, flags)`

> > `SetViewport()` tells the driver to make the upper left-hand corner of the visible screen correspond to coordinate `(x,y)` on the framebuffer. `Flags` currently defined are:

> > `DGA_FLIP_IMMEDIATE`

> > > The viewport change should occur immediately.

> > `DGA_FLIP_RETRACE`

> > > The viewport change should occur at the vertical retrace, but this function should return sooner if possible.

> > The `(x,y)` locations will be passed as the client specified them, however, the driver is expected to round these locations down to the next supported location as specified by the `xViewportStep` and `yViewportStep` for the current mode.

> `int GetViewport (pScrn)`

> > `GetViewport()` gets the current page flip status. Set bits in the returned int correspond to viewport change requests still pending. For instance, set bit zero if the last SetViewport request is still pending, bit one if the one before that is still pending, etc.

> `void Sync (pScrn)`

> > This function should ensure that any graphics accelerator operations have finished. This function should not return until the graphics accelerator is idle.

> `void FillRect (pScrn, x, y, w, h, color)`

> > This optional function should fill a rectangle `w x h` located at `(x,y)` in the given color.

> `void BlitRect (pScrn, srcx, srcy, w, h, dstx, dsty)`

> > This optional function should copy an area `w x h` located at `(srcx,srcy)` to location `(dstx,dsty)`. This function will need to handle copy directions as appropriate.

> `void BlitTransRect (pScrn, srcx, srcy, w, h, dstx, dsty, color)`

> > This optional function is the same as BlitRect except that pixels in the source corresponding to the color key `color` should be skipped.

XFree86® server 4.x Design (DRAFT) : DGA Extension
Previous: DPMS Extension
Next: The XFree86 X Video Extension (Xv) Device Dependent Layer