From 0f834b91a4768673833ab4917e87d86c237bb1a6 Mon Sep 17 00:00:00 2001 From: marha Date: Fri, 23 Mar 2012 10:05:55 +0100 Subject: libX11 xserver fontconfig mesa pixman xkbcomp xkeyboard-config git update 23 Mar 2012 --- xorg-server/exa/exa.h | 1659 ++++++++++++++++++++++++------------------------- 1 file changed, 816 insertions(+), 843 deletions(-) (limited to 'xorg-server/exa/exa.h') diff --git a/xorg-server/exa/exa.h b/xorg-server/exa/exa.h index 3109607d8..75340021e 100644 --- a/xorg-server/exa/exa.h +++ b/xorg-server/exa/exa.h @@ -1,843 +1,816 @@ -/* - * - * Copyright (C) 2000 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 - * This is the header containing the public API of EXA for exa drivers. - */ - -#ifndef EXA_H -#define EXA_H - -#include "scrnintstr.h" -#include "pixmapstr.h" -#include "windowstr.h" -#include "gcstruct.h" -#include "picturestr.h" -#include "fb.h" - -#define EXA_VERSION_MAJOR 2 -#define EXA_VERSION_MINOR 5 -#define EXA_VERSION_RELEASE 0 - -typedef struct _ExaOffscreenArea ExaOffscreenArea; - -typedef void (*ExaOffscreenSaveProc) (ScreenPtr pScreen, ExaOffscreenArea *area); - -typedef enum _ExaOffscreenState { - ExaOffscreenAvail, - ExaOffscreenRemovable, - ExaOffscreenLocked -} ExaOffscreenState; - -struct _ExaOffscreenArea { - int base_offset; /* allocation base */ - int offset; /* aligned offset */ - int size; /* total allocation size */ - unsigned last_use; - pointer privData; - - ExaOffscreenSaveProc save; - - ExaOffscreenState state; - - ExaOffscreenArea *next; - - unsigned eviction_cost; - - ExaOffscreenArea *prev; /* Double-linked list for defragmentation */ - int align; /* required alignment */ -}; - -/** - * The ExaDriver structure is allocated through exaDriverAlloc(), and then - * fllled in by drivers. - */ -typedef struct _ExaDriver { - /** - * exa_major and exa_minor should be set by the driver to the version of - * EXA which the driver was compiled for (or configures itself at runtime - * to support). This allows EXA to extend the structure for new features - * without breaking ABI for drivers compiled against older versions. - */ - int exa_major, exa_minor; - - /** - * memoryBase is the address of the beginning of framebuffer memory. - * The visible screen should be within memoryBase to memoryBase + - * memorySize. - */ - CARD8 *memoryBase; - - /** - * offScreenBase is the offset from memoryBase of the beginning of the area - * to be managed by EXA's linear offscreen memory manager. - * - * In XFree86 DDX drivers, this is probably: - * (pScrn->displayWidth * cpp * pScrn->virtualY) - */ - unsigned long offScreenBase; - - /** - * memorySize is the length (in bytes) of framebuffer memory beginning - * from memoryBase. - * - * The offscreen memory manager will manage the area beginning at - * (memoryBase + offScreenBase), with a length of (memorySize - - * offScreenBase) - * - * In XFree86 DDX drivers, this is probably (pScrn->videoRam * 1024) - */ - unsigned long memorySize; - - /** - * pixmapOffsetAlign is the byte alignment necessary for pixmap offsets - * within framebuffer. - * - * Hardware typically has a required alignment of offsets, which may or may - * not be a power of two. EXA will ensure that pixmaps managed by the - * offscreen memory manager meet this alignment requirement. - */ - int pixmapOffsetAlign; - - /** - * pixmapPitchAlign is the byte alignment necessary for pixmap pitches - * within the framebuffer. - * - * Hardware typically has a required alignment of pitches for acceleration. - * For 3D hardware, Composite acceleration often requires that source and - * mask pixmaps (textures) have a power-of-two pitch, which can be demanded - * using EXA_OFFSCREEN_ALIGN_POT. These pitch requirements only apply to - * pixmaps managed by the offscreen memory manager. Thus, it is up to the - * driver to ensure that the visible screen has an appropriate pitch for - * acceleration. - */ - int pixmapPitchAlign; - - /** - * The flags field is bitfield of boolean values controlling EXA's behavior. - * - * The flags in clude EXA_OFFSCREEN_PIXMAPS, EXA_OFFSCREEN_ALIGN_POT, and - * EXA_TWO_BITBLT_DIRECTIONS. - */ - int flags; - - /** @{ */ - /** - * maxX controls the X coordinate limitation for rendering from the card. - * The driver should never receive a request for rendering beyond maxX - * in the X direction from the origin of a pixmap. - */ - int maxX; - - /** - * maxY controls the Y coordinate limitation for rendering from the card. - * The driver should never receive a request for rendering beyond maxY - * in the Y direction from the origin of a pixmap. - */ - int maxY; - /** @} */ - - /* private */ - ExaOffscreenArea *offScreenAreas; - Bool needsSync; - int lastMarker; - - /** @name Solid - * @{ - */ - /** - * PrepareSolid() 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 PrepareSolid() call is required of all drivers, but it may fail for any - * reason. Failure results in a fallback to software rendering. - */ - Bool (*PrepareSolid) (PixmapPtr pPixmap, - int alu, - Pixel planemask, - Pixel fg); - - /** - * Solid() performs a solid fill set up in the last PrepareSolid() 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 PrepareSolid() 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 likely means using exaGetPixmapOffset() and - * exaGetPixmapPitch(). - * - * This call is required if PrepareSolid() ever succeeds. - */ - void (*Solid) (PixmapPtr pPixmap, int x1, int y1, int x2, int y2); - - /** - * DoneSolid() finishes a set of solid fills. - * - * @param pPixmap destination pixmap. - * - * The DoneSolid() call is called at the end of a series of consecutive - * Solid() calls following a successful PrepareSolid(). This allows drivers - * to finish up emitting drawing commands that were buffered, or clean up - * state from PrepareSolid(). - * - * This call is required if PrepareSolid() ever succeeds. - */ - void (*DoneSolid) (PixmapPtr pPixmap); - /** @} */ - - /** @name Copy - * @{ - */ - /** - * PrepareCopy() 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 - * #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* - * 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 PrepareCopy() call is required of all drivers, but it may fail for any - * reason. Failure results in a fallback to software rendering. - */ - Bool (*PrepareCopy) (PixmapPtr pSrcPixmap, - PixmapPtr pDstPixmap, - int dx, - int dy, - int alu, - Pixel planemask); - - /** - * Copy() performs a copy set up in the last PrepareCopy 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 PrepareCopy() 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 PrepareCopy(). 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 exaGetPixmapOffset() and exaGetPixmapPitch(). - * - * This call is required if PrepareCopy ever succeeds. - */ - void (*Copy) (PixmapPtr pDstPixmap, - int srcX, - int srcY, - int dstX, - int dstY, - int width, - int height); - - /** - * DoneCopy() finishes a set of copies. - * - * @param pPixmap destination pixmap. - * - * The DoneCopy() call is called at the end of a series of consecutive - * Copy() calls following a successful PrepareCopy(). This allows drivers - * to finish up emitting drawing commands that were buffered, or clean up - * state from PrepareCopy(). - * - * This call is required if PrepareCopy() ever succeeds. - */ - void (*DoneCopy) (PixmapPtr pDstPixmap); - /** @} */ - - /** @name Composite - * @{ - */ - /** - * CheckComposite() 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 CheckComposite() 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. This avoids costly pixmap - * migration to the wrong places when the driver can't accelerate - * operations. Note that because migration hasn't happened, the driver - * can't know during CheckComposite() what the offsets and pitches of the - * pixmaps are going to be. - * - * See PrepareComposite() for more details on likely issues that drivers - * will have in accelerating Composite operations. - * - * The CheckComposite() call is recommended if PrepareComposite() is - * implemented, but is not required. - */ - Bool (*CheckComposite) (int op, - PicturePtr pSrcPicture, - PicturePtr pMaskPicture, - PicturePtr pDstPicture); - - /** - * PrepareComposite() 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 - * PrepareComposite 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 #EXA_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 PrepareComposite() 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 (*PrepareComposite) (int op, - PicturePtr pSrcPicture, - PicturePtr pMaskPicture, - PicturePtr pDstPicture, - PixmapPtr pSrc, - PixmapPtr pMask, - PixmapPtr pDst); - - /** - * Composite() performs a Composite operation set up in the last - * PrepareComposite() 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 PrepareComposite() - * 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 PrepareComposite() ever succeeds. - */ - void (*Composite) (PixmapPtr pDst, - int srcX, - int srcY, - int maskX, - int maskY, - int dstX, - int dstY, - int width, - int height); - - /** - * DoneComposite() finishes a set of Composite operations. - * - * @param pPixmap destination pixmap. - * - * The DoneComposite() call is called at the end of a series of consecutive - * Composite() calls following a successful PrepareComposite(). This allows - * drivers to finish up emitting drawing commands that were buffered, or - * clean up state from PrepareComposite(). - * - * This call is required if PrepareComposite() ever succeeds. - */ - void (*DoneComposite) (PixmapPtr pDst); - /** @} */ - - /** - * UploadToScreen() 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. - * - * UploadToScreen() 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. - * - * If UploadToScreen() is performed asynchronously, it is up to the driver - * to call exaMarkSync(). This is in contrast to most other acceleration - * calls in EXA. - * - * UploadToScreen() can aid in pixmap migration, but is most important for - * the performance of exaGlyphs() (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 EXA should fall back to doing the upload in software. - * - * UploadToScreen() is not required, but is recommended if Composite - * acceleration is supported. - */ - Bool (*UploadToScreen) (PixmapPtr pDst, - int x, - int y, - int w, - int h, - char *src, - int src_pitch); - - /** - * UploadToScratch() is no longer used and will be removed next time the EXA - * major version needs to be bumped. - */ - Bool (*UploadToScratch) (PixmapPtr pSrc, - PixmapPtr pDst); - - /** - * DownloadFromScreen() 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. - * - * DownloadFromScreen() 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, EXA leaves it up to the driver to call - * exaMarkSync() if DownloadFromScreen() was asynchronous. This is in - * contrast to most other acceleration calls in EXA. - * - * DownloadFromScreen() can aid in the largest bottleneck in pixmap - * migration, which is the read from framebuffer when evicting pixmaps from - * framebuffer memory. Thus, it is highly recommended, even though - * implementations are typically complicated. - * - * @return TRUE if the driver successfully downloaded the data. FALSE - * indicates that EXA should fall back to doing the download in software. - * - * DownloadFromScreen() is not required, but is highly recommended. - */ - Bool (*DownloadFromScreen)(PixmapPtr pSrc, - int x, int y, - int w, int h, - char *dst, int dst_pitch); - - /** - * MarkSync() requests that the driver mark a synchronization point, - * returning an driver-defined integer marker which could be requested for - * synchronization to later in WaitMarker(). This might be used in the - * future to avoid waiting for full hardware stalls before accessing pixmap - * data with the CPU, but is not important in the current incarnation of - * EXA. - * - * Note that drivers should call exaMarkSync() when they have done some - * acceleration, rather than their own MarkSync() handler, as otherwise EXA - * will be unaware of the driver's acceleration and not sync to it during - * fallbacks. - * - * MarkSync() is optional. - */ - int (*MarkSync) (ScreenPtr pScreen); - - /** - * WaitMarker() waits for all rendering before the given marker to have - * completed. If the driver does not implement MarkSync(), marker is - * meaningless, and all rendering by the hardware should be completed before - * WaitMarker() returns. - * - * Note that drivers should call exaWaitSync() to wait for all acceleration - * to finish, as otherwise EXA will be unaware of the driver having - * synchronized, resulting in excessive WaitMarker() calls. - * - * WaitMarker() is required of all drivers. - */ - void (*WaitMarker) (ScreenPtr pScreen, int marker); - - /** @{ */ - /** - * PrepareAccess() is called before CPU access to an offscreen pixmap. - * - * @param pPix the pixmap being accessed - * @param index the index of the pixmap being accessed. - * - * PrepareAccess() 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 #EXA_PREPARE_DEST, #EXA_PREPARE_SRC, - * #EXA_PREPARE_MASK, #EXA_PREPARE_AUX_DEST, #EXA_PREPARE_AUX_SRC, or - * #EXA_PREPARE_AUX_MASK. Since only up to #EXA_NUM_PREPARE_INDICES pixmaps - * will have PrepareAccess() called on them per operation, drivers can have - * a small, statically-allocated space to maintain state for PrepareAccess() - * and FinishAccess() in. Note that PrepareAccess() is only called once per - * pixmap and operation, regardless of whether the pixmap is used as a - * destination and/or source, and the index may not reflect the usage. - * - * 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() - * fails, EXA will migrate the pixmap to system memory. - * DownloadFromScreen() must be implemented and must not fail if a driver - * wishes to fail in PrepareAccess(). PrepareAccess() must not fail when - * pPix is the visible screen, because the visible screen can not be - * migrated. - * - * @return TRUE if PrepareAccess() successfully prepared the pixmap for CPU - * drawing. - * @return FALSE if PrepareAccess() is unsuccessful and EXA should use - * DownloadFromScreen() to migate the pixmap out. - */ - Bool (*PrepareAccess)(PixmapPtr pPix, int index); - - /** - * FinishAccess() is called after CPU access to an offscreen pixmap. - * - * @param pPix the pixmap being accessed - * @param index the index of the pixmap being accessed. - * - * FinishAccess() will be called after finishing CPU access of an offscreen - * pixmap set up by PrepareAccess(). Note that the FinishAccess() will not be - * called if PrepareAccess() failed and the pixmap was migrated out. - */ - void (*FinishAccess)(PixmapPtr pPix, int index); - - /** - * PixmapIsOffscreen() is an optional driver replacement to - * exaPixmapHasGpuCopy(). Set to NULL if you want the standard behaviour - * of exaPixmapHasGpuCopy(). - * - * @param pPix the pixmap - * @return TRUE if the given drawable is in framebuffer memory. - * - * exaPixmapHasGpuCopy() 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 PrepareAccess()/FinishAccess() when accessing it - * with the CPU. - * - * - */ - Bool (*PixmapIsOffscreen)(PixmapPtr pPix); - - /** @name PrepareAccess() and FinishAccess() indices - * @{ - */ - /** - * EXA_PREPARE_DEST is the index for a pixmap that may be drawn to or - * read from. - */ - #define EXA_PREPARE_DEST 0 - /** - * EXA_PREPARE_SRC is the index for a pixmap that may be read from - */ - #define EXA_PREPARE_SRC 1 - /** - * EXA_PREPARE_SRC is the index for a second pixmap that may be read - * from. - */ - #define EXA_PREPARE_MASK 2 - /** - * EXA_PREPARE_AUX* are additional indices for other purposes, e.g. - * separate alpha maps with Composite operations. - */ - #define EXA_PREPARE_AUX_DEST 3 - #define EXA_PREPARE_AUX_SRC 4 - #define EXA_PREPARE_AUX_MASK 5 - #define EXA_NUM_PREPARE_INDICES 6 - /** @} */ - - /** - * maxPitchPixels controls the pitch limitation for rendering from - * the card. - * The driver should never receive a request for rendering a pixmap - * that has a pitch (in pixels) beyond maxPitchPixels. - * - * Setting this field is optional -- if your hardware doesn't have - * a pitch limitation in pixels, don't set this. If neither this value - * nor maxPitchBytes is set, then maxPitchPixels is set to maxX. - * If set, it must not be smaller than maxX. - * - * @sa maxPitchBytes - */ - int maxPitchPixels; - - /** - * maxPitchBytes controls the pitch limitation for rendering from - * the card. - * The driver should never receive a request for rendering a pixmap - * that has a pitch (in bytes) beyond maxPitchBytes. - * - * Setting this field is optional -- if your hardware doesn't have - * a pitch limitation in bytes, don't set this. - * If set, it must not be smaller than maxX * 4. - * There's no default value for maxPitchBytes. - * - * @sa maxPitchPixels - */ - int maxPitchBytes; - - /* Hooks to allow driver to its own pixmap memory management */ - void *(*CreatePixmap)(ScreenPtr pScreen, int size, int align); - void (*DestroyPixmap)(ScreenPtr pScreen, void *driverPriv); - /** - * Returning a pixmap with non-NULL devPrivate.ptr implies a pixmap which is - * not offscreen, which will never be accelerated and Prepare/FinishAccess won't - * be called. - */ - Bool (*ModifyPixmapHeader)(PixmapPtr pPixmap, int width, int height, - int depth, int bitsPerPixel, int devKind, - pointer pPixData); - - /* hooks for drivers with tiling support: - * driver MUST fill out new_fb_pitch with valid pitch of pixmap - */ - void *(*CreatePixmap2)(ScreenPtr pScreen, int width, int height, - int depth, int usage_hint, int bitsPerPixel, - int *new_fb_pitch); - /** @} */ -} ExaDriverRec, *ExaDriverPtr; - -/** @name EXA driver flags - * @{ - */ -/** - * EXA_OFFSCREEN_PIXMAPS indicates to EXA that the driver can support - * offscreen pixmaps. - */ -#define EXA_OFFSCREEN_PIXMAPS (1 << 0) - -/** - * EXA_OFFSCREEN_ALIGN_POT indicates to EXA that the driver needs pixmaps - * to have a power-of-two pitch. - */ -#define EXA_OFFSCREEN_ALIGN_POT (1 << 1) - -/** - * EXA_TWO_BITBLT_DIRECTIONS indicates to EXA that the driver can only - * support copies that are (left-to-right, top-to-bottom) or - * (right-to-left, bottom-to-top). - */ -#define EXA_TWO_BITBLT_DIRECTIONS (1 << 2) - -/** - * EXA_HANDLES_PIXMAPS indicates to EXA that the driver can handle - * all pixmap addressing and migration. - */ -#define EXA_HANDLES_PIXMAPS (1 << 3) - -/** - * EXA_SUPPORTS_PREPARE_AUX indicates to EXA that the driver can handle the - * EXA_PREPARE_AUX* indices in the Prepare/FinishAccess hooks. If there are no - * such hooks, this flag has no effect. - */ -#define EXA_SUPPORTS_PREPARE_AUX (1 << 4) - -/** - * EXA_SUPPORTS_OFFSCREEN_OVERLAPS indicates to EXA that the driver Copy hooks - * can handle the source and destination occupying overlapping offscreen memory - * areas. This allows the offscreen memory defragmentation code to defragment - * areas where the defragmented position overlaps the fragmented position. - * - * Typically this is supported by traditional 2D engines but not by 3D engines. - */ -#define EXA_SUPPORTS_OFFSCREEN_OVERLAPS (1 << 5) - -/** - * EXA_MIXED_PIXMAPS will hide unacceleratable pixmaps from drivers and manage the - * problem known software fallbacks like trapezoids. This only migrates pixmaps one way - * into a driver pixmap and then pins it. - */ -#define EXA_MIXED_PIXMAPS (1 << 6) - -/** @} */ - -/* in exa.c */ -extern _X_EXPORT ExaDriverPtr -exaDriverAlloc(void); - -extern _X_EXPORT Bool -exaDriverInit(ScreenPtr pScreen, - ExaDriverPtr pScreenInfo); - -extern _X_EXPORT void -exaDriverFini(ScreenPtr pScreen); - -extern _X_EXPORT void -exaMarkSync(ScreenPtr pScreen); -extern _X_EXPORT void -exaWaitSync(ScreenPtr pScreen); - -extern _X_EXPORT unsigned long -exaGetPixmapOffset(PixmapPtr pPix); - -extern _X_EXPORT unsigned long -exaGetPixmapPitch(PixmapPtr pPix); - -extern _X_EXPORT unsigned long -exaGetPixmapSize(PixmapPtr pPix); - -extern _X_EXPORT void * -exaGetPixmapDriverPrivate(PixmapPtr p); - - -/* in exa_offscreen.c */ -extern _X_EXPORT ExaOffscreenArea * -exaOffscreenAlloc(ScreenPtr pScreen, int size, int align, - Bool locked, - ExaOffscreenSaveProc save, - pointer privData); - -extern _X_EXPORT ExaOffscreenArea * -exaOffscreenFree(ScreenPtr pScreen, ExaOffscreenArea *area); - -extern _X_EXPORT void -ExaOffscreenMarkUsed (PixmapPtr pPixmap); - -extern _X_EXPORT void -exaEnableDisableFBAccess (int index, Bool enable); - -extern _X_EXPORT Bool -exaDrawableIsOffscreen (DrawablePtr pDrawable); - -/* in exa.c */ -extern _X_EXPORT void -exaMoveInPixmap (PixmapPtr pPixmap); - -extern _X_EXPORT void -exaMoveOutPixmap (PixmapPtr pPixmap); - - -/* in exa_unaccel.c */ -extern _X_EXPORT CARD32 -exaGetPixmapFirstPixel (PixmapPtr pPixmap); - - -/** - * Returns TRUE if the given planemask covers all the significant bits in the - * pixel values for pDrawable. - */ -#define EXA_PM_IS_SOLID(_pDrawable, _pm) \ - (((_pm) & FbFullMask((_pDrawable)->depth)) == \ - FbFullMask((_pDrawable)->depth)) - -#endif /* EXA_H */ +/* + * + * Copyright (C) 2000 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 + * This is the header containing the public API of EXA for exa drivers. + */ + +#ifndef EXA_H +#define EXA_H + +#include "scrnintstr.h" +#include "pixmapstr.h" +#include "windowstr.h" +#include "gcstruct.h" +#include "picturestr.h" +#include "fb.h" + +#define EXA_VERSION_MAJOR 2 +#define EXA_VERSION_MINOR 5 +#define EXA_VERSION_RELEASE 0 + +typedef struct _ExaOffscreenArea ExaOffscreenArea; + +typedef void (*ExaOffscreenSaveProc) (ScreenPtr pScreen, + ExaOffscreenArea * area); + +typedef enum _ExaOffscreenState { + ExaOffscreenAvail, + ExaOffscreenRemovable, + ExaOffscreenLocked +} ExaOffscreenState; + +struct _ExaOffscreenArea { + int base_offset; /* allocation base */ + int offset; /* aligned offset */ + int size; /* total allocation size */ + unsigned last_use; + pointer privData; + + ExaOffscreenSaveProc save; + + ExaOffscreenState state; + + ExaOffscreenArea *next; + + unsigned eviction_cost; + + ExaOffscreenArea *prev; /* Double-linked list for defragmentation */ + int align; /* required alignment */ +}; + +/** + * The ExaDriver structure is allocated through exaDriverAlloc(), and then + * fllled in by drivers. + */ +typedef struct _ExaDriver { + /** + * exa_major and exa_minor should be set by the driver to the version of + * EXA which the driver was compiled for (or configures itself at runtime + * to support). This allows EXA to extend the structure for new features + * without breaking ABI for drivers compiled against older versions. + */ + int exa_major, exa_minor; + + /** + * memoryBase is the address of the beginning of framebuffer memory. + * The visible screen should be within memoryBase to memoryBase + + * memorySize. + */ + CARD8 *memoryBase; + + /** + * offScreenBase is the offset from memoryBase of the beginning of the area + * to be managed by EXA's linear offscreen memory manager. + * + * In XFree86 DDX drivers, this is probably: + * (pScrn->displayWidth * cpp * pScrn->virtualY) + */ + unsigned long offScreenBase; + + /** + * memorySize is the length (in bytes) of framebuffer memory beginning + * from memoryBase. + * + * The offscreen memory manager will manage the area beginning at + * (memoryBase + offScreenBase), with a length of (memorySize - + * offScreenBase) + * + * In XFree86 DDX drivers, this is probably (pScrn->videoRam * 1024) + */ + unsigned long memorySize; + + /** + * pixmapOffsetAlign is the byte alignment necessary for pixmap offsets + * within framebuffer. + * + * Hardware typically has a required alignment of offsets, which may or may + * not be a power of two. EXA will ensure that pixmaps managed by the + * offscreen memory manager meet this alignment requirement. + */ + int pixmapOffsetAlign; + + /** + * pixmapPitchAlign is the byte alignment necessary for pixmap pitches + * within the framebuffer. + * + * Hardware typically has a required alignment of pitches for acceleration. + * For 3D hardware, Composite acceleration often requires that source and + * mask pixmaps (textures) have a power-of-two pitch, which can be demanded + * using EXA_OFFSCREEN_ALIGN_POT. These pitch requirements only apply to + * pixmaps managed by the offscreen memory manager. Thus, it is up to the + * driver to ensure that the visible screen has an appropriate pitch for + * acceleration. + */ + int pixmapPitchAlign; + + /** + * The flags field is bitfield of boolean values controlling EXA's behavior. + * + * The flags in clude EXA_OFFSCREEN_PIXMAPS, EXA_OFFSCREEN_ALIGN_POT, and + * EXA_TWO_BITBLT_DIRECTIONS. + */ + int flags; + + /** @{ */ + /** + * maxX controls the X coordinate limitation for rendering from the card. + * The driver should never receive a request for rendering beyond maxX + * in the X direction from the origin of a pixmap. + */ + int maxX; + + /** + * maxY controls the Y coordinate limitation for rendering from the card. + * The driver should never receive a request for rendering beyond maxY + * in the Y direction from the origin of a pixmap. + */ + int maxY; + /** @} */ + + /* private */ + ExaOffscreenArea *offScreenAreas; + Bool needsSync; + int lastMarker; + + /** @name Solid + * @{ + */ + /** + * PrepareSolid() 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 PrepareSolid() call is required of all drivers, but it may fail for any + * reason. Failure results in a fallback to software rendering. + */ + Bool (*PrepareSolid) (PixmapPtr pPixmap, + int alu, Pixel planemask, Pixel fg); + + /** + * Solid() performs a solid fill set up in the last PrepareSolid() 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 PrepareSolid() 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 likely means using exaGetPixmapOffset() and + * exaGetPixmapPitch(). + * + * This call is required if PrepareSolid() ever succeeds. + */ + void (*Solid) (PixmapPtr pPixmap, int x1, int y1, int x2, int y2); + + /** + * DoneSolid() finishes a set of solid fills. + * + * @param pPixmap destination pixmap. + * + * The DoneSolid() call is called at the end of a series of consecutive + * Solid() calls following a successful PrepareSolid(). This allows drivers + * to finish up emitting drawing commands that were buffered, or clean up + * state from PrepareSolid(). + * + * This call is required if PrepareSolid() ever succeeds. + */ + void (*DoneSolid) (PixmapPtr pPixmap); + /** @} */ + + /** @name Copy + * @{ + */ + /** + * PrepareCopy() 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 + * #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* + * 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 PrepareCopy() call is required of all drivers, but it may fail for any + * reason. Failure results in a fallback to software rendering. + */ + Bool (*PrepareCopy) (PixmapPtr pSrcPixmap, + PixmapPtr pDstPixmap, + int dx, int dy, int alu, Pixel planemask); + + /** + * Copy() performs a copy set up in the last PrepareCopy 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 PrepareCopy() 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 PrepareCopy(). 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 exaGetPixmapOffset() and exaGetPixmapPitch(). + * + * This call is required if PrepareCopy ever succeeds. + */ + void (*Copy) (PixmapPtr pDstPixmap, + int srcX, + int srcY, int dstX, int dstY, int width, int height); + + /** + * DoneCopy() finishes a set of copies. + * + * @param pPixmap destination pixmap. + * + * The DoneCopy() call is called at the end of a series of consecutive + * Copy() calls following a successful PrepareCopy(). This allows drivers + * to finish up emitting drawing commands that were buffered, or clean up + * state from PrepareCopy(). + * + * This call is required if PrepareCopy() ever succeeds. + */ + void (*DoneCopy) (PixmapPtr pDstPixmap); + /** @} */ + + /** @name Composite + * @{ + */ + /** + * CheckComposite() 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 CheckComposite() 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. This avoids costly pixmap + * migration to the wrong places when the driver can't accelerate + * operations. Note that because migration hasn't happened, the driver + * can't know during CheckComposite() what the offsets and pitches of the + * pixmaps are going to be. + * + * See PrepareComposite() for more details on likely issues that drivers + * will have in accelerating Composite operations. + * + * The CheckComposite() call is recommended if PrepareComposite() is + * implemented, but is not required. + */ + Bool (*CheckComposite) (int op, + PicturePtr pSrcPicture, + PicturePtr pMaskPicture, PicturePtr pDstPicture); + + /** + * PrepareComposite() 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 + * PrepareComposite 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 #EXA_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 PrepareComposite() 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 (*PrepareComposite) (int op, + PicturePtr pSrcPicture, + PicturePtr pMaskPicture, + PicturePtr pDstPicture, + PixmapPtr pSrc, PixmapPtr pMask, PixmapPtr pDst); + + /** + * Composite() performs a Composite operation set up in the last + * PrepareComposite() 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 PrepareComposite() + * 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 PrepareComposite() ever succeeds. + */ + void (*Composite) (PixmapPtr pDst, + int srcX, + int srcY, + int maskX, + int maskY, int dstX, int dstY, int width, int height); + + /** + * DoneComposite() finishes a set of Composite operations. + * + * @param pPixmap destination pixmap. + * + * The DoneComposite() call is called at the end of a series of consecutive + * Composite() calls following a successful PrepareComposite(). This allows + * drivers to finish up emitting drawing commands that were buffered, or + * clean up state from PrepareComposite(). + * + * This call is required if PrepareComposite() ever succeeds. + */ + void (*DoneComposite) (PixmapPtr pDst); + /** @} */ + + /** + * UploadToScreen() 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. + * + * UploadToScreen() 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. + * + * If UploadToScreen() is performed asynchronously, it is up to the driver + * to call exaMarkSync(). This is in contrast to most other acceleration + * calls in EXA. + * + * UploadToScreen() can aid in pixmap migration, but is most important for + * the performance of exaGlyphs() (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 EXA should fall back to doing the upload in software. + * + * UploadToScreen() is not required, but is recommended if Composite + * acceleration is supported. + */ + Bool (*UploadToScreen) (PixmapPtr pDst, + int x, + int y, int w, int h, char *src, int src_pitch); + + /** + * UploadToScratch() is no longer used and will be removed next time the EXA + * major version needs to be bumped. + */ + Bool (*UploadToScratch) (PixmapPtr pSrc, PixmapPtr pDst); + + /** + * DownloadFromScreen() 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. + * + * DownloadFromScreen() 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, EXA leaves it up to the driver to call + * exaMarkSync() if DownloadFromScreen() was asynchronous. This is in + * contrast to most other acceleration calls in EXA. + * + * DownloadFromScreen() can aid in the largest bottleneck in pixmap + * migration, which is the read from framebuffer when evicting pixmaps from + * framebuffer memory. Thus, it is highly recommended, even though + * implementations are typically complicated. + * + * @return TRUE if the driver successfully downloaded the data. FALSE + * indicates that EXA should fall back to doing the download in software. + * + * DownloadFromScreen() is not required, but is highly recommended. + */ + Bool (*DownloadFromScreen) (PixmapPtr pSrc, + int x, int y, + int w, int h, char *dst, int dst_pitch); + + /** + * MarkSync() requests that the driver mark a synchronization point, + * returning an driver-defined integer marker which could be requested for + * synchronization to later in WaitMarker(). This might be used in the + * future to avoid waiting for full hardware stalls before accessing pixmap + * data with the CPU, but is not important in the current incarnation of + * EXA. + * + * Note that drivers should call exaMarkSync() when they have done some + * acceleration, rather than their own MarkSync() handler, as otherwise EXA + * will be unaware of the driver's acceleration and not sync to it during + * fallbacks. + * + * MarkSync() is optional. + */ + int (*MarkSync) (ScreenPtr pScreen); + + /** + * WaitMarker() waits for all rendering before the given marker to have + * completed. If the driver does not implement MarkSync(), marker is + * meaningless, and all rendering by the hardware should be completed before + * WaitMarker() returns. + * + * Note that drivers should call exaWaitSync() to wait for all acceleration + * to finish, as otherwise EXA will be unaware of the driver having + * synchronized, resulting in excessive WaitMarker() calls. + * + * WaitMarker() is required of all drivers. + */ + void (*WaitMarker) (ScreenPtr pScreen, int marker); + + /** @{ */ + /** + * PrepareAccess() is called before CPU access to an offscreen pixmap. + * + * @param pPix the pixmap being accessed + * @param index the index of the pixmap being accessed. + * + * PrepareAccess() 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 #EXA_PREPARE_DEST, #EXA_PREPARE_SRC, + * #EXA_PREPARE_MASK, #EXA_PREPARE_AUX_DEST, #EXA_PREPARE_AUX_SRC, or + * #EXA_PREPARE_AUX_MASK. Since only up to #EXA_NUM_PREPARE_INDICES pixmaps + * will have PrepareAccess() called on them per operation, drivers can have + * a small, statically-allocated space to maintain state for PrepareAccess() + * and FinishAccess() in. Note that PrepareAccess() is only called once per + * pixmap and operation, regardless of whether the pixmap is used as a + * destination and/or source, and the index may not reflect the usage. + * + * 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() + * fails, EXA will migrate the pixmap to system memory. + * DownloadFromScreen() must be implemented and must not fail if a driver + * wishes to fail in PrepareAccess(). PrepareAccess() must not fail when + * pPix is the visible screen, because the visible screen can not be + * migrated. + * + * @return TRUE if PrepareAccess() successfully prepared the pixmap for CPU + * drawing. + * @return FALSE if PrepareAccess() is unsuccessful and EXA should use + * DownloadFromScreen() to migate the pixmap out. + */ + Bool (*PrepareAccess) (PixmapPtr pPix, int index); + + /** + * FinishAccess() is called after CPU access to an offscreen pixmap. + * + * @param pPix the pixmap being accessed + * @param index the index of the pixmap being accessed. + * + * FinishAccess() will be called after finishing CPU access of an offscreen + * pixmap set up by PrepareAccess(). Note that the FinishAccess() will not be + * called if PrepareAccess() failed and the pixmap was migrated out. + */ + void (*FinishAccess) (PixmapPtr pPix, int index); + + /** + * PixmapIsOffscreen() is an optional driver replacement to + * exaPixmapHasGpuCopy(). Set to NULL if you want the standard behaviour + * of exaPixmapHasGpuCopy(). + * + * @param pPix the pixmap + * @return TRUE if the given drawable is in framebuffer memory. + * + * exaPixmapHasGpuCopy() 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 PrepareAccess()/FinishAccess() when accessing it + * with the CPU. + * + * + */ + Bool (*PixmapIsOffscreen) (PixmapPtr pPix); + + /** @name PrepareAccess() and FinishAccess() indices + * @{ + */ + /** + * EXA_PREPARE_DEST is the index for a pixmap that may be drawn to or + * read from. + */ +#define EXA_PREPARE_DEST 0 + /** + * EXA_PREPARE_SRC is the index for a pixmap that may be read from + */ +#define EXA_PREPARE_SRC 1 + /** + * EXA_PREPARE_SRC is the index for a second pixmap that may be read + * from. + */ +#define EXA_PREPARE_MASK 2 + /** + * EXA_PREPARE_AUX* are additional indices for other purposes, e.g. + * separate alpha maps with Composite operations. + */ +#define EXA_PREPARE_AUX_DEST 3 +#define EXA_PREPARE_AUX_SRC 4 +#define EXA_PREPARE_AUX_MASK 5 +#define EXA_NUM_PREPARE_INDICES 6 + /** @} */ + + /** + * maxPitchPixels controls the pitch limitation for rendering from + * the card. + * The driver should never receive a request for rendering a pixmap + * that has a pitch (in pixels) beyond maxPitchPixels. + * + * Setting this field is optional -- if your hardware doesn't have + * a pitch limitation in pixels, don't set this. If neither this value + * nor maxPitchBytes is set, then maxPitchPixels is set to maxX. + * If set, it must not be smaller than maxX. + * + * @sa maxPitchBytes + */ + int maxPitchPixels; + + /** + * maxPitchBytes controls the pitch limitation for rendering from + * the card. + * The driver should never receive a request for rendering a pixmap + * that has a pitch (in bytes) beyond maxPitchBytes. + * + * Setting this field is optional -- if your hardware doesn't have + * a pitch limitation in bytes, don't set this. + * If set, it must not be smaller than maxX * 4. + * There's no default value for maxPitchBytes. + * + * @sa maxPitchPixels + */ + int maxPitchBytes; + + /* Hooks to allow driver to its own pixmap memory management */ + void *(*CreatePixmap) (ScreenPtr pScreen, int size, int align); + void (*DestroyPixmap) (ScreenPtr pScreen, void *driverPriv); + /** + * Returning a pixmap with non-NULL devPrivate.ptr implies a pixmap which is + * not offscreen, which will never be accelerated and Prepare/FinishAccess won't + * be called. + */ + Bool (*ModifyPixmapHeader) (PixmapPtr pPixmap, int width, int height, + int depth, int bitsPerPixel, int devKind, + pointer pPixData); + + /* hooks for drivers with tiling support: + * driver MUST fill out new_fb_pitch with valid pitch of pixmap + */ + void *(*CreatePixmap2) (ScreenPtr pScreen, int width, int height, + int depth, int usage_hint, int bitsPerPixel, + int *new_fb_pitch); + /** @} */ +} ExaDriverRec, *ExaDriverPtr; + +/** @name EXA driver flags + * @{ + */ +/** + * EXA_OFFSCREEN_PIXMAPS indicates to EXA that the driver can support + * offscreen pixmaps. + */ +#define EXA_OFFSCREEN_PIXMAPS (1 << 0) + +/** + * EXA_OFFSCREEN_ALIGN_POT indicates to EXA that the driver needs pixmaps + * to have a power-of-two pitch. + */ +#define EXA_OFFSCREEN_ALIGN_POT (1 << 1) + +/** + * EXA_TWO_BITBLT_DIRECTIONS indicates to EXA that the driver can only + * support copies that are (left-to-right, top-to-bottom) or + * (right-to-left, bottom-to-top). + */ +#define EXA_TWO_BITBLT_DIRECTIONS (1 << 2) + +/** + * EXA_HANDLES_PIXMAPS indicates to EXA that the driver can handle + * all pixmap addressing and migration. + */ +#define EXA_HANDLES_PIXMAPS (1 << 3) + +/** + * EXA_SUPPORTS_PREPARE_AUX indicates to EXA that the driver can handle the + * EXA_PREPARE_AUX* indices in the Prepare/FinishAccess hooks. If there are no + * such hooks, this flag has no effect. + */ +#define EXA_SUPPORTS_PREPARE_AUX (1 << 4) + +/** + * EXA_SUPPORTS_OFFSCREEN_OVERLAPS indicates to EXA that the driver Copy hooks + * can handle the source and destination occupying overlapping offscreen memory + * areas. This allows the offscreen memory defragmentation code to defragment + * areas where the defragmented position overlaps the fragmented position. + * + * Typically this is supported by traditional 2D engines but not by 3D engines. + */ +#define EXA_SUPPORTS_OFFSCREEN_OVERLAPS (1 << 5) + +/** + * EXA_MIXED_PIXMAPS will hide unacceleratable pixmaps from drivers and manage the + * problem known software fallbacks like trapezoids. This only migrates pixmaps one way + * into a driver pixmap and then pins it. + */ +#define EXA_MIXED_PIXMAPS (1 << 6) + +/** @} */ + +/* in exa.c */ +extern _X_EXPORT ExaDriverPtr exaDriverAlloc(void); + +extern _X_EXPORT Bool + exaDriverInit(ScreenPtr pScreen, ExaDriverPtr pScreenInfo); + +extern _X_EXPORT void + exaDriverFini(ScreenPtr pScreen); + +extern _X_EXPORT void + exaMarkSync(ScreenPtr pScreen); +extern _X_EXPORT void + exaWaitSync(ScreenPtr pScreen); + +extern _X_EXPORT unsigned long + exaGetPixmapOffset(PixmapPtr pPix); + +extern _X_EXPORT unsigned long + exaGetPixmapPitch(PixmapPtr pPix); + +extern _X_EXPORT unsigned long + exaGetPixmapSize(PixmapPtr pPix); + +extern _X_EXPORT void *exaGetPixmapDriverPrivate(PixmapPtr p); + +/* in exa_offscreen.c */ +extern _X_EXPORT ExaOffscreenArea *exaOffscreenAlloc(ScreenPtr pScreen, + int size, int align, + Bool locked, + ExaOffscreenSaveProc save, + pointer privData); + +extern _X_EXPORT ExaOffscreenArea *exaOffscreenFree(ScreenPtr pScreen, + ExaOffscreenArea * area); + +extern _X_EXPORT void + ExaOffscreenMarkUsed(PixmapPtr pPixmap); + +extern _X_EXPORT void + exaEnableDisableFBAccess(int index, Bool enable); + +extern _X_EXPORT Bool + exaDrawableIsOffscreen(DrawablePtr pDrawable); + +/* in exa.c */ +extern _X_EXPORT void + exaMoveInPixmap(PixmapPtr pPixmap); + +extern _X_EXPORT void + exaMoveOutPixmap(PixmapPtr pPixmap); + +/* in exa_unaccel.c */ +extern _X_EXPORT CARD32 + exaGetPixmapFirstPixel(PixmapPtr pPixmap); + +/** + * Returns TRUE if the given planemask covers all the significant bits in the + * pixel values for pDrawable. + */ +#define EXA_PM_IS_SOLID(_pDrawable, _pm) \ + (((_pm) & FbFullMask((_pDrawable)->depth)) == \ + FbFullMask((_pDrawable)->depth)) + +#endif /* EXA_H */ -- cgit v1.2.3