1 2 /* 3 * Copyright 2006 The Android Open Source Project 4 * 5 * Use of this source code is governed by a BSD-style license that can be 6 * found in the LICENSE file. 7 */ 8 9 10 #ifndef SkCanvas_DEFINED 11 #define SkCanvas_DEFINED 12 13 #include "SkTypes.h" 14 #include "SkBitmap.h" 15 #include "SkDeque.h" 16 #include "SkClipStack.h" 17 #include "SkPaint.h" 18 #include "SkRefCnt.h" 19 #include "SkPath.h" 20 #include "SkRegion.h" 21 #include "SkScalarCompare.h" 22 #include "SkXfermode.h" 23 24 class SkBounder; 25 class SkDevice; 26 class SkDraw; 27 class SkDrawFilter; 28 class SkMetaData; 29 class SkPicture; 30 class SkRRect; 31 class SkSurface_Base; 32 33 #ifdef SK_BUILD_FOR_ANDROID 34 namespace WebCore { 35 class RasterRenderer; 36 class GaneshRenderer; 37 } 38 #endif 39 40 /** \class SkCanvas 41 42 A Canvas encapsulates all of the state about drawing into a device (bitmap). 43 This includes a reference to the device itself, and a stack of matrix/clip 44 values. For any given draw call (e.g. drawRect), the geometry of the object 45 being drawn is transformed by the concatenation of all the matrices in the 46 stack. The transformed geometry is clipped by the intersection of all of 47 the clips in the stack. 48 49 While the Canvas holds the state of the drawing device, the state (style) 50 of the object being drawn is held by the Paint, which is provided as a 51 parameter to each of the draw() methods. The Paint holds attributes such as 52 color, typeface, textSize, strokeWidth, shader (e.g. gradients, patterns), 53 etc. 54 */ 55 class SK_API SkCanvas : public SkRefCnt { 56 public: 57 SK_DECLARE_INST_COUNT(SkCanvas) 58 59 SkCanvas(); 60 61 /** Construct a canvas with the specified device to draw into. 62 63 @param device Specifies a device for the canvas to draw into. 64 */ 65 explicit SkCanvas(SkDevice* device); 66 67 /** Deprecated - Construct a canvas with the specified bitmap to draw into. 68 @param bitmap Specifies a bitmap for the canvas to draw into. Its 69 structure are copied to the canvas. 70 */ 71 explicit SkCanvas(const SkBitmap& bitmap); 72 virtual ~SkCanvas(); 73 74 SkMetaData& getMetaData(); 75 76 /////////////////////////////////////////////////////////////////////////// 77 78 /** 79 * Trigger the immediate execution of all pending draw operations. 80 */ 81 void flush(); 82 83 /** 84 * Return the width/height of the underlying device. The current drawable 85 * area may be small (due to clipping or saveLayer). For a canvas with 86 * no device, 0,0 will be returned. 87 */ 88 SkISize getDeviceSize() const; 89 90 /** Return the canvas' device object, which may be null. The device holds 91 the bitmap of the pixels that the canvas draws into. The reference count 92 of the returned device is not changed by this call. 93 */ 94 SkDevice* getDevice() const; 95 96 /** 97 * saveLayer() can create another device (which is later drawn onto 98 * the previous device). getTopDevice() returns the top-most device current 99 * installed. Note that this can change on other calls like save/restore, 100 * so do not access this device after subsequent canvas calls. 101 * The reference count of the device is not changed. 102 * 103 * @param updateMatrixClip If this is true, then before the device is 104 * returned, we ensure that its has been notified about the current 105 * matrix and clip. Note: this happens automatically when the device 106 * is drawn to, but is optional here, as there is a small perf hit 107 * sometimes. 108 */ 109 SkDevice* getTopDevice(bool updateMatrixClip = false) const; 110 111 /** 112 * Shortcut for getDevice()->createCompatibleDevice(...). 113 * If getDevice() == NULL, this method does nothing, and returns NULL. 114 */ 115 SkDevice* createCompatibleDevice(SkBitmap::Config config, 116 int width, int height, 117 bool isOpaque); 118 119 /////////////////////////////////////////////////////////////////////////// 120 121 /** 122 * This enum can be used with read/writePixels to perform a pixel ops to or 123 * from an 8888 config other than Skia's native config (SkPMColor). There 124 * are three byte orders supported: native, BGRA, and RGBA. Each has a 125 * premultiplied and unpremultiplied variant. 126 * 127 * Components of a 8888 pixel can be packed/unpacked from a 32bit word using 128 * either byte offsets or shift values. Byte offsets are endian-invariant 129 * while shifts are not. BGRA and RGBA configs are defined by byte 130 * orderings. The native config is defined by shift values (SK_A32_SHIFT, 131 * ..., SK_B32_SHIFT). 132 */ 133 enum Config8888 { 134 /** 135 * Skia's native order specified by: 136 * SK_A32_SHIFT, SK_R32_SHIFT, SK_G32_SHIFT, and SK_B32_SHIFT 137 * 138 * kNative_Premul_Config8888 is equivalent to SkPMColor 139 * kNative_Unpremul_Config8888 has the same component order as SkPMColor 140 * but is not premultiplied. 141 */ 142 kNative_Premul_Config8888, 143 kNative_Unpremul_Config8888, 144 /** 145 * low byte to high byte: B, G, R, A. 146 */ 147 kBGRA_Premul_Config8888, 148 kBGRA_Unpremul_Config8888, 149 /** 150 * low byte to high byte: R, G, B, A. 151 */ 152 kRGBA_Premul_Config8888, 153 kRGBA_Unpremul_Config8888 154 }; 155 156 /** 157 * On success (returns true), copy the canvas pixels into the bitmap. 158 * On failure, the bitmap parameter is left unchanged and false is 159 * returned. 160 * 161 * The canvas' pixels are converted to the bitmap's config. The only 162 * supported config is kARGB_8888_Config, though this is likely to be 163 * relaxed in the future. The meaning of config kARGB_8888_Config is 164 * modified by the enum param config8888. The default value interprets 165 * kARGB_8888_Config as SkPMColor 166 * 167 * If the bitmap has pixels already allocated, the canvas pixels will be 168 * written there. If not, bitmap->allocPixels() will be called 169 * automatically. If the bitmap is backed by a texture readPixels will 170 * fail. 171 * 172 * The actual pixels written is the intersection of the canvas' bounds, and 173 * the rectangle formed by the bitmap's width,height and the specified x,y. 174 * If bitmap pixels extend outside of that intersection, they will not be 175 * modified. 176 * 177 * Other failure conditions: 178 * * If the canvas is backed by a non-raster device (e.g. PDF) then 179 * readPixels will fail. 180 * * If bitmap is texture-backed then readPixels will fail. (This may be 181 * relaxed in the future.) 182 * 183 * Example that reads the entire canvas into a bitmap using the native 184 * SkPMColor: 185 * SkISize size = canvas->getDeviceSize(); 186 * bitmap->setConfig(SkBitmap::kARGB_8888_Config, size.fWidth, 187 * size.fHeight); 188 * if (canvas->readPixels(bitmap, 0, 0)) { 189 * // use the pixels 190 * } 191 */ 192 bool readPixels(SkBitmap* bitmap, 193 int x, int y, 194 Config8888 config8888 = kNative_Premul_Config8888); 195 196 /** 197 * DEPRECATED: This will be removed as soon as webkit is no longer relying 198 * on it. The bitmap is resized to the intersection of srcRect and the 199 * canvas bounds. New pixels are always allocated on success. Bitmap is 200 * unmodified on failure. 201 */ 202 bool readPixels(const SkIRect& srcRect, SkBitmap* bitmap); 203 204 /** 205 * Similar to draw sprite, this method will copy the pixels in bitmap onto 206 * the canvas, with the top/left corner specified by (x, y). The canvas' 207 * pixel values are completely replaced: there is no blending. 208 * 209 * Currently if bitmap is backed by a texture this is a no-op. This may be 210 * relaxed in the future. 211 * 212 * If the bitmap has config kARGB_8888_Config then the config8888 param 213 * will determines how the pixel valuess are intepreted. If the bitmap is 214 * not kARGB_8888_Config then this parameter is ignored. 215 * 216 * Note: If you are recording drawing commands on this canvas to 217 * SkPicture, writePixels() is ignored! 218 */ 219 void writePixels(const SkBitmap& bitmap, 220 int x, int y, 221 Config8888 config8888 = kNative_Premul_Config8888); 222 223 /////////////////////////////////////////////////////////////////////////// 224 225 enum SaveFlags { 226 /** save the matrix state, restoring it on restore() */ 227 kMatrix_SaveFlag = 0x01, 228 /** save the clip state, restoring it on restore() */ 229 kClip_SaveFlag = 0x02, 230 /** the layer needs to support per-pixel alpha */ 231 kHasAlphaLayer_SaveFlag = 0x04, 232 /** the layer needs to support 8-bits per color component */ 233 kFullColorLayer_SaveFlag = 0x08, 234 /** the layer should clip against the bounds argument */ 235 kClipToLayer_SaveFlag = 0x10, 236 237 // helper masks for common choices 238 kMatrixClip_SaveFlag = 0x03, 239 kARGB_NoClipLayer_SaveFlag = 0x0F, 240 kARGB_ClipLayer_SaveFlag = 0x1F 241 }; 242 243 /** This call saves the current matrix, clip, and drawFilter, and pushes a 244 copy onto a private stack. Subsequent calls to translate, scale, 245 rotate, skew, concat or clipRect, clipPath, and setDrawFilter all 246 operate on this copy. 247 When the balancing call to restore() is made, the previous matrix, clip, 248 and drawFilter are restored. 249 @return The value to pass to restoreToCount() to balance this save() 250 */ 251 virtual int save(SaveFlags flags = kMatrixClip_SaveFlag); 252 253 /** This behaves the same as save(), but in addition it allocates an 254 offscreen bitmap. All drawing calls are directed there, and only when 255 the balancing call to restore() is made is that offscreen transfered to 256 the canvas (or the previous layer). 257 @param bounds (may be null) This rect, if non-null, is used as a hint to 258 limit the size of the offscreen, and thus drawing may be 259 clipped to it, though that clipping is not guaranteed to 260 happen. If exact clipping is desired, use clipRect(). 261 @param paint (may be null) This is copied, and is applied to the 262 offscreen when restore() is called 263 @param flags LayerFlags 264 @return The value to pass to restoreToCount() to balance this save() 265 */ 266 virtual int saveLayer(const SkRect* bounds, const SkPaint* paint, 267 SaveFlags flags = kARGB_ClipLayer_SaveFlag); 268 269 /** This behaves the same as save(), but in addition it allocates an 270 offscreen bitmap. All drawing calls are directed there, and only when 271 the balancing call to restore() is made is that offscreen transfered to 272 the canvas (or the previous layer). 273 @param bounds (may be null) This rect, if non-null, is used as a hint to 274 limit the size of the offscreen, and thus drawing may be 275 clipped to it, though that clipping is not guaranteed to 276 happen. If exact clipping is desired, use clipRect(). 277 @param alpha This is applied to the offscreen when restore() is called. 278 @param flags LayerFlags 279 @return The value to pass to restoreToCount() to balance this save() 280 */ 281 int saveLayerAlpha(const SkRect* bounds, U8CPU alpha, 282 SaveFlags flags = kARGB_ClipLayer_SaveFlag); 283 284 /** This call balances a previous call to save(), and is used to remove all 285 modifications to the matrix/clip/drawFilter state since the last save 286 call. 287 It is an error to call restore() more times than save() was called. 288 */ 289 virtual void restore(); 290 291 /** Returns the number of matrix/clip states on the SkCanvas' private stack. 292 This will equal # save() calls - # restore() calls. 293 */ 294 int getSaveCount() const; 295 296 /** Efficient way to pop any calls to save() that happened after the save 297 count reached saveCount. It is an error for saveCount to be less than 298 getSaveCount() 299 @param saveCount The number of save() levels to restore from 300 */ 301 void restoreToCount(int saveCount); 302 303 /** Returns true if drawing is currently going to a layer (from saveLayer) 304 * rather than to the root device. 305 */ 306 virtual bool isDrawingToLayer() const; 307 308 /** Preconcat the current matrix with the specified translation 309 @param dx The distance to translate in X 310 @param dy The distance to translate in Y 311 returns true if the operation succeeded (e.g. did not overflow) 312 */ 313 virtual bool translate(SkScalar dx, SkScalar dy); 314 315 /** Preconcat the current matrix with the specified scale. 316 @param sx The amount to scale in X 317 @param sy The amount to scale in Y 318 returns true if the operation succeeded (e.g. did not overflow) 319 */ 320 virtual bool scale(SkScalar sx, SkScalar sy); 321 322 /** Preconcat the current matrix with the specified rotation. 323 @param degrees The amount to rotate, in degrees 324 returns true if the operation succeeded (e.g. did not overflow) 325 */ 326 virtual bool rotate(SkScalar degrees); 327 328 /** Preconcat the current matrix with the specified skew. 329 @param sx The amount to skew in X 330 @param sy The amount to skew in Y 331 returns true if the operation succeeded (e.g. did not overflow) 332 */ 333 virtual bool skew(SkScalar sx, SkScalar sy); 334 335 /** Preconcat the current matrix with the specified matrix. 336 @param matrix The matrix to preconcatenate with the current matrix 337 @return true if the operation succeeded (e.g. did not overflow) 338 */ 339 virtual bool concat(const SkMatrix& matrix); 340 341 /** Replace the current matrix with a copy of the specified matrix. 342 @param matrix The matrix that will be copied into the current matrix. 343 */ 344 virtual void setMatrix(const SkMatrix& matrix); 345 346 /** Helper for setMatrix(identity). Sets the current matrix to identity. 347 */ 348 void resetMatrix(); 349 350 /** 351 * Modify the current clip with the specified rectangle. 352 * @param rect The rect to combine with the current clip 353 * @param op The region op to apply to the current clip 354 * @param doAntiAlias true if the clip should be antialiased 355 * @return true if the canvas' clip is non-empty 356 */ 357 virtual bool clipRect(const SkRect& rect, 358 SkRegion::Op op = SkRegion::kIntersect_Op, 359 bool doAntiAlias = false); 360 361 /** 362 * Modify the current clip with the specified SkRRect. 363 * @param rrect The rrect to combine with the current clip 364 * @param op The region op to apply to the current clip 365 * @param doAntiAlias true if the clip should be antialiased 366 * @return true if the canvas' clip is non-empty 367 */ 368 virtual bool clipRRect(const SkRRect& rrect, 369 SkRegion::Op op = SkRegion::kIntersect_Op, 370 bool doAntiAlias = false); 371 372 /** 373 * Modify the current clip with the specified path. 374 * @param path The path to combine with the current clip 375 * @param op The region op to apply to the current clip 376 * @param doAntiAlias true if the clip should be antialiased 377 * @return true if the canvas' new clip is non-empty 378 */ 379 virtual bool clipPath(const SkPath& path, 380 SkRegion::Op op = SkRegion::kIntersect_Op, 381 bool doAntiAlias = false); 382 383 /** EXPERIMENTAL -- only used for testing 384 Set to false to force clips to be hard, even if doAntiAlias=true is 385 passed to clipRect or clipPath. 386 */ 387 void setAllowSoftClip(bool allow) { 388 fAllowSoftClip = allow; 389 } 390 391 /** Modify the current clip with the specified region. Note that unlike 392 clipRect() and clipPath() which transform their arguments by the current 393 matrix, clipRegion() assumes its argument is already in device 394 coordinates, and so no transformation is performed. 395 @param deviceRgn The region to apply to the current clip 396 @param op The region op to apply to the current clip 397 @return true if the canvas' new clip is non-empty 398 */ 399 virtual bool clipRegion(const SkRegion& deviceRgn, 400 SkRegion::Op op = SkRegion::kIntersect_Op); 401 402 /** Helper for clipRegion(rgn, kReplace_Op). Sets the current clip to the 403 specified region. This does not intersect or in any other way account 404 for the existing clip region. 405 @param deviceRgn The region to copy into the current clip. 406 @return true if the new clip region is non-empty 407 */ 408 bool setClipRegion(const SkRegion& deviceRgn) { 409 return this->clipRegion(deviceRgn, SkRegion::kReplace_Op); 410 } 411 412 /** Return true if the specified rectangle, after being transformed by the 413 current matrix, would lie completely outside of the current clip. Call 414 this to check if an area you intend to draw into is clipped out (and 415 therefore you can skip making the draw calls). 416 @param rect the rect to compare with the current clip 417 @return true if the rect (transformed by the canvas' matrix) does not 418 intersect with the canvas' clip 419 */ 420 bool quickReject(const SkRect& rect) const; 421 422 /** Return true if the specified path, after being transformed by the 423 current matrix, would lie completely outside of the current clip. Call 424 this to check if an area you intend to draw into is clipped out (and 425 therefore you can skip making the draw calls). Note, for speed it may 426 return false even if the path itself might not intersect the clip 427 (i.e. the bounds of the path intersects, but the path does not). 428 @param path The path to compare with the current clip 429 @return true if the path (transformed by the canvas' matrix) does not 430 intersect with the canvas' clip 431 */ 432 bool quickReject(const SkPath& path) const; 433 434 /** Return true if the horizontal band specified by top and bottom is 435 completely clipped out. This is a conservative calculation, meaning 436 that it is possible that if the method returns false, the band may still 437 in fact be clipped out, but the converse is not true. If this method 438 returns true, then the band is guaranteed to be clipped out. 439 @param top The top of the horizontal band to compare with the clip 440 @param bottom The bottom of the horizontal and to compare with the clip 441 @return true if the horizontal band is completely clipped out (i.e. does 442 not intersect the current clip) 443 */ 444 bool quickRejectY(SkScalar top, SkScalar bottom) const { 445 SkASSERT(SkScalarToCompareType(top) <= SkScalarToCompareType(bottom)); 446 const SkRectCompareType& clipR = this->getLocalClipBoundsCompareType(); 447 // In the case where the clip is empty and we are provided with a 448 // negative top and positive bottom parameter then this test will return 449 // false even though it will be clipped. We have chosen to exclude that 450 // check as it is rare and would result double the comparisons. 451 return SkScalarToCompareType(top) >= clipR.fBottom 452 || SkScalarToCompareType(bottom) <= clipR.fTop; 453 } 454 455 /** Return the bounds of the current clip (in local coordinates) in the 456 bounds parameter, and return true if it is non-empty. This can be useful 457 in a way similar to quickReject, in that it tells you that drawing 458 outside of these bounds will be clipped out. 459 */ 460 bool getClipBounds(SkRect* bounds) const; 461 462 /** Return the bounds of the current clip, in device coordinates; returns 463 true if non-empty. Maybe faster than getting the clip explicitly and 464 then taking its bounds. 465 */ 466 bool getClipDeviceBounds(SkIRect* bounds) const; 467 468 469 /** Fill the entire canvas' bitmap (restricted to the current clip) with the 470 specified ARGB color, using the specified mode. 471 @param a the alpha component (0..255) of the color to fill the canvas 472 @param r the red component (0..255) of the color to fill the canvas 473 @param g the green component (0..255) of the color to fill the canvas 474 @param b the blue component (0..255) of the color to fill the canvas 475 @param mode the mode to apply the color in (defaults to SrcOver) 476 */ 477 void drawARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b, 478 SkXfermode::Mode mode = SkXfermode::kSrcOver_Mode); 479 480 /** Fill the entire canvas' bitmap (restricted to the current clip) with the 481 specified color and mode. 482 @param color the color to draw with 483 @param mode the mode to apply the color in (defaults to SrcOver) 484 */ 485 void drawColor(SkColor color, 486 SkXfermode::Mode mode = SkXfermode::kSrcOver_Mode); 487 488 /** 489 * This erases the entire drawing surface to the specified color, 490 * irrespective of the clip. It does not blend with the previous pixels, 491 * but always overwrites them. 492 * 493 * It is roughly equivalent to the following: 494 * canvas.save(); 495 * canvas.clipRect(hugeRect, kReplace_Op); 496 * paint.setColor(color); 497 * paint.setXfermodeMode(kSrc_Mode); 498 * canvas.drawPaint(paint); 499 * canvas.restore(); 500 * though it is almost always much more efficient. 501 */ 502 virtual void clear(SkColor); 503 504 /** 505 * Fill the entire canvas' bitmap (restricted to the current clip) with the 506 * specified paint. 507 * @param paint The paint used to fill the canvas 508 */ 509 virtual void drawPaint(const SkPaint& paint); 510 511 enum PointMode { 512 /** drawPoints draws each point separately */ 513 kPoints_PointMode, 514 /** drawPoints draws each pair of points as a line segment */ 515 kLines_PointMode, 516 /** drawPoints draws the array of points as a polygon */ 517 kPolygon_PointMode 518 }; 519 520 /** Draw a series of points, interpreted based on the PointMode mode. For 521 all modes, the count parameter is interpreted as the total number of 522 points. For kLine mode, count/2 line segments are drawn. 523 For kPoint mode, each point is drawn centered at its coordinate, and its 524 size is specified by the paint's stroke-width. It draws as a square, 525 unless the paint's cap-type is round, in which the points are drawn as 526 circles. 527 For kLine mode, each pair of points is drawn as a line segment, 528 respecting the paint's settings for cap/join/width. 529 For kPolygon mode, the entire array is drawn as a series of connected 530 line segments. 531 Note that, while similar, kLine and kPolygon modes draw slightly 532 differently than the equivalent path built with a series of moveto, 533 lineto calls, in that the path will draw all of its contours at once, 534 with no interactions if contours intersect each other (think XOR 535 xfermode). drawPoints always draws each element one at a time. 536 @param mode PointMode specifying how to draw the array of points. 537 @param count The number of points in the array 538 @param pts Array of points to draw 539 @param paint The paint used to draw the points 540 */ 541 virtual void drawPoints(PointMode mode, size_t count, const SkPoint pts[], 542 const SkPaint& paint); 543 544 /** Helper method for drawing a single point. See drawPoints() for a more 545 details. 546 */ 547 void drawPoint(SkScalar x, SkScalar y, const SkPaint& paint); 548 549 /** Draws a single pixel in the specified color. 550 @param x The X coordinate of which pixel to draw 551 @param y The Y coordiante of which pixel to draw 552 @param color The color to draw 553 */ 554 void drawPoint(SkScalar x, SkScalar y, SkColor color); 555 556 /** Draw a line segment with the specified start and stop x,y coordinates, 557 using the specified paint. NOTE: since a line is always "framed", the 558 paint's Style is ignored. 559 @param x0 The x-coordinate of the start point of the line 560 @param y0 The y-coordinate of the start point of the line 561 @param x1 The x-coordinate of the end point of the line 562 @param y1 The y-coordinate of the end point of the line 563 @param paint The paint used to draw the line 564 */ 565 void drawLine(SkScalar x0, SkScalar y0, SkScalar x1, SkScalar y1, 566 const SkPaint& paint); 567 568 /** Draw the specified rectangle using the specified paint. The rectangle 569 will be filled or stroked based on the Style in the paint. 570 @param rect The rect to be drawn 571 @param paint The paint used to draw the rect 572 */ 573 virtual void drawRect(const SkRect& rect, const SkPaint& paint); 574 575 /** Draw the specified rectangle using the specified paint. The rectangle 576 will be filled or framed based on the Style in the paint. 577 @param rect The rect to be drawn 578 @param paint The paint used to draw the rect 579 */ 580 void drawIRect(const SkIRect& rect, const SkPaint& paint) 581 { 582 SkRect r; 583 r.set(rect); // promotes the ints to scalars 584 this->drawRect(r, paint); 585 } 586 587 /** Draw the specified rectangle using the specified paint. The rectangle 588 will be filled or framed based on the Style in the paint. 589 @param left The left side of the rectangle to be drawn 590 @param top The top side of the rectangle to be drawn 591 @param right The right side of the rectangle to be drawn 592 @param bottom The bottom side of the rectangle to be drawn 593 @param paint The paint used to draw the rect 594 */ 595 void drawRectCoords(SkScalar left, SkScalar top, SkScalar right, 596 SkScalar bottom, const SkPaint& paint); 597 598 /** Draw the specified oval using the specified paint. The oval will be 599 filled or framed based on the Style in the paint. 600 @param oval The rectangle bounds of the oval to be drawn 601 @param paint The paint used to draw the oval 602 */ 603 virtual void drawOval(const SkRect& oval, const SkPaint&); 604 605 /** 606 * Draw the specified RRect using the specified paint The rrect will be filled or stroked 607 * based on the Style in the paint. 608 * 609 * @param rrect The round-rect to draw 610 * @param paint The paint used to draw the round-rect 611 */ 612 virtual void drawRRect(const SkRRect& rrect, const SkPaint& paint); 613 614 /** Draw the specified circle using the specified paint. If radius is <= 0, 615 then nothing will be drawn. The circle will be filled 616 or framed based on the Style in the paint. 617 @param cx The x-coordinate of the center of the cirle to be drawn 618 @param cy The y-coordinate of the center of the cirle to be drawn 619 @param radius The radius of the cirle to be drawn 620 @param paint The paint used to draw the circle 621 */ 622 void drawCircle(SkScalar cx, SkScalar cy, SkScalar radius, 623 const SkPaint& paint); 624 625 /** Draw the specified arc, which will be scaled to fit inside the 626 specified oval. If the sweep angle is >= 360, then the oval is drawn 627 completely. Note that this differs slightly from SkPath::arcTo, which 628 treats the sweep angle mod 360. 629 @param oval The bounds of oval used to define the shape of the arc 630 @param startAngle Starting angle (in degrees) where the arc begins 631 @param sweepAngle Sweep angle (in degrees) measured clockwise 632 @param useCenter true means include the center of the oval. For filling 633 this will draw a wedge. False means just use the arc. 634 @param paint The paint used to draw the arc 635 */ 636 void drawArc(const SkRect& oval, SkScalar startAngle, SkScalar sweepAngle, 637 bool useCenter, const SkPaint& paint); 638 639 /** Draw the specified round-rect using the specified paint. The round-rect 640 will be filled or framed based on the Style in the paint. 641 @param rect The rectangular bounds of the roundRect to be drawn 642 @param rx The x-radius of the oval used to round the corners 643 @param ry The y-radius of the oval used to round the corners 644 @param paint The paint used to draw the roundRect 645 */ 646 void drawRoundRect(const SkRect& rect, SkScalar rx, SkScalar ry, 647 const SkPaint& paint); 648 649 /** Draw the specified path using the specified paint. The path will be 650 filled or framed based on the Style in the paint. 651 @param path The path to be drawn 652 @param paint The paint used to draw the path 653 */ 654 virtual void drawPath(const SkPath& path, const SkPaint& paint); 655 656 /** Draw the specified bitmap, with its top/left corner at (x,y), using the 657 specified paint, transformed by the current matrix. Note: if the paint 658 contains a maskfilter that generates a mask which extends beyond the 659 bitmap's original width/height, then the bitmap will be drawn as if it 660 were in a Shader with CLAMP mode. Thus the color outside of the original 661 width/height will be the edge color replicated. 662 @param bitmap The bitmap to be drawn 663 @param left The position of the left side of the bitmap being drawn 664 @param top The position of the top side of the bitmap being drawn 665 @param paint The paint used to draw the bitmap, or NULL 666 */ 667 virtual void drawBitmap(const SkBitmap& bitmap, SkScalar left, SkScalar top, 668 const SkPaint* paint = NULL); 669 670 /** Draw the specified bitmap, with the specified matrix applied (before the 671 canvas' matrix is applied). 672 @param bitmap The bitmap to be drawn 673 @param src Optional: specify the subset of the bitmap to be drawn 674 @param dst The destination rectangle where the scaled/translated 675 image will be drawn 676 @param paint The paint used to draw the bitmap, or NULL 677 */ 678 virtual void drawBitmapRectToRect(const SkBitmap& bitmap, const SkRect* src, 679 const SkRect& dst, 680 const SkPaint* paint); 681 682 void drawBitmapRect(const SkBitmap& bitmap, const SkRect& dst, 683 const SkPaint* paint) { 684 this->drawBitmapRectToRect(bitmap, NULL, dst, paint); 685 } 686 687 void drawBitmapRect(const SkBitmap& bitmap, const SkIRect* isrc, 688 const SkRect& dst, const SkPaint* paint = NULL) { 689 SkRect realSrcStorage; 690 SkRect* realSrcPtr = NULL; 691 if (isrc) { 692 realSrcStorage.set(*isrc); 693 realSrcPtr = &realSrcStorage; 694 } 695 this->drawBitmapRectToRect(bitmap, realSrcPtr, dst, paint); 696 } 697 698 virtual void drawBitmapMatrix(const SkBitmap& bitmap, const SkMatrix& m, 699 const SkPaint* paint = NULL); 700 701 /** 702 * Draw the bitmap stretched differentially to fit into dst. 703 * center is a rect within the bitmap, and logically divides the bitmap 704 * into 9 sections (3x3). For example, if the middle pixel of a [5x5] 705 * bitmap is the "center", then the center-rect should be [2, 2, 3, 3]. 706 * 707 * If the dst is >= the bitmap size, then... 708 * - The 4 corners are not stretch at all. 709 * - The sides are stretch in only one axis. 710 * - The center is stretch in both axes. 711 * Else, for each axis where dst < bitmap, 712 * - The corners shrink proportionally 713 * - The sides (along the shrink axis) and center are not drawn 714 */ 715 virtual void drawBitmapNine(const SkBitmap& bitmap, const SkIRect& center, 716 const SkRect& dst, const SkPaint* paint = NULL); 717 718 /** Draw the specified bitmap, with its top/left corner at (x,y), 719 NOT transformed by the current matrix. Note: if the paint 720 contains a maskfilter that generates a mask which extends beyond the 721 bitmap's original width/height, then the bitmap will be drawn as if it 722 were in a Shader with CLAMP mode. Thus the color outside of the original 723 width/height will be the edge color replicated. 724 @param bitmap The bitmap to be drawn 725 @param left The position of the left side of the bitmap being drawn 726 @param top The position of the top side of the bitmap being drawn 727 @param paint The paint used to draw the bitmap, or NULL 728 */ 729 virtual void drawSprite(const SkBitmap& bitmap, int left, int top, 730 const SkPaint* paint = NULL); 731 732 /** Draw the text, with origin at (x,y), using the specified paint. 733 The origin is interpreted based on the Align setting in the paint. 734 @param text The text to be drawn 735 @param byteLength The number of bytes to read from the text parameter 736 @param x The x-coordinate of the origin of the text being drawn 737 @param y The y-coordinate of the origin of the text being drawn 738 @param paint The paint used for the text (e.g. color, size, style) 739 */ 740 virtual void drawText(const void* text, size_t byteLength, SkScalar x, 741 SkScalar y, const SkPaint& paint); 742 743 /** Draw the text, with each character/glyph origin specified by the pos[] 744 array. The origin is interpreted by the Align setting in the paint. 745 @param text The text to be drawn 746 @param byteLength The number of bytes to read from the text parameter 747 @param pos Array of positions, used to position each character 748 @param paint The paint used for the text (e.g. color, size, style) 749 */ 750 virtual void drawPosText(const void* text, size_t byteLength, 751 const SkPoint pos[], const SkPaint& paint); 752 753 /** Draw the text, with each character/glyph origin specified by the x 754 coordinate taken from the xpos[] array, and the y from the constY param. 755 The origin is interpreted by the Align setting in the paint. 756 @param text The text to be drawn 757 @param byteLength The number of bytes to read from the text parameter 758 @param xpos Array of x-positions, used to position each character 759 @param constY The shared Y coordinate for all of the positions 760 @param paint The paint used for the text (e.g. color, size, style) 761 */ 762 virtual void drawPosTextH(const void* text, size_t byteLength, 763 const SkScalar xpos[], SkScalar constY, 764 const SkPaint& paint); 765 766 /** Draw the text, with origin at (x,y), using the specified paint, along 767 the specified path. The paint's Align setting determins where along the 768 path to start the text. 769 @param text The text to be drawn 770 @param byteLength The number of bytes to read from the text parameter 771 @param path The path the text should follow for its baseline 772 @param hOffset The distance along the path to add to the text's 773 starting position 774 @param vOffset The distance above(-) or below(+) the path to 775 position the text 776 @param paint The paint used for the text 777 */ 778 void drawTextOnPathHV(const void* text, size_t byteLength, 779 const SkPath& path, SkScalar hOffset, 780 SkScalar vOffset, const SkPaint& paint); 781 782 /** Draw the text, with origin at (x,y), using the specified paint, along 783 the specified path. The paint's Align setting determins where along the 784 path to start the text. 785 @param text The text to be drawn 786 @param byteLength The number of bytes to read from the text parameter 787 @param path The path the text should follow for its baseline 788 @param matrix (may be null) Applied to the text before it is 789 mapped onto the path 790 @param paint The paint used for the text 791 */ 792 virtual void drawTextOnPath(const void* text, size_t byteLength, 793 const SkPath& path, const SkMatrix* matrix, 794 const SkPaint& paint); 795 796 #ifdef SK_BUILD_FOR_ANDROID 797 /** Draw the text on path, with each character/glyph origin specified by the pos[] 798 array. The origin is interpreted by the Align setting in the paint. 799 @param text The text to be drawn 800 @param byteLength The number of bytes to read from the text parameter 801 @param pos Array of positions, used to position each character 802 @param paint The paint used for the text (e.g. color, size, style) 803 @param path The path to draw on 804 @param matrix The canvas matrix 805 */ 806 void drawPosTextOnPath(const void* text, size_t byteLength, 807 const SkPoint pos[], const SkPaint& paint, 808 const SkPath& path, const SkMatrix* matrix); 809 #endif 810 811 /** Draw the picture into this canvas. This method effective brackets the 812 playback of the picture's draw calls with save/restore, so the state 813 of this canvas will be unchanged after this call. 814 @param picture The recorded drawing commands to playback into this 815 canvas. 816 */ 817 virtual void drawPicture(SkPicture& picture); 818 819 enum VertexMode { 820 kTriangles_VertexMode, 821 kTriangleStrip_VertexMode, 822 kTriangleFan_VertexMode 823 }; 824 825 /** Draw the array of vertices, interpreted as triangles (based on mode). 826 @param vmode How to interpret the array of vertices 827 @param vertexCount The number of points in the vertices array (and 828 corresponding texs and colors arrays if non-null) 829 @param vertices Array of vertices for the mesh 830 @param texs May be null. If not null, specifies the coordinate 831 in texture space for each vertex. 832 @param colors May be null. If not null, specifies a color for each 833 vertex, to be interpolated across the triangle. 834 @param xmode Used if both texs and colors are present. In this 835 case the colors are combined with the texture using mode, 836 before being drawn using the paint. If mode is null, then 837 kModulate_Mode is used. 838 @param indices If not null, array of indices to reference into the 839 vertex (texs, colors) array. 840 @param indexCount number of entries in the indices array (if not null) 841 @param paint Specifies the shader/texture if present. 842 */ 843 virtual void drawVertices(VertexMode vmode, int vertexCount, 844 const SkPoint vertices[], const SkPoint texs[], 845 const SkColor colors[], SkXfermode* xmode, 846 const uint16_t indices[], int indexCount, 847 const SkPaint& paint); 848 849 /** Send a blob of data to the canvas. 850 For canvases that draw, this call is effectively a no-op, as the data 851 is not parsed, but just ignored. However, this call exists for 852 subclasses like SkPicture's recording canvas, that can store the data 853 and then play it back later (via another call to drawData). 854 */ 855 virtual void drawData(const void* data, size_t length); 856 857 ////////////////////////////////////////////////////////////////////////// 858 859 /** Get the current bounder object. 860 The bounder's reference count is unchaged. 861 @return the canva's bounder (or NULL). 862 */ 863 SkBounder* getBounder() const { return fBounder; } 864 865 /** Set a new bounder (or NULL). 866 Pass NULL to clear any previous bounder. 867 As a convenience, the parameter passed is also returned. 868 If a previous bounder exists, its reference count is decremented. 869 If bounder is not NULL, its reference count is incremented. 870 @param bounder the new bounder (or NULL) to be installed in the canvas 871 @return the set bounder object 872 */ 873 virtual SkBounder* setBounder(SkBounder* bounder); 874 875 /** Get the current filter object. The filter's reference count is not 876 affected. The filter is saved/restored, just like the matrix and clip. 877 @return the canvas' filter (or NULL). 878 */ 879 SkDrawFilter* getDrawFilter() const; 880 881 /** Set the new filter (or NULL). Pass NULL to clear any existing filter. 882 As a convenience, the parameter is returned. If an existing filter 883 exists, its refcnt is decrement. If the new filter is not null, its 884 refcnt is incremented. The filter is saved/restored, just like the 885 matrix and clip. 886 @param filter the new filter (or NULL) 887 @return the new filter 888 */ 889 virtual SkDrawFilter* setDrawFilter(SkDrawFilter* filter); 890 891 ////////////////////////////////////////////////////////////////////////// 892 893 /** Return the current matrix on the canvas. 894 This does not account for the translate in any of the devices. 895 @return The current matrix on the canvas. 896 */ 897 const SkMatrix& getTotalMatrix() const; 898 899 enum ClipType { 900 kEmpty_ClipType = 0, 901 kRect_ClipType, 902 kComplex_ClipType 903 }; 904 905 /** Returns a description of the total clip; may be cheaper than 906 getting the clip and querying it directly. 907 */ 908 ClipType getClipType() const; 909 910 /** Return the current device clip (concatenation of all clip calls). 911 * This does not account for the translate in any of the devices. 912 * @return the current device clip (concatenation of all clip calls). 913 * 914 * DEPRECATED -- call getClipDeviceBounds() instead. 915 */ 916 const SkRegion& getTotalClip() const; 917 918 /** Return the clip stack. The clip stack stores all the individual 919 * clips organized by the save/restore frame in which they were 920 * added. 921 * @return the current clip stack ("list" of individual clip elements) 922 */ 923 const SkClipStack* getClipStack() const { 924 return &fClipStack; 925 } 926 927 class ClipVisitor { 928 public: 929 virtual ~ClipVisitor(); 930 virtual void clipRect(const SkRect&, SkRegion::Op, bool antialias) = 0; 931 virtual void clipPath(const SkPath&, SkRegion::Op, bool antialias) = 0; 932 }; 933 934 /** 935 * Replays the clip operations, back to front, that have been applied to 936 * the canvas, calling the appropriate method on the visitor for each 937 * clip. All clips have already been transformed into device space. 938 */ 939 void replayClips(ClipVisitor*) const; 940 941 /////////////////////////////////////////////////////////////////////////// 942 943 /** After calling saveLayer(), there can be any number of devices that make 944 up the top-most drawing area. LayerIter can be used to iterate through 945 those devices. Note that the iterator is only valid until the next API 946 call made on the canvas. Ownership of all pointers in the iterator stays 947 with the canvas, so none of them should be modified or deleted. 948 */ 949 class SK_API LayerIter /*: SkNoncopyable*/ { 950 public: 951 /** Initialize iterator with canvas, and set values for 1st device */ 952 LayerIter(SkCanvas*, bool skipEmptyClips); 953 ~LayerIter(); 954 955 /** Return true if the iterator is done */ 956 bool done() const { return fDone; } 957 /** Cycle to the next device */ 958 void next(); 959 960 // These reflect the current device in the iterator 961 962 SkDevice* device() const; 963 const SkMatrix& matrix() const; 964 const SkRegion& clip() const; 965 const SkPaint& paint() const; 966 int x() const; 967 int y() const; 968 969 private: 970 // used to embed the SkDrawIter object directly in our instance, w/o 971 // having to expose that class def to the public. There is an assert 972 // in our constructor to ensure that fStorage is large enough 973 // (though needs to be a compile-time-assert!). We use intptr_t to work 974 // safely with 32 and 64 bit machines (to ensure the storage is enough) 975 intptr_t fStorage[32]; 976 class SkDrawIter* fImpl; // this points at fStorage 977 SkPaint fDefaultPaint; 978 bool fDone; 979 }; 980 981 protected: 982 // Returns the canvas to be used by DrawIter. Default implementation 983 // returns this. Subclasses that encapsulate an indirect canvas may 984 // need to overload this method. The impl must keep track of this, as it 985 // is not released or deleted by the caller. 986 virtual SkCanvas* canvasForDrawIter(); 987 988 // all of the drawBitmap variants call this guy 989 void commonDrawBitmap(const SkBitmap&, const SkIRect*, const SkMatrix&, 990 const SkPaint& paint); 991 992 // Clip rectangle bounds. Called internally by saveLayer. 993 // returns false if the entire rectangle is entirely clipped out 994 bool clipRectBounds(const SkRect* bounds, SaveFlags flags, 995 SkIRect* intersection); 996 997 // notify our surface (if we have one) that we are about to draw, so it 998 // can perform copy-on-write or invalidate any cached images 999 void predrawNotify(); 1000 1001 /** DEPRECATED -- use constructor(device) 1002 1003 Marked as 'protected' to avoid new clients using this before we can 1004 completely remove it. 1005 1006 Specify a device for this canvas to draw into. If it is not null, its 1007 reference count is incremented. If the canvas was already holding a 1008 device, its reference count is decremented. The new device is returned. 1009 */ 1010 virtual SkDevice* setDevice(SkDevice* device); 1011 1012 #ifdef SK_BUILD_FOR_ANDROID 1013 friend class WebCore::GaneshRenderer; 1014 friend class WebCore::RasterRenderer; 1015 #endif 1016 1017 private: 1018 class MCRec; 1019 1020 SkClipStack fClipStack; 1021 SkDeque fMCStack; 1022 // points to top of stack 1023 MCRec* fMCRec; 1024 // the first N recs that can fit here mean we won't call malloc 1025 uint32_t fMCRecStorage[32]; 1026 1027 SkBounder* fBounder; 1028 int fSaveLayerCount; // number of successful saveLayer calls 1029 1030 SkMetaData* fMetaData; 1031 1032 SkSurface_Base* fSurfaceBase; 1033 SkSurface_Base* getSurfaceBase() const { return fSurfaceBase; } 1034 void setSurfaceBase(SkSurface_Base* sb) { 1035 fSurfaceBase = sb; 1036 } 1037 friend class SkSurface_Base; 1038 1039 bool fDeviceCMDirty; // cleared by updateDeviceCMCache() 1040 void updateDeviceCMCache(); 1041 1042 friend class SkDrawIter; // needs setupDrawForLayerDevice() 1043 friend class AutoDrawLooper; 1044 1045 SkDevice* createLayerDevice(SkBitmap::Config, int width, int height, 1046 bool isOpaque); 1047 1048 SkDevice* init(SkDevice*); 1049 1050 // internal methods are not virtual, so they can safely be called by other 1051 // canvas apis, without confusing subclasses (like SkPictureRecording) 1052 void internalDrawBitmap(const SkBitmap&, const SkIRect*, const SkMatrix& m, 1053 const SkPaint* paint); 1054 void internalDrawBitmapRect(const SkBitmap& bitmap, const SkRect* src, 1055 const SkRect& dst, const SkPaint* paint); 1056 void internalDrawBitmapNine(const SkBitmap& bitmap, const SkIRect& center, 1057 const SkRect& dst, const SkPaint* paint); 1058 void internalDrawPaint(const SkPaint& paint); 1059 int internalSaveLayer(const SkRect* bounds, const SkPaint* paint, 1060 SaveFlags, bool justForImageFilter); 1061 void internalDrawDevice(SkDevice*, int x, int y, const SkPaint*); 1062 1063 // shared by save() and saveLayer() 1064 int internalSave(SaveFlags flags); 1065 void internalRestore(); 1066 static void DrawRect(const SkDraw& draw, const SkPaint& paint, 1067 const SkRect& r, SkScalar textSize); 1068 static void DrawTextDecorations(const SkDraw& draw, const SkPaint& paint, 1069 const char text[], size_t byteLength, 1070 SkScalar x, SkScalar y); 1071 1072 /* These maintain a cache of the clip bounds in local coordinates, 1073 (converted to 2s-compliment if floats are slow). 1074 */ 1075 mutable SkRectCompareType fLocalBoundsCompareType; 1076 mutable bool fLocalBoundsCompareTypeDirty; 1077 bool fAllowSoftClip; 1078 1079 const SkRectCompareType& getLocalClipBoundsCompareType() const { 1080 if (fLocalBoundsCompareTypeDirty) { 1081 this->computeLocalClipBoundsCompareType(); 1082 fLocalBoundsCompareTypeDirty = false; 1083 } 1084 return fLocalBoundsCompareType; 1085 } 1086 void computeLocalClipBoundsCompareType() const; 1087 1088 class AutoValidateClip : ::SkNoncopyable { 1089 public: 1090 explicit AutoValidateClip(SkCanvas* canvas) : fCanvas(canvas) { 1091 fCanvas->validateClip(); 1092 } 1093 ~AutoValidateClip() { fCanvas->validateClip(); } 1094 1095 private: 1096 const SkCanvas* fCanvas; 1097 }; 1098 1099 #ifdef SK_DEBUG 1100 void validateClip() const; 1101 #else 1102 void validateClip() const {} 1103 #endif 1104 1105 typedef SkRefCnt INHERITED; 1106 }; 1107 1108 /** Stack helper class to automatically call restoreToCount() on the canvas 1109 when this object goes out of scope. Use this to guarantee that the canvas 1110 is restored to a known state. 1111 */ 1112 class SkAutoCanvasRestore : SkNoncopyable { 1113 public: 1114 SkAutoCanvasRestore(SkCanvas* canvas, bool doSave) : fCanvas(canvas) { 1115 SkASSERT(canvas); 1116 fSaveCount = canvas->getSaveCount(); 1117 if (doSave) { 1118 canvas->save(); 1119 } 1120 } 1121 ~SkAutoCanvasRestore() { 1122 if (fCanvas) { 1123 fCanvas->restoreToCount(fSaveCount); 1124 } 1125 } 1126 1127 /** 1128 * Perform the restore now, instead of waiting for the destructor. Will 1129 * only do this once. 1130 */ 1131 void restore() { 1132 if (fCanvas) { 1133 fCanvas->restoreToCount(fSaveCount); 1134 fCanvas = NULL; 1135 } 1136 } 1137 1138 private: 1139 SkCanvas* fCanvas; 1140 int fSaveCount; 1141 }; 1142 1143 #endif 1144
