542 lines
22 KiB
C
542 lines
22 KiB
C
/*
|
|
* Copyright © 2000, 2008 Keith Packard
|
|
* 2004 Eric Anholt
|
|
* 2005 Zack Rusin
|
|
*
|
|
* Permission to use, copy, modify, distribute, and sell this software and its
|
|
* documentation for any purpose is hereby granted without fee, provided that
|
|
* the above copyright notice appear in all copies and that both that
|
|
* copyright notice and this permission notice appear in supporting
|
|
* documentation, and that the name of copyright holders not be used in
|
|
* advertising or publicity pertaining to distribution of the software without
|
|
* specific, written prior permission. Copyright holders make no
|
|
* representations about the suitability of this software for any purpose. It
|
|
* is provided "as is" without express or implied warranty.
|
|
*
|
|
* THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
|
|
* SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
|
|
* FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
|
* SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
|
|
* AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
|
|
* OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
|
|
* SOFTWARE.
|
|
*/
|
|
|
|
/** @file
|
|
* UXA - the unified memory acceleration architecture.
|
|
*
|
|
* This is the header containing the public API of UXA for uxa drivers.
|
|
*/
|
|
|
|
#ifndef UXA_H
|
|
#define UXA_H
|
|
|
|
#include "scrnintstr.h"
|
|
#include "pixmapstr.h"
|
|
#include "windowstr.h"
|
|
#include "gcstruct.h"
|
|
#include "picturestr.h"
|
|
#include "fb.h"
|
|
|
|
#define UXA_VERSION_MAJOR 1
|
|
#define UXA_VERSION_MINOR 0
|
|
#define UXA_VERSION_RELEASE 0
|
|
|
|
typedef enum {
|
|
UXA_ACCESS_RO,
|
|
UXA_ACCESS_RW
|
|
} uxa_access_t;
|
|
|
|
/**
|
|
* The UxaDriver structure is allocated through uxa_driver_alloc(), and then
|
|
* fllled in by drivers.
|
|
*/
|
|
typedef struct _UxaDriver {
|
|
/**
|
|
* uxa_major and uxa_minor should be set by the driver to the version of
|
|
* UXA which the driver was compiled for (or configures itself at runtime
|
|
* to support). This allows UXA to extend the structure for new features
|
|
* without breaking ABI for drivers compiled against older versions.
|
|
*/
|
|
int uxa_major, uxa_minor;
|
|
|
|
/**
|
|
* The flags field is bitfield of boolean values controlling UXA's behavior.
|
|
*
|
|
* The flags include UXA_TWO_BITBLT_DIRECTIONS.
|
|
*/
|
|
int flags;
|
|
|
|
/** @name solid
|
|
* @{
|
|
*/
|
|
/**
|
|
* prepare_solid() sets up the driver for doing a solid fill.
|
|
* @param pPixmap Destination pixmap
|
|
* @param alu raster operation
|
|
* @param planemask write mask for the fill
|
|
* @param fg "foreground" color for the fill
|
|
*
|
|
* This call should set up the driver for doing a series of solid fills
|
|
* through the solid() call. The alu raster op is one of the GX*
|
|
* graphics functions listed in X.h, and typically maps to a similar
|
|
* single-byte "ROP" setting in all hardware. The planemask controls
|
|
* which bits of the destination should be affected, and will only represent
|
|
* the bits up to the depth of pPixmap. The fg is the pixel value of the
|
|
* foreground color referred to in ROP descriptions.
|
|
*
|
|
* Note that many drivers will need to store some of the data in the driver
|
|
* private record, for sending to the hardware with each drawing command.
|
|
*
|
|
* The prepare_solid() call is required of all drivers, but it may fail for any
|
|
* reason. Failure results in a fallback to software rendering.
|
|
*/
|
|
Bool (*prepare_solid) (PixmapPtr pPixmap,
|
|
int alu,
|
|
Pixel planemask,
|
|
Pixel fg);
|
|
|
|
/**
|
|
* solid() performs a solid fill set up in the last prepare_solid() call.
|
|
*
|
|
* @param pPixmap destination pixmap
|
|
* @param x1 left coordinate
|
|
* @param y1 top coordinate
|
|
* @param x2 right coordinate
|
|
* @param y2 bottom coordinate
|
|
*
|
|
* Performs the fill set up by the last prepare_solid() call, covering the
|
|
* area from (x1,y1) to (x2,y2) in pPixmap. Note that the coordinates are
|
|
* in the coordinate space of the destination pixmap, so the driver will
|
|
* need to set up the hardware's offset and pitch for the destination
|
|
* coordinates according to the pixmap's offset and pitch within
|
|
* framebuffer.
|
|
*
|
|
* This call is required if prepare_solid() ever succeeds.
|
|
*/
|
|
void (*solid) (PixmapPtr pPixmap, int x1, int y1, int x2, int y2);
|
|
|
|
/**
|
|
* done_solid() finishes a set of solid fills.
|
|
*
|
|
* @param pPixmap destination pixmap.
|
|
*
|
|
* The done_solid() call is called at the end of a series of consecutive
|
|
* solid() calls following a successful prepare_solid(). This allows drivers
|
|
* to finish up emitting drawing commands that were buffered, or clean up
|
|
* state from prepare_solid().
|
|
*
|
|
* This call is required if prepare_solid() ever succeeds.
|
|
*/
|
|
void (*done_solid) (PixmapPtr pPixmap);
|
|
/** @} */
|
|
|
|
/** @name copy
|
|
* @{
|
|
*/
|
|
/**
|
|
* prepare_copy() sets up the driver for doing a copy within video
|
|
* memory.
|
|
*
|
|
* @param pSrcPixmap source pixmap
|
|
* @param pDstPixmap destination pixmap
|
|
* @param dx X copy direction
|
|
* @param dy Y copy direction
|
|
* @param alu raster operation
|
|
* @param planemask write mask for the fill
|
|
*
|
|
* This call should set up the driver for doing a series of copies from the
|
|
* the pSrcPixmap to the pDstPixmap. The dx flag will be positive if the
|
|
* hardware should do the copy from the left to the right, and dy will be
|
|
* positive if the copy should be done from the top to the bottom. This
|
|
* is to deal with self-overlapping copies when pSrcPixmap == pDstPixmap.
|
|
* If your hardware can only support blits that are (left to right, top to
|
|
* bottom) or (right to left, bottom to top), then you should set
|
|
* #UXA_TWO_BITBLT_DIRECTIONS, and UXA will break down copy operations to
|
|
* ones that meet those requirements. The alu raster op is one of the GX*
|
|
* graphics functions listed in X.h, and typically maps to a similar
|
|
* single-byte "ROP" setting in all hardware. The planemask controls which
|
|
* bits of the destination should be affected, and will only represent the
|
|
* bits up to the depth of pPixmap.
|
|
*
|
|
* Note that many drivers will need to store some of the data in the driver
|
|
* private record, for sending to the hardware with each drawing command.
|
|
*
|
|
* The prepare_copy() call is required of all drivers, but it may fail for any
|
|
* reason. Failure results in a fallback to software rendering.
|
|
*/
|
|
Bool (*prepare_copy) (PixmapPtr pSrcPixmap,
|
|
PixmapPtr pDstPixmap,
|
|
int dx,
|
|
int dy,
|
|
int alu,
|
|
Pixel planemask);
|
|
|
|
/**
|
|
* copy() performs a copy set up in the last prepare_copy call.
|
|
*
|
|
* @param pDstPixmap destination pixmap
|
|
* @param srcX source X coordinate
|
|
* @param srcY source Y coordinate
|
|
* @param dstX destination X coordinate
|
|
* @param dstY destination Y coordinate
|
|
* @param width width of the rectangle to be copied
|
|
* @param height height of the rectangle to be copied.
|
|
*
|
|
* Performs the copy set up by the last prepare_copy() call, copying the
|
|
* rectangle from (srcX, srcY) to (srcX + width, srcY + width) in the source
|
|
* pixmap to the same-sized rectangle at (dstX, dstY) in the destination
|
|
* pixmap. Those rectangles may overlap in memory, if
|
|
* pSrcPixmap == pDstPixmap. Note that this call does not receive the
|
|
* pSrcPixmap as an argument -- if it's needed in this function, it should
|
|
* be stored in the driver private during prepare_copy(). As with solid(),
|
|
* the coordinates are in the coordinate space of each pixmap, so the driver
|
|
* will need to set up source and destination pitches and offsets from those
|
|
* pixmaps, probably using uxaGetPixmapOffset() and uxa_get_pixmap_pitch().
|
|
*
|
|
* This call is required if prepare_copy ever succeeds.
|
|
*/
|
|
void (*copy) (PixmapPtr pDstPixmap,
|
|
int srcX,
|
|
int srcY,
|
|
int dstX,
|
|
int dstY,
|
|
int width,
|
|
int height);
|
|
|
|
/**
|
|
* done_copy() finishes a set of copies.
|
|
*
|
|
* @param pPixmap destination pixmap.
|
|
*
|
|
* The done_copy() call is called at the end of a series of consecutive
|
|
* copy() calls following a successful prepare_copy(). This allows drivers
|
|
* to finish up emitting drawing commands that were buffered, or clean up
|
|
* state from prepare_copy().
|
|
*
|
|
* This call is required if prepare_copy() ever succeeds.
|
|
*/
|
|
void (*done_copy) (PixmapPtr pDstPixmap);
|
|
/** @} */
|
|
|
|
/** @name composite
|
|
* @{
|
|
*/
|
|
/**
|
|
* check_composite() checks to see if a composite operation could be
|
|
* accelerated.
|
|
*
|
|
* @param op Render operation
|
|
* @param pSrcPicture source Picture
|
|
* @param pMaskPicture mask picture
|
|
* @param pDstPicture destination Picture
|
|
*
|
|
* The check_composite() call checks if the driver could handle acceleration
|
|
* of op with the given source, mask, and destination pictures. This allows
|
|
* drivers to check source and destination formats, supported operations,
|
|
* transformations, and component alpha state, and send operations it can't
|
|
* support to software rendering early on.
|
|
*
|
|
* See prepare_composite() for more details on likely issues that drivers
|
|
* will have in accelerating composite operations.
|
|
*
|
|
* The check_composite() call is recommended if prepare_composite() is
|
|
* implemented, but is not required.
|
|
*/
|
|
Bool (*check_composite) (int op,
|
|
PicturePtr pSrcPicture,
|
|
PicturePtr pMaskPicture,
|
|
PicturePtr pDstPicture);
|
|
|
|
/**
|
|
* prepare_composite() sets up the driver for doing a composite operation
|
|
* described in the Render extension protocol spec.
|
|
*
|
|
* @param op Render operation
|
|
* @param pSrcPicture source Picture
|
|
* @param pMaskPicture mask picture
|
|
* @param pDstPicture destination Picture
|
|
* @param pSrc source pixmap
|
|
* @param pMask mask pixmap
|
|
* @param pDst destination pixmap
|
|
*
|
|
* This call should set up the driver for doing a series of composite
|
|
* operations, as described in the Render protocol spec, with the given
|
|
* pSrcPicture, pMaskPicture, and pDstPicture. The pSrc, pMask, and
|
|
* pDst are the pixmaps containing the pixel data, and should be used for
|
|
* setting the offset and pitch used for the coordinate spaces for each of
|
|
* the Pictures.
|
|
*
|
|
* Notes on interpreting Picture structures:
|
|
* - The Picture structures will always have a valid pDrawable.
|
|
* - The Picture structures will never have alphaMap set.
|
|
* - The mask Picture (and therefore pMask) may be NULL, in which case the
|
|
* operation is simply src OP dst instead of src IN mask OP dst, and
|
|
* mask coordinates should be ignored.
|
|
* - pMarkPicture may have componentAlpha set, which greatly changes
|
|
* the behavior of the composite operation. componentAlpha has no effect
|
|
* when set on pSrcPicture or pDstPicture.
|
|
* - The source and mask Pictures may have a transformation set
|
|
* (Picture->transform != NULL), which means that the source coordinates
|
|
* should be transformed by that transformation, resulting in scaling,
|
|
* rotation, etc. The PictureTransformPoint() call can transform
|
|
* coordinates for you. Transforms have no effect on Pictures when used
|
|
* as a destination.
|
|
* - The source and mask pictures may have a filter set. PictFilterNearest
|
|
* and PictFilterBilinear are defined in the Render protocol, but others
|
|
* may be encountered, and must be handled correctly (usually by
|
|
* prepare_composite failing, and falling back to software). Filters have
|
|
* no effect on Pictures when used as a destination.
|
|
* - The source and mask Pictures may have repeating set, which must be
|
|
* respected. Many chipsets will be unable to support repeating on
|
|
* pixmaps that have a width or height that is not a power of two.
|
|
*
|
|
* If your hardware can't support source pictures (textures) with
|
|
* non-power-of-two pitches, you should set #UXA_OFFSCREEN_ALIGN_POT.
|
|
*
|
|
* Note that many drivers will need to store some of the data in the driver
|
|
* private record, for sending to the hardware with each drawing command.
|
|
*
|
|
* The prepare_composite() call is not required. However, it is highly
|
|
* recommended for performance of antialiased font rendering and performance
|
|
* of cairo applications. Failure results in a fallback to software
|
|
* rendering.
|
|
*/
|
|
Bool (*prepare_composite) (int op,
|
|
PicturePtr pSrcPicture,
|
|
PicturePtr pMaskPicture,
|
|
PicturePtr pDstPicture,
|
|
PixmapPtr pSrc,
|
|
PixmapPtr pMask,
|
|
PixmapPtr pDst);
|
|
|
|
/**
|
|
* composite() performs a composite operation set up in the last
|
|
* prepare_composite() call.
|
|
*
|
|
* @param pDstPixmap destination pixmap
|
|
* @param srcX source X coordinate
|
|
* @param srcY source Y coordinate
|
|
* @param maskX source X coordinate
|
|
* @param maskY source Y coordinate
|
|
* @param dstX destination X coordinate
|
|
* @param dstY destination Y coordinate
|
|
* @param width destination rectangle width
|
|
* @param height destination rectangle height
|
|
*
|
|
* Performs the composite operation set up by the last prepare_composite()
|
|
* call, to the rectangle from (dstX, dstY) to (dstX + width, dstY + height)
|
|
* in the destination Pixmap. Note that if a transformation was set on
|
|
* the source or mask Pictures, the source rectangles may not be the same
|
|
* size as the destination rectangles and filtering. Getting the coordinate
|
|
* transformation right at the subpixel level can be tricky, and rendercheck
|
|
* can test this for you.
|
|
*
|
|
* This call is required if prepare_composite() ever succeeds.
|
|
*/
|
|
void (*composite) (PixmapPtr pDst,
|
|
int srcX,
|
|
int srcY,
|
|
int maskX,
|
|
int maskY,
|
|
int dstX,
|
|
int dstY,
|
|
int width,
|
|
int height);
|
|
|
|
/**
|
|
* done_composite() finishes a set of composite operations.
|
|
*
|
|
* @param pPixmap destination pixmap.
|
|
*
|
|
* The done_composite() call is called at the end of a series of consecutive
|
|
* composite() calls following a successful prepare_composite(). This allows
|
|
* drivers to finish up emitting drawing commands that were buffered, or
|
|
* clean up state from prepare_composite().
|
|
*
|
|
* This call is required if prepare_composite() ever succeeds.
|
|
*/
|
|
void (*done_composite) (PixmapPtr pDst);
|
|
/** @} */
|
|
|
|
/**
|
|
* put_image() loads a rectangle of data from src into pDst.
|
|
*
|
|
* @param pDst destination pixmap
|
|
* @param x destination X coordinate.
|
|
* @param y destination Y coordinate
|
|
* @param width width of the rectangle to be copied
|
|
* @param height height of the rectangle to be copied
|
|
* @param src pointer to the beginning of the source data
|
|
* @param src_pitch pitch (in bytes) of the lines of source data.
|
|
*
|
|
* put_image() copies data in system memory beginning at src (with
|
|
* pitch src_pitch) into the destination pixmap from (x, y) to
|
|
* (x + width, y + height). This is typically done with hostdata uploads,
|
|
* where the CPU sets up a blit command on the hardware with instructions
|
|
* that the blit data will be fed through some sort of aperture on the card.
|
|
*
|
|
* put_image() is most important for the performance of uxa_glyphs()
|
|
* (antialiased font drawing) by allowing pipelining of data uploads,
|
|
* avoiding a sync of the card after each glyph.
|
|
*
|
|
* @return TRUE if the driver successfully uploaded the data. FALSE
|
|
* indicates that UXA should fall back to doing the upload in software.
|
|
*
|
|
* put_image() is not required, but is recommended if composite
|
|
* acceleration is supported.
|
|
*/
|
|
Bool (*put_image) (PixmapPtr pDst,
|
|
int x,
|
|
int y,
|
|
int w,
|
|
int h,
|
|
char *src,
|
|
int src_pitch);
|
|
|
|
/**
|
|
* get_image() loads a rectangle of data from pSrc into dst
|
|
*
|
|
* @param pSrc source pixmap
|
|
* @param x source X coordinate.
|
|
* @param y source Y coordinate
|
|
* @param width width of the rectangle to be copied
|
|
* @param height height of the rectangle to be copied
|
|
* @param dst pointer to the beginning of the destination data
|
|
* @param dst_pitch pitch (in bytes) of the lines of destination data.
|
|
*
|
|
* get_image() copies data from offscreen memory in pSrc from
|
|
* (x, y) to (x + width, y + height), to system memory starting at
|
|
* dst (with pitch dst_pitch). This would usually be done
|
|
* using scatter-gather DMA, supported by a DRM call, or by blitting to AGP
|
|
* and then synchronously reading from AGP. Because the implementation
|
|
* might be synchronous, UXA leaves it up to the driver to call
|
|
* uxa_mark_sync() if get_image() was asynchronous. This is in
|
|
* contrast to most other acceleration calls in UXA.
|
|
*
|
|
* @return TRUE if the driver successfully downloaded the data. FALSE
|
|
* indicates that UXA should fall back to doing the download in software.
|
|
*
|
|
* get_image() is not required, but is highly recommended.
|
|
*/
|
|
Bool (*get_image)(PixmapPtr pSrc,
|
|
int x, int y,
|
|
int w, int h,
|
|
char *dst, int dst_pitch);
|
|
|
|
/** @{ */
|
|
/**
|
|
* prepare_access() is called before CPU access to an offscreen pixmap.
|
|
*
|
|
* @param pPix the pixmap being accessed
|
|
* @param index the index of the pixmap being accessed.
|
|
*
|
|
* prepare_access() will be called before CPU access to an offscreen pixmap.
|
|
* This can be used to set up hardware surfaces for byteswapping or
|
|
* untiling, or to adjust the pixmap's devPrivate.ptr for the purpose of
|
|
* making CPU access use a different aperture.
|
|
*
|
|
* The index is one of #UXA_PREPARE_DEST, #UXA_PREPARE_SRC, or
|
|
* #UXA_PREPARE_MASK, indicating which pixmap is in question. Since only up
|
|
* to three pixmaps will have prepare_access() called on them per operation,
|
|
* drivers can have a small, statically-allocated space to maintain state
|
|
* for prepare_access() and finish_access() in. Note that the same pixmap may
|
|
* have prepare_access() called on it more than once, for uxample when doing
|
|
* a copy within the same pixmap (so it gets prepare_access as()
|
|
* #UXA_PREPARE_DEST and then as #UXA_PREPARE_SRC).
|
|
*
|
|
* prepare_access() may fail. An uxample might be the case of hardware that
|
|
* can set up 1 or 2 surfaces for CPU access, but not 3. If prepare_access()
|
|
* fails, UXA will migrate the pixmap to system memory.
|
|
* get_image() must be implemented and must not fail if a driver
|
|
* wishes to fail in prepare_access(). prepare_access() must not fail when
|
|
* pPix is the visible screen, because the visible screen can not be
|
|
* migrated.
|
|
*
|
|
* @return TRUE if prepare_access() successfully prepared the pixmap for CPU
|
|
* drawing.
|
|
* @return FALSE if prepare_access() is unsuccessful and UXA should use
|
|
* get_image() to migate the pixmap out.
|
|
*/
|
|
Bool (*prepare_access)(PixmapPtr pPix, uxa_access_t access);
|
|
|
|
/**
|
|
* finish_access() is called after CPU access to an offscreen pixmap.
|
|
*
|
|
* @param pPix the pixmap being accessed
|
|
* @param index the index of the pixmap being accessed.
|
|
*
|
|
* finish_access() will be called after finishing CPU access of an offscreen
|
|
* pixmap set up by prepare_access(). Note that the finish_access() will not be
|
|
* called if prepare_access() failed.
|
|
*/
|
|
void (*finish_access)(PixmapPtr pPix);
|
|
|
|
/**
|
|
* PixmapIsOffscreen() is an optional driver replacement to
|
|
* uxa_pixmap_is_offscreen(). Set to NULL if you want the standard behaviour
|
|
* of uxa_pixmap_is_offscreen().
|
|
*
|
|
* @param pPix the pixmap
|
|
* @return TRUE if the given drawable is in framebuffer memory.
|
|
*
|
|
* uxa_pixmap_is_offscreen() is used to determine if a pixmap is in offscreen
|
|
* memory, meaning that acceleration could probably be done to it, and that it
|
|
* will need to be wrapped by prepare_access()/finish_access() when accessing it
|
|
* with the CPU.
|
|
*
|
|
*
|
|
*/
|
|
Bool (*pixmap_is_offscreen)(PixmapPtr pPix);
|
|
|
|
/** @} */
|
|
} uxa_driver_t;
|
|
|
|
/** @name UXA driver flags
|
|
* @{
|
|
*/
|
|
/**
|
|
* UXA_TWO_BITBLT_DIRECTIONS indicates to UXA that the driver can only
|
|
* support copies that are (left-to-right, top-to-bottom) or
|
|
* (right-to-left, bottom-to-top).
|
|
*/
|
|
#define UXA_TWO_BITBLT_DIRECTIONS (1 << 2)
|
|
|
|
/** @} */
|
|
|
|
/** @name UXA CreatePixmap hint flags
|
|
* @{
|
|
*/
|
|
/**
|
|
* Flag to hint that the first operation on the pixmap will be a
|
|
* prepare_access.
|
|
*/
|
|
#define UXA_CREATE_PIXMAP_FOR_MAP 0x20000000
|
|
/** @} */
|
|
|
|
uxa_driver_t *
|
|
uxa_driver_alloc(void);
|
|
|
|
Bool
|
|
uxa_driver_init(ScreenPtr screen, uxa_driver_t *uxa_driver);
|
|
|
|
void
|
|
uxa_driver_fini(ScreenPtr pScreen);
|
|
|
|
CARD32
|
|
uxa_get_pixmap_first_pixel (PixmapPtr pPixmap);
|
|
|
|
void
|
|
uxa_set_fallback_debug (ScreenPtr screen, Bool enable);
|
|
|
|
/**
|
|
* Returns TRUE if the given planemask covers all the significant bits in the
|
|
* pixel values for pDrawable.
|
|
*/
|
|
#define UXA_PM_IS_SOLID(_pDrawable, _pm) \
|
|
(((_pm) & FbFullMask((_pDrawable)->depth)) == \
|
|
FbFullMask((_pDrawable)->depth))
|
|
|
|
#endif /* UXA_H */
|