frederik
/
xserver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve doxygen formatting, and attempt to clarify the 1:1 ratio of 

successful PrepareCopy()s to DoneCopy()s.
This commit is contained in:
Eric Anholt 2006-03-12 03:04:52 +00:00
parent 9a7fba5fd0
commit 9ed3463450
2 changed files with 91 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
ChangeLog
View File

@ -1,3 +1,9 @@
2006-03-11 Eric Anholt <anholt@FreeBSD.org>
* exa/exa.h:
Improve doxygen formatting, and attempt to clarify the 1:1 ratio of
successful PrepareCopy()s to DoneCopy()s.
2006-03-11 Eric Anholt <anholt@FreeBSD.org> 2006-03-11 Eric Anholt <anholt@FreeBSD.org>
reviewed by: jbarnes reviewed by: jbarnes

166
exa/exa.h
View File

@ -163,20 +163,19 @@ typedef struct _ExaDriver {
* @{ * @{
*/ */
/** /**
* PrepareSolid sets up the driver for doing a solid fill. * PrepareSolid() sets up the driver for doing a solid fill.
* @param pPixmap Destination pixmap * @param pPixmap Destination pixmap
* @param alu raster operation * @param alu raster operation
* @param planemask write mask for the fill * @param planemask write mask for the fill
* @param fg "foreground" color for the fill * @param fg "foreground" color for the fill
* *
* This call should set up the driver for doing a series of solid fills * 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* * 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 * graphics functions listed in X.h, and typically maps to a similar
* single-byte "ROP" setting in all hardware. The planemask controls * single-byte "ROP" setting in all hardware. The planemask controls
* which bits of * which bits of the destination should be affected, and will only represent
* the destination should be affected, and will only represent the bits up * the bits up to the depth of pPixmap. The fg is the pixel value of the
* to the depth of pPixmap. The fg is the pixel value of the foreground * foreground color referred to in ROP descriptions.
* color referred to in ROP descriptions.
* *
* Note that many drivers will need to store some of the data in the driver * 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. * private record, for sending to the hardware with each drawing command.
@ -190,7 +189,7 @@ typedef struct _ExaDriver {
Pixel fg); Pixel fg);
/** /**
* Solid performs a solid fill set up in the last PrepareSolid call. * Solid() performs a solid fill set up in the last PrepareSolid() call.
* *
* @param pPixmap destination pixmap * @param pPixmap destination pixmap
* @param x1 left coordinate * @param x1 left coordinate
@ -211,13 +210,14 @@ typedef struct _ExaDriver {
void (*Solid) (PixmapPtr pPixmap, int x1, int y1, int x2, int y2); void (*Solid) (PixmapPtr pPixmap, int x1, int y1, int x2, int y2);
/** /**
* DoneSolid finishes a set of solid fills. * DoneSolid() finishes a set of solid fills.
* *
* @param pPixmap destination pixmap. * @param pPixmap destination pixmap.
* *
* The DoneSolid call is called at the end of a set of a series of Solid() * The DoneSolid() call is called at the end of a series of consecutive
* calls following a PrepareSolid() that was called. This allows drivers to * Solid() calls following a successful PrepareSolid(). This allows drivers
* finish up emitting drawing commands that were buffered. * to finish up emitting drawing commands that were buffered, or clean up
* state from PrepareSolid().
* *
* This call is required if PrepareSolid() ever succeeds. * This call is required if PrepareSolid() ever succeeds.
*/ */
@ -228,7 +228,9 @@ typedef struct _ExaDriver {
* @{ * @{
*/ */
/** /**
* PrepareCopy sets up the driver for doing a copy within offscreen memory. * PrepareCopy() sets up the driver for doing a copy within offscreen
* memory.
*
* @param pSrcPixmap source pixmap * @param pSrcPixmap source pixmap
* @param pDstPixmap destination pixmap * @param pDstPixmap destination pixmap
* @param dx X copy direction * @param dx X copy direction
@ -243,7 +245,7 @@ typedef struct _ExaDriver {
* is to deal with self-overlapping copies when pSrcPixmap == pDstPixmap. * is to deal with self-overlapping copies when pSrcPixmap == pDstPixmap.
* If your hardware can only support blits that are (left to right, top to * 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 * bottom) or (right to left, bottom to top), then you should set
* EXA_TWO_BITBLT_DIRECTIONS, and EXA will break down Copy operations to * #EXA_TWO_BITBLT_DIRECTIONS, and EXA will break down Copy operations to
* ones that meet those requirements. The alu raster op is one of the GX* * 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 * graphics functions listed in X.h, and typically maps to a similar
* single-byte "ROP" setting in all hardware. The planemask controls which * single-byte "ROP" setting in all hardware. The planemask controls which
@ -264,7 +266,7 @@ typedef struct _ExaDriver {
Pixel planemask); Pixel planemask);
/** /**
* Copy performs a copy set up in the last PrepareCopy call. * Copy() performs a copy set up in the last PrepareCopy call.
* *
* @param pDstPixmap destination pixmap * @param pDstPixmap destination pixmap
* @param srcX source X coordinate * @param srcX source X coordinate
@ -296,15 +298,16 @@ typedef struct _ExaDriver {
int height); int height);
/** /**
* DoneCopy finishes a set of copies. * DoneCopy() finishes a set of copies.
* *
* @param pPixmap destination pixmap. * @param pPixmap destination pixmap.
* *
* The DoneCopy call is called at the end of a set of a series of Copy() * The DoneCopy() call is called at the end of a series of consecutive
* calls following a PrepareCopy() that was called. This allows drivers to * Copy() calls following a successful PrepareCopy(). This allows drivers
* finish up emitting drawing commands that were buffered. * to finish up emitting drawing commands that were buffered, or clean up
* state from PrepareCopy().
* *
* This call is required if PrepareCopy ever succeeds. * This call is required if PrepareCopy() ever succeeds.
*/ */
void (*DoneCopy) (PixmapPtr pDstPixmap); void (*DoneCopy) (PixmapPtr pDstPixmap);
/** @} */ /** @} */
@ -313,27 +316,28 @@ typedef struct _ExaDriver {
* @{ * @{
*/ */
/** /**
* CheckComposite checks to see if a composite operation could be accelerated. * CheckComposite() checks to see if a composite operation could be
* accelerated.
* *
* @param op Render operation * @param op Render operation
* @param pSrcPicture source Picture * @param pSrcPicture source Picture
* @param pMaskPicture mask picture * @param pMaskPicture mask picture
* @param pDstPicture destination Picture * @param pDstPicture destination Picture
* *
* The CheckComposite call checks if the driver could handle acceleration of * The CheckComposite() call checks if the driver could handle acceleration
* op with the given source, mask, and destination pictures. This allows * of op with the given source, mask, and destination pictures. This allows
* drivers to check source and destination formats, supported operations, * drivers to check source and destination formats, supported operations,
* transformations, and component alpha state, and send operations it can't * transformations, and component alpha state, and send operations it can't
* support to software rendering early on. This avoids costly pixmap * support to software rendering early on. This avoids costly pixmap
* migration to the wrong places when the driver can't accelerate * migration to the wrong places when the driver can't accelerate
* operations. Note that because migration hasn't happened, the driver * operations. Note that because migration hasn't happened, the driver
* can't know during CheckComposite what the pitches and offsets of the * can't know during CheckComposite() what the offsets and pitches of the
* pixmaps are going to be. * pixmaps are going to be.
* *
* See PrepareComposite() for more details on likely issues that drivers * See PrepareComposite() for more details on likely issues that drivers
* will have in accelerating Composite operations. * will have in accelerating Composite operations.
* *
* The CheckComposite call is recommended if PrepareComposite() is * The CheckComposite() call is recommended if PrepareComposite() is
* implemented, but is not required. * implemented, but is not required.
*/ */
Bool (*CheckComposite) (int op, Bool (*CheckComposite) (int op,
@ -342,7 +346,7 @@ typedef struct _ExaDriver {
PicturePtr pDstPicture); PicturePtr pDstPicture);
/** /**
* PrepareComposite sets up the driver for doing a Composite operations * PrepareComposite() sets up the driver for doing a Composite operation
* described in the Render extension protocol spec. * described in the Render extension protocol spec.
* *
* @param op Render operation * @param op Render operation
@ -385,14 +389,15 @@ typedef struct _ExaDriver {
* pixmaps that have a width or height that is not a power of two. * pixmaps that have a width or height that is not a power of two.
* *
* If your hardware can't support source pictures (textures) with * If your hardware can't support source pictures (textures) with
* non-power-of-two pitches, you should set EXA_OFFSCREEN_ALIGN_POT. * non-power-of-two pitches, you should set #EXA_OFFSCREEN_ALIGN_POT.
* *
* Note that many drivers will need to store some of the data in the driver * 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. * private record, for sending to the hardware with each drawing command.
* *
* The PrepareCopy call is not required. However, it is highly recommended * The PrepareComposite() call is not required. However, it is highly
* for performance of antialiased font rendering and performance of cairo * recommended for performance of antialiased font rendering and performance
* applications. Failure results in a fallback to software rendering. * of cairo applications. Failure results in a fallback to software
* rendering.
*/ */
Bool (*PrepareComposite) (int op, Bool (*PrepareComposite) (int op,
PicturePtr pSrcPicture, PicturePtr pSrcPicture,
@ -403,8 +408,8 @@ typedef struct _ExaDriver {
PixmapPtr pDst); PixmapPtr pDst);
/** /**
* Composite performs a Composite operation set up in the last * Composite() performs a Composite operation set up in the last
* PrepareComposite call. * PrepareComposite() call.
* *
* @param pDstPixmap destination pixmap * @param pDstPixmap destination pixmap
* @param srcX source X coordinate * @param srcX source X coordinate
@ -416,7 +421,7 @@ typedef struct _ExaDriver {
* @param width destination rectangle width * @param width destination rectangle width
* @param height destination rectangle height * @param height destination rectangle height
* *
* Performs the Composite operation set up by the last PrepareComposite * Performs the Composite operation set up by the last PrepareComposite()
* call, to the rectangle from (dstX, dstY) to (dstX + width, dstY + height) * call, to the rectangle from (dstX, dstY) to (dstX + width, dstY + height)
* in the destination Pixmap. Note that if a transformation was set on * 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 * the source or mask Pictures, the source rectangles may not be the same
@ -424,7 +429,7 @@ typedef struct _ExaDriver {
* transformation right at the subpixel level can be tricky, and rendercheck * transformation right at the subpixel level can be tricky, and rendercheck
* can test this for you. * can test this for you.
* *
* This call is required if PrepareComposite ever succeeds. * This call is required if PrepareComposite() ever succeeds.
*/ */
void (*Composite) (PixmapPtr pDst, void (*Composite) (PixmapPtr pDst,
int srcX, int srcX,
@ -437,15 +442,16 @@ typedef struct _ExaDriver {
int height); int height);
/** /**
* DoneComposite finishes a set of Composite operations. * DoneComposite() finishes a set of Composite operations.
* *
* @param pPixmap destination pixmap. * @param pPixmap destination pixmap.
* *
* The DoneComposite call is called at the end of a set of a series of * The DoneComposite() call is called at the end of a series of consecutive
* Composite() calls following a PrepareCopy() that was called. This allows * Composite() calls following a successful PrepareComposite(). This allows
* drivers to finish up emitting drawing commands that were buffered. * drivers to finish up emitting drawing commands that were buffered, or
* clean up state from PrepareComposite().
* *
* This call is required if PrepareComposite ever succeeds. * This call is required if PrepareComposite() ever succeeds.
*/ */
void (*DoneComposite) (PixmapPtr pDst); void (*DoneComposite) (PixmapPtr pDst);
/** @} */ /** @} */
@ -467,12 +473,12 @@ typedef struct _ExaDriver {
* where the CPU sets up a blit command on the hardware with instructions * 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. * that the blit data will be fed through some sort of aperture on the card.
* *
* If UploadToScreen is performed asynchronously, it is up to the driver to * If UploadToScreen() is performed asynchronously, it is up to the driver
* call exaMarkSync(). This is in contrast to most other acceleration calls * to call exaMarkSync(). This is in contrast to most other acceleration
* in EXA. * calls in EXA.
* *
* UploadToScreen can aid in pixmap migration, but is most important for * UploadToScreen() can aid in pixmap migration, but is most important for
* the performance of exaGlyphs (antialiased font drawing) by allowing * the performance of exaGlyphs() (antialiased font drawing) by allowing
* pipelining of data uploads, avoiding a sync of the card after each glyph. * pipelining of data uploads, avoiding a sync of the card after each glyph.
* *
* @return TRUE if the driver successfully uploaded the data. FALSE * @return TRUE if the driver successfully uploaded the data. FALSE
@ -498,26 +504,25 @@ typedef struct _ExaDriver {
* *
* The UploadToScratch() call was added to support Xati before Xati had * The UploadToScratch() call was added to support Xati before Xati had
* support for hostdata uploads and before exaGlyphs() was written. It * support for hostdata uploads and before exaGlyphs() was written. It
* behaves incorrectly (uses an invalid pixmap as pDst), and UploadToScreen() * behaves incorrectly (uses an invalid pixmap as pDst),
* should be implemented instead. * and UploadToScreen() should be implemented instead.
* *
* Drivers implementing UploadToScratch() had to set up space (likely in a * Drivers implementing UploadToScratch() had to set up space (likely in a
* statically allocated area) in offscreen memory, copy pSrc to that * statically allocated area) in offscreen memory, copy pSrc to that
* scratch area, and adust pDst->devKind for the pitch and * scratch area, and adust pDst->devKind for the pitch and
* pDst->devPrivate.ptr for the pointer to that scratch area. The driver * pDst->devPrivate.ptr for the pointer to that scratch area. The driver
* was responsible for syncing (as it was implemented using memcpy() in * was responsible for syncing (as it was implemented using memcpy() in
* Xati), and only the data from the last UploadToScratch() was guaranteed to * Xati), and only the data from the last UploadToScratch() was guaranteed
* be valid at any given time. * to be valid at any given time.
* *
* UploadToScratch() should not be implemented by drivers, and will likely be * UploadToScratch() should not be implemented by drivers, and will likely
* removed in a future version of EXA. * be removed in a future version of EXA.
*/ */
Bool (*UploadToScratch) (PixmapPtr pSrc, Bool (*UploadToScratch) (PixmapPtr pSrc,
PixmapPtr pDst); PixmapPtr pDst);
/** /**
* DownloadFromScreen loads a rectangle of data from @param pSrc into * DownloadFromScreen() loads a rectangle of data from pSrc into dst
* @param dst
* *
* @param pSrc source pixmap * @param pSrc source pixmap
* @param x source X coordinate. * @param x source X coordinate.
@ -527,41 +532,37 @@ typedef struct _ExaDriver {
* @param dst pointer to the beginning of the destination data * @param dst pointer to the beginning of the destination data
* @param dst_pitch pitch (in bytes) of the lines of destination data. * @param dst_pitch pitch (in bytes) of the lines of destination data.
* *
* DownloadFromScreen copies data from offscreen memory in pSrc from * DownloadFromScreen() copies data from offscreen memory in pSrc from
* (x, y) to (x + width, y + height), to system memory starting at * (x, y) to (x + width, y + height), to system memory starting at
* dst (with pitch dst_pitch). This would usually be done * dst (with pitch dst_pitch). This would usually be done
* using scatter-gather DMA, supported by a DRM call, or by blitting to AGP * using scatter-gather DMA, supported by a DRM call, or by blitting to AGP
* and then synchronously reading from AGP. Because the implementation * and then synchronously reading from AGP. Because the implementation
* might be synchronous, EXA leaves it up to the driver to call * might be synchronous, EXA leaves it up to the driver to call
* exaMarkSync() if DownloadFromScreen was asynchronous. This is in * exaMarkSync() if DownloadFromScreen() was asynchronous. This is in
* contrast to most other acceleration calls in EXA. * contrast to most other acceleration calls in EXA.
* *
* DownloadFromScreen can aid in the largest bottleneck in pixmap migration, * DownloadFromScreen() can aid in the largest bottleneck in pixmap
* which is the read from framebuffer when evicting pixmaps from framebuffer * migration, which is the read from framebuffer when evicting pixmaps from
* memory. Thus, it is highly recommended, even though implementations are * framebuffer memory. Thus, it is highly recommended, even though
* typically complicated. * implementations are typically complicated.
* *
* @return TRUE if the driver successfully downloaded the data. FALSE * @return TRUE if the driver successfully downloaded the data. FALSE
* indicates that EXA should fall back to doing the download in software. * indicates that EXA should fall back to doing the download in software.
* *
* UploadToScreen is not required, but is highly recommended. * DownloadFromScreen() is not required, but is highly recommended.
*/ */
Bool (*DownloadFromScreen)(PixmapPtr pSrc, Bool (*DownloadFromScreen)(PixmapPtr pSrc,
int x, int y, int x, int y,
int w, int h, int w, int h,
char *dst, int dst_pitch); char *dst, int dst_pitch);
/* Should return a hrdware-dependent marker number which can
* be waited for with WaitMarker(). It can be not implemented in which
* case WaitMarker() must wait for idle on any given marker
* number.
*/
/** /**
* MarkSync() requests that the driver mark a synchronization point, returning * MarkSync() requests that the driver mark a synchronization point,
* an driver-devined integer marker which could be requested for * returning an driver-defined integer marker which could be requested for
* synchronization to later in WaitMarker(). This might be used in the future * synchronization to later in WaitMarker(). This might be used in the
* to avoid waiting for full hardware stalls before accessing pixmap data * future to avoid waiting for full hardware stalls before accessing pixmap
* with the CPU, but is not important in the current incarnation of EXA. * data with the CPU, but is not important in the current incarnation of
* EXA.
* *
* MarkSync() is optional. * MarkSync() is optional.
*/ */
@ -589,24 +590,27 @@ typedef struct _ExaDriver {
* untiling, or to adjust the pixmap's devPrivate.ptr for the purpose of * untiling, or to adjust the pixmap's devPrivate.ptr for the purpose of
* making CPU access use a different aperture. * making CPU access use a different aperture.
* *
* The index is one of EXA_PREPARE_DEST, EXA_PREPARE_SRC, or EXA_PREPARE_MASK, * The index is one of #EXA_PREPARE_DEST, #EXA_PREPARE_SRC, or
* indicating which pixmap is in question. Since only up to three * #EXA_PREPARE_MASK, indicating which pixmap is in question. Since only up
* pixmaps will have PrepareAccess() called on them per operation, drivers * to three pixmaps will have PrepareAccess() called on them per operation,
* can have a small, statically-allocated space to maintain state * drivers can have a small, statically-allocated space to maintain state
* for PrepareAccess() and FinishAccess() in. Note that the same pixmap may have * for PrepareAccess() and FinishAccess() in. Note that the same pixmap may
* PrepareAccess() called on it more than once, for example when doing a copy * have PrepareAccess() called on it more than once, for example when doing
* within the same pixmap (so it gets PrepareAccess as EXA_PREPARE_DEST and * a copy within the same pixmap (so it gets PrepareAccess as()
* then as EXA_PREPARE_SRC). * #EXA_PREPARE_DEST and then as #EXA_PREPARE_SRC).
* *
* PrepareAccess() may fail. An example might be the case of hardware that * PrepareAccess() 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 PrepareAccess * can set up 1 or 2 surfaces for CPU access, but not 3. If PrepareAccess()
* fails, EXA will migrate the pixmap to system memory. For this migration, * fails, EXA will migrate the pixmap to system memory.
* DownloadFromScreen() must be implemented, and must not fail. * DownloadFromScreen() must be implemented and must not fail if a driver
* PrepareAccess() must not fail when pPix is the visible screen, because * wishes to fail in PrepareAccess(). PrepareAccess() must not fail when
* the visible screen can not be migrated. * pPix is the visible screen, because the visible screen can not be
* migrated.
* *
* @return TRUE if PrepareAccess() successfully prepared the pixmap for CPU * @return TRUE if PrepareAccess() successfully prepared the pixmap for CPU
* drawing. * drawing.
* @return FALSE if PrepareAccess() is unsuccessful and EXA should use
* DownloadFromScreen() to migate the pixmap out.
*/ */
Bool (*PrepareAccess)(PixmapPtr pPix, int index); Bool (*PrepareAccess)(PixmapPtr pPix, int index);