Initial revision

1 files changed, 1427 insertions, 0 deletions

diff --git a/hw/xfree86/xaa/XAA.HOWTO b/hw/xfree86/xaa/XAA.HOWTO
new file mode 100644
index 000000000..95d9d6100
--- /dev/null
+++ b/hw/xfree86/xaa/XAA.HOWTO
@@ -0,0 +1,1427 @@
+
+
+                          XAA.HOWTO
+
+  This file describes how to add basic XAA support to a chipset driver.
+
+0)  What is XAA
+1)  XAA Initialization and Shutdown
+2)  The Primitives
+  2.0  Generic Flags
+  2.1  Screen to Screen Copies
+  2.2  Solid Fills
+  2.3  Solid Lines
+  2.4  Dashed Lines
+  2.5  Color Expand Fills
+    2.5.1 Screen to Screen Color Expansion
+    2.5.2 CPU to Screen Color Expansion
+      2.5.2.1 The Direct Method
+      2.5.2.2 The Indirect Method
+  2.6  8x8 Mono Pattern Fills
+  2.7  8x8 Color Pattern Fills
+  2.8  Image Writes
+    2.8.1 The Direct Method
+    2.8.2 The Indirect Method
+  2.9 Clipping
+3)  The Pixmap Cache
+4)  Offscreen Pixmaps
+
+/********************************************************************/
+
+0) WHAT IS XAA
+	
+   XAA (the XFree86 Acceleration Architecture) is a device dependent
+layer that encapsulates the unaccelerated framebuffer rendering layer,
+intercepting rendering commands sent to it from higher levels of the
+server.  For rendering tasks where hardware acceleration is not 
+possible, XAA allows the requests to proceed to the software rendering
+code.  Otherwise, XAA breaks the sometimes complicated X primitives
+into simpler primitives more suitable for hardware acceleration and
+will use accelerated functions exported by the chipset driver to 
+render these.
+
+   XAA provides a simple, easy to use driver interface that allows
+the driver to communicate its acceleration capabilities and restrictions
+back to XAA.  XAA will use the information provided by the driver
+to determine whether or not acceleration will be possible for a
+particular X primitive.
+
+
+
+1) XAA INITIALIZATION AND SHUTDOWN
+
+   All relevant prototypes and defines are in xaa.h.
+
+   To Initialize the XAA layer, the driver should allocate an XAAInfoRec
+via XAACreateInfoRec(), fill it out as described in this document
+and pass it to XAAInit().  XAAInit() must be called _after_ the 
+framebuffer initialization (usually cfb?ScreenInit or similar) since 
+it is "wrapping" that layer.  XAAInit() should be called _before_ the 
+cursor initialization (usually miDCInitialize) since the cursor
+layer needs to "wrap" all the rendering code including XAA.
+
+   When shutting down, the driver should free the XAAInfoRec
+structure in its CloseScreen function via XAADestroyInfoRec().
+The prototypes for the functions mentioned above are as follows:
+
+   XAAInfoRecPtr XAACreateInfoRec(void);
+   Bool XAAInit(ScreenPtr, XAAInfoRecPtr);
+   void XAADestroyInfoRec(XAAInfoRec);
+
+   The driver informs XAA of it's acceleration capablities by
+filling out an XAAInfoRec structure and passing it to XAAInit().
+The XAAInfoRec structure contains many fields, most of which are
+function pointers and flags.  Each primitive will typically have
+two functions and a set of flags associated with it, but it may
+have more.  These two functions are the "SetupFor" and "Subsequent" 
+functions.  The "SetupFor" function tells the driver that the 
+hardware should be initialized for a particular type of graphics 
+operation.  After the "SetupFor" function, one or more calls to the 
+"Subsequent" function will be made to indicate that an instance
+of the particular primitive should be rendered by the hardware.
+The details of each instance (width, height, etc...) are given
+with each "Subsequent" function.   The set of flags associated
+with each primitive lets the driver tell XAA what its hardware
+limitations are (eg. It doesn't support a planemask, it can only
+do one of the raster-ops, etc...).
+
+  Of the XAAInfoRec fields, one is required.  This is the
+Sync function.  XAA initialization will fail if this function
+is not provided.
+
+void Sync(ScrnInfoPtr pScrn)			/* Required */
+
+   Sync will be called when XAA needs to be certain that all
+   graphics coprocessor operations are finished, such as when
+   the framebuffer must be written to or read from directly
+   and it must be certain that the accelerator will not be
+   overwriting the area of interest.
+
+   One needs to make certain that the Sync function not only
+   waits for the accelerator fifo to empty, but that it waits for
+   the rendering of that last operation to complete.
+
+   It is guaranteed that no direct framebuffer access will
+   occur after a "SetupFor" or "Subsequent" function without
+   the Sync function being called first.
+
+
+
+2)  THE PRIMITIVES
+
+2.0  Generic Flags
+
+  Each primitive type has a set of flags associated with it which
+allow the driver to tell XAA what the hardware limitations are.
+The common ones are as follows:
+
+/* Foreground, Background, rop and planemask restrictions */
+
+   GXCOPY_ONLY
+
+     This indicates that the accelerator only supports GXcopy
+     for the particular primitive.
+
+   ROP_NEEDS_SOURCE
+
+     This indicates that the accelerator doesn't supports a
+     particular primitive with rops that don't involve the source.
+     These rops are GXclear, GXnoop, GXinvert and GXset. If neither
+     this flag nor GXCOPY_ONLY is defined, it is assumed that the
+     accelerator supports all 16 raster operations (rops) for that
+     primitive.
+
+   NO_PLANEMASK
+
+     This indicates that the accelerator does not support a hardware
+     write planemask for the particular primitive.
+
+   RGB_EQUAL
+
+     This indicates that the particular primitive requires the red, 
+     green and blue bytes of the foreground color (and background color,
+     if applicable) to be equal. This is useful for 24bpp when a graphics
+     coprocessor is used in 8bpp mode, which is not uncommon in older
+     hardware since some have no support for or only limited support for 
+     acceleration at 24bpp. This way, many operations will be accelerated 
+     for the common case of "grayscale" colors.  This flag should only
+     be used in 24bpp.
+
+  In addition to the common ones listed above which are possible for
+nearly all primitives, each primitive may have its own flags specific
+to that primitive.  If such flags exist they are documented in the
+descriptions of those primitives below.
+ 
+
+
+
+2.1  Screen to Screen Copies
+
+   The SetupFor and Subsequent ScreenToScreenCopy functions provide
+   an interface for copying rectangular areas from video memory to
+   video memory.  To accelerate this primitive the driver should
+   provide both the SetupFor and Subsequent functions and indicate
+   the hardware restrictions via the ScreenToScreenCopyFlags.  The
+   NO_PLANEMASK, GXCOPY_ONLY and ROP_NEEDS_SOURCE flags as described
+   in Section 2.0 are valid as well as the following:
+
+    NO_TRANSPARENCY
+     
+      This indicates that the accelerator does not support skipping
+      of color keyed pixels when copying from the source to the destination.
+
+    TRANSPARENCY_GXCOPY_ONLY
+
+      This indicates that the accelerator supports skipping of color keyed
+      pixels only when the rop is GXcopy.
+
+    ONLY_LEFT_TO_RIGHT_BITBLT
+
+      This indicates that the hardware only accepts blitting when the
+      x direction is positive.
+
+    ONLY_TWO_BITBLT_DIRECTIONS
+
+      This indicates that the hardware can only cope with blitting when
+      the direction of x is the same as the direction in y.
+
+
+void SetupForScreenToScreenCopy( ScrnInfoPtr pScrn,
+			int xdir, int ydir,
+			int rop,
+			unsigned int planemask,
+			int trans_color )
+
+    When this is called, SubsequentScreenToScreenCopy will be called
+    one or more times directly after.  If ydir is 1, then the accelerator
+    should copy starting from the top (minimum y) of the source and
+    proceed downward.  If ydir is -1, then the accelerator should copy
+    starting from the bottom of the source (maximum y) and proceed
+    upward.  If xdir is 1, then the accelerator should copy each
+    y scanline starting from the leftmost pixel of the source.  If
+    xdir is -1, it should start from the rightmost pixel.  
+       If trans_color is not -1 then trans_color indicates that the
+    accelerator should not copy pixels with the color trans_color
+    from the source to the destination, but should skip them. 
+    Trans_color is always -1 if the NO_TRANSPARENCY flag is set.
+ 
+
+void SubsequentScreenToScreenCopy(ScrnInfoPtr pScrn,
+			int x1, int y1,
+			int x2, int y2,
+			int width, int height)
+
+    Copy a rectangle "width" x "height" from the source (x1,y1) to the 
+    destination (x2,y2) using the parameters passed by the last
+    SetupForScreenToScreenCopy call. (x1,y1) and (x2,y2) always denote 
+    the upper left hand corners of the source and destination regardless 
+    of which xdir and ydir values are given by SetupForScreenToScreenCopy.  
+
+
+
+2.2 Solid Fills
+
+   The SetupFor and Subsequent SolidFill(Rect/Trap) functions provide
+   an interface for filling rectangular areas of the screen with a
+   foreground color.  To accelerate this primitive the driver should
+   provide both the SetupForSolidFill and SubsequentSolidFillRect 
+   functions and indicate the hardware restrictions via the SolidFillFlags.
+   The driver may optionally provide a SubsequentSolidFillTrap if
+   it is capable of rendering the primitive correctly.  
+   The GXCOPY_ONLY, ROP_NEEDS_SOURCE, NO_PLANEMASK and RGB_EQUAL flags
+   as described in Section 2.0 are valid.
+
+  
+void SetupForSolidFill(ScrnInfoPtr pScrn, 
+                       int color, int rop, unsigned int planemask)
+
+    SetupForSolidFill indicates that any combination of the following 
+    may follow it.
+
+	SubsequentSolidFillRect
+	SubsequentSolidFillTrap
+
+
+ 
+void SubsequentSolidFillRect(ScrnInfoPtr pScrn, int x, int y, int w, int h)
+
+     Fill a rectangle of dimensions "w" by "h" with origin at (x,y) 
+     using the color, rop and planemask given by the last 
+     SetupForSolidFill call.
+
+void SubsequentSolidFillTrap(ScrnInfoPtr pScrn, int y, int h, 
+	int left, int dxL, int dyL, int eL,
+	int right, int dxR, int dyR, int eR)
+
+     These parameters describe a trapezoid via a version of
+     Bresenham's parameters. "y" is the top line. "h" is the
+     number of spans to be filled in the positive Y direction.
+     "left" and "right" indicate the starting X values of the
+     left and right edges.  dy/dx describes the edge slope.
+     These are not the deltas between the beginning and ending
+     points on an edge.  They merely describe the slope. "e" is
+     the initial error term.  It's the relationships between dx,
+     dy and e that define the edge.
+	If your engine does not do bresenham trapezoids or does
+     not allow the programmer to specify the error term then
+     you are not expected to be able to accelerate them.
+
+
+2.3  Solid Lines
+
+    XAA provides an interface for drawing thin lines.  In order to
+    draw X lines correctly a high degree of accuracy is required.
+    This usually limits line acceleration to hardware which has a
+    Bresenham line engine, though depending on the algorithm used,
+    other line engines may come close if they accept 16 bit line 
+    deltas.  XAA has both a Bresenham line interface and a two-point
+    line interface for drawing lines of arbitrary orientation.  
+    Additionally there is a SubsequentSolidHorVertLine which will
+    be used for all horizontal and vertical lines.  Horizontal and
+    vertical lines are handled separately since hardware that doesn't
+    have a line engine (or has one that is unusable due to precision
+    problems) can usually draw these lines by some other method such
+    as drawing them as thin rectangles.  Even for hardware that can
+    draw arbitrary lines via the Bresenham or two-point interfaces,
+    the SubsequentSolidHorVertLine is used for horizontal and vertical
+    lines since most hardware is able to render the horizontal lines
+    and sometimes the vertical lines faster by other methods (Hint:
+    try rendering horizontal lines as flattened rectangles).  If you have 
+    not provided a SubsequentSolidHorVertLine but you have provided 
+    Bresenham or two-point lines, a SubsequentSolidHorVertLine function 
+    will be supplied for you.
+
+    The flags field associated with Solid Lines is SolidLineFlags and 
+    the GXCOPY_ONLY, ROP_NEEDS_SOURCE, NO_PLANEMASK and RGB_EQUAL flags as
+    described in Section 2.0 are valid restrictions.  
+
+    Some line engines have line biases hardcoded to comply with
+    Microsoft line biasing rules.  A tell-tale sign of this is the
+    hardware lines not matching the software lines in the zeroth and
+    fourth octants.  The driver can set the flag:
+	
+	MICROSOFT_ZERO_LINE_BIAS
+
+    in the AccelInfoRec.Flags field to adjust the software lines to
+    match the hardware lines.   This is in the generic flags field
+    rather than the SolidLineFlags since this flag applies to all
+    software zero-width lines on the screen and not just the solid ones.
+
+
+void SetupForSolidLine(ScrnInfoPtr pScrn, 
+                       int color, int rop, unsigned int planemask)
+
+    SetupForSolidLine indicates that any combination of the following 
+    may follow it.
+
+	SubsequentSolidBresenhamLine
+	SubsequentSolidTwoPointLine
+        SubsequentSolidHorVertLine 	
+
+
+void SubsequentSolidHorVertLine( ScrnInfoPtr pScrn,
+        			int x, int y, int len, int dir )
+
+    All vertical and horizontal solid thin lines are rendered with
+    this function.  The line starts at coordinate (x,y) and extends
+    "len" pixels inclusive.  In the direction indicated by "dir."
+    The direction is either DEGREES_O or DEGREES_270.  That is, it
+    always extends to the right or down.
+
+
+
+void SubsequentSolidTwoPointLine(ScrnInfoPtr pScrn,
+        	int x1, int y1, int x2, int y2, int flags)
+
+    Draw a line from (x1,y1) to (x2,y2).  If the flags field contains
+    the flag OMIT_LAST, the last pixel should not be drawn.  Otherwise,
+    the pixel at (x2,y2) should be drawn.
+
+    If you use the TwoPoint line interface there is a good possibility
+    that your line engine has hard-coded line biases that do not match
+    the default X zero-width lines.  If so, you may need to set the
+    MICROSOFT_ZERO_LINE_BIAS flag described above.  Note that since
+    any vertex in the 16-bit signed coordinate system is valid, your
+    line engine is expected to handle 16-bit values if you have hardware
+    line clipping enabled.  If your engine cannot handle 16-bit values,
+    you should not use hardware line clipping.
+
+
+void SubsequentSolidBresenhamLine(ScrnInfoPtr pScrn,
+        int x, int y, int major, int minor, int err, int len, int octant)
+
+    "X" and "y" are the starting point of the line.  "Major" and "minor" 
+    are the major and minor step constants.  "Err" is the initial error
+    term.  "Len" is the number of pixels to be drawn (inclusive). "Octant"
+    can be any combination of the following flags OR'd together:
+
+      Y_MAJOR		Y is the major axis (X otherwise)
+      X_DECREASING	The line is drawn from right to left
+      Y_DECREASING	The line is drawn from bottom to top
+	  
+    The major, minor and err terms are the "raw" Bresenham parameters
+    consistent with a line engine that does:
+
+	e = err;
+	while(len--) {
+	   DRAW_POINT(x,y);
+	   e += minor;
+	   if(e >= 0) {
+		e -= major;
+		TAKE_ONE_STEP_ALONG_MINOR_AXIS;
+	   }
+	   TAKE_ONE_STEP_ALONG_MAJOR_AXIS;
+	}
+
+    IBM 8514 style Bresenham line interfaces require their parameters
+    modified in the following way:
+
+	Axial = minor;
+	Diagonal = minor - major;
+	Error = minor + err;
+
+SolidBresenhamLineErrorTermBits
+
+    This field allows the driver to tell XAA how many bits large its
+    Bresenham parameter registers are.  Many engines have registers that
+    only accept 12 or 13 bit Bresenham parameters, and the parameters
+    for clipped lines may overflow these if they are not scaled down.
+    If this field is not set, XAA will assume the engine can accomodate
+    16 bit parameters, otherwise, it will scale the parameters to the
+    size specified.
+
+
+2.4  Dashed Lines
+
+    The same degree of accuracy required by the solid lines is required
+    for drawing dashed lines as well.  The dash pattern itself is a
+    buffer of binary data where ones are expanded into the foreground
+    color and zeros either correspond to the background color or
+    indicate transparency depending on whether or not DoubleDash or
+    OnOffDashes are being drawn.  
+
+    The flags field associated with dashed Lines is DashedLineFlags and 
+    the GXCOPY_ONLY, ROP_NEEDS_SOURCE, NO_PLANEMASK and RGB_EQUAL flags as
+    described in Section 2.0 are valid restrictions.  Additionally, the
+    following flags are valid:
+
+      NO_TRANSPARENCY
+
+	This indicates that the driver cannot support dashed lines
+	with transparent backgrounds (OnOffDashes).
+
+      TRANSPARENCY_ONLY
+
+	This indicates that the driver cannot support dashes with
+	both a foreground and background color (DoubleDashes).
+
+      LINE_PATTERN_POWER_OF_2_ONLY
+
+	This indicates that only patterns with a power of 2 length
+	can be accelerated.
+
+      LINE_PATTERN_LSBFIRST_MSBJUSTIFIED
+      LINE_PATTERN_LSBFIRST_LSBJUSTIFIED
+      LINE_PATTERN_MSBFIRST_MSBJUSTIFIED
+      LINE_PATTERN_MSBFIRST_LSBJUSTIFIED
+
+	These describe how the line pattern should be packed.
+	The pattern buffer is DWORD padded.  LSBFIRST indicates
+	that the pattern runs from the LSB end to the MSB end.
+	MSBFIRST indicates that the pattern runs from the MSB end
+	to the LSB end.  When the pattern does not completely fill
+	the DWORD padded buffer, the pattern will be justified 
+	towards the MSB or LSB end based on the flags above.
+
+
+    The following field indicates the maximum length dash pattern that
+    should be accelerated.
+
+	int DashPatternMaxLength
+
+
+void SetupForDashedLine(ScrnInfoPtr pScrn,
+		int fg, int bg, int rop, unsigned int planemask,
+        	int length, unsigned char *pattern)
+
+    
+    SetupForDashedLine indicates that any combination of the following 
+    may follow it.
+
+	SubsequentDashedBresenhamLine
+	SubsequentDashedTwoPointLine
+
+    If "bg" is -1, then the background (pixels corresponding to clear
+    bits in the pattern) should remain unmodified. "Bg" indicates the
+    background color otherwise.  "Length" indicates the length of
+    the pattern in bits and "pattern" points to the DWORD padded buffer
+    holding the pattern which has been packed according to the flags
+    set above.  
+
+    
+void SubsequentDashedTwoPointLine( ScrnInfoPtr pScrn,
+        int x1, int y1, int x2, int y2, int flags, int phase)
+
+void SubsequentDashedBresenhamLine(ScrnInfoPtr pScrn,
+        int x1, int y1, int major, int minor, int err, int len, int octant,
+        int phase)
+  
+    These are the same as the SubsequentSolidTwoPointLine and
+    SubsequentBresenhamLine functions except for the addition
+    of the "phase" field which indicates the offset into the dash 
+    pattern that the pixel at (x1,y1) corresponds to.
+
+    As with the SubsequentBresenhamLine, there is an
+ 
+	int DashedBresenhamLineErrorTermBits 
+   
+    field which indicates the size of the error term registers
+    used with dashed lines.  This is usually the same value as
+    the field for the solid lines (because it's usually the same
+    register).
+       
+      
+
+2.5   Color Expansion Fills
+
+    When filling a color expansion rectangle, the accelerator
+    paints each pixel depending on whether or not a bit in a
+    corresponding bitmap is set or clear. Opaque expansions are 
+    when a set bit corresponds to the foreground color and a clear 
+    bit corresponds to the background color.  A transparent expansion
+    is when a set bit corresponds to the foreground color and a
+    clear bit indicates that the pixel should remain unmodified.
+   
+    The graphics accelerator usually has access to the source 
+    bitmap in one of two ways: 1) the bitmap data is sent serially
+    to the accelerator by the CPU through some memory mapped aperture
+    or 2) the accelerator reads the source bitmap out of offscreen
+    video memory.  Some types of primitives are better suited towards 
+    one method or the other.  Type 2 is useful for reusable patterns
+    such as stipples which can be cached in offscreen memory.  The
+    aperature method can be used for stippling but the CPU must pass
+    the data across the bus each time a stippled fill is to be performed.  
+    For expanding 1bpp client pixmaps or text strings to the screen,
+    the aperature method is usually superior because the intermediate
+    copy in offscreen memory needed by the second method would only be 
+    used once.  Unfortunately, many accelerators can only do one of these
+    methods and not both.  
+
+    XAA provides both ScreenToScreen and CPUToScreen color expansion 
+    interfaces for doing color expansion fills.  The ScreenToScreen
+    functions can only be used with hardware that supports reading
+    of source bitmaps from offscreen video memory, and these are only
+    used for cacheable patterns such as stipples.  There are two
+    variants of the CPUToScreen routines - a direct method intended
+    for hardware that has a transfer aperature, and an indirect method
+    intended for hardware without transfer aperatures or hardware
+    with unusual transfer requirements.  Hardware that can only expand
+    bitmaps from video memory should supply ScreenToScreen routines
+    but also ScanlineCPUToScreen (indirect) routines to optimize transfers 
+    of non-cacheable data.  Hardware that can only accept source bitmaps
+    through an aperature should supply CPUToScreen (or ScanlineCPUToScreen) 
+    routines. Hardware that can do both should provide both ScreenToScreen 
+    and CPUToScreen routines.
+
+    For both ScreenToScreen and CPUToScreen interfaces, the GXCOPY_ONLY,
+    ROP_NEEDS_SOURCE, NO_PLANEMASK and RGB_EQUAL flags described in
+    Section 2.0 are valid as well as the following:
+
+    /* bit order requirements (one of these must be set) */
+   
+    BIT_ORDER_IN_BYTE_LSBFIRST
+
+      This indicates that least significant bit in each byte of the source
+      data corresponds to the leftmost of that block of 8 pixels.  This
+      is the prefered format.
+
+    BIT_ORDER_IN_BYTE_MSBFIRST    
+
+      This indicates that most significant bit in each byte of the source
+      data corresponds to the leftmost of that block of 8 pixels.
+
+    /* transparency restrictions */
+
+    NO_TRANSPARENCY
+
+      This indicates that the accelerator cannot do a transparent expansion.
+
+    TRANSPARENCY_ONLY
+
+      This indicates that the accelerator cannot do an opaque expansion.
+      In cases where where the background needs to be filled, XAA will
+      render the primitive in two passes when using the CPUToScreen
+      interface, but will not do so with the ScreenToScreen interface 
+      since that would require caching of two patterns.  Some 
+      ScreenToScreen hardware may be able to render two passes at the
+      driver level and remove the TRANSPARENCY_ONLY restriction if
+      it can render pixels corresponding to the zero bits.
+
+
+
+2.5.1  Screen To Screen Color Expansion
+
+    The ScreenToScreenColorExpandFill routines provide an interface
+    for doing expansion blits from source patterns stored in offscreen
+    video memory.
+
+    void SetupForScreenToScreenColorExpandFill (ScrnInfoPtr pScrn,
+        			int fg, int bg, 
+				int rop, unsigned int planemask)
+
+
+    Ones in the source bitmap will correspond to the fg color.
+    Zeros in the source bitmap will correspond to the bg color
+    unless bg = -1.  In that case the pixels corresponding to the
+    zeros in the bitmap shall be left unmodified by the accelerator.
+
+    For hardware that doesn't allow an easy implementation of skipleft, the
+    driver can replace CacheMonoStipple function with one that stores multiple
+    rotated copies of the stipple and select between them. In this case the
+    driver should set CacheColorExpandDensity to tell XAA how many copies of
+    the pattern are stored in the width of a cache slot. For instance if the
+    hardware can specify the starting address in bytes, then 8 rotated copies
+    of the stipple are needed and CacheColorExpandDensity should be set to 8.
+
+    void SubsequentScreenToScreenColorExpandFill( ScrnInfoPtr pScrn,
+				int x, int y, int w, int h,
+				int srcx, int srcy, int offset )
+
+   
+    Fill a rectangle "w" x "h" at location (x,y).  The source pitch
+    between scanlines is the framebuffer pitch (pScrn->displayWidth
+    pixels) and srcx and srcy indicate the start of the source pattern 
+    in units of framebuffer pixels. "Offset" indicates the bit offset
+    into the pattern that corresponds to the pixel being painted at
+    "x" on the screen.  Some hardware accepts source coordinates in
+    units of bits which makes implementation of the offset trivial.
+    In that case, the bit address of the source bit corresponding to
+    the pixel painted at (x,y) would be:
+	
+     (srcy * pScrn->displayWidth + srcx) * pScrn->bitsPerPixel + offset
+
+    It should be noted that the offset assumes LSBFIRST hardware.  
+    For MSBFIRST hardware, the driver may need to implement the 
+    offset by bliting only from byte boundaries and hardware clipping.
+
+
+
+2.5.2  CPU To Screen Color Expansion
+
+
+    The CPUToScreenColorExpandFill routines provide an interface for 
+    doing expansion blits from source patterns stored in system memory.
+    There are two varieties of this primitive, a CPUToScreenColorExpandFill
+    and a ScanlineCPUToScreenColorExpandFill.  With the 
+    CPUToScreenColorExpandFill method, the source data is sent serially
+    through a memory mapped aperature.  With the Scanline version, the
+    data is rendered scanline at a time into intermediate buffers with
+    a call to SubsequentColorExpandScanline following each scanline.
+
+    These two methods have separate flags fields, the
+    CPUToScreenColorExpandFillFlags and ScanlineCPUToScreenColorExpandFillFlags
+    respectively.  Flags specific to one method or the other are described 
+    in sections 2.5.2.1 and 2.5.2.2 but for both cases the bit order and
+    transparency restrictions listed at the beginning of section 2.5 are 
+    valid as well as the following:
+    
+    /* clipping  (optional) */
+    
+    LEFT_EDGE_CLIPPING
+ 
+      This indicates that the accelerator supports omission of up to
+      31 pixels on the left edge of the rectangle to be filled.  This
+      is beneficial since it allows transfer of the source bitmap to
+      always occur from DWORD boundaries. 
+
+    LEFT_EDGE_CLIPPING_NEGATIVE_X
+
+      This flag indicates that the accelerator can render color expansion
+      rectangles even if the value of x origin is negative (off of
+      the screen on the left edge).
+
+    /* misc */
+
+    TRIPLE_BITS_24BPP
+
+      When enabled (must be in 24bpp mode), color expansion functions
+      are expected to require three times the amount of bits to be
+      transferred so that 24bpp grayscale colors can be used with color
+      expansion in 8bpp coprocessor mode. Each bit is expanded to 3
+      bits when writing the monochrome data.
+
+
+ 2.5.1 The Direct Method 
+
+
+    Using the direct method of color expansion XAA will send all
+    bitmap data to the accelerator serially through an memory mapped
+    transfer window defined by the following two fields:
+
+      unsigned char *ColorExpandBase
+
+        This indicates the memory address of the beginning of the aperture.
+
+      int ColorExpandRange
+
+        This indicates the size in bytes of the aperture.
+
+    The driver should specify how the transfered data should be padded.
+    There are options for both the padding of each Y scanline and for the
+    total transfer to the aperature.
+    One of the following two flags must be set:
+
+      CPU_TRANSFER_PAD_DWORD
+
+        This indicates that the total transfer (sum of all scanlines) sent
+        to the aperature must be DWORD padded.  This is the default behavior.
+
+      CPU_TRANSFER_PAD_QWORD 
+
+	This indicates that the total transfer (sum of all scanlines) sent
+	to the aperature must be QWORD padded.  With this set, XAA will send
+        an extra DWORD to the aperature when needed to ensure that only
+        an even number of DWORDs are sent.
+
+    And then there are the flags for padding of each scanline:
+
+      SCANLINE_PAD_DWORD
+
+	This indicates that each Y scanline should be DWORD padded.
+        This is the only option available and is the default.
+
+    Finally, there is the CPU_TRANSFER_BASE_FIXED flag which indicates
+    that the aperture is a single register rather than a range of
+    registers, and XAA should write all of the data to the first DWORD.
+    If the ColorExpandRange is not large enough to accomodate scanlines
+    the width of the screen, this option will be forced. That is, the
+    ColorExpandRange must be:
+
+        ((virtualX + 31)/32) * 4   bytes or more.
+
+        ((virtualX + 62)/32 * 4) if LEFT_EDGE_CLIPPING_NEGATIVE_X is set.
+  
+    If the TRIPLE_BITS_24BPP flag is set, the required area should be 
+    multiplied by three.
+     
+    
+void SetupForCPUToScreenColorExpandFill(ScrnInfoPtr pScrn,
+        		int fg, int bg,
+			int rop,
+			unsigned int planemask)
+
+  
+ 
+     Ones in the source bitmap will correspond to the fg color.
+     Zeros in the source bitmap will correspond to the bg color
+     unless bg = -1.  In that case the pixels corresponding to the
+     zeros in the bitmap shall be left unmodified by the accelerator.
+
+
+void SubsequentCPUToScreenColorExpandFill(ScrnInfoPtr pScrn,
+			int x, int y, int w, int h,
+			int skipleft )
+
+     When this function is called, the accelerator should be setup
+     to fill a rectangle of dimension "w" by "h" with origin at (x,y)
+     in the fill style prescribed by the last call to 
+     SetupForCPUToScreenColorExpandFill.  XAA will pass the data to 
+     the aperture immediately after this function is called.  If the 
+     skipleft is non-zero (and LEFT_EDGE_CLIPPING has been enabled), then 
+     the accelerator _should_not_ render skipleft pixels on the leftmost
+     edge of the rectangle.  Some engines have an alignment feature
+     like this built in, some others can do this using a clipping
+     window.
+
+     It can be arranged for XAA to call Sync() after it is through 
+     calling the Subsequent function by setting SYNC_AFTER_COLOR_EXPAND 
+     in the  CPUToScreenColorExpandFillFlags.  This can provide the driver 
+     with an oportunity to reset a clipping window if needed.
+
+    
+2.5.2  The Indirect Method 
+
+     Using the indirect method, XAA will render the bitmap data scanline
+     at a time to one or more buffers.  These buffers may be memory
+     mapped apertures or just intermediate storage.
+
+     int NumScanlineColorExpandBuffers
+
+       This indicates the number of buffers available.
+
+     unsigned char **ScanlineColorExpandBuffers
+
+       This is an array of pointers to the memory locations of each buffer.
+       Each buffer is expected to be large enough to accommodate scanlines
+       the width of the screen.  That is:
+
+        ((virtualX + 31)/32) * 4   bytes or more.
+
+        ((virtualX + 62)/32 * 4) if LEFT_EDGE_CLIPPING_NEGATIVE_X is set.
+  
+     Scanlines are always DWORD padded.
+     If the TRIPLE_BITS_24BPP flag is set, the required area should be 
+     multiplied by three.
+
+
+void SetupForScanlineCPUToScreenColorExpandFill(ScrnInfoPtr pScrn,
+        		int fg, int bg,
+			int rop,
+			unsigned int planemask)
+ 
+     Ones in the source bitmap will correspond to the fg color.
+     Zeros in the source bitmap will correspond to the bg color
+     unless bg = -1.  In that case the pixels corresponding to the
+     zeros in the bitmap shall be left unmodified by the accelerator.
+
+     
+void SubsequentScanlineCPUToScreenColorExpandFill(ScrnInfoPtr pScrn,
+			int x, int y, int w, int h,
+			int skipleft )
+
+void SubsequentColorExpandScanline(ScrnInfoPtr pScrn, int bufno)
+
+
+    When SubsequentScanlineCPUToScreenColorExpandFill is called, XAA 
+    will begin transfering the source data scanline at a time, calling  
+    SubsequentColorExpandScanline after each scanline.  If more than
+    one buffer is available, XAA will cycle through the buffers.
+    Subsequent scanlines will use the next buffer and go back to the
+    buffer 0 again when the last buffer is reached.  The index into
+    the ScanlineColorExpandBuffers array is presented as "bufno"
+    with each SubsequentColorExpandScanline call.
+
+    The skipleft field is the same as for the direct method.
+
+    The indirect method can be use to send the source data directly 
+    to a memory mapped aperture represented by a single color expand
+    buffer, scanline at a time, but more commonly it is used to place 
+    the data into offscreen video memory so that the accelerator can 
+    blit it to the visible screen from there.  In the case where the
+    accelerator permits rendering into offscreen video memory while
+    the accelerator is active, several buffers can be used so that
+    XAA can be placing source data into the next buffer while the
+    accelerator is blitting the current buffer.  For cases where
+    the accelerator requires some special manipulation of the source
+    data first, the buffers can be in system memory.  The CPU can
+    manipulate these buffers and then send the data to the accelerator.
+
+
+
+2.6   8x8 Mono Pattern Fills
+
+    XAA provides support for two types of 8x8 hardware patterns -
+    "Mono" patterns and "Color" patterns.  Mono pattern data is
+    64 bits of color expansion data with ones indicating the
+    foreground color and zeros indicating the background color.
+    The source bitmaps for the 8x8 mono patterns can be presented
+    to the graphics accelerator in one of two ways.  They can be
+    passed as two DWORDS to the 8x8 mono pattern functions or
+    they can be cached in offscreen memory and their locations
+    passed to the 8x8 mono pattern functions.  In addition to the
+    GXCOPY_ONLY, ROP_NEEDS_SOURCE, NO_PLANEMASK and RGB_EQUAL flags
+    defined in Section 2.0, the following are defined for the
+    Mono8x8PatternFillFlags:
+
+    HARDWARE_PATTERN_PROGRAMMED_BITS
+
+      This indicates that the 8x8 patterns should be packed into two
+      DWORDS and passed to the 8x8 mono pattern functions.  The default
+      behavior is to cache the patterns in offscreen video memory and
+      pass the locations of these patterns to the functions instead.
+      The pixmap cache must be enabled for the default behavior (8x8 
+      pattern caching) to work.  See Section 3 for how to enable the
+      pixmap cache. The pixmap cache is not necessary for 
+      HARDWARE_PATTERN_PROGRAMMED_BITS.
+
+    HARDWARE_PATTERN_PROGRAMMED_ORIGIN
+
+      If the hardware supports programmable pattern offsets then
+      this option should be set. See the table below for further
+      infomation.
+
+    HARDWARE_PATTERN_SCREEN_ORIGIN
+
+      Some hardware wants the pattern offset specified with respect to the
+      upper left-hand corner of the primitive being drawn.  Other hardware 
+      needs the option HARDWARE_PATTERN_SCREEN_ORIGIN set to indicate that 
+      all pattern offsets should be referenced to the upper left-hand 
+      corner of the screen.  HARDWARE_PATTERN_SCREEN_ORIGIN is preferable 
+      since this is more natural for the X-Window system and offsets will 
+      have to be recalculated for each Subsequent function otherwise.
+
+    BIT_ORDER_IN_BYTE_MSBFIRST
+    BIT_ORDER_IN_BYTE_LSBFIRST
+
+      As with other color expansion routines this indicates whether the
+      most or the least significant bit in each byte from the pattern is 
+      the leftmost on the screen.
+
+    TRANSPARENCY_ONLY
+    NO_TRANSPARENCY
+
+      This means the same thing as for the color expansion rect routines
+      except that for TRANSPARENCY_ONLY XAA will not render the primitive
+      in two passes since this is more easily handled by the driver.
+      It is recommended that TRANSPARENCY_ONLY hardware handle rendering
+      of opaque patterns in two passes (the background can be filled as
+      a rectangle in GXcopy) in the Subsequent function so that the
+      TRANSPARENCY_ONLY restriction can be removed. 
+
+
+
+    Additional information about cached patterns...
+    For the case where HARDWARE_PATTERN_PROGRAMMED_BITS is not set and 
+    the pattern must be cached in offscreen memory, the first pattern
+    starts at the cache slot boundary which is set by the 
+    CachePixelGranularity field used to configure the pixmap cache.
+    One should ensure that the CachePixelGranularity reflects any 
+    alignment restrictions that the accelerator may put on 8x8 pattern 
+    storage locations.  When HARDWARE_PATTERN_PROGRAMMED_ORIGIN is set 
+    there is only one pattern stored.  When this flag is not set,
+    all 64 pre-rotated copies of the pattern are cached in offscreen memory.
+    The MonoPatternPitch field can be used to specify the X position pixel
+    granularity that each of these patterns must align on.  If the
+    MonoPatternPitch is not supplied, the patterns will be densely packed
+    within the cache slot.  The behavior of the default XAA 8x8 pattern
+    caching mechanism to store all 8x8 patterns linearly in video memory.
+    If the accelerator needs the patterns stored in a more unusual fashion,
+    the driver will need to provide its own 8x8 mono pattern caching 
+    routines for XAA to use. 
+
+    The following table describes the meanings of the "patx" and "paty"
+    fields in both the SetupFor and Subsequent functions.
+
+    With HARDWARE_PATTERN_SCREEN_ORIGIN
+    -----------------------------------
+
+    HARDWARE_PATTERN_PROGRAMMED_BITS and HARDWARE_PATTERN_PROGRAMMED_ORIGIN
+
+	SetupFor: patx and paty are the first and second DWORDS of the
+		  8x8 mono pattern.
+
+	Subsequent: patx and paty are the x,y offset into that pattern.
+		    All Subsequent calls will have the same offset in 
+		    the case of HARDWARE_PATTERN_SCREEN_ORIGIN so only
+		    the offset specified by the first Subsequent call 
+		    after a SetupFor call will need to be observed.
+
+    HARDWARE_PATTERN_PROGRAMMED_BITS only
+
+	SetupFor: patx and paty hold the first and second DWORDS of
+		  the 8x8 mono pattern pre-rotated to match the desired
+		  offset.
+
+	Subsequent: These just hold the same patterns and can be ignored.
+
+    HARDWARE_PATTERN_PROGRAMMED_ORIGIN only
+
+	SetupFor: patx and paty hold the x,y coordinates of the offscreen
+		  memory location where the 8x8 pattern is stored.  The
+		  bits are stored linearly in memory at that location.
+
+	Subsequent: patx and paty hold the offset into the pattern.
+		    All Subsequent calls will have the same offset in 
+		    the case of HARDWARE_PATTERN_SCREEN_ORIGIN so only
+		    the offset specified by the first Subsequent call 
+		    after a SetupFor call will need to be observed.
+
+    Neither programmed bits or origin
+
+	SetupFor: patx and paty hold the x,y coordinates of the offscreen 	
+		  memory location where the pre-rotated 8x8 pattern is
+		  stored.
+
+	Subsequent: patx and paty are the same as in the SetupFor function
+		    and can be ignored.
+		  
+
+    Without HARDWARE_PATTERN_SCREEN_ORIGIN
+    -------------------------------------- 
+
+    HARDWARE_PATTERN_PROGRAMMED_BITS and HARDWARE_PATTERN_PROGRAMMED_ORIGIN
+
+	SetupFor: patx and paty are the first and second DWORDS of the
+		  8x8 mono pattern.
+
+	Subsequent: patx and paty are the x,y offset into that pattern.
+
+    HARDWARE_PATTERN_PROGRAMMED_BITS only
+
+	SetupFor: patx and paty holds the first and second DWORDS of
+		  the unrotated 8x8 mono pattern.  This can be ignored. 
+
+	Subsequent: patx and paty hold the rotated 8x8 pattern to be 
+		    rendered.
+
+    HARDWARE_PATTERN_PROGRAMMED_ORIGIN only
+
+	SetupFor: patx and paty hold the x,y coordinates of the offscreen
+		  memory location where the 8x8 pattern is stored.  The
+		  bits are stored linearly in memory at that location.
+
+	Subsequent: patx and paty hold the offset into the pattern.
+
+    Neither programmed bits or origin
+
+	SetupFor: patx and paty hold the x,y coordinates of the offscreen 	
+		  memory location where the unrotated 8x8 pattern is
+		  stored.  This can be ignored.
+
+	Subsequent: patx and paty hold the x,y coordinates of the
+		    rotated 8x8 pattern to be rendered.
+
+
+
+void SetupForMono8x8PatternFill(ScrnInfoPtr pScrn, int patx, int paty,
+        int fg, int bg, int rop, unsigned int planemask)
+
+    SetupForMono8x8PatternFill indicates that any combination of the 
+    following  may follow it.
+
+	SubsequentMono8x8PatternFillRect
+	SubsequentMono8x8PatternFillTrap
+
+    The fg, bg, rop and planemask fields have the same meaning as the
+    ones used for the other color expansion routines.  Patx's and paty's
+    meaning can be determined from the table above.
+
+ 
+void SubsequentMono8x8PatternFillRect( ScrnInfoPtr pScrn,
+        	int patx, int paty, int x, int y, int w, int h)
+
+     Fill a rectangle of dimensions "w" by "h" with origin at (x,y) 
+     using the parameters give by the last SetupForMono8x8PatternFill
+     call.  The meanings of patx and paty can be determined by the
+     table above.
+
+void SubsequentMono8x8PatternFillTrap( ScrnInfoPtr pScrn,
+     			   int patx, int paty, int y, int h, 
+     			   int left, int dxL, int dyL, int eL,
+     			   int right, int dxR, int dyR, int eR )
+
+     The meanings of patx and paty can be determined by the table above.
+     The rest of the fields have the same meanings as those in the 
+     SubsequentSolidFillTrap function. 
+
+
+
+2.7   8x8 Color Pattern Fills
+  
+    8x8 color pattern data is 64 pixels of full color data that
+    is stored linearly in offscreen video memory.  8x8 color patterns 
+    are useful as a substitute for 8x8 mono patterns when tiling,
+    doing opaque stipples, or in the case where transperency is
+    supported, regular stipples.  8x8 color pattern fills also have
+    the additional benefit of being able to tile full color 8x8
+    patterns instead of just 2 color ones like the mono patterns.
+    However, full color 8x8 patterns aren't used very often in the
+    X Window system so you might consider passing this primitive
+    by if you already can do mono patterns, especially if they 
+    require alot of cache area.  Color8x8PatternFillFlags is
+    the flags field for this primitive and the GXCOPY_ONLY,
+    ROP_NEEDS_SOURCE and NO_PLANEMASK flags as described in
+    Section 2.0 are valid as well as the following:
+
+
+    HARDWARE_PATTERN_PROGRAMMED_ORIGIN
+
+      If the hardware supports programmable pattern offsets then
+      this option should be set.  
+
+    HARDWARE_PATTERN_SCREEN_ORIGIN
+
+      Some hardware wants the pattern offset specified with respect to the
+      upper left-hand corner of the primitive being drawn.  Other hardware 
+      needs the option HARDWARE_PATTERN_SCREEN_ORIGIN set to indicate that 
+      all pattern offsets should be referenced to the upper left-hand 
+      corner of the screen.  HARDWARE_PATTERN_SCREEN_ORIGIN is preferable 
+      since this is more natural for the X-Window system and offsets will 
+      have to be recalculated for each Subsequent function otherwise.
+
+    NO_TRANSPARENCY
+    TRANSPARENCY_GXCOPY_ONLY
+
+      These mean the same as for the ScreenToScreenCopy functions.
+
+
+    The following table describes the meanings of patx and paty passed
+    to the SetupFor and Subsequent fields:
+
+    HARDWARE_PATTERN_PROGRAMMED_ORIGIN && HARDWARE_PATTERN_SCREEN_ORIGIN
+	
+	SetupFor: patx and paty hold the x,y location of the unrotated 
+		  pattern.
+
+	Subsequent: patx and paty hold the pattern offset.  For the case
+		    of HARDWARE_PATTERN_SCREEN_ORIGIN all Subsequent calls
+		    have the same offset so only the first call will need
+		    to be observed.
+
+    
+    HARDWARE_PATTERN_PROGRAMMED_ORIGIN only
+
+	SetupFor: patx and paty hold the x,y location of the unrotated
+		  pattern.
+
+	Subsequent: patx and paty hold the pattern offset. 
+
+    HARDWARE_PATTERN_SCREEN_ORIGIN
+
+	SetupFor: patx and paty hold the x,y location of the rotated pattern.
+
+	Subsequent: patx and paty hold the same location as the SetupFor
+		    function so these can be ignored.
+
+    neither flag
+
+	SetupFor: patx and paty hold the x,y location of the unrotated
+		  pattern.  This can be ignored.
+
+	Subsequent: patx and paty hold the x,y location of the rotated
+		    pattern.
+
+    Additional information about cached patterns...
+    All 8x8 color patterns are cached in offscreen video memory so
+    the pixmap cache must be enabled to use them. The first pattern
+    starts at the cache slot boundary which is set by the 
+    CachePixelGranularity field used to configure the pixmap cache.
+    One should ensure that the CachePixelGranularity reflects any 
+    alignment restrictions that the accelerator may put on 8x8 pattern 
+    storage locations.  When HARDWARE_PATTERN_PROGRAMMED_ORIGIN is set 
+    there is only one pattern stored.  When this flag is not set,
+    all 64 rotations off the pattern are accessible but it is assumed
+    that the accelerator is capable of accessing data stored on 8
+    pixel boundaries.  If the accelerator has stricter alignment 
+    requirements than this the dirver will need to provide its own 
+    8x8 color pattern caching routines. 
+
+
+void SetupForColor8x8PatternFill(ScrnInfoPtr pScrn, int patx, int paty,
+        	int rop, unsigned int planemask, int trans_color)
+
+    SetupForColor8x8PatternFill indicates that any combination of the 
+    following  may follow it.
+
+	SubsequentColor8x8PatternFillRect
+	SubsequentColor8x8PatternFillTrap	(not implemented yet)
+
+    For the meanings of patx and paty, see the table above.  Trans_color
+    means the same as for the ScreenToScreenCopy functions.
+
+
+ 
+void SubsequentColor8x8PatternFillRect( ScrnInfoPtr pScrn,
+        	int patx, int paty, int x, int y, int w, int h)
+
+     Fill a rectangle of dimensions "w" by "h" with origin at (x,y) 
+     using the parameters give by the last SetupForColor8x8PatternFill
+     call.  The meanings of patx and paty can be determined by the
+     table above.
+
+void SubsequentColor8x8PatternFillTrap( ScrnInfoPtr pScrn,
+     			   int patx, int paty, int y, int h, 
+     			   int left, int dxL, int dyL, int eL,
+     			   int right, int dxR, int dyR, int eR )
+
+    For the meanings of patx and paty, see the table above. 
+    The rest of the fields have the same meanings as those in the 
+    SubsequentSolidFillTrap function. 
+
+
+
+2.8  Image Writes
+
+    XAA provides a mechanism for transfering full color pixel data from
+    system memory to video memory through the accelerator.  This is 
+    useful for dealing with alignment issues and performing raster ops
+    on the data when writing it to the framebuffer.  As with color
+    expansion rectangles, there is a direct and indirect method.  The
+    direct method sends all data through a memory mapped aperature.
+    The indirect method sends the data to an intermediated buffer scanline 
+    at a time.
+
+    The direct and indirect methods have separate flags fields, the
+    ImageWriteFlags and ScanlineImageWriteFlags respectively.
+    Flags specific to one method or the other are described in sections 
+    2.8.1 and 2.8.2 but for both cases the GXCOPY_ONLY, ROP_NEEDS_SOURCE
+    and NO_PLANEMASK flags described in Section 2.0 are valid as well as
+    the following:
+
+    NO_GXCOPY
+
+      In order to have accelerated image transfers faster than the 
+      software versions for GXcopy, the engine needs to support clipping,
+      be using the direct method and have a large enough image transfer
+      range so that CPU_TRANSFER_BASE_FIXED doesn't need to be set.
+      If these are not supported, then it is unlikely that transfering
+      the data through the accelerator will be of any advantage for the
+      simple case of GXcopy.  In fact, it may be much slower.  For such
+      cases it's probably best to set the NO_GXCOPY flag so that 
+      Image writes will only be used for the more complicated rops.
+
+    /* transparency restrictions */
+
+    NO_TRANSPARENCY
+     
+      This indicates that the accelerator does not support skipping
+      of color keyed pixels when copying from the source to the destination.
+
+    TRANSPARENCY_GXCOPY_ONLY
+
+      This indicates that the accelerator supports skipping of color keyed
+      pixels only when the rop is GXcopy.
+
+    /* clipping  (optional) */
+    
+    LEFT_EDGE_CLIPPING
+ 
+      This indicates that the accelerator supports omission of up to
+      3 pixels on the left edge of the rectangle to be filled.  This
+      is beneficial since it allows transfer from the source pixmap to
+      always occur from DWORD boundaries. 
+
+    LEFT_EDGE_CLIPPING_NEGATIVE_X
+
+      This flag indicates that the accelerator can fill areas with
+      image write data even if the value of x origin is negative (off of
+      the screen on the left edge).
+
+
+2.8.1 The Direct Method
+
+    Using the direct method of ImageWrite XAA will send all
+    bitmap data to the accelerator serially through an memory mapped
+    transfer window defined by the following two fields:
+
+      unsigned char *ImageWriteBase
+
+        This indicates the memory address of the beginning of the aperture.
+
+      int ImageWriteRange
+
+        This indicates the size in bytes of the aperture.
+
+    The driver should specify how the transfered data should be padded.
+    There are options for both the padding of each Y scanline and for the
+    total transfer to the aperature.
+    One of the following two flags must be set:
+
+      CPU_TRANSFER_PAD_DWORD
+
+        This indicates that the total transfer (sum of all scanlines) sent
+        to the aperature must be DWORD padded.  This is the default behavior.
+
+      CPU_TRANSFER_PAD_QWORD 
+
+	This indicates that the total transfer (sum of all scanlines) sent
+	to the aperature must be QWORD padded.  With this set, XAA will send
+        an extra DWORD to the aperature when needed to ensure that only
+        an even number of DWORDs are sent.
+
+    And then there are the flags for padding of each scanline:
+
+      SCANLINE_PAD_DWORD
+
+	This indicates that each Y scanline should be DWORD padded.
+        This is the only option available and is the default.
+
+    Finally, there is the CPU_TRANSFER_BASE_FIXED flag which indicates
+    that the aperture is a single register rather than a range of
+    registers, and XAA should write all of the data to the first DWORD.
+    XAA will automatically select CPU_TRANSFER_BASE_FIXED if the 
+    ImageWriteRange is not large enough to accomodate an entire scanline.   
+
+
+void SetupForImageWrite(ScrnInfoPtr pScrn, int rop, unsigned int planemask,
+        			int trans_color, int bpp, int depth)
+
+     If trans_color is not -1 then trans_color indicates the transparency
+     color key and pixels with color trans_color passed through the 
+     aperature should not be transfered to the screen but should be 
+     skipped.  Bpp and depth indicate the bits per pixel and depth of
+     the source pixmap.  Trans_color is always -1 if the NO_TRANSPARENCY
+     flag is set.
+
+
+void SubsequentImageWriteRect(ScrnInfoPtr pScrn, 
+				int x, int y, int w, int h, int skipleft)
+
+     
+     Data passed through the aperature should be copied to a rectangle
+     of width "w" and height "h" with origin (x,y).  If LEFT_EDGE_CLIPPING
+     has been enabled, skipleft will correspond to the number of pixels
+     on the left edge that should not be drawn.  Skipleft is zero 
+     otherwise.
+
+     It can be arranged for XAA to call Sync() after it is through 
+     calling the Subsequent functions by setting SYNC_AFTER_IMAGE_WRITE 
+     in the  ImageWriteFlags.  This can provide the driver with an
+     oportunity to reset a clipping window if needed.
+
+2.8.2  The Indirect Method
+
+     Using the indirect method, XAA will render the pixel data scanline
+     at a time to one or more buffers.  These buffers may be memory
+     mapped apertures or just intermediate storage.
+
+     int NumScanlineImageWriteBuffers
+
+       This indicates the number of buffers available.
+
+     unsigned char **ScanlineImageWriteBuffers
+
+       This is an array of pointers to the memory locations of each buffer.
+       Each buffer is expected to be large enough to accommodate scanlines
+       the width of the screen.  That is:
+
+         pScrn->VirtualX * pScreen->bitsPerPixel/8   bytes or more.
+
+       If LEFT_EDGE_CLIPPING_NEGATIVE_X is set, add an additional 4
+       bytes to that requirement in 8 and 16bpp, 12 bytes in 24bpp.
+  
+     Scanlines are always DWORD padded.
+
+void SetupForScanlineImageWrite(ScrnInfoPtr pScrn, int rop, 
+				unsigned int planemask, int trans_color, 
+				int bpp, int depth)
+
+     If trans_color is not -1 then trans_color indicates the transparency
+     color key and pixels with color trans_color in the buffer should not 
+     be transfered to the screen but should be skipped.  Bpp and depth 
+     indicate the bits per pixel and depth of the source bitmap.  
+     Trans_color is always -1 if the NO_TRANSPARENCY flag is set.
+
+
+void SubsequentImageWriteRect(ScrnInfoPtr pScrn, 
+				int x, int y, int w, int h, int skipleft)
+
+     
+void SubsequentImageWriteScanline(ScrnInfoPtr pScrn, int bufno)
+
+
+    When SubsequentImageWriteRect is called, XAA will begin
+    transfering the source data scanline at a time, calling  
+    SubsequentImageWriteScanline after each scanline.  If more than
+    one buffer is available, XAA will cycle through the buffers.
+    Subsequent scanlines will use the next buffer and go back to the
+    buffer 0 again when the last buffer is reached.  The index into
+    the ScanlineImageWriteBuffers array is presented as "bufno"
+    with each SubsequentImageWriteScanline call.
+
+    The skipleft field is the same as for the direct method.
+
+    The indirect method can be use to send the source data directly 
+    to a memory mapped aperture represented by a single image write
+    buffer, scanline at a time, but more commonly it is used to place 
+    the data into offscreen video memory so that the accelerator can 
+    blit it to the visible screen from there.  In the case where the
+    accelerator permits rendering into offscreen video memory while
+    the accelerator is active, several buffers can be used so that
+    XAA can be placing source data into the next buffer while the
+    accelerator is blitting the current buffer.  For cases where
+    the accelerator requires some special manipulation of the source
+    data first, the buffers can be in system memory.  The CPU can
+    manipulate these buffers and then send the data to the accelerator.
+
+
+2.9 Clipping
+
+    XAA supports hardware clipping rectangles.  To use clipping
+    in this way it is expected that the graphics accelerator can
+    clip primitives with verticies anywhere in the 16 bit signed 
+    coordinate system. 
+
+void SetClippingRectangle ( ScrnInfoPtr pScrn,
+        		int left, int top, int right, int bottom)
+
+void DisableClipping (ScrnInfoPtr pScrn)
+
+    When SetClippingRectangle is called, all hardware rendering
+    following it should be clipped to the rectangle specified
+    until DisableClipping is called.
+
+    The ClippingFlags field indicates which operations this sort
+    of Set/Disable pairing can be used with.  Any of the following
+    flags may be OR'd together.
+
+	HARDWARE_CLIP_SCREEN_TO_SCREEN_COLOR_EXPAND
+	HARDWARE_CLIP_SCREEN_TO_SCREEN_COPY
+	HARDWARE_CLIP_MONO_8x8_FILL
+	HARDWARE_CLIP_COLOR_8x8_FILL
+	HARDWARE_CLIP_SOLID_FILL
+	HARDWARE_CLIP_DASHED_LINE
+	HARDWARE_CLIP_SOLID_LINE
+
+
+
+3)  XAA PIXMAP CACHE
+
+   /* NOTE:  XAA has no knowledge of framebuffer particulars so until
+	the framebuffer is able to render into offscreen memory, usage
+	of the pixmap cache requires that the driver provide ImageWrite
+	routines or a WritePixmap or WritePixmapToCache replacement so
+	that patterns can even be placed in the cache.
+
+      ADDENDUM: XAA can now load the pixmap cache without requiring
+	that the driver supply an ImageWrite function, but this can
+	only be done on linear framebuffers.  If you have a linear
+	framebuffer, set LINEAR_FRAMEBUFFER in the XAAInfoRec.Flags
+	field and XAA will then be able to upload pixmaps into the
+	cache without the driver providing functions to do so.
+   */
+
+
+   The XAA pixmap cache provides a mechanism for caching of patterns
+   in offscreen video memory so that tiled fills and in some cases
+   stippling can be done by blitting the source patterns from offscreen
+   video memory. The pixmap cache also provides the mechanism for caching 
+   of 8x8 color and mono hardware patterns.  Any unused offscreen video
+   memory gets used for the pixmap cache and that information is 
+   provided by the XFree86 Offscreen Memory Manager. XAA registers a 
+   callback with the manager so that it can be informed of any changes 
+   in the offscreen memory configuration.  The driver writer does not 
+   need to deal with any of this since it is all automatic.  The driver 
+   merely needs to initialize the Offscreen Memory Manager as described 
+   in the DESIGN document and set the PIXMAP_CACHE flag in the 
+   XAAInfoRec.Flags field.  The Offscreen Memory Manager initialization 
+   must occur before XAA is initialized or else pixmap cache 
+   initialization will fail.  
+
+   PixmapCacheFlags is an XAAInfoRec field which allows the driver to
+   control pixmap cache behavior to some extent.  Currently only one
+   flag is defined:
+
+   DO_NOT_BLIT_STIPPLES
+
+     This indicates that the stippling should not be done by blitting
+     from the pixmap cache.  This does not apply to 8x8 pattern fills. 
+
+
+   CachePixelGranularity is an optional field.  If the hardware requires
+   that a 8x8 patterns have some particular pixel alignment it should
+   be reflected in this field.  Ignoring this field or setting it to
+   zero or one means there are no alignment issues.
+
+
+4)  OFFSCREEN PIXMAPS
+
+   XAA has the ability to store pixmap drawables in offscreen video 
+   memory and render into them with full hardware acceleration.  Placement
+   of pixmaps in the cache is done automatically on a first-come basis and 
+   only if there is room.  To enable this feature, set the OFFSCREEN_PIXMAPS
+   flag in the XAAInfoRec.Flags field.  This is only available when a
+   ScreenToScreenCopy function is provided, when the Offscreen memory 
+   manager has been initialized and when the LINEAR_FRAMEBUFFER flag is
+   also set.
+
+   int maxOffPixWidth
+   int maxOffPixHeight
+
+       These two fields allow the driver to limit the maximum dimensions
+     of an offscreen pixmap.  If one of these is not set, it is assumed
+     that there is no limit on that dimension.  Note that if an offscreen
+     pixmap with a particular dimension is allowed, then your driver will be
+     expected to render primitives as large as that pixmap.  
+
+$XFree86: xc/programs/Xserver/hw/xfree86/xaa/XAA.HOWTO,v 1.13 2001/05/22 18:51:09 mvojkovi Exp $