exa/exa.h

   1 /*
   2  *
   3  * Copyright (C) 2000 Keith Packard
   4  *               2004 Eric Anholt
   5  *               2005 Zack Rusin
   6  *
   7  * Permission to use, copy, modify, distribute, and sell this software and its
   8  * documentation for any purpose is hereby granted without fee, provided that
   9  * the above copyright notice appear in all copies and that both that
  10  * copyright notice and this permission notice appear in supporting
  11  * documentation, and that the name of copyright holders not be used in
  12  * advertising or publicity pertaining to distribution of the software without
  13  * specific, written prior permission. Copyright holders make no
  14  * representations about the suitability of this software for any purpose.  It
  15  * is provided "as is" without express or implied warranty.
  16  *
  17  * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
  18  * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  19  * FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
  20  * SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  21  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
  22  * AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
  23  * OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
  24  * SOFTWARE.
  25  */
  26
  27 /** @file
  28  * This is the header containing the public API of EXA for exa drivers.
  29  */
  30
  31 #ifndef EXA_H
  32 #define EXA_H
  33
  34 #include "scrnintstr.h"
  35 #include "pixmapstr.h"
  36 #include "windowstr.h"
  37 #include "gcstruct.h"
  38 #include "picturestr.h"
  39 #include "fb.h"
  40
  41 #define EXA_VERSION_MAJOR   2
  42 #define EXA_VERSION_MINOR   5
  43 #define EXA_VERSION_RELEASE 0
  44
  45 typedef struct _ExaOffscreenArea ExaOffscreenArea;
  46
  47 typedef void (*ExaOffscreenSaveProc) (ScreenPtr pScreen,
  48                                       ExaOffscreenArea * area);
  49
  50 typedef enum _ExaOffscreenState {
  51     ExaOffscreenAvail,
  52     ExaOffscreenRemovable,
  53     ExaOffscreenLocked
  54 } ExaOffscreenState;
  55
  56 struct _ExaOffscreenArea {
  57     int base_offset;            /* allocation base */
  58     int offset;                 /* aligned offset */
  59     int size;                   /* total allocation size */
  60     unsigned last_use;
  61     pointer privData;
  62
  63     ExaOffscreenSaveProc save;
  64
  65     ExaOffscreenState state;
  66
  67     ExaOffscreenArea *next;
  68
  69     unsigned eviction_cost;
  70
  71     ExaOffscreenArea *prev;     /* Double-linked list for defragmentation */
  72     int align;                  /* required alignment */
  73 };
  74
  75 /**
  76  * The ExaDriver structure is allocated through exaDriverAlloc(), and then
  77  * fllled in by drivers.
  78  */
  79 typedef struct _ExaDriver {
  80     /**
  81      * exa_major and exa_minor should be set by the driver to the version of
  82      * EXA which the driver was compiled for (or configures itself at runtime
  83      * to support).  This allows EXA to extend the structure for new features
  84      * without breaking ABI for drivers compiled against older versions.
  85      */
  86     int exa_major, exa_minor;
  87
  88     /**
  89      * memoryBase is the address of the beginning of framebuffer memory.
  90      * The visible screen should be within memoryBase to memoryBase +
  91      * memorySize.
  92      */
  93     CARD8 *memoryBase;
  94
  95     /**
  96      * offScreenBase is the offset from memoryBase of the beginning of the area
  97      * to be managed by EXA's linear offscreen memory manager.
  98      *
  99      * In XFree86 DDX drivers, this is probably:
 100      *   (pScrn->displayWidth * cpp * pScrn->virtualY)
 101      */
 102     unsigned long offScreenBase;
 103
 104     /**
 105      * memorySize is the length (in bytes) of framebuffer memory beginning
 106      * from memoryBase.
 107      *
 108      * The offscreen memory manager will manage the area beginning at
 109      * (memoryBase + offScreenBase), with a length of (memorySize -
 110      * offScreenBase)
 111      *
 112      * In XFree86 DDX drivers, this is probably (pScrn->videoRam * 1024)
 113      */
 114     unsigned long memorySize;
 115
 116     /**
 117      * pixmapOffsetAlign is the byte alignment necessary for pixmap offsets
 118      * within framebuffer.
 119      *
 120      * Hardware typically has a required alignment of offsets, which may or may
 121      * not be a power of two.  EXA will ensure that pixmaps managed by the
 122      * offscreen memory manager meet this alignment requirement.
 123      */
 124     int pixmapOffsetAlign;
 125
 126     /**
 127      * pixmapPitchAlign is the byte alignment necessary for pixmap pitches
 128      * within the framebuffer.
 129      *
 130      * Hardware typically has a required alignment of pitches for acceleration.
 131      * For 3D hardware, Composite acceleration often requires that source and
 132      * mask pixmaps (textures) have a power-of-two pitch, which can be demanded
 133      * using EXA_OFFSCREEN_ALIGN_POT.  These pitch requirements only apply to
 134      * pixmaps managed by the offscreen memory manager.  Thus, it is up to the
 135      * driver to ensure that the visible screen has an appropriate pitch for
 136      * acceleration.
 137      */
 138     int pixmapPitchAlign;
 139
 140     /**
 141      * The flags field is bitfield of boolean values controlling EXA's behavior.
 142      *
 143      * The flags in clude EXA_OFFSCREEN_PIXMAPS, EXA_OFFSCREEN_ALIGN_POT, and
 144      * EXA_TWO_BITBLT_DIRECTIONS.
 145      */
 146     int flags;
 147
 148     /** @{ */
 149     /**
 150      * maxX controls the X coordinate limitation for rendering from the card.
 151      * The driver should never receive a request for rendering beyond maxX
 152      * in the X direction from the origin of a pixmap.
 153      */
 154     int maxX;
 155
 156     /**
 157      * maxY controls the Y coordinate limitation for rendering from the card.
 158      * The driver should never receive a request for rendering beyond maxY
 159      * in the Y direction from the origin of a pixmap.
 160      */
 161     int maxY;
 162     /** @} */
 163
 164     /* private */
 165     ExaOffscreenArea *offScreenAreas;
 166     Bool needsSync;
 167     int lastMarker;
 168
 169     /** @name Solid
 170      * @{
 171      */
 172     /**
 173      * PrepareSolid() sets up the driver for doing a solid fill.
 174      * @param pPixmap Destination pixmap
 175      * @param alu raster operation
 176      * @param planemask write mask for the fill
 177      * @param fg "foreground" color for the fill
 178      *
 179      * This call should set up the driver for doing a series of solid fills
 180      * through the Solid() call.  The alu raster op is one of the GX*
 181      * graphics functions listed in X.h, and typically maps to a similar
 182      * single-byte "ROP" setting in all hardware.  The planemask controls
 183      * which bits of the destination should be affected, and will only represent
 184      * the bits up to the depth of pPixmap.  The fg is the pixel value of the
 185      * foreground color referred to in ROP descriptions.
 186      *
 187      * Note that many drivers will need to store some of the data in the driver
 188      * private record, for sending to the hardware with each drawing command.
 189      *
 190      * The PrepareSolid() call is required of all drivers, but it may fail for any
 191      * reason.  Failure results in a fallback to software rendering.
 192      */
 193     Bool (*PrepareSolid) (PixmapPtr pPixmap,
 194                           int alu, Pixel planemask, Pixel fg);
 195
 196     /**
 197      * Solid() performs a solid fill set up in the last PrepareSolid() call.
 198      *
 199      * @param pPixmap destination pixmap
 200      * @param x1 left coordinate
 201      * @param y1 top coordinate
 202      * @param x2 right coordinate
 203      * @param y2 bottom coordinate
 204      *
 205      * Performs the fill set up by the last PrepareSolid() call, covering the
 206      * area from (x1,y1) to (x2,y2) in pPixmap.  Note that the coordinates are
 207      * in the coordinate space of the destination pixmap, so the driver will
 208      * need to set up the hardware's offset and pitch for the destination
 209      * coordinates according to the pixmap's offset and pitch within
 210      * framebuffer.  This likely means using exaGetPixmapOffset() and
 211      * exaGetPixmapPitch().
 212      *
 213      * This call is required if PrepareSolid() ever succeeds.
 214      */
 215     void (*Solid) (PixmapPtr pPixmap, int x1, int y1, int x2, int y2);
 216
 217     /**
 218      * DoneSolid() finishes a set of solid fills.
 219      *
 220      * @param pPixmap destination pixmap.
 221      *
 222      * The DoneSolid() call is called at the end of a series of consecutive
 223      * Solid() calls following a successful PrepareSolid().  This allows drivers
 224      * to finish up emitting drawing commands that were buffered, or clean up
 225      * state from PrepareSolid().
 226      *
 227      * This call is required if PrepareSolid() ever succeeds.
 228      */
 229     void (*DoneSolid) (PixmapPtr pPixmap);
 230     /** @} */
 231
 232     /** @name Copy
 233      * @{
 234      */
 235     /**
 236      * PrepareCopy() sets up the driver for doing a copy within video
 237      * memory.
 238      *
 239      * @param pSrcPixmap source pixmap
 240      * @param pDstPixmap destination pixmap
 241      * @param dx X copy direction
 242      * @param dy Y copy direction
 243      * @param alu raster operation
 244      * @param planemask write mask for the fill
 245      *
 246      * This call should set up the driver for doing a series of copies from the
 247      * the pSrcPixmap to the pDstPixmap.  The dx flag will be positive if the
 248      * hardware should do the copy from the left to the right, and dy will be
 249      * positive if the copy should be done from the top to the bottom.  This
 250      * is to deal with self-overlapping copies when pSrcPixmap == pDstPixmap.
 251      * If your hardware can only support blits that are (left to right, top to
 252      * bottom) or (right to left, bottom to top), then you should set
 253      * #EXA_TWO_BITBLT_DIRECTIONS, and EXA will break down Copy operations to
 254      * ones that meet those requirements.  The alu raster op is one of the GX*
 255      * graphics functions listed in X.h, and typically maps to a similar
 256      * single-byte "ROP" setting in all hardware.  The planemask controls which
 257      * bits of the destination should be affected, and will only represent the
 258      * bits up to the depth of pPixmap.
 259      *
 260      * Note that many drivers will need to store some of the data in the driver
 261      * private record, for sending to the hardware with each drawing command.
 262      *
 263      * The PrepareCopy() call is required of all drivers, but it may fail for any
 264      * reason.  Failure results in a fallback to software rendering.
 265      */
 266     Bool (*PrepareCopy) (PixmapPtr pSrcPixmap,
 267                          PixmapPtr pDstPixmap,
 268                          int dx, int dy, int alu, Pixel planemask);
 269
 270     /**
 271      * Copy() performs a copy set up in the last PrepareCopy call.
 272      *
 273      * @param pDstPixmap destination pixmap
 274      * @param srcX source X coordinate
 275      * @param srcY source Y coordinate
 276      * @param dstX destination X coordinate
 277      * @param dstY destination Y coordinate
 278      * @param width width of the rectangle to be copied
 279      * @param height height of the rectangle to be copied.
 280      *
 281      * Performs the copy set up by the last PrepareCopy() call, copying the
 282      * rectangle from (srcX, srcY) to (srcX + width, srcY + width) in the source
 283      * pixmap to the same-sized rectangle at (dstX, dstY) in the destination
 284      * pixmap.  Those rectangles may overlap in memory, if
 285      * pSrcPixmap == pDstPixmap.  Note that this call does not receive the
 286      * pSrcPixmap as an argument -- if it's needed in this function, it should
 287      * be stored in the driver private during PrepareCopy().  As with Solid(),
 288      * the coordinates are in the coordinate space of each pixmap, so the driver
 289      * will need to set up source and destination pitches and offsets from those
 290      * pixmaps, probably using exaGetPixmapOffset() and exaGetPixmapPitch().
 291      *
 292      * This call is required if PrepareCopy ever succeeds.
 293      */
 294     void (*Copy) (PixmapPtr pDstPixmap,
 295                   int srcX,
 296                   int srcY, int dstX, int dstY, int width, int height);
 297
 298     /**
 299      * DoneCopy() finishes a set of copies.
 300      *
 301      * @param pPixmap destination pixmap.
 302      *
 303      * The DoneCopy() call is called at the end of a series of consecutive
 304      * Copy() calls following a successful PrepareCopy().  This allows drivers
 305      * to finish up emitting drawing commands that were buffered, or clean up
 306      * state from PrepareCopy().
 307      *
 308      * This call is required if PrepareCopy() ever succeeds.
 309      */
 310     void (*DoneCopy) (PixmapPtr pDstPixmap);
 311     /** @} */
 312
 313     /** @name Composite
 314      * @{
 315      */
 316     /**
 317      * CheckComposite() checks to see if a composite operation could be
 318      * accelerated.
 319      *
 320      * @param op Render operation
 321      * @param pSrcPicture source Picture
 322      * @param pMaskPicture mask picture
 323      * @param pDstPicture destination Picture
 324      *
 325      * The CheckComposite() call checks if the driver could handle acceleration
 326      * of op with the given source, mask, and destination pictures.  This allows
 327      * drivers to check source and destination formats, supported operations,
 328      * transformations, and component alpha state, and send operations it can't
 329      * support to software rendering early on.  This avoids costly pixmap
 330      * migration to the wrong places when the driver can't accelerate
 331      * operations.  Note that because migration hasn't happened, the driver
 332      * can't know during CheckComposite() what the offsets and pitches of the
 333      * pixmaps are going to be.
 334      *
 335      * See PrepareComposite() for more details on likely issues that drivers
 336      * will have in accelerating Composite operations.
 337      *
 338      * The CheckComposite() call is recommended if PrepareComposite() is
 339      * implemented, but is not required.
 340      */
 341     Bool (*CheckComposite) (int op,
 342                             PicturePtr pSrcPicture,
 343                             PicturePtr pMaskPicture, PicturePtr pDstPicture);
 344
 345     /**
 346      * PrepareComposite() sets up the driver for doing a Composite operation
 347      * described in the Render extension protocol spec.
 348      *
 349      * @param op Render operation
 350      * @param pSrcPicture source Picture
 351      * @param pMaskPicture mask picture
 352      * @param pDstPicture destination Picture
 353      * @param pSrc source pixmap
 354      * @param pMask mask pixmap
 355      * @param pDst destination pixmap
 356      *
 357      * This call should set up the driver for doing a series of Composite
 358      * operations, as described in the Render protocol spec, with the given
 359      * pSrcPicture, pMaskPicture, and pDstPicture.  The pSrc, pMask, and
 360      * pDst are the pixmaps containing the pixel data, and should be used for
 361      * setting the offset and pitch used for the coordinate spaces for each of
 362      * the Pictures.
 363      *
 364      * Notes on interpreting Picture structures:
 365      * - The Picture structures will always have a valid pDrawable.
 366      * - The Picture structures will never have alphaMap set.
 367      * - The mask Picture (and therefore pMask) may be NULL, in which case the
 368      *   operation is simply src OP dst instead of src IN mask OP dst, and
 369      *   mask coordinates should be ignored.
 370      * - pMarkPicture may have componentAlpha set, which greatly changes
 371      *   the behavior of the Composite operation.  componentAlpha has no effect
 372      *   when set on pSrcPicture or pDstPicture.
 373      * - The source and mask Pictures may have a transformation set
 374      *   (Picture->transform != NULL), which means that the source coordinates
 375      *   should be transformed by that transformation, resulting in scaling,
 376      *   rotation, etc.  The PictureTransformPoint() call can transform
 377      *   coordinates for you.  Transforms have no effect on Pictures when used
 378      *   as a destination.
 379      * - The source and mask pictures may have a filter set.  PictFilterNearest
 380      *   and PictFilterBilinear are defined in the Render protocol, but others
 381      *   may be encountered, and must be handled correctly (usually by
 382      *   PrepareComposite failing, and falling back to software).  Filters have
 383      *   no effect on Pictures when used as a destination.
 384      * - The source and mask Pictures may have repeating set, which must be
 385      *   respected.  Many chipsets will be unable to support repeating on
 386      *   pixmaps that have a width or height that is not a power of two.
 387      *
 388      * If your hardware can't support source pictures (textures) with
 389      * non-power-of-two pitches, you should set #EXA_OFFSCREEN_ALIGN_POT.
 390      *
 391      * Note that many drivers will need to store some of the data in the driver
 392      * private record, for sending to the hardware with each drawing command.
 393      *
 394      * The PrepareComposite() call is not required.  However, it is highly
 395      * recommended for performance of antialiased font rendering and performance
 396      * of cairo applications.  Failure results in a fallback to software
 397      * rendering.
 398      */
 399     Bool (*PrepareComposite) (int op,
 400                               PicturePtr pSrcPicture,
 401                               PicturePtr pMaskPicture,
 402                               PicturePtr pDstPicture,
 403                               PixmapPtr pSrc, PixmapPtr pMask, PixmapPtr pDst);
 404
 405     /**
 406      * Composite() performs a Composite operation set up in the last
 407      * PrepareComposite() call.
 408      *
 409      * @param pDstPixmap destination pixmap
 410      * @param srcX source X coordinate
 411      * @param srcY source Y coordinate
 412      * @param maskX source X coordinate
 413      * @param maskY source Y coordinate
 414      * @param dstX destination X coordinate
 415      * @param dstY destination Y coordinate
 416      * @param width destination rectangle width
 417      * @param height destination rectangle height
 418      *
 419      * Performs the Composite operation set up by the last PrepareComposite()
 420      * call, to the rectangle from (dstX, dstY) to (dstX + width, dstY + height)
 421      * in the destination Pixmap.  Note that if a transformation was set on
 422      * the source or mask Pictures, the source rectangles may not be the same
 423      * size as the destination rectangles and filtering.  Getting the coordinate
 424      * transformation right at the subpixel level can be tricky, and rendercheck
 425      * can test this for you.
 426      *
 427      * This call is required if PrepareComposite() ever succeeds.
 428      */
 429     void (*Composite) (PixmapPtr pDst,
 430                        int srcX,
 431                        int srcY,
 432                        int maskX,
 433                        int maskY, int dstX, int dstY, int width, int height);
 434
 435     /**
 436      * DoneComposite() finishes a set of Composite operations.
 437      *
 438      * @param pPixmap destination pixmap.
 439      *
 440      * The DoneComposite() call is called at the end of a series of consecutive
 441      * Composite() calls following a successful PrepareComposite().  This allows
 442      * drivers to finish up emitting drawing commands that were buffered, or
 443      * clean up state from PrepareComposite().
 444      *
 445      * This call is required if PrepareComposite() ever succeeds.
 446      */
 447     void (*DoneComposite) (PixmapPtr pDst);
 448     /** @} */
 449
 450     /**
 451      * UploadToScreen() loads a rectangle of data from src into pDst.
 452      *
 453      * @param pDst destination pixmap
 454      * @param x destination X coordinate.
 455      * @param y destination Y coordinate
 456      * @param width width of the rectangle to be copied
 457      * @param height height of the rectangle to be copied
 458      * @param src pointer to the beginning of the source data
 459      * @param src_pitch pitch (in bytes) of the lines of source data.
 460      *
 461      * UploadToScreen() copies data in system memory beginning at src (with
 462      * pitch src_pitch) into the destination pixmap from (x, y) to
 463      * (x + width, y + height).  This is typically done with hostdata uploads,
 464      * where the CPU sets up a blit command on the hardware with instructions
 465      * that the blit data will be fed through some sort of aperture on the card.
 466      *
 467      * If UploadToScreen() is performed asynchronously, it is up to the driver
 468      * to call exaMarkSync().  This is in contrast to most other acceleration
 469      * calls in EXA.
 470      *
 471      * UploadToScreen() can aid in pixmap migration, but is most important for
 472      * the performance of exaGlyphs() (antialiased font drawing) by allowing
 473      * pipelining of data uploads, avoiding a sync of the card after each glyph.
 474      *
 475      * @return TRUE if the driver successfully uploaded the data.  FALSE
 476      * indicates that EXA should fall back to doing the upload in software.
 477      *
 478      * UploadToScreen() is not required, but is recommended if Composite
 479      * acceleration is supported.
 480      */
 481     Bool (*UploadToScreen) (PixmapPtr pDst,
 482                             int x,
 483                             int y, int w, int h, char *src, int src_pitch);
 484
 485     /**
 486      * UploadToScratch() is no longer used and will be removed next time the EXA
 487      * major version needs to be bumped.
 488      */
 489     Bool (*UploadToScratch) (PixmapPtr pSrc, PixmapPtr pDst);
 490
 491     /**
 492      * DownloadFromScreen() loads a rectangle of data from pSrc into dst
 493      *
 494      * @param pSrc source pixmap
 495      * @param x source X coordinate.
 496      * @param y source Y coordinate
 497      * @param width width of the rectangle to be copied
 498      * @param height height of the rectangle to be copied
 499      * @param dst pointer to the beginning of the destination data
 500      * @param dst_pitch pitch (in bytes) of the lines of destination data.
 501      *
 502      * DownloadFromScreen() copies data from offscreen memory in pSrc from
 503      * (x, y) to (x + width, y + height), to system memory starting at
 504      * dst (with pitch dst_pitch).  This would usually be done
 505      * using scatter-gather DMA, supported by a DRM call, or by blitting to AGP
 506      * and then synchronously reading from AGP.  Because the implementation
 507      * might be synchronous, EXA leaves it up to the driver to call
 508      * exaMarkSync() if DownloadFromScreen() was asynchronous.  This is in
 509      * contrast to most other acceleration calls in EXA.
 510      *
 511      * DownloadFromScreen() can aid in the largest bottleneck in pixmap
 512      * migration, which is the read from framebuffer when evicting pixmaps from
 513      * framebuffer memory.  Thus, it is highly recommended, even though
 514      * implementations are typically complicated.
 515      *
 516      * @return TRUE if the driver successfully downloaded the data.  FALSE
 517      * indicates that EXA should fall back to doing the download in software.
 518      *
 519      * DownloadFromScreen() is not required, but is highly recommended.
 520      */
 521     Bool (*DownloadFromScreen) (PixmapPtr pSrc,
 522                                 int x, int y,
 523                                 int w, int h, char *dst, int dst_pitch);
 524
 525     /**
 526      * MarkSync() requests that the driver mark a synchronization point,
 527      * returning an driver-defined integer marker which could be requested for
 528      * synchronization to later in WaitMarker().  This might be used in the
 529      * future to avoid waiting for full hardware stalls before accessing pixmap
 530      * data with the CPU, but is not important in the current incarnation of
 531      * EXA.
 532      *
 533      * Note that drivers should call exaMarkSync() when they have done some
 534      * acceleration, rather than their own MarkSync() handler, as otherwise EXA
 535      * will be unaware of the driver's acceleration and not sync to it during
 536      * fallbacks.
 537      *
 538      * MarkSync() is optional.
 539      */
 540     int (*MarkSync) (ScreenPtr pScreen);
 541
 542     /**
 543      * WaitMarker() waits for all rendering before the given marker to have
 544      * completed.  If the driver does not implement MarkSync(), marker is
 545      * meaningless, and all rendering by the hardware should be completed before
 546      * WaitMarker() returns.
 547      *
 548      * Note that drivers should call exaWaitSync() to wait for all acceleration
 549      * to finish, as otherwise EXA will be unaware of the driver having
 550      * synchronized, resulting in excessive WaitMarker() calls.
 551      *
 552      * WaitMarker() is required of all drivers.
 553      */
 554     void (*WaitMarker) (ScreenPtr pScreen, int marker);
 555
 556     /** @{ */
 557     /**
 558      * PrepareAccess() is called before CPU access to an offscreen pixmap.
 559      *
 560      * @param pPix the pixmap being accessed
 561      * @param index the index of the pixmap being accessed.
 562      *
 563      * PrepareAccess() will be called before CPU access to an offscreen pixmap.
 564      * This can be used to set up hardware surfaces for byteswapping or
 565      * untiling, or to adjust the pixmap's devPrivate.ptr for the purpose of
 566      * making CPU access use a different aperture.
 567      *
 568      * The index is one of #EXA_PREPARE_DEST, #EXA_PREPARE_SRC,
 569      * #EXA_PREPARE_MASK, #EXA_PREPARE_AUX_DEST, #EXA_PREPARE_AUX_SRC, or
 570      * #EXA_PREPARE_AUX_MASK. Since only up to #EXA_NUM_PREPARE_INDICES pixmaps
 571      * will have PrepareAccess() called on them per operation, drivers can have
 572      * a small, statically-allocated space to maintain state for PrepareAccess()
 573      * and FinishAccess() in.  Note that PrepareAccess() is only called once per
 574      * pixmap and operation, regardless of whether the pixmap is used as a
 575      * destination and/or source, and the index may not reflect the usage.
 576      *
 577      * PrepareAccess() may fail.  An example might be the case of hardware that
 578      * can set up 1 or 2 surfaces for CPU access, but not 3.  If PrepareAccess()
 579      * fails, EXA will migrate the pixmap to system memory.
 580      * DownloadFromScreen() must be implemented and must not fail if a driver
 581      * wishes to fail in PrepareAccess().  PrepareAccess() must not fail when
 582      * pPix is the visible screen, because the visible screen can not be
 583      * migrated.
 584      *
 585      * @return TRUE if PrepareAccess() successfully prepared the pixmap for CPU
 586      * drawing.
 587      * @return FALSE if PrepareAccess() is unsuccessful and EXA should use
 588      * DownloadFromScreen() to migate the pixmap out.
 589      */
 590     Bool (*PrepareAccess) (PixmapPtr pPix, int index);
 591
 592     /**
 593      * FinishAccess() is called after CPU access to an offscreen pixmap.
 594      *
 595      * @param pPix the pixmap being accessed
 596      * @param index the index of the pixmap being accessed.
 597      *
 598      * FinishAccess() will be called after finishing CPU access of an offscreen
 599      * pixmap set up by PrepareAccess().  Note that the FinishAccess() will not be
 600      * called if PrepareAccess() failed and the pixmap was migrated out.
 601      */
 602     void (*FinishAccess) (PixmapPtr pPix, int index);
 603
 604     /**
 605      * PixmapIsOffscreen() is an optional driver replacement to
 606      * exaPixmapHasGpuCopy(). Set to NULL if you want the standard behaviour
 607      * of exaPixmapHasGpuCopy().
 608      *
 609      * @param pPix the pixmap
 610      * @return TRUE if the given drawable is in framebuffer memory.
 611      *
 612      * exaPixmapHasGpuCopy() is used to determine if a pixmap is in offscreen
 613      * memory, meaning that acceleration could probably be done to it, and that it
 614      * will need to be wrapped by PrepareAccess()/FinishAccess() when accessing it
 615      * with the CPU.
 616      *
 617      *
 618      */
 619     Bool (*PixmapIsOffscreen) (PixmapPtr pPix);
 620
 621         /** @name PrepareAccess() and FinishAccess() indices
 622          * @{
 623          */
 624         /**
 625          * EXA_PREPARE_DEST is the index for a pixmap that may be drawn to or
 626          * read from.
 627          */
 628 #define EXA_PREPARE_DEST        0
 629         /**
 630          * EXA_PREPARE_SRC is the index for a pixmap that may be read from
 631          */
 632 #define EXA_PREPARE_SRC         1
 633         /**
 634          * EXA_PREPARE_SRC is the index for a second pixmap that may be read
 635          * from.
 636          */
 637 #define EXA_PREPARE_MASK        2
 638         /**
 639          * EXA_PREPARE_AUX* are additional indices for other purposes, e.g.
 640          * separate alpha maps with Composite operations.
 641          */
 642 #define EXA_PREPARE_AUX_DEST    3
 643 #define EXA_PREPARE_AUX_SRC     4
 644 #define EXA_PREPARE_AUX_MASK    5
 645 #define EXA_NUM_PREPARE_INDICES 6
 646         /** @} */
 647
 648     /**
 649      * maxPitchPixels controls the pitch limitation for rendering from
 650      * the card.
 651      * The driver should never receive a request for rendering a pixmap
 652      * that has a pitch (in pixels) beyond maxPitchPixels.
 653      *
 654      * Setting this field is optional -- if your hardware doesn't have
 655      * a pitch limitation in pixels, don't set this. If neither this value
 656      * nor maxPitchBytes is set, then maxPitchPixels is set to maxX.
 657      * If set, it must not be smaller than maxX.
 658      *
 659      * @sa maxPitchBytes
 660      */
 661     int maxPitchPixels;
 662
 663     /**
 664      * maxPitchBytes controls the pitch limitation for rendering from
 665      * the card.
 666      * The driver should never receive a request for rendering a pixmap
 667      * that has a pitch (in bytes) beyond maxPitchBytes.
 668      *
 669      * Setting this field is optional -- if your hardware doesn't have
 670      * a pitch limitation in bytes, don't set this.
 671      * If set, it must not be smaller than maxX * 4.
 672      * There's no default value for maxPitchBytes.
 673      *
 674      * @sa maxPitchPixels
 675      */
 676     int maxPitchBytes;
 677
 678     /* Hooks to allow driver to its own pixmap memory management */
 679     void *(*CreatePixmap) (ScreenPtr pScreen, int size, int align);
 680     void (*DestroyPixmap) (ScreenPtr pScreen, void *driverPriv);
 681     /**
 682      * Returning a pixmap with non-NULL devPrivate.ptr implies a pixmap which is
 683      * not offscreen, which will never be accelerated and Prepare/FinishAccess won't
 684      * be called.
 685      */
 686     Bool (*ModifyPixmapHeader) (PixmapPtr pPixmap, int width, int height,
 687                                 int depth, int bitsPerPixel, int devKind,
 688                                 pointer pPixData);
 689
 690     /* hooks for drivers with tiling support:
 691      * driver MUST fill out new_fb_pitch with valid pitch of pixmap
 692      */
 693     void *(*CreatePixmap2) (ScreenPtr pScreen, int width, int height,
 694                             int depth, int usage_hint, int bitsPerPixel,
 695                             int *new_fb_pitch);
 696     /** @} */
 697 } ExaDriverRec, *ExaDriverPtr;
 698
 699 /** @name EXA driver flags
 700  * @{
 701  */
 702 /**
 703  * EXA_OFFSCREEN_PIXMAPS indicates to EXA that the driver can support
 704  * offscreen pixmaps.
 705  */
 706 #define EXA_OFFSCREEN_PIXMAPS           (1 << 0)
 707
 708 /**
 709  * EXA_OFFSCREEN_ALIGN_POT indicates to EXA that the driver needs pixmaps
 710  * to have a power-of-two pitch.
 711  */
 712 #define EXA_OFFSCREEN_ALIGN_POT         (1 << 1)
 713
 714 /**
 715  * EXA_TWO_BITBLT_DIRECTIONS indicates to EXA that the driver can only
 716  * support copies that are (left-to-right, top-to-bottom) or
 717  * (right-to-left, bottom-to-top).
 718  */
 719 #define EXA_TWO_BITBLT_DIRECTIONS       (1 << 2)
 720
 721 /**
 722  * EXA_HANDLES_PIXMAPS indicates to EXA that the driver can handle
 723  * all pixmap addressing and migration.
 724  */
 725 #define EXA_HANDLES_PIXMAPS             (1 << 3)
 726
 727 /**
 728  * EXA_SUPPORTS_PREPARE_AUX indicates to EXA that the driver can handle the
 729  * EXA_PREPARE_AUX* indices in the Prepare/FinishAccess hooks. If there are no
 730  * such hooks, this flag has no effect.
 731  */
 732 #define EXA_SUPPORTS_PREPARE_AUX        (1 << 4)
 733
 734 /**
 735  * EXA_SUPPORTS_OFFSCREEN_OVERLAPS indicates to EXA that the driver Copy hooks
 736  * can handle the source and destination occupying overlapping offscreen memory
 737  * areas. This allows the offscreen memory defragmentation code to defragment
 738  * areas where the defragmented position overlaps the fragmented position.
 739  *
 740  * Typically this is supported by traditional 2D engines but not by 3D engines.
 741  */
 742 #define EXA_SUPPORTS_OFFSCREEN_OVERLAPS (1 << 5)
 743
 744 /**
 745  * EXA_MIXED_PIXMAPS will hide unacceleratable pixmaps from drivers and manage the
 746  * problem known software fallbacks like trapezoids. This only migrates pixmaps one way
 747  * into a driver pixmap and then pins it.
 748  */
 749 #define EXA_MIXED_PIXMAPS (1 << 6)
 750
 751 /** @} */
 752
 753 /* in exa.c */
 754 extern _X_EXPORT ExaDriverPtr exaDriverAlloc(void);
 755
 756 extern _X_EXPORT Bool
 757  exaDriverInit(ScreenPtr pScreen, ExaDriverPtr pScreenInfo);
 758
 759 extern _X_EXPORT void
 760  exaDriverFini(ScreenPtr pScreen);
 761
 762 extern _X_EXPORT void
 763  exaMarkSync(ScreenPtr pScreen);
 764 extern _X_EXPORT void
 765  exaWaitSync(ScreenPtr pScreen);
 766
 767 extern _X_EXPORT unsigned long
 768  exaGetPixmapOffset(PixmapPtr pPix);
 769
 770 extern _X_EXPORT unsigned long
 771  exaGetPixmapPitch(PixmapPtr pPix);
 772
 773 extern _X_EXPORT unsigned long
 774  exaGetPixmapSize(PixmapPtr pPix);
 775
 776 extern _X_EXPORT void *exaGetPixmapDriverPrivate(PixmapPtr p);
 777
 778 /* in exa_offscreen.c */
 779 extern _X_EXPORT ExaOffscreenArea *exaOffscreenAlloc(ScreenPtr pScreen,
 780                                                      int size, int align,
 781                                                      Bool locked,
 782                                                      ExaOffscreenSaveProc save,
 783                                                      pointer privData);
 784
 785 extern _X_EXPORT ExaOffscreenArea *exaOffscreenFree(ScreenPtr pScreen,
 786                                                     ExaOffscreenArea * area);
 787
 788 extern _X_EXPORT void
 789  ExaOffscreenMarkUsed(PixmapPtr pPixmap);
 790
 791 extern _X_EXPORT void
 792  exaEnableDisableFBAccess(int index, Bool enable);
 793
 794 extern _X_EXPORT Bool
 795  exaDrawableIsOffscreen(DrawablePtr pDrawable);
 796
 797 /* in exa.c */
 798 extern _X_EXPORT void
 799  exaMoveInPixmap(PixmapPtr pPixmap);
 800
 801 extern _X_EXPORT void
 802  exaMoveOutPixmap(PixmapPtr pPixmap);
 803
 804 /* in exa_unaccel.c */
 805 extern _X_EXPORT CARD32
 806  exaGetPixmapFirstPixel(PixmapPtr pPixmap);
 807
 808 /**
 809  * Returns TRUE if the given planemask covers all the significant bits in the
 810  * pixel values for pDrawable.
 811  */
 812 #define EXA_PM_IS_SOLID(_pDrawable, _pm) \
 813         (((_pm) & FbFullMask((_pDrawable)->depth)) == \
 814          FbFullMask((_pDrawable)->depth))
 815
 816 #endif                          /* EXA_H */