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

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