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.

/** The DGAFunctionRec **/

typedef struct {
  Bool (*OpenFramebuffer)(
       ScrnInfoPtr pScrn, 
       char **name,
       unsigned char **mem, 
       int *size,
       int *offset,
       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 (*Flush)(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.

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 Flush (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 × 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 × 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.