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