| 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 6 |
| 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 | Bool (*SharePixmapBacking)(PixmapPtr pPixmap, ScreenPtr slave, void **handle_p); |
| 698 | |
| 699 | Bool (*SetSharedPixmapBacking)(PixmapPtr pPixmap, void *handle); |
| 700 | |
| 701 | } ExaDriverRec, *ExaDriverPtr; |
| 702 | |
| 703 | /** @name EXA driver flags |
| 704 | * @{ |
| 705 | */ |
| 706 | /** |
| 707 | * EXA_OFFSCREEN_PIXMAPS indicates to EXA that the driver can support |
| 708 | * offscreen pixmaps. |
| 709 | */ |
| 710 | #define EXA_OFFSCREEN_PIXMAPS (1 << 0) |
| 711 | |
| 712 | /** |
| 713 | * EXA_OFFSCREEN_ALIGN_POT indicates to EXA that the driver needs pixmaps |
| 714 | * to have a power-of-two pitch. |
| 715 | */ |
| 716 | #define EXA_OFFSCREEN_ALIGN_POT (1 << 1) |
| 717 | |
| 718 | /** |
| 719 | * EXA_TWO_BITBLT_DIRECTIONS indicates to EXA that the driver can only |
| 720 | * support copies that are (left-to-right, top-to-bottom) or |
| 721 | * (right-to-left, bottom-to-top). |
| 722 | */ |
| 723 | #define EXA_TWO_BITBLT_DIRECTIONS (1 << 2) |
| 724 | |
| 725 | /** |
| 726 | * EXA_HANDLES_PIXMAPS indicates to EXA that the driver can handle |
| 727 | * all pixmap addressing and migration. |
| 728 | */ |
| 729 | #define EXA_HANDLES_PIXMAPS (1 << 3) |
| 730 | |
| 731 | /** |
| 732 | * EXA_SUPPORTS_PREPARE_AUX indicates to EXA that the driver can handle the |
| 733 | * EXA_PREPARE_AUX* indices in the Prepare/FinishAccess hooks. If there are no |
| 734 | * such hooks, this flag has no effect. |
| 735 | */ |
| 736 | #define EXA_SUPPORTS_PREPARE_AUX (1 << 4) |
| 737 | |
| 738 | /** |
| 739 | * EXA_SUPPORTS_OFFSCREEN_OVERLAPS indicates to EXA that the driver Copy hooks |
| 740 | * can handle the source and destination occupying overlapping offscreen memory |
| 741 | * areas. This allows the offscreen memory defragmentation code to defragment |
| 742 | * areas where the defragmented position overlaps the fragmented position. |
| 743 | * |
| 744 | * Typically this is supported by traditional 2D engines but not by 3D engines. |
| 745 | */ |
| 746 | #define EXA_SUPPORTS_OFFSCREEN_OVERLAPS (1 << 5) |
| 747 | |
| 748 | /** |
| 749 | * EXA_MIXED_PIXMAPS will hide unacceleratable pixmaps from drivers and manage the |
| 750 | * problem known software fallbacks like trapezoids. This only migrates pixmaps one way |
| 751 | * into a driver pixmap and then pins it. |
| 752 | */ |
| 753 | #define EXA_MIXED_PIXMAPS (1 << 6) |
| 754 | |
| 755 | /** @} */ |
| 756 | |
| 757 | /* in exa.c */ |
| 758 | extern _X_EXPORT ExaDriverPtr exaDriverAlloc(void); |
| 759 | |
| 760 | extern _X_EXPORT Bool |
| 761 | exaDriverInit(ScreenPtr pScreen, ExaDriverPtr pScreenInfo); |
| 762 | |
| 763 | extern _X_EXPORT void |
| 764 | exaDriverFini(ScreenPtr pScreen); |
| 765 | |
| 766 | extern _X_EXPORT void |
| 767 | exaMarkSync(ScreenPtr pScreen); |
| 768 | extern _X_EXPORT void |
| 769 | exaWaitSync(ScreenPtr pScreen); |
| 770 | |
| 771 | extern _X_EXPORT unsigned long |
| 772 | exaGetPixmapOffset(PixmapPtr pPix); |
| 773 | |
| 774 | extern _X_EXPORT unsigned long |
| 775 | exaGetPixmapPitch(PixmapPtr pPix); |
| 776 | |
| 777 | extern _X_EXPORT unsigned long |
| 778 | exaGetPixmapSize(PixmapPtr pPix); |
| 779 | |
| 780 | extern _X_EXPORT void *exaGetPixmapDriverPrivate(PixmapPtr p); |
| 781 | |
| 782 | /* in exa_offscreen.c */ |
| 783 | extern _X_EXPORT ExaOffscreenArea *exaOffscreenAlloc(ScreenPtr pScreen, |
| 784 | int size, int align, |
| 785 | Bool locked, |
| 786 | ExaOffscreenSaveProc save, |
| 787 | pointer privData); |
| 788 | |
| 789 | extern _X_EXPORT ExaOffscreenArea *exaOffscreenFree(ScreenPtr pScreen, |
| 790 | ExaOffscreenArea * area); |
| 791 | |
| 792 | extern _X_EXPORT void |
| 793 | ExaOffscreenMarkUsed(PixmapPtr pPixmap); |
| 794 | |
| 795 | extern _X_EXPORT void |
| 796 | exaEnableDisableFBAccess(ScreenPtr pScreen, Bool enable); |
| 797 | |
| 798 | extern _X_EXPORT Bool |
| 799 | exaDrawableIsOffscreen(DrawablePtr pDrawable); |
| 800 | |
| 801 | /* in exa.c */ |
| 802 | extern _X_EXPORT void |
| 803 | exaMoveInPixmap(PixmapPtr pPixmap); |
| 804 | |
| 805 | extern _X_EXPORT void |
| 806 | exaMoveOutPixmap(PixmapPtr pPixmap); |
| 807 | |
| 808 | /* in exa_unaccel.c */ |
| 809 | extern _X_EXPORT CARD32 |
| 810 | exaGetPixmapFirstPixel(PixmapPtr pPixmap); |
| 811 | |
| 812 | /** |
| 813 | * Returns TRUE if the given planemask covers all the significant bits in the |
| 814 | * pixel values for pDrawable. |
| 815 | */ |
| 816 | #define EXA_PM_IS_SOLID(_pDrawable, _pm) \ |
| 817 | (((_pm) & FbFullMask((_pDrawable)->depth)) == \ |
| 818 | FbFullMask((_pDrawable)->depth)) |
| 819 | |
| 820 | #endif /* EXA_H */ |