src/third_party/skia/include/core/SkPaint.h

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