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, uxa_access_t access); 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 /** @name UXA CreatePixmap hint flags 548 * @{ 549 */ 550 /** 551 * Flag to hint that the first operation on the pixmap will be a 552 * prepare_access. 553 */ 554 #define UXA_CREATE_PIXMAP_FOR_MAP 0x20000000 555 /** @} */ 556 557 uxa_driver_t *uxa_driver_alloc(void); 558 559 Bool uxa_driver_init(ScreenPtr screen, uxa_driver_t * uxa_driver); 560 Bool uxa_resources_init(ScreenPtr screen); 561 562 void uxa_driver_fini(ScreenPtr pScreen); 563 564 CARD32 uxa_get_pixmap_first_pixel(PixmapPtr pPixmap); 565 566 Bool 567 uxa_get_color_for_pixmap (PixmapPtr pixmap, 568 CARD32 src_format, 569 CARD32 dst_format, 570 CARD32 *pixel); 571 572 void uxa_set_fallback_debug(ScreenPtr screen, Bool enable); 573 void uxa_set_force_fallback(ScreenPtr screen, Bool enable); 574 575 /** 576 * Returns TRUE if the given planemask covers all the significant bits in the 577 * pixel values for pDrawable. 578 */ 579 #define UXA_PM_IS_SOLID(_pDrawable, _pm) \ 580 (((_pm) & FbFullMask((_pDrawable)->depth)) == \ 581 FbFullMask((_pDrawable)->depth)) 582 583 #endif /* UXA_H */ 584