qbit/xenocara
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
4344ac3914
xenocara/xserver/hw/xfree86/xaa/XAA.HOWTO
matthieu 889b860699 Importing xserver from X.Org 7.2RC2
2006-11-26 18:13:41 +00:00

1428 lines
57 KiB
Plaintext
Raw Blame History

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 $
Reference in New Issue View Git Blame Copy Permalink