diff options
author | Eric Anholt <eric@anholt.net> | 2009-10-06 16:30:08 -0700 |
---|---|---|
committer | Eric Anholt <eric@anholt.net> | 2009-10-06 17:10:31 -0700 |
commit | 8ae0e44e42db645abe6d385f561260d2ae4a1960 (patch) | |
tree | 2002c65e2d302a32ec5d0b19a8708c3c7264b7c6 /uxa/uxa.h | |
parent | b9b159c49854d8d9d2207946bb583537bb0d48d6 (diff) |
Move to kernel coding style.
We've talked about doing this since the start of the project, putting it off
until "some convenient time". Just after removing a third of the driver seems
like a convenient time, when backporting's probably not happening much anyway.
Diffstat (limited to 'uxa/uxa.h')
-rw-r--r-- | uxa/uxa.h | 889 |
1 files changed, 441 insertions, 448 deletions
@@ -53,444 +53,442 @@ typedef enum { * 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_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 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. + * + * @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 example 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 @@ -515,20 +513,15 @@ typedef struct _UxaDriver { #define UXA_CREATE_PIXMAP_FOR_MAP 0x20000000 /** @} */ -uxa_driver_t * -uxa_driver_alloc(void); +uxa_driver_t *uxa_driver_alloc(void); -Bool -uxa_driver_init(ScreenPtr screen, uxa_driver_t *uxa_driver); +Bool uxa_driver_init(ScreenPtr screen, uxa_driver_t * uxa_driver); -void -uxa_driver_fini(ScreenPtr pScreen); +void uxa_driver_fini(ScreenPtr pScreen); -CARD32 -uxa_get_pixmap_first_pixel (PixmapPtr pPixmap); +CARD32 uxa_get_pixmap_first_pixel(PixmapPtr pPixmap); -void -uxa_set_fallback_debug (ScreenPtr screen, Bool enable); +void uxa_set_fallback_debug(ScreenPtr screen, Bool enable); /** * Returns TRUE if the given planemask covers all the significant bits in the |