exa.h (33048B)
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 void *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 include 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 void *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 secondary, 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 void *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 */