aboutsummaryrefslogtreecommitdiff
path: root/xorg-server/hw/xfree86/xaa
diff options
context:
space:
mode:
Diffstat (limited to 'xorg-server/hw/xfree86/xaa')
-rw-r--r--xorg-server/hw/xfree86/xaa/.gitignore4
-rw-r--r--xorg-server/hw/xfree86/xaa/XAA.HOWTO2854
-rw-r--r--xorg-server/hw/xfree86/xaa/xaaInit.c40
-rw-r--r--xorg-server/hw/xfree86/xaa/xaalocal.h8
4 files changed, 1454 insertions, 1452 deletions
diff --git a/xorg-server/hw/xfree86/xaa/.gitignore b/xorg-server/hw/xfree86/xaa/.gitignore
new file mode 100644
index 000000000..1ba5b2602
--- /dev/null
+++ b/xorg-server/hw/xfree86/xaa/.gitignore
@@ -0,0 +1,4 @@
+# Add & Override for this directory and it's subdirectories
+[lms]-xaa*.c
+[lm]f3-xaa*.c
+[lm][f3]-xaa*.c
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 $
diff --git a/xorg-server/hw/xfree86/xaa/xaaInit.c b/xorg-server/hw/xfree86/xaa/xaaInit.c
index 48d0605fa..f146f3adf 100644
--- a/xorg-server/hw/xfree86/xaa/xaaInit.c
+++ b/xorg-server/hw/xfree86/xaa/xaaInit.c
@@ -27,7 +27,7 @@
#define MIN_OFFPIX_SIZE (320*200)
-static Bool XAACloseScreen(int i, ScreenPtr pScreen);
+static Bool XAACloseScreen(ScreenPtr pScreen);
static void XAAGetImage(DrawablePtr pDrawable, int sx, int sy, int w, int h,
unsigned int format, unsigned long planemask,
char *pdstLine);
@@ -36,10 +36,10 @@ static void XAAGetSpans(DrawablePtr pDrawable, int wMax, DDXPointPtr ppt,
static PixmapPtr XAACreatePixmap(ScreenPtr pScreen, int w, int h, int depth,
unsigned usage_hint);
static Bool XAADestroyPixmap(PixmapPtr pPixmap);
-static Bool XAAEnterVT(int index, int flags);
-static void XAALeaveVT(int index, int flags);
-static int XAASetDGAMode(int index, int num, DGADevicePtr devRet);
-static void XAAEnableDisableFBAccess(int index, Bool enable);
+static Bool XAAEnterVT(ScrnInfoPtr pScrn);
+static void XAALeaveVT(ScrnInfoPtr pScrn);
+static int XAASetDGAMode(ScrnInfoPtr pScrn, int num, DGADevicePtr devRet);
+static void XAAEnableDisableFBAccess(ScrnInfoPtr pScrn, Bool enable);
static Bool XAAChangeWindowAttributes(WindowPtr pWin, unsigned long mask);
static DevPrivateKeyRec XAAScreenKeyRec;
@@ -214,7 +214,7 @@ XAAInit(ScreenPtr pScreen, XAAInfoRecPtr infoRec)
}
static Bool
-XAACloseScreen(int i, ScreenPtr pScreen)
+XAACloseScreen(ScreenPtr pScreen)
{
ScrnInfoPtr pScrn = xf86ScreenToScrn(pScreen);
XAAScreenPtr pScreenPriv =
@@ -238,7 +238,7 @@ XAACloseScreen(int i, ScreenPtr pScreen)
free((pointer) pScreenPriv);
- return (*pScreen->CloseScreen) (i, pScreen);
+ return (*pScreen->CloseScreen) (pScreen);
}
static void
@@ -509,26 +509,24 @@ XAAChangeWindowAttributes(WindowPtr pWin, unsigned long mask)
/* These two aren't really needed for anything */
static Bool
-XAAEnterVT(int index, int flags)
+XAAEnterVT(ScrnInfoPtr pScrn)
{
- ScrnInfoPtr pScrn = xf86Screens[index];
Bool ret;
- ScreenPtr pScreen = screenInfo.screens[index];
+ ScreenPtr pScreen = xf86ScrnToScreen(pScrn);
XAAScreenPtr pScreenPriv =
(XAAScreenPtr) dixLookupPrivate(&pScreen->devPrivates, XAAScreenKey);
pScrn->EnterVT = pScreenPriv->EnterVT;
- ret = ((*pScreenPriv->EnterVT) (index, flags));
+ ret = ((*pScreenPriv->EnterVT) (pScrn));
pScreenPriv->EnterVT = pScrn->EnterVT;
pScrn->EnterVT = XAAEnterVT;
return ret;
}
static void
-XAALeaveVT(int index, int flags)
+XAALeaveVT(ScrnInfoPtr pScrn)
{
- ScrnInfoPtr pScrn = xf86Screens[index];
- ScreenPtr pScreen = screenInfo.screens[index];
+ ScreenPtr pScreen = xf86ScrnToScreen(pScrn);
XAAScreenPtr pScreenPriv =
(XAAScreenPtr) dixLookupPrivate(&pScreen->devPrivates, XAAScreenKey);
XAAInfoRecPtr infoRec = pScreenPriv->AccelInfoRec;
@@ -539,7 +537,7 @@ XAALeaveVT(int index, int flags)
}
pScrn->LeaveVT = pScreenPriv->LeaveVT;
- (*pScreenPriv->LeaveVT) (index, flags);
+ (*pScreenPriv->LeaveVT) (pScrn);
pScreenPriv->LeaveVT = pScrn->LeaveVT;
pScrn->LeaveVT = XAALeaveVT;
}
@@ -551,9 +549,9 @@ typedef struct {
} SavedCacheState, *SavedCacheStatePtr;
static int
-XAASetDGAMode(int index, int num, DGADevicePtr devRet)
+XAASetDGAMode(ScrnInfoPtr pScrn, int num, DGADevicePtr devRet)
{
- ScreenPtr pScreen = screenInfo.screens[index];
+ ScreenPtr pScreen = xf86ScrnToScreen(pScrn);
XAAInfoRecPtr infoRec = GET_XAAINFORECPTR_FROM_SCREEN(pScreen);
XAAScreenPtr pScreenPriv =
(XAAScreenPtr) dixLookupPrivate(&pScreen->devPrivates, XAAScreenKey);
@@ -569,7 +567,7 @@ XAASetDGAMode(int index, int num, DGADevicePtr devRet)
infoRec->dgaSaves = NULL;
}
- ret = (*pScreenPriv->SetDGAMode) (index, num, devRet);
+ ret = (*pScreenPriv->SetDGAMode) (pScrn, num, devRet);
if (ret != Success)
return ret;
@@ -612,9 +610,9 @@ XAASetDGAMode(int index, int num, DGADevicePtr devRet)
}
static void
-XAAEnableDisableFBAccess(int index, Bool enable)
+XAAEnableDisableFBAccess(ScrnInfoPtr pScrn, Bool enable)
{
- ScreenPtr pScreen = screenInfo.screens[index];
+ ScreenPtr pScreen = xf86ScrnToScreen(pScrn);
XAAInfoRecPtr infoRec = GET_XAAINFORECPTR_FROM_SCREEN(pScreen);
XAAScreenPtr pScreenPriv =
(XAAScreenPtr) dixLookupPrivate(&pScreen->devPrivates, XAAScreenKey);
@@ -627,7 +625,7 @@ XAAEnableDisableFBAccess(int index, Bool enable)
SwitchedOut = TRUE;
}
- (*pScreenPriv->EnableDisableFBAccess) (index, enable);
+ (*pScreenPriv->EnableDisableFBAccess) (pScrn, enable);
if (enable) {
if ((infoRec->Flags & OFFSCREEN_PIXMAPS) && (infoRec->OffscreenPixmaps))
diff --git a/xorg-server/hw/xfree86/xaa/xaalocal.h b/xorg-server/hw/xfree86/xaa/xaalocal.h
index c028ef033..61d9eebe5 100644
--- a/xorg-server/hw/xfree86/xaa/xaalocal.h
+++ b/xorg-server/hw/xfree86/xaa/xaalocal.h
@@ -47,10 +47,10 @@ typedef struct _XAAScreen {
DestroyPixmapProcPtr DestroyPixmap;
ChangeWindowAttributesProcPtr ChangeWindowAttributes;
XAAInfoRecPtr AccelInfoRec;
- Bool (*EnterVT) (int, int);
- void (*LeaveVT) (int, int);
- int (*SetDGAMode) (int, int, DGADevicePtr);
- void (*EnableDisableFBAccess) (int, Bool);
+ Bool (*EnterVT) (ScrnInfoPtr);
+ void (*LeaveVT) (ScrnInfoPtr);
+ int (*SetDGAMode) (ScrnInfoPtr, int, DGADevicePtr);
+ void (*EnableDisableFBAccess) (ScrnInfoPtr, Bool);
CompositeProcPtr Composite;
GlyphsProcPtr Glyphs;
} XAAScreenRec, *XAAScreenPtr;