Used synchronise script to update files

1 files changed, 1427 insertions, 1427 deletions

diff --git a/xorg-server/hw/xfree86/xaa/XAA.HOWTO b/xorg-server/hw/xfree86/xaa/XAA.HOWTO
index cbd71c138..531ead0a0 100644
--- a/xorg-server/hw/xfree86/xaa/XAA.HOWTO
+++ b/xorg-server/hw/xfree86/xaa/XAA.HOWTO
@@ -1,1427 +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.12 2000/04/12 14:44:42 tsi Exp $
+

+

+                          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.12 2000/04/12 14:44:42 tsi Exp $