uxa/uxa.h

   1 /*
   2  * Copyright © 2000, 2008 Keith Packard
   3  *             2004 Eric Anholt
   4  *             2005 Zack Rusin
   5  *
   6  * Permission to use, copy, modify, distribute, and sell this software and its
   7  * documentation for any purpose is hereby granted without fee, provided that
   8  * the above copyright notice appear in all copies and that both that
   9  * copyright notice and this permission notice appear in supporting
  10  * documentation, and that the name of copyright holders not be used in
  11  * advertising or publicity pertaining to distribution of the software without
  12  * specific, written prior permission. Copyright holders make no
  13  * representations about the suitability of this software for any purpose.  It
  14  * is provided "as is" without express or implied warranty.
  15  *
  16  * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
  17  * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  18  * FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
  19  * SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  20  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
  21  * AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
  22  * OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
  23  * SOFTWARE.
  24  */
  25
  26 /** @file
  27  * UXA - the unified memory acceleration architecture.
  28  *
  29  * This is the header containing the public API of UXA for uxa drivers.
  30  */
  31
  32 #ifndef UXA_H
  33 #define UXA_H
  34
  35 #include "scrnintstr.h"
  36 #include "pixmapstr.h"
  37 #include "windowstr.h"
  38 #include "gcstruct.h"
  39 #include "picturestr.h"
  40 #include "fb.h"
  41
  42 #define UXA_VERSION_MAJOR   1
  43 #define UXA_VERSION_MINOR   0
  44 #define UXA_VERSION_RELEASE 0
  45
  46 typedef enum {
  47         UXA_ACCESS_RO,
  48         UXA_ACCESS_RW
  49 } uxa_access_t;
  50
  51 /**
  52  * The UxaDriver structure is allocated through uxa_driver_alloc(), and then
  53  * fllled in by drivers.
  54  */
  55 typedef struct _UxaDriver {
  56         /**
  57          * uxa_major and uxa_minor should be set by the driver to the version of
  58          * UXA which the driver was compiled for (or configures itself at
  59          * runtime to support).  This allows UXA to extend the structure for
  60          * new features without breaking ABI for drivers compiled against
  61          * older versions.
  62          */
  63         int uxa_major, uxa_minor;
  64
  65         /**
  66          * The flags field is bitfield of boolean values controlling UXA's
  67          * behavior.
  68          *
  69          * The flags include UXA_TWO_BITBLT_DIRECTIONS.
  70          */
  71         int flags;
  72
  73         /** @name solid
  74          * @{
  75          */
  76         /**
  77          * check_solid() checks whether the driver can do a solid fill to this drawable.
  78          * @param pDrawable Destination drawable
  79          * @param alu raster operation
  80          * @param planemask write mask for the fill
  81          *
  82          * The check_solid() call is recommended if prepare_solid() is
  83          * implemented, but is not required.
  84          */
  85         Bool(*check_solid) (DrawablePtr pDrawable, int alu, Pixel planemask);
  86
  87         /**
  88          * prepare_solid() sets up the driver for doing a solid fill.
  89          * @param pPixmap Destination pixmap
  90          * @param alu raster operation
  91          * @param planemask write mask for the fill
  92          * @param fg "foreground" color for the fill
  93          *
  94          * This call should set up the driver for doing a series of solid fills
  95          * through the solid() call.  The alu raster op is one of the GX*
  96          * graphics functions listed in X.h, and typically maps to a similar
  97          * single-byte "ROP" setting in all hardware.  The planemask controls
  98          * which bits of the destination should be affected, and will only
  99          * represent the bits up to the depth of pPixmap.  The fg is the pixel
 100          * value of the foreground color referred to in ROP descriptions.
 101          *
 102          * Note that many drivers will need to store some of the data in the
 103          * driver private record, for sending to the hardware with each
 104          * drawing command.
 105          *
 106          * The prepare_solid() call is required of all drivers, but it may fail
 107          * for any reason.  Failure results in a fallback to software rendering.
 108          */
 109         Bool(*prepare_solid) (PixmapPtr pPixmap,
 110                               int alu, Pixel planemask, Pixel fg);
 111
 112         /**
 113          * solid() performs a solid fill set up in the last prepare_solid()
 114          * call.
 115          *
 116          * @param pPixmap destination pixmap
 117          * @param x1 left coordinate
 118          * @param y1 top coordinate
 119          * @param x2 right coordinate
 120          * @param y2 bottom coordinate
 121          *
 122          * Performs the fill set up by the last prepare_solid() call,
 123          * covering the area from (x1,y1) to (x2,y2) in pPixmap.  Note that
 124          * the coordinates are in the coordinate space of the destination
 125          * pixmap, so the driver will need to set up the hardware's offset
 126          * and pitch for the destination coordinates according to the pixmap's
 127          * offset and pitch within framebuffer.
 128          *
 129          * This call is required if prepare_solid() ever succeeds.
 130          */
 131         void (*solid) (PixmapPtr pPixmap, int x1, int y1, int x2, int y2);
 132
 133         /**
 134          * done_solid() finishes a set of solid fills.
 135          *
 136          * @param pPixmap destination pixmap.
 137          *
 138          * The done_solid() call is called at the end of a series of consecutive
 139          * solid() calls following a successful prepare_solid().  This allows
 140          * drivers to finish up emitting drawing commands that were buffered, or
 141          * clean up state from prepare_solid().
 142          *
 143          * This call is required if prepare_solid() ever succeeds.
 144          */
 145         void (*done_solid) (PixmapPtr pPixmap);
 146         /** @} */
 147
 148         /** @name copy
 149          * @{
 150          */
 151         /**
 152          * check_copy() checks whether the driver can blit between the two Pictures
 153          */
 154         Bool(*check_copy) (PixmapPtr pSrc, PixmapPtr pDst, int alu, Pixel planemask);
 155         /**
 156          * prepare_copy() sets up the driver for doing a copy within video
 157          * memory.
 158          -     *
 159          * @param pSrcPixmap source pixmap
 160          * @param pDstPixmap destination pixmap
 161          * @param dx X copy direction
 162          * @param dy Y copy direction
 163          * @param alu raster operation
 164          * @param planemask write mask for the fill
 165          *
 166          * This call should set up the driver for doing a series of copies
 167          * from the pSrcPixmap to the pDstPixmap.  The dx flag will be
 168          * positive if the
 169          * hardware should do the copy from the left to the right, and dy will
 170          * be positive if the copy should be done from the top to the bottom.
 171          * This is to deal with self-overlapping copies when
 172          * pSrcPixmap == pDstPixmap.
 173          *
 174          * If your hardware can only support blits that are (left to right,
 175          * top to bottom) or (right to left, bottom to top), then you should
 176          * set #UXA_TWO_BITBLT_DIRECTIONS, and UXA will break down copy
 177          * operations to ones that meet those requirements.  The alu raster
 178          * op is one of the GX* graphics functions listed in X.h, and
 179          * typically maps to a similar single-byte "ROP" setting in all
 180          * hardware.  The planemask controls which bits of the destination
 181          * should be affected, and will only represent the bits up to the
 182          * depth of pPixmap.
 183          *
 184          * Note that many drivers will need to store some of the data in the
 185          * driver private record, for sending to the hardware with each
 186          * drawing command.
 187          *
 188          * The prepare_copy() call is required of all drivers, but it may fail
 189          * for any reason.  Failure results in a fallback to software rendering.
 190          */
 191         Bool(*prepare_copy) (PixmapPtr pSrcPixmap,
 192                              PixmapPtr pDstPixmap,
 193                              int dx, int dy, int alu, Pixel planemask);
 194
 195         /**
 196          * copy() performs a copy set up in the last prepare_copy call.
 197          *
 198          * @param pDstPixmap destination pixmap
 199          * @param srcX source X coordinate
 200          * @param srcY source Y coordinate
 201          * @param dstX destination X coordinate
 202          * @param dstY destination Y coordinate
 203          * @param width width of the rectangle to be copied
 204          * @param height height of the rectangle to be copied.
 205          *
 206          * Performs the copy set up by the last prepare_copy() call, copying the
 207          * rectangle from (srcX, srcY) to (srcX + width, srcY + width) in the
 208          * source pixmap to the same-sized rectangle at (dstX, dstY) in the
 209          * destination pixmap.  Those rectangles may overlap in memory, if
 210          * pSrcPixmap == pDstPixmap.  Note that this call does not receive the
 211          * pSrcPixmap as an argument -- if it's needed in this function, it
 212          * should be stored in the driver private during prepare_copy().  As
 213          * with solid(), the coordinates are in the coordinate space of each
 214          * pixmap, so the driver will need to set up source and destination
 215          * pitches and offsets from those pixmaps, probably using
 216          * uxaGetPixmapOffset() and uxa_get_pixmap_pitch().
 217          *
 218          * This call is required if prepare_copy ever succeeds.
 219          */
 220         void (*copy) (PixmapPtr pDstPixmap,
 221                       int srcX,
 222                       int srcY, int dstX, int dstY, int width, int height);
 223
 224         /**
 225          * done_copy() finishes a set of copies.
 226          *
 227          * @param pPixmap destination pixmap.
 228          *
 229          * The done_copy() call is called at the end of a series of consecutive
 230          * copy() calls following a successful prepare_copy().  This allows
 231          * drivers to finish up emitting drawing commands that were buffered,
 232          * or clean up state from prepare_copy().
 233          *
 234          * This call is required if prepare_copy() ever succeeds.
 235          */
 236         void (*done_copy) (PixmapPtr pDstPixmap);
 237         /** @} */
 238
 239         /** @name composite
 240          * @{
 241          */
 242         /**
 243          * check_composite() checks to see if a composite operation could be
 244          * accelerated.
 245          *
 246          * @param op Render operation
 247          * @param pSrcPicture source Picture
 248          * @param pMaskPicture mask picture
 249          * @param pDstPicture destination Picture
 250          * @param width The width of the composite operation
 251          * @param height The height of the composite operation
 252          *
 253          * The check_composite() call checks if the driver could handle
 254          * acceleration of op with the given source, mask, and destination
 255          * pictures.  This allows drivers to check source and destination
 256          * formats, supported operations, transformations, and component
 257          * alpha state, and send operations it can't support to software
 258          * rendering early on.
 259          *
 260          * See prepare_composite() for more details on likely issues that
 261          * drivers will have in accelerating composite operations.
 262          *
 263          * The check_composite() call is recommended if prepare_composite() is
 264          * implemented, but is not required.
 265          */
 266         Bool(*check_composite) (int op,
 267                                 PicturePtr pSrcPicture,
 268                                 PicturePtr pMaskPicture,
 269                                 PicturePtr pDstPicture,
 270                                 int width, int height);
 271
 272         /**
 273          * check_composite_target() checks to see if the destination of the composite
 274          * operation can be used without midification.
 275          *
 276          * @param pixmap Destination Pixmap
 277          *
 278          * The check_composite_target() call is recommended if prepare_composite() is
 279          * implemented, but is not required.
 280          */
 281         Bool(*check_composite_target) (PixmapPtr pixmap);
 282
 283         /**
 284          * check_composite_texture() checks to see if a source to the composite
 285          * operation can be used without midification.
 286          *
 287          * @param pScreen Screen
 288          * @param pPicture Picture
 289          *
 290          * The check_composite_texture() call is recommended if prepare_composite() is
 291          * implemented, but is not required.
 292          */
 293         Bool(*check_composite_texture) (ScreenPtr pScreen,
 294                                         PicturePtr pPicture);
 295
 296         /**
 297          * prepare_composite() sets up the driver for doing a composite
 298          * operation described in the Render extension protocol spec.
 299          *
 300          * @param op Render operation
 301          * @param pSrcPicture source Picture
 302          * @param pMaskPicture mask picture
 303          * @param pDstPicture destination Picture
 304          * @param pSrc source pixmap
 305          * @param pMask mask pixmap
 306          * @param pDst destination pixmap
 307          *
 308          * This call should set up the driver for doing a series of composite
 309          * operations, as described in the Render protocol spec, with the given
 310          * pSrcPicture, pMaskPicture, and pDstPicture.  The pSrc, pMask, and
 311          * pDst are the pixmaps containing the pixel data, and should be used
 312          * for setting the offset and pitch used for the coordinate spaces for
 313          * each of the Pictures.
 314          *
 315          * Notes on interpreting Picture structures:
 316          * - The Picture structures will always have a valid pDrawable.
 317          * - The Picture structures will never have alphaMap set.
 318          * - The mask Picture (and therefore pMask) may be NULL, in which case
 319          *   the operation is simply src OP dst instead of src IN mask OP dst,
 320          *   and mask coordinates should be ignored.
 321          * - pMarkPicture may have componentAlpha set, which greatly changes
 322          *   the behavior of the composite operation.  componentAlpha has no
 323          *   effect when set on pSrcPicture or pDstPicture.
 324          * - The source and mask Pictures may have a transformation set
 325          *   (Picture->transform != NULL), which means that the source
 326          *   coordinates should be transformed by that transformation,
 327          *   resulting in scaling, rotation, etc.  The PictureTransformPoint()
 328          *   call can transform coordinates for you.  Transforms have no
 329          *   effect on Pictures when used as a destination.
 330          * - The source and mask pictures may have a filter set.
 331          *   PictFilterNearest and PictFilterBilinear are defined in the
 332          *   Render protocol, but others may be encountered, and must be
 333          *   handled correctly (usually by prepare_composite failing, and
 334          *   falling back to software).  Filters have
 335          *   no effect on Pictures when used as a destination.
 336          * - The source and mask Pictures may have repeating set, which must be
 337          *   respected.  Many chipsets will be unable to support repeating on
 338          *   pixmaps that have a width or height that is not a power of two.
 339          *
 340          * If your hardware can't support source pictures (textures) with
 341          * non-power-of-two pitches, you should set #UXA_OFFSCREEN_ALIGN_POT.
 342          *
 343          * Note that many drivers will need to store some of the data in the
 344          * driver private record, for sending to the hardware with each
 345          * drawing command.
 346          *
 347          * The prepare_composite() call is not required.  However, it is highly
 348          * recommended for performance of antialiased font rendering and
 349          * performance of cairo applications.  Failure results in a fallback
 350          * to software rendering.
 351          */
 352         Bool(*prepare_composite) (int op,
 353                                   PicturePtr pSrcPicture,
 354                                   PicturePtr pMaskPicture,
 355                                   PicturePtr pDstPicture,
 356                                   PixmapPtr pSrc,
 357                                   PixmapPtr pMask, PixmapPtr pDst);
 358
 359         /**
 360          * composite() performs a composite operation set up in the last
 361          * prepare_composite() call.
 362          *
 363          * @param pDstPixmap destination pixmap
 364          * @param srcX source X coordinate
 365          * @param srcY source Y coordinate
 366          * @param maskX source X coordinate
 367          * @param maskY source Y coordinate
 368          * @param dstX destination X coordinate
 369          * @param dstY destination Y coordinate
 370          * @param width destination rectangle width
 371          * @param height destination rectangle height
 372          *
 373          * Performs the composite operation set up by the last
 374          * prepare_composite() call, to the rectangle from (dstX, dstY) to
 375          * (dstX + width, dstY + height) in the destination Pixmap.  Note that
 376          * if a transformation was set on the source or mask Pictures, the
 377          * source rectangles may not be the same size as the destination
 378          * rectangles and filtering.  Getting the coordinate transformation
 379          * right at the subpixel level can be tricky, and rendercheck
 380          * can test this for you.
 381          *
 382          * This call is required if prepare_composite() ever succeeds.
 383          */
 384         void (*composite) (PixmapPtr pDst,
 385                            int srcX,
 386                            int srcY,
 387                            int maskX,
 388                            int maskY,
 389                            int dstX, int dstY, int width, int height);
 390
 391         /**
 392          * done_composite() finishes a set of composite operations.
 393          *
 394          * @param pPixmap destination pixmap.
 395          *
 396          * The done_composite() call is called at the end of a series of
 397          * consecutive composite() calls following a successful
 398          * prepare_composite().  This allows drivers to finish up emitting
 399          * drawing commands that were buffered, or clean up state from
 400          * prepare_composite().
 401          *
 402          * This call is required if prepare_composite() ever succeeds.
 403          */
 404         void (*done_composite) (PixmapPtr pDst);
 405         /** @} */
 406
 407         /**
 408          * put_image() loads a rectangle of data from src into pDst.
 409          *
 410          * @param pDst destination pixmap
 411          * @param x destination X coordinate.
 412          * @param y destination Y coordinate
 413          * @param width width of the rectangle to be copied
 414          * @param height height of the rectangle to be copied
 415          * @param src pointer to the beginning of the source data
 416          * @param src_pitch pitch (in bytes) of the lines of source data.
 417          *
 418          * put_image() copies data in system memory beginning at src (with
 419          * pitch src_pitch) into the destination pixmap from (x, y) to
 420          * (x + width, y + height).  This is typically done with hostdata
 421          * uploads, where the CPU sets up a blit command on the hardware with
 422          * instructions that the blit data will be fed through some sort of
 423          * aperture on the card.
 424          *
 425          * put_image() is most important for the performance of uxa_glyphs()
 426          * (antialiased font drawing) by allowing pipelining of data uploads,
 427          * avoiding a sync of the card after each glyph.
 428          *
 429          * @return TRUE if the driver successfully uploaded the data.  FALSE
 430          * indicates that UXA should fall back to doing the upload in software.
 431          *
 432          * put_image() is not required, but is recommended if composite
 433          * acceleration is supported.
 434          */
 435         Bool(*put_image) (PixmapPtr pDst,
 436                           int x,
 437                           int y, int w, int h, char *src, int src_pitch);
 438
 439         /**
 440          * get_image() loads a rectangle of data from pSrc into dst
 441          *
 442          * @param pSrc source pixmap
 443          * @param x source X coordinate.
 444          * @param y source Y coordinate
 445          * @param width width of the rectangle to be copied
 446          * @param height height of the rectangle to be copied
 447          * @param dst pointer to the beginning of the destination data
 448          * @param dst_pitch pitch (in bytes) of the lines of destination data.
 449          *
 450          * get_image() copies data from offscreen memory in pSrc from
 451          * (x, y) to (x + width, y + height), to system memory starting at
 452          * dst (with pitch dst_pitch).  This would usually be done
 453          * using scatter-gather DMA, supported by a DRM call, or by blitting
 454          * to AGP and then synchronously reading from AGP.
 455          *
 456          * @return TRUE if the driver successfully downloaded the data.  FALSE
 457          * indicates that UXA should fall back to doing the download in
 458          * software.
 459          *
 460          * get_image() is not required, but is highly recommended.
 461          */
 462         Bool(*get_image) (PixmapPtr pSrc,
 463                           int x, int y,
 464                           int w, int h, char *dst, int dst_pitch);
 465
 466         /** @{ */
 467         /**
 468          * prepare_access() is called before CPU access to an offscreen pixmap.
 469          *
 470          * @param pPix the pixmap being accessed
 471          * @param index the index of the pixmap being accessed.
 472          *
 473          * prepare_access() will be called before CPU access to an offscreen
 474          * pixmap.
 475          *
 476          * This can be used to set up hardware surfaces for byteswapping or
 477          * untiling, or to adjust the pixmap's devPrivate.ptr for the purpose of
 478          * making CPU access use a different aperture.
 479          *
 480          * The index is one of #UXA_PREPARE_DEST, #UXA_PREPARE_SRC, or
 481          * #UXA_PREPARE_MASK, indicating which pixmap is in question.  Since
 482          * only up to three pixmaps will have prepare_access() called on them
 483          * per operation, drivers can have a small, statically-allocated space
 484          * to maintain state for prepare_access() and finish_access() in.
 485          * Note that the same pixmap may have prepare_access() called on it
 486          * more than once, for uxample when doing a copy within the same
 487          * pixmap (so it gets prepare_access as
 488          * #UXA_PREPARE_DEST and then as #UXA_PREPARE_SRC).
 489          *
 490          * prepare_access() may fail.  An example might be the case of
 491          * hardware that can set up 1 or 2 surfaces for CPU access, but not
 492          * 3.  If prepare_access()
 493          * fails, UXA will migrate the pixmap to system memory.
 494          * get_image() must be implemented and must not fail if a driver
 495          * wishes to fail in prepare_access().  prepare_access() must not
 496          * fail when pPix is the visible screen, because the visible screen
 497          * can not be migrated.
 498          *
 499          * @return TRUE if prepare_access() successfully prepared the pixmap
 500          * for CPU drawing.
 501          * @return FALSE if prepare_access() is unsuccessful and UXA should use
 502          * get_image() to migate the pixmap out.
 503          */
 504         Bool(*prepare_access) (PixmapPtr pPix, uxa_access_t access);
 505
 506         /**
 507          * finish_access() is called after CPU access to an offscreen pixmap.
 508          *
 509          * @param pPix the pixmap being accessed
 510          * @param index the index of the pixmap being accessed.
 511          *
 512          * finish_access() will be called after finishing CPU access of an
 513          * offscreen pixmap set up by prepare_access().  Note that the
 514          * finish_access() will not be called if prepare_access() failed.
 515          */
 516         void (*finish_access) (PixmapPtr pPix);
 517
 518         /**
 519          * PixmapIsOffscreen() is an optional driver replacement to
 520          * uxa_pixmap_is_offscreen(). Set to NULL if you want the standard
 521          * behaviour of uxa_pixmap_is_offscreen().
 522          *
 523          * @param pPix the pixmap
 524          * @return TRUE if the given drawable is in framebuffer memory.
 525          *
 526          * uxa_pixmap_is_offscreen() is used to determine if a pixmap is in
 527          * offscreen memory, meaning that acceleration could probably be done
 528          * to it, and that it will need to be wrapped by
 529          * prepare_access()/finish_access() when accessing it with the CPU.
 530          */
 531         Bool(*pixmap_is_offscreen) (PixmapPtr pPix);
 532
 533         /** @} */
 534 } uxa_driver_t;
 535
 536 /** @name UXA driver flags
 537  * @{
 538  */
 539 /**
 540  * UXA_TWO_BITBLT_DIRECTIONS indicates to UXA that the driver can only
 541  * support copies that are (left-to-right, top-to-bottom) or
 542  * (right-to-left, bottom-to-top).
 543  */
 544 #define UXA_TWO_BITBLT_DIRECTIONS       (1 << 2)
 545
 546 /** @} */
 547
 548 /** @name UXA CreatePixmap hint flags
 549  * @{
 550  */
 551 /**
 552  * Flag to hint that the first operation on the pixmap will be a
 553  * prepare_access.
 554  */
 555 #define UXA_CREATE_PIXMAP_FOR_MAP       0x20000000
 556 /** @} */
 557
 558 uxa_driver_t *uxa_driver_alloc(void);
 559
 560 Bool uxa_driver_init(ScreenPtr screen, uxa_driver_t * uxa_driver);
 561 Bool uxa_resources_init(ScreenPtr screen);
 562
 563 void uxa_driver_fini(ScreenPtr pScreen);
 564
 565 CARD32 uxa_get_pixmap_first_pixel(PixmapPtr pPixmap);
 566
 567 Bool
 568 uxa_get_color_for_pixmap (PixmapPtr      pixmap,
 569                           CARD32         src_format,
 570                           CARD32         dst_format,
 571                           CARD32        *pixel);
 572
 573 void uxa_set_fallback_debug(ScreenPtr screen, Bool enable);
 574 void uxa_set_force_fallback(ScreenPtr screen, Bool enable);
 575
 576 /**
 577  * Returns TRUE if the given planemask covers all the significant bits in the
 578  * pixel values for pDrawable.
 579  */
 580 #define UXA_PM_IS_SOLID(_pDrawable, _pm) \
 581         (((_pm) & FbFullMask((_pDrawable)->depth)) == \
 582          FbFullMask((_pDrawable)->depth))
 583
 584 #endif /* UXA_H */