SkPaint.h revision e8807f49ed24be3933acf84c9ffa840a03fa43dc
1 2 3/* 4 * Copyright 2006 The Android Open Source Project 5 * 6 * Use of this source code is governed by a BSD-style license that can be 7 * found in the LICENSE file. 8 */ 9 10 11#ifndef SkPaint_DEFINED 12#define SkPaint_DEFINED 13 14#include "SkColor.h" 15#include "SkDrawLooper.h" 16#include "SkMatrix.h" 17#include "SkXfermode.h" 18#ifdef SK_BUILD_FOR_ANDROID 19#include "SkPaintOptionsAndroid.h" 20#endif 21 22class SkAnnotation; 23class SkAutoGlyphCache; 24class SkColorFilter; 25class SkDescriptor; 26struct SkDeviceProperties; 27class SkReadBuffer; 28class SkWriteBuffer; 29struct SkGlyph; 30struct SkRect; 31class SkGlyphCache; 32class SkImageFilter; 33class SkMaskFilter; 34class SkPath; 35class SkPathEffect; 36struct SkPoint; 37class SkRasterizer; 38class SkShader; 39class SkTypeface; 40 41typedef const SkGlyph& (*SkDrawCacheProc)(SkGlyphCache*, const char**, 42 SkFixed x, SkFixed y); 43 44typedef const SkGlyph& (*SkMeasureCacheProc)(SkGlyphCache*, const char**); 45 46#define kBicubicFilterBitmap_Flag kHighQualityFilterBitmap_Flag 47 48/** \class SkPaint 49 50 The SkPaint class holds the style and color information about how to draw 51 geometries, text and bitmaps. 52*/ 53 54class SK_API SkPaint { 55 enum { 56 // DEPRECATED -- use setFilterLevel instead 57 kFilterBitmap_Flag = 0x02, // temporary flag 58 // DEPRECATED -- use setFilterLevel instead 59 kHighQualityFilterBitmap_Flag = 0x4000, // temporary flag 60 // DEPRECATED -- use setFilterLevel instead 61 kHighQualityDownsampleBitmap_Flag = 0x8000, // temporary flag 62 }; 63public: 64 SkPaint(); 65 SkPaint(const SkPaint& paint); 66 ~SkPaint(); 67 68 SkPaint& operator=(const SkPaint&); 69 70 SK_API friend bool operator==(const SkPaint& a, const SkPaint& b); 71 friend bool operator!=(const SkPaint& a, const SkPaint& b) { 72 return !(a == b); 73 } 74 75 void flatten(SkWriteBuffer&) const; 76 void unflatten(SkReadBuffer&); 77 78 /** Restores the paint to its initial settings. 79 */ 80 void reset(); 81 82 /** Specifies the level of hinting to be performed. These names are taken 83 from the Gnome/Cairo names for the same. They are translated into 84 Freetype concepts the same as in cairo-ft-font.c: 85 kNo_Hinting -> FT_LOAD_NO_HINTING 86 kSlight_Hinting -> FT_LOAD_TARGET_LIGHT 87 kNormal_Hinting -> <default, no option> 88 kFull_Hinting -> <same as kNormalHinting, unless we are rendering 89 subpixel glyphs, in which case TARGET_LCD or 90 TARGET_LCD_V is used> 91 */ 92 enum Hinting { 93 kNo_Hinting = 0, 94 kSlight_Hinting = 1, 95 kNormal_Hinting = 2, //!< this is the default 96 kFull_Hinting = 3 97 }; 98 99 Hinting getHinting() const { 100 return static_cast<Hinting>(fHinting); 101 } 102 103 void setHinting(Hinting hintingLevel); 104 105 /** Specifies the bit values that are stored in the paint's flags. 106 */ 107 enum Flags { 108 kAntiAlias_Flag = 0x01, //!< mask to enable antialiasing 109 kDither_Flag = 0x04, //!< mask to enable dithering 110 kUnderlineText_Flag = 0x08, //!< mask to enable underline text 111 kStrikeThruText_Flag = 0x10, //!< mask to enable strike-thru text 112 kFakeBoldText_Flag = 0x20, //!< mask to enable fake-bold text 113 kLinearText_Flag = 0x40, //!< mask to enable linear-text 114 kSubpixelText_Flag = 0x80, //!< mask to enable subpixel text positioning 115 kDevKernText_Flag = 0x100, //!< mask to enable device kerning text 116 kLCDRenderText_Flag = 0x200, //!< mask to enable subpixel glyph renderering 117 kEmbeddedBitmapText_Flag = 0x400, //!< mask to enable embedded bitmap strikes 118 kAutoHinting_Flag = 0x800, //!< mask to force Freetype's autohinter 119 kVerticalText_Flag = 0x1000, 120 kGenA8FromLCD_Flag = 0x2000, // hack for GDI -- do not use if you can help it 121 kDistanceFieldTextTEMP_Flag = 0x4000, //!< TEMPORARY mask to enable distance fields 122 // currently overrides LCD and subpixel rendering 123 // when adding extra flags, note that the fFlags member is specified 124 // with a bit-width and you'll have to expand it. 125 126 kAllFlags = 0xFFFF 127 }; 128 129 /** Return the paint's flags. Use the Flag enum to test flag values. 130 @return the paint's flags (see enums ending in _Flag for bit masks) 131 */ 132 uint32_t getFlags() const { return fFlags; } 133 134 /** Set the paint's flags. Use the Flag enum to specific flag values. 135 @param flags The new flag bits for the paint (see Flags enum) 136 */ 137 void setFlags(uint32_t flags); 138 139 /** Helper for getFlags(), returning true if kAntiAlias_Flag bit is set 140 @return true if the antialias bit is set in the paint's flags. 141 */ 142 bool isAntiAlias() const { 143 return SkToBool(this->getFlags() & kAntiAlias_Flag); 144 } 145 146 /** Helper for setFlags(), setting or clearing the kAntiAlias_Flag bit 147 @param aa true to enable antialiasing, false to disable it 148 */ 149 void setAntiAlias(bool aa); 150 151 /** Helper for getFlags(), returning true if kDither_Flag bit is set 152 @return true if the dithering bit is set in the paint's flags. 153 */ 154 bool isDither() const { 155 return SkToBool(this->getFlags() & kDither_Flag); 156 } 157 158 /** Helper for setFlags(), setting or clearing the kDither_Flag bit 159 @param dither true to enable dithering, false to disable it 160 */ 161 void setDither(bool dither); 162 163 /** Helper for getFlags(), returning true if kLinearText_Flag bit is set 164 @return true if the lineartext bit is set in the paint's flags 165 */ 166 bool isLinearText() const { 167 return SkToBool(this->getFlags() & kLinearText_Flag); 168 } 169 170 /** Helper for setFlags(), setting or clearing the kLinearText_Flag bit 171 @param linearText true to set the linearText bit in the paint's flags, 172 false to clear it. 173 */ 174 void setLinearText(bool linearText); 175 176 /** Helper for getFlags(), returning true if kSubpixelText_Flag bit is set 177 @return true if the lineartext bit is set in the paint's flags 178 */ 179 bool isSubpixelText() const { 180 return SkToBool(this->getFlags() & kSubpixelText_Flag); 181 } 182 183 /** 184 * Helper for setFlags(), setting or clearing the kSubpixelText_Flag. 185 * @param subpixelText true to set the subpixelText bit in the paint's 186 * flags, false to clear it. 187 */ 188 void setSubpixelText(bool subpixelText); 189 190 bool isLCDRenderText() const { 191 return SkToBool(this->getFlags() & kLCDRenderText_Flag); 192 } 193 194 /** 195 * Helper for setFlags(), setting or clearing the kLCDRenderText_Flag. 196 * Note: antialiasing must also be on for lcd rendering 197 * @param lcdText true to set the LCDRenderText bit in the paint's flags, 198 * false to clear it. 199 */ 200 void setLCDRenderText(bool lcdText); 201 202 bool isEmbeddedBitmapText() const { 203 return SkToBool(this->getFlags() & kEmbeddedBitmapText_Flag); 204 } 205 206 /** Helper for setFlags(), setting or clearing the kEmbeddedBitmapText_Flag bit 207 @param useEmbeddedBitmapText true to set the kEmbeddedBitmapText bit in the paint's flags, 208 false to clear it. 209 */ 210 void setEmbeddedBitmapText(bool useEmbeddedBitmapText); 211 212 bool isAutohinted() const { 213 return SkToBool(this->getFlags() & kAutoHinting_Flag); 214 } 215 216 /** Helper for setFlags(), setting or clearing the kAutoHinting_Flag bit 217 @param useAutohinter true to set the kEmbeddedBitmapText bit in the 218 paint's flags, 219 false to clear it. 220 */ 221 void setAutohinted(bool useAutohinter); 222 223 bool isVerticalText() const { 224 return SkToBool(this->getFlags() & kVerticalText_Flag); 225 } 226 227 /** 228 * Helper for setting or clearing the kVerticalText_Flag bit in 229 * setFlags(...). 230 * 231 * If this bit is set, then advances are treated as Y values rather than 232 * X values, and drawText will places its glyphs vertically rather than 233 * horizontally. 234 */ 235 void setVerticalText(bool); 236 237 /** Helper for getFlags(), returning true if kUnderlineText_Flag bit is set 238 @return true if the underlineText bit is set in the paint's flags. 239 */ 240 bool isUnderlineText() const { 241 return SkToBool(this->getFlags() & kUnderlineText_Flag); 242 } 243 244 /** Helper for setFlags(), setting or clearing the kUnderlineText_Flag bit 245 @param underlineText true to set the underlineText bit in the paint's 246 flags, false to clear it. 247 */ 248 void setUnderlineText(bool underlineText); 249 250 /** Helper for getFlags(), returns true if kStrikeThruText_Flag bit is set 251 @return true if the strikeThruText bit is set in the paint's flags. 252 */ 253 bool isStrikeThruText() const { 254 return SkToBool(this->getFlags() & kStrikeThruText_Flag); 255 } 256 257 /** Helper for setFlags(), setting or clearing the kStrikeThruText_Flag bit 258 @param strikeThruText true to set the strikeThruText bit in the 259 paint's flags, false to clear it. 260 */ 261 void setStrikeThruText(bool strikeThruText); 262 263 /** Helper for getFlags(), returns true if kFakeBoldText_Flag bit is set 264 @return true if the kFakeBoldText_Flag bit is set in the paint's flags. 265 */ 266 bool isFakeBoldText() const { 267 return SkToBool(this->getFlags() & kFakeBoldText_Flag); 268 } 269 270 /** Helper for setFlags(), setting or clearing the kFakeBoldText_Flag bit 271 @param fakeBoldText true to set the kFakeBoldText_Flag bit in the paint's 272 flags, false to clear it. 273 */ 274 void setFakeBoldText(bool fakeBoldText); 275 276 /** Helper for getFlags(), returns true if kDevKernText_Flag bit is set 277 @return true if the kernText bit is set in the paint's flags. 278 */ 279 bool isDevKernText() const { 280 return SkToBool(this->getFlags() & kDevKernText_Flag); 281 } 282 283 /** Helper for setFlags(), setting or clearing the kKernText_Flag bit 284 @param kernText true to set the kKernText_Flag bit in the paint's 285 flags, false to clear it. 286 */ 287 void setDevKernText(bool devKernText); 288 289 /** Helper for getFlags(), returns true if kDistanceFieldTextTEMP_Flag bit is set 290 @return true if the distanceFieldText bit is set in the paint's flags. 291 */ 292 bool isDistanceFieldTextTEMP() const { 293 return SkToBool(this->getFlags() & kDistanceFieldTextTEMP_Flag); 294 } 295 296 /** Helper for setFlags(), setting or clearing the kDistanceFieldTextTEMP_Flag bit 297 @param distanceFieldText true to set the kDistanceFieldTextTEMP_Flag bit in the paint's 298 flags, false to clear it. 299 */ 300 void setDistanceFieldTextTEMP(bool distanceFieldText); 301 302 enum FilterLevel { 303 kNone_FilterLevel, 304 kLow_FilterLevel, 305 kMedium_FilterLevel, 306 kHigh_FilterLevel 307 }; 308 309 /** 310 * Return the filter level. This affects the quality (and performance) of 311 * drawing scaled images. 312 */ 313 FilterLevel getFilterLevel() const; 314 315 /** 316 * Set the filter level. This affects the quality (and performance) of 317 * drawing scaled images. 318 */ 319 void setFilterLevel(FilterLevel); 320 321 /** 322 * If the predicate is true, set the filterLevel to Low, else set it to 323 * None. 324 */ 325 SK_ATTR_DEPRECATED("use setFilterLevel") 326 void setFilterBitmap(bool doFilter) { 327 this->setFilterLevel(doFilter ? kLow_FilterLevel : kNone_FilterLevel); 328 } 329 330 /** 331 * Returns true if getFilterLevel() returns anything other than None. 332 */ 333 SK_ATTR_DEPRECATED("use getFilterLevel") 334 bool isFilterBitmap() const { 335 return kNone_FilterLevel != this->getFilterLevel(); 336 } 337 338 /** Styles apply to rect, oval, path, and text. 339 Bitmaps are always drawn in "fill", and lines are always drawn in 340 "stroke". 341 342 Note: strokeandfill implicitly draws the result with 343 SkPath::kWinding_FillType, so if the original path is even-odd, the 344 results may not appear the same as if it was drawn twice, filled and 345 then stroked. 346 */ 347 enum Style { 348 kFill_Style, //!< fill the geometry 349 kStroke_Style, //!< stroke the geometry 350 kStrokeAndFill_Style, //!< fill and stroke the geometry 351 }; 352 enum { 353 kStyleCount = kStrokeAndFill_Style + 1 354 }; 355 356 /** Return the paint's style, used for controlling how primitives' 357 geometries are interpreted (except for drawBitmap, which always assumes 358 kFill_Style). 359 @return the paint's Style 360 */ 361 Style getStyle() const { return (Style)fStyle; } 362 363 /** Set the paint's style, used for controlling how primitives' 364 geometries are interpreted (except for drawBitmap, which always assumes 365 Fill). 366 @param style The new style to set in the paint 367 */ 368 void setStyle(Style style); 369 370 /** Return the paint's color. Note that the color is a 32bit value 371 containing alpha as well as r,g,b. This 32bit value is not 372 premultiplied, meaning that its alpha can be any value, regardless of 373 the values of r,g,b. 374 @return the paint's color (and alpha). 375 */ 376 SkColor getColor() const { return fColor; } 377 378 /** Set the paint's color. Note that the color is a 32bit value containing 379 alpha as well as r,g,b. This 32bit value is not premultiplied, meaning 380 that its alpha can be any value, regardless of the values of r,g,b. 381 @param color The new color (including alpha) to set in the paint. 382 */ 383 void setColor(SkColor color); 384 385 /** Helper to getColor() that just returns the color's alpha value. 386 @return the alpha component of the paint's color. 387 */ 388 uint8_t getAlpha() const { return SkToU8(SkColorGetA(fColor)); } 389 390 /** Helper to setColor(), that only assigns the color's alpha value, 391 leaving its r,g,b values unchanged. 392 @param a set the alpha component (0..255) of the paint's color. 393 */ 394 void setAlpha(U8CPU a); 395 396 /** Helper to setColor(), that takes a,r,g,b and constructs the color value 397 using SkColorSetARGB() 398 @param a The new alpha component (0..255) of the paint's color. 399 @param r The new red component (0..255) of the paint's color. 400 @param g The new green component (0..255) of the paint's color. 401 @param b The new blue component (0..255) of the paint's color. 402 */ 403 void setARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b); 404 405 /** Return the width for stroking. 406 <p /> 407 A value of 0 strokes in hairline mode. 408 Hairlines always draw 1-pixel wide, regardless of the matrix. 409 @return the paint's stroke width, used whenever the paint's style is 410 Stroke or StrokeAndFill. 411 */ 412 SkScalar getStrokeWidth() const { return fWidth; } 413 414 /** Set the width for stroking. 415 Pass 0 to stroke in hairline mode. 416 Hairlines always draw 1-pixel wide, regardless of the matrix. 417 @param width set the paint's stroke width, used whenever the paint's 418 style is Stroke or StrokeAndFill. 419 */ 420 void setStrokeWidth(SkScalar width); 421 422 /** Return the paint's stroke miter value. This is used to control the 423 behavior of miter joins when the joins angle is sharp. 424 @return the paint's miter limit, used whenever the paint's style is 425 Stroke or StrokeAndFill. 426 */ 427 SkScalar getStrokeMiter() const { return fMiterLimit; } 428 429 /** Set the paint's stroke miter value. This is used to control the 430 behavior of miter joins when the joins angle is sharp. This value must 431 be >= 0. 432 @param miter set the miter limit on the paint, used whenever the 433 paint's style is Stroke or StrokeAndFill. 434 */ 435 void setStrokeMiter(SkScalar miter); 436 437 /** Cap enum specifies the settings for the paint's strokecap. This is the 438 treatment that is applied to the beginning and end of each non-closed 439 contour (e.g. lines). 440 */ 441 enum Cap { 442 kButt_Cap, //!< begin/end contours with no extension 443 kRound_Cap, //!< begin/end contours with a semi-circle extension 444 kSquare_Cap, //!< begin/end contours with a half square extension 445 446 kCapCount, 447 kDefault_Cap = kButt_Cap 448 }; 449 450 /** Join enum specifies the settings for the paint's strokejoin. This is 451 the treatment that is applied to corners in paths and rectangles. 452 */ 453 enum Join { 454 kMiter_Join, //!< connect path segments with a sharp join 455 kRound_Join, //!< connect path segments with a round join 456 kBevel_Join, //!< connect path segments with a flat bevel join 457 458 kJoinCount, 459 kDefault_Join = kMiter_Join 460 }; 461 462 /** Return the paint's stroke cap type, controlling how the start and end 463 of stroked lines and paths are treated. 464 @return the line cap style for the paint, used whenever the paint's 465 style is Stroke or StrokeAndFill. 466 */ 467 Cap getStrokeCap() const { return (Cap)fCapType; } 468 469 /** Set the paint's stroke cap type. 470 @param cap set the paint's line cap style, used whenever the paint's 471 style is Stroke or StrokeAndFill. 472 */ 473 void setStrokeCap(Cap cap); 474 475 /** Return the paint's stroke join type. 476 @return the paint's line join style, used whenever the paint's style is 477 Stroke or StrokeAndFill. 478 */ 479 Join getStrokeJoin() const { return (Join)fJoinType; } 480 481 /** Set the paint's stroke join type. 482 @param join set the paint's line join style, used whenever the paint's 483 style is Stroke or StrokeAndFill. 484 */ 485 void setStrokeJoin(Join join); 486 487 /** 488 * Applies any/all effects (patheffect, stroking) to src, returning the 489 * result in dst. The result is that drawing src with this paint will be 490 * the same as drawing dst with a default paint (at least from the 491 * geometric perspective). 492 * 493 * @param src input path 494 * @param dst output path (may be the same as src) 495 * @param cullRect If not null, the dst path may be culled to this rect. 496 * @return true if the path should be filled, or false if it should be 497 * drawn with a hairline (width == 0) 498 */ 499 bool getFillPath(const SkPath& src, SkPath* dst, 500 const SkRect* cullRect = NULL) const; 501 502 /** Get the paint's shader object. 503 <p /> 504 The shader's reference count is not affected. 505 @return the paint's shader (or NULL) 506 */ 507 SkShader* getShader() const { return fShader; } 508 509 /** Set or clear the shader object. 510 * Shaders specify the source color(s) for what is being drawn. If a paint 511 * has no shader, then the paint's color is used. If the paint has a 512 * shader, then the shader's color(s) are use instead, but they are 513 * modulated by the paint's alpha. This makes it easy to create a shader 514 * once (e.g. bitmap tiling or gradient) and then change its transparency 515 * w/o having to modify the original shader... only the paint's alpha needs 516 * to be modified. 517 * 518 * There is an exception to this only-respect-paint's-alpha rule: If the shader only generates 519 * alpha (e.g. SkShader::CreateBitmapShader(bitmap, ...) where bitmap's colortype is kAlpha_8) 520 * then the shader will use the paint's entire color to "colorize" its output (modulating the 521 * bitmap's alpha with the paint's color+alpha). 522 * 523 * Pass NULL to clear any previous shader. 524 * As a convenience, the parameter passed is also returned. 525 * If a previous shader exists, its reference count is decremented. 526 * If shader is not NULL, its reference count is incremented. 527 * @param shader May be NULL. The shader to be installed in the paint 528 * @return shader 529 */ 530 SkShader* setShader(SkShader* shader); 531 532 /** Get the paint's colorfilter. If there is a colorfilter, its reference 533 count is not changed. 534 @return the paint's colorfilter (or NULL) 535 */ 536 SkColorFilter* getColorFilter() const { return fColorFilter; } 537 538 /** Set or clear the paint's colorfilter, returning the parameter. 539 <p /> 540 If the paint already has a filter, its reference count is decremented. 541 If filter is not NULL, its reference count is incremented. 542 @param filter May be NULL. The filter to be installed in the paint 543 @return filter 544 */ 545 SkColorFilter* setColorFilter(SkColorFilter* filter); 546 547 /** Get the paint's xfermode object. 548 <p /> 549 The xfermode's reference count is not affected. 550 @return the paint's xfermode (or NULL) 551 */ 552 SkXfermode* getXfermode() const { return fXfermode; } 553 554 /** Set or clear the xfermode object. 555 <p /> 556 Pass NULL to clear any previous xfermode. 557 As a convenience, the parameter passed is also returned. 558 If a previous xfermode exists, its reference count is decremented. 559 If xfermode is not NULL, its reference count is incremented. 560 @param xfermode May be NULL. The new xfermode to be installed in the 561 paint 562 @return xfermode 563 */ 564 SkXfermode* setXfermode(SkXfermode* xfermode); 565 566 /** Create an xfermode based on the specified Mode, and assign it into the 567 paint, returning the mode that was set. If the Mode is SrcOver, then 568 the paint's xfermode is set to null. 569 */ 570 SkXfermode* setXfermodeMode(SkXfermode::Mode); 571 572 /** Get the paint's patheffect object. 573 <p /> 574 The patheffect reference count is not affected. 575 @return the paint's patheffect (or NULL) 576 */ 577 SkPathEffect* getPathEffect() const { return fPathEffect; } 578 579 /** Set or clear the patheffect object. 580 <p /> 581 Pass NULL to clear any previous patheffect. 582 As a convenience, the parameter passed is also returned. 583 If a previous patheffect exists, its reference count is decremented. 584 If patheffect is not NULL, its reference count is incremented. 585 @param effect May be NULL. The new patheffect to be installed in the 586 paint 587 @return effect 588 */ 589 SkPathEffect* setPathEffect(SkPathEffect* effect); 590 591 /** Get the paint's maskfilter object. 592 <p /> 593 The maskfilter reference count is not affected. 594 @return the paint's maskfilter (or NULL) 595 */ 596 SkMaskFilter* getMaskFilter() const { return fMaskFilter; } 597 598 /** Set or clear the maskfilter object. 599 <p /> 600 Pass NULL to clear any previous maskfilter. 601 As a convenience, the parameter passed is also returned. 602 If a previous maskfilter exists, its reference count is decremented. 603 If maskfilter is not NULL, its reference count is incremented. 604 @param maskfilter May be NULL. The new maskfilter to be installed in 605 the paint 606 @return maskfilter 607 */ 608 SkMaskFilter* setMaskFilter(SkMaskFilter* maskfilter); 609 610 // These attributes are for text/fonts 611 612 /** Get the paint's typeface object. 613 <p /> 614 The typeface object identifies which font to use when drawing or 615 measuring text. The typeface reference count is not affected. 616 @return the paint's typeface (or NULL) 617 */ 618 SkTypeface* getTypeface() const { return fTypeface; } 619 620 /** Set or clear the typeface object. 621 <p /> 622 Pass NULL to clear any previous typeface. 623 As a convenience, the parameter passed is also returned. 624 If a previous typeface exists, its reference count is decremented. 625 If typeface is not NULL, its reference count is incremented. 626 @param typeface May be NULL. The new typeface to be installed in the 627 paint 628 @return typeface 629 */ 630 SkTypeface* setTypeface(SkTypeface* typeface); 631 632 /** Get the paint's rasterizer (or NULL). 633 <p /> 634 The raster controls how paths/text are turned into alpha masks. 635 @return the paint's rasterizer (or NULL) 636 */ 637 SkRasterizer* getRasterizer() const { return fRasterizer; } 638 639 /** Set or clear the rasterizer object. 640 <p /> 641 Pass NULL to clear any previous rasterizer. 642 As a convenience, the parameter passed is also returned. 643 If a previous rasterizer exists in the paint, its reference count is 644 decremented. If rasterizer is not NULL, its reference count is 645 incremented. 646 @param rasterizer May be NULL. The new rasterizer to be installed in 647 the paint. 648 @return rasterizer 649 */ 650 SkRasterizer* setRasterizer(SkRasterizer* rasterizer); 651 652 SkImageFilter* getImageFilter() const { return fImageFilter; } 653 SkImageFilter* setImageFilter(SkImageFilter*); 654 655 SkAnnotation* getAnnotation() const { return fAnnotation; } 656 SkAnnotation* setAnnotation(SkAnnotation*); 657 658 /** 659 * Returns true if there is an annotation installed on this paint, and 660 * the annotation specifics no-drawing. 661 */ 662 SK_ATTR_DEPRECATED("use getAnnotation and check for non-null") 663 bool isNoDrawAnnotation() const { return this->getAnnotation() != NULL; } 664 665 /** 666 * Return the paint's SkDrawLooper (if any). Does not affect the looper's 667 * reference count. 668 */ 669 SkDrawLooper* getLooper() const { return fLooper; } 670 671 /** 672 * Set or clear the looper object. 673 * <p /> 674 * Pass NULL to clear any previous looper. 675 * As a convenience, the parameter passed is also returned. 676 * If a previous looper exists in the paint, its reference count is 677 * decremented. If looper is not NULL, its reference count is 678 * incremented. 679 * @param looper May be NULL. The new looper to be installed in the paint. 680 * @return looper 681 */ 682 SkDrawLooper* setLooper(SkDrawLooper* looper); 683 684 enum Align { 685 kLeft_Align, 686 kCenter_Align, 687 kRight_Align, 688 }; 689 enum { 690 kAlignCount = 3 691 }; 692 693 /** Return the paint's Align value for drawing text. 694 @return the paint's Align value for drawing text. 695 */ 696 Align getTextAlign() const { return (Align)fTextAlign; } 697 698 /** Set the paint's text alignment. 699 @param align set the paint's Align value for drawing text. 700 */ 701 void setTextAlign(Align align); 702 703 /** Return the paint's text size. 704 @return the paint's text size. 705 */ 706 SkScalar getTextSize() const { return fTextSize; } 707 708 /** Set the paint's text size. This value must be > 0 709 @param textSize set the paint's text size. 710 */ 711 void setTextSize(SkScalar textSize); 712 713 /** Return the paint's horizontal scale factor for text. The default value 714 is 1.0. 715 @return the paint's scale factor in X for drawing/measuring text 716 */ 717 SkScalar getTextScaleX() const { return fTextScaleX; } 718 719 /** Set the paint's horizontal scale factor for text. The default value 720 is 1.0. Values > 1.0 will stretch the text wider. Values < 1.0 will 721 stretch the text narrower. 722 @param scaleX set the paint's scale factor in X for drawing/measuring 723 text. 724 */ 725 void setTextScaleX(SkScalar scaleX); 726 727 /** Return the paint's horizontal skew factor for text. The default value 728 is 0. 729 @return the paint's skew factor in X for drawing text. 730 */ 731 SkScalar getTextSkewX() const { return fTextSkewX; } 732 733 /** Set the paint's horizontal skew factor for text. The default value 734 is 0. For approximating oblique text, use values around -0.25. 735 @param skewX set the paint's skew factor in X for drawing text. 736 */ 737 void setTextSkewX(SkScalar skewX); 738 739 /** Describes how to interpret the text parameters that are passed to paint 740 methods like measureText() and getTextWidths(). 741 */ 742 enum TextEncoding { 743 kUTF8_TextEncoding, //!< the text parameters are UTF8 744 kUTF16_TextEncoding, //!< the text parameters are UTF16 745 kUTF32_TextEncoding, //!< the text parameters are UTF32 746 kGlyphID_TextEncoding //!< the text parameters are glyph indices 747 }; 748 749 TextEncoding getTextEncoding() const { return (TextEncoding)fTextEncoding; } 750 751 void setTextEncoding(TextEncoding encoding); 752 753 struct FontMetrics { 754 /** Flags which indicate the confidence level of various metrics. 755 A set flag indicates that the metric may be trusted. 756 */ 757 enum FontMetricsFlags { 758 kUnderlineThinknessIsValid_Flag = 1 << 0, 759 kUnderlinePositionIsValid_Flag = 1 << 1, 760 }; 761 762 uint32_t fFlags; //!< Bit field to identify which values are unknown 763 SkScalar fTop; //!< The greatest distance above the baseline for any glyph (will be <= 0) 764 SkScalar fAscent; //!< The recommended distance above the baseline (will be <= 0) 765 SkScalar fDescent; //!< The recommended distance below the baseline (will be >= 0) 766 SkScalar fBottom; //!< The greatest distance below the baseline for any glyph (will be >= 0) 767 SkScalar fLeading; //!< The recommended distance to add between lines of text (will be >= 0) 768 SkScalar fAvgCharWidth; //!< the average character width (>= 0) 769 SkScalar fMaxCharWidth; //!< the max character width (>= 0) 770 SkScalar fXMin; //!< The minimum bounding box x value for all glyphs 771 SkScalar fXMax; //!< The maximum bounding box x value for all glyphs 772 SkScalar fXHeight; //!< The height of an 'x' in px, or 0 if no 'x' in face 773 SkScalar fCapHeight; //!< The cap height (> 0), or 0 if cannot be determined. 774 SkScalar fUnderlineThickness; //!< underline thickness, or 0 if cannot be determined 775 776 /** Underline Position - position of the top of the Underline stroke 777 relative to the baseline, this can have following values 778 - Negative - means underline should be drawn above baseline. 779 - Positive - means below baseline. 780 - Zero - mean underline should be drawn on baseline. 781 */ 782 SkScalar fUnderlinePosition; //!< underline position, or 0 if cannot be determined 783 784 /** If the fontmetrics has a valid underlinethickness, return true, and set the 785 thickness param to that value. If it doesn't return false and ignore the 786 thickness param. 787 */ 788 bool hasUnderlineThickness(SkScalar* thickness) const { 789 if (SkToBool(fFlags & kUnderlineThinknessIsValid_Flag)) { 790 *thickness = fUnderlineThickness; 791 return true; 792 } 793 return false; 794 } 795 796 /** If the fontmetrics has a valid underlineposition, return true, and set the 797 thickness param to that value. If it doesn't return false and ignore the 798 thickness param. 799 */ 800 bool hasUnderlinePosition(SkScalar* position) const { 801 if (SkToBool(fFlags & kUnderlinePositionIsValid_Flag)) { 802 *position = fUnderlinePosition; 803 return true; 804 } 805 return false; 806 } 807 808 }; 809 810 /** Return the recommend spacing between lines (which will be 811 fDescent - fAscent + fLeading). 812 If metrics is not null, return in it the font metrics for the 813 typeface/pointsize/etc. currently set in the paint. 814 @param metrics If not null, returns the font metrics for the 815 current typeface/pointsize/etc setting in this 816 paint. 817 @param scale If not 0, return width as if the canvas were scaled 818 by this value 819 @param return the recommended spacing between lines 820 */ 821 SkScalar getFontMetrics(FontMetrics* metrics, SkScalar scale = 0) const; 822 823 /** Return the recommend line spacing. This will be 824 fDescent - fAscent + fLeading 825 */ 826 SkScalar getFontSpacing() const { return this->getFontMetrics(NULL, 0); } 827 828 /** Convert the specified text into glyph IDs, returning the number of 829 glyphs ID written. If glyphs is NULL, it is ignore and only the count 830 is returned. 831 */ 832 int textToGlyphs(const void* text, size_t byteLength, 833 uint16_t glyphs[]) const; 834 835 /** Return true if all of the specified text has a corresponding non-zero 836 glyph ID. If any of the code-points in the text are not supported in 837 the typeface (i.e. the glyph ID would be zero), then return false. 838 839 If the text encoding for the paint is kGlyph_TextEncoding, then this 840 returns true if all of the specified glyph IDs are non-zero. 841 */ 842 bool containsText(const void* text, size_t byteLength) const; 843 844 /** Convert the glyph array into Unichars. Unconvertable glyphs are mapped 845 to zero. Note: this does not look at the text-encoding setting in the 846 paint, only at the typeface. 847 */ 848 void glyphsToUnichars(const uint16_t glyphs[], int count, 849 SkUnichar text[]) const; 850 851 /** Return the number of drawable units in the specified text buffer. 852 This looks at the current TextEncoding field of the paint. If you also 853 want to have the text converted into glyph IDs, call textToGlyphs 854 instead. 855 */ 856 int countText(const void* text, size_t byteLength) const { 857 return this->textToGlyphs(text, byteLength, NULL); 858 } 859 860 /** Return the width of the text. This will return the vertical measure 861 * if isVerticalText() is true, in which case the returned value should 862 * be treated has a height instead of a width. 863 * 864 * @param text The text to be measured 865 * @param length Number of bytes of text to measure 866 * @param bounds If not NULL, returns the bounds of the text, 867 * relative to (0, 0). 868 * @param scale If not 0, return width as if the canvas were scaled 869 * by this value 870 * @return The advance width of the text 871 */ 872 SkScalar measureText(const void* text, size_t length, 873 SkRect* bounds, SkScalar scale = 0) const; 874 875 /** Return the width of the text. This will return the vertical measure 876 * if isVerticalText() is true, in which case the returned value should 877 * be treated has a height instead of a width. 878 * 879 * @param text Address of the text 880 * @param length Number of bytes of text to measure 881 * @return The advance width of the text 882 */ 883 SkScalar measureText(const void* text, size_t length) const { 884 return this->measureText(text, length, NULL, 0); 885 } 886 887 /** Specify the direction the text buffer should be processed in breakText() 888 */ 889 enum TextBufferDirection { 890 /** When measuring text for breakText(), begin at the start of the text 891 buffer and proceed forward through the data. This is the default. 892 */ 893 kForward_TextBufferDirection, 894 /** When measuring text for breakText(), begin at the end of the text 895 buffer and proceed backwards through the data. 896 */ 897 kBackward_TextBufferDirection 898 }; 899 900 /** Return the number of bytes of text that were measured. If 901 * isVerticalText() is true, then the vertical advances are used for 902 * the measurement. 903 * 904 * @param text The text to be measured 905 * @param length Number of bytes of text to measure 906 * @param maxWidth Maximum width. Only the subset of text whose accumulated 907 * widths are <= maxWidth are measured. 908 * @param measuredWidth Optional. If non-null, this returns the actual 909 * width of the measured text. 910 * @param tbd Optional. The direction the text buffer should be 911 * traversed during measuring. 912 * @return The number of bytes of text that were measured. Will be 913 * <= length. 914 */ 915 size_t breakText(const void* text, size_t length, SkScalar maxWidth, 916 SkScalar* measuredWidth = NULL, 917 TextBufferDirection tbd = kForward_TextBufferDirection) 918 const; 919 920 /** Return the advances for the text. These will be vertical advances if 921 * isVerticalText() returns true. 922 * 923 * @param text the text 924 * @param byteLength number of bytes to of text 925 * @param widths If not null, returns the array of advances for 926 * the glyphs. If not NULL, must be at least a large 927 * as the number of unichars in the specified text. 928 * @param bounds If not null, returns the bounds for each of 929 * character, relative to (0, 0) 930 * @return the number of unichars in the specified text. 931 */ 932 int getTextWidths(const void* text, size_t byteLength, SkScalar widths[], 933 SkRect bounds[] = NULL) const; 934 935 /** Return the path (outline) for the specified text. 936 Note: just like SkCanvas::drawText, this will respect the Align setting 937 in the paint. 938 */ 939 void getTextPath(const void* text, size_t length, SkScalar x, SkScalar y, 940 SkPath* path) const; 941 942 void getPosTextPath(const void* text, size_t length, 943 const SkPoint pos[], SkPath* path) const; 944 945#ifdef SK_BUILD_FOR_ANDROID 946 uint32_t getGenerationID() const; 947 void setGenerationID(uint32_t generationID); 948 949 /** Returns the base glyph count for the strike associated with this paint 950 */ 951 unsigned getBaseGlyphCount(SkUnichar text) const; 952 953 const SkPaintOptionsAndroid& getPaintOptionsAndroid() const { 954 return fPaintOptionsAndroid; 955 } 956 void setPaintOptionsAndroid(const SkPaintOptionsAndroid& options); 957#endif 958 959 // returns true if the paint's settings (e.g. xfermode + alpha) resolve to 960 // mean that we need not draw at all (e.g. SrcOver + 0-alpha) 961 bool nothingToDraw() const; 962 963 /////////////////////////////////////////////////////////////////////////// 964 // would prefer to make these private... 965 966 /** Returns true if the current paint settings allow for fast computation of 967 bounds (i.e. there is nothing complex like a patheffect that would make 968 the bounds computation expensive. 969 */ 970 bool canComputeFastBounds() const { 971 if (this->getLooper()) { 972 return this->getLooper()->canComputeFastBounds(*this); 973 } 974 return !this->getRasterizer(); 975 } 976 977 /** Only call this if canComputeFastBounds() returned true. This takes a 978 raw rectangle (the raw bounds of a shape), and adjusts it for stylistic 979 effects in the paint (e.g. stroking). If needed, it uses the storage 980 rect parameter. It returns the adjusted bounds that can then be used 981 for quickReject tests. 982 983 The returned rect will either be orig or storage, thus the caller 984 should not rely on storage being set to the result, but should always 985 use the retured value. It is legal for orig and storage to be the same 986 rect. 987 988 e.g. 989 if (paint.canComputeFastBounds()) { 990 SkRect r, storage; 991 path.computeBounds(&r, SkPath::kFast_BoundsType); 992 const SkRect& fastR = paint.computeFastBounds(r, &storage); 993 if (canvas->quickReject(fastR, ...)) { 994 // don't draw the path 995 } 996 } 997 */ 998 const SkRect& computeFastBounds(const SkRect& orig, SkRect* storage) const { 999 SkPaint::Style style = this->getStyle(); 1000 // ultra fast-case: filling with no effects that affect geometry 1001 if (kFill_Style == style) { 1002 uintptr_t effects = reinterpret_cast<uintptr_t>(this->getLooper()); 1003 effects |= reinterpret_cast<uintptr_t>(this->getMaskFilter()); 1004 effects |= reinterpret_cast<uintptr_t>(this->getPathEffect()); 1005 effects |= reinterpret_cast<uintptr_t>(this->getImageFilter()); 1006 if (!effects) { 1007 return orig; 1008 } 1009 } 1010 1011 return this->doComputeFastBounds(orig, storage, style); 1012 } 1013 1014 const SkRect& computeFastStrokeBounds(const SkRect& orig, 1015 SkRect* storage) const { 1016 return this->doComputeFastBounds(orig, storage, kStroke_Style); 1017 } 1018 1019 // Take the style explicitly, so the caller can force us to be stroked 1020 // without having to make a copy of the paint just to change that field. 1021 const SkRect& doComputeFastBounds(const SkRect& orig, SkRect* storage, 1022 Style) const; 1023 1024 /** 1025 * Return a matrix that applies the paint's text values: size, scale, skew 1026 */ 1027 static SkMatrix* SetTextMatrix(SkMatrix* matrix, SkScalar size, 1028 SkScalar scaleX, SkScalar skewX) { 1029 matrix->setScale(size * scaleX, size); 1030 if (skewX) { 1031 matrix->postSkew(skewX, 0); 1032 } 1033 return matrix; 1034 } 1035 1036 SkMatrix* setTextMatrix(SkMatrix* matrix) const { 1037 return SetTextMatrix(matrix, fTextSize, fTextScaleX, fTextSkewX); 1038 } 1039 1040 SK_TO_STRING_NONVIRT() 1041 1042 struct FlatteningTraits { 1043 static void Flatten(SkWriteBuffer& buffer, const SkPaint& paint); 1044 static void Unflatten(SkReadBuffer& buffer, SkPaint* paint); 1045 }; 1046 1047private: 1048 SkTypeface* fTypeface; 1049 SkPathEffect* fPathEffect; 1050 SkShader* fShader; 1051 SkXfermode* fXfermode; 1052 SkMaskFilter* fMaskFilter; 1053 SkColorFilter* fColorFilter; 1054 SkRasterizer* fRasterizer; 1055 SkDrawLooper* fLooper; 1056 SkImageFilter* fImageFilter; 1057 SkAnnotation* fAnnotation; 1058 1059 SkScalar fTextSize; 1060 SkScalar fTextScaleX; 1061 SkScalar fTextSkewX; 1062 SkColor fColor; 1063 SkScalar fWidth; 1064 SkScalar fMiterLimit; 1065 union { 1066 struct { 1067 // all of these bitfields should add up to 32 1068 unsigned fFlags : 16; 1069 unsigned fTextAlign : 2; 1070 unsigned fCapType : 2; 1071 unsigned fJoinType : 2; 1072 unsigned fStyle : 2; 1073 unsigned fTextEncoding : 2; // 3 values 1074 unsigned fHinting : 2; 1075 //unsigned fFreeBits : 4; 1076 }; 1077 uint32_t fBitfields; 1078 }; 1079 uint32_t fDirtyBits; 1080 1081 uint32_t getBitfields() const { return fBitfields; } 1082 void setBitfields(uint32_t bitfields); 1083 1084 SkDrawCacheProc getDrawCacheProc() const; 1085 SkMeasureCacheProc getMeasureCacheProc(TextBufferDirection dir, 1086 bool needFullMetrics) const; 1087 1088 SkScalar measure_text(SkGlyphCache*, const char* text, size_t length, 1089 int* count, SkRect* bounds) const; 1090 1091 SkGlyphCache* detachCache(const SkDeviceProperties* deviceProperties, const SkMatrix*) const; 1092 1093 void descriptorProc(const SkDeviceProperties* deviceProperties, const SkMatrix* deviceMatrix, 1094 void (*proc)(SkTypeface*, const SkDescriptor*, void*), 1095 void* context, bool ignoreGamma = false) const; 1096 1097 static void Term(); 1098 1099 enum { 1100 /* This is the size we use when we ask for a glyph's path. We then 1101 * post-transform it as we draw to match the request. 1102 * This is done to try to re-use cache entries for the path. 1103 * 1104 * This value is somewhat arbitrary. In theory, it could be 1, since 1105 * we store paths as floats. However, we get the path from the font 1106 * scaler, and it may represent its paths as fixed-point (or 26.6), 1107 * so we shouldn't ask for something too big (might overflow 16.16) 1108 * or too small (underflow 26.6). 1109 * 1110 * This value could track kMaxSizeForGlyphCache, assuming the above 1111 * constraints, but since we ask for unhinted paths, the two values 1112 * need not match per-se. 1113 */ 1114 kCanonicalTextSizeForPaths = 64, 1115 1116 /* 1117 * Above this size (taking into account CTM and textSize), we never use 1118 * the cache for bits or metrics (we might overflow), so we just ask 1119 * for a caononical size and post-transform that. 1120 */ 1121 kMaxSizeForGlyphCache = 256, 1122 }; 1123 1124 static bool TooBigToUseCache(const SkMatrix& ctm, const SkMatrix& textM); 1125 1126 bool tooBigToUseCache() const; 1127 bool tooBigToUseCache(const SkMatrix& ctm) const; 1128 1129 // Set flags/hinting/textSize up to use for drawing text as paths. 1130 // Returns scale factor to restore the original textSize, since will will 1131 // have change it to kCanonicalTextSizeForPaths. 1132 SkScalar setupForAsPaths(); 1133 1134 static SkScalar MaxCacheSize2() { 1135 static const SkScalar kMaxSize = SkIntToScalar(kMaxSizeForGlyphCache); 1136 static const SkScalar kMag2Max = kMaxSize * kMaxSize; 1137 return kMag2Max; 1138 } 1139 1140 friend class SkAutoGlyphCache; 1141 friend class SkCanvas; 1142 friend class SkDraw; 1143 friend class SkGraphics; // So Term() can be called. 1144 friend class SkPDFDevice; 1145 friend class GrBitmapTextContext; 1146 friend class GrDistanceFieldTextContext; 1147 friend class SkTextToPathIter; 1148 friend class SkCanonicalizePaint; 1149 1150#ifdef SK_BUILD_FOR_ANDROID 1151 SkPaintOptionsAndroid fPaintOptionsAndroid; 1152 1153 // In order for the == operator to work properly this must be the last field 1154 // in the struct so that we can do a memcmp to this field's offset. 1155 uint32_t fGenerationID; 1156#endif 1157}; 1158 1159#endif 1160