From 990bc3f015a4f8fce2eb918375defcd44980a845 Mon Sep 17 00:00:00 2001 From: marha Date: Fri, 8 Jun 2012 09:33:13 +0200 Subject: Used synchronise script to update files --- xorg-server/hw/xfree86/xaa/.gitignore | 4 + xorg-server/hw/xfree86/xaa/XAA.HOWTO | 2854 ++++++++++++++++----------------- xorg-server/hw/xfree86/xaa/xaaInit.c | 40 +- xorg-server/hw/xfree86/xaa/xaalocal.h | 8 +- 4 files changed, 1454 insertions(+), 1452 deletions(-) create mode 100644 xorg-server/hw/xfree86/xaa/.gitignore (limited to 'xorg-server/hw/xfree86/xaa') 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; -- cgit v1.2.3