1
2
3/*
4 * Copyright 2006 The Android Open Source Project
5 *
6 * Use of this source code is governed by a BSD-style license that can be
7 * found in the LICENSE file.
8 */
9
10
11#ifndef SkPaint_DEFINED
12#define SkPaint_DEFINED
13
14#include "SkColor.h"
15#include "SkDrawLooper.h"
16#include "SkMatrix.h"
17#include "SkXfermode.h"
18#ifdef SK_BUILD_FOR_ANDROID
19#include "SkPaintOptionsAndroid.h"
20#endif
21
22class SkAnnotation;
23class SkAutoGlyphCache;
24class SkColorFilter;
25class SkDescriptor;
26struct SkDeviceProperties;
27class SkFlattenableReadBuffer;
28class SkFlattenableWriteBuffer;
29struct SkGlyph;
30struct SkRect;
31class SkGlyphCache;
32class SkImageFilter;
33class SkMaskFilter;
34class SkPath;
35class SkPathEffect;
36struct SkPoint;
37class SkRasterizer;
38class SkShader;
39class SkTypeface;
40
41typedef const SkGlyph& (*SkDrawCacheProc)(SkGlyphCache*, const char**,
42                                           SkFixed x, SkFixed y);
43
44typedef const SkGlyph& (*SkMeasureCacheProc)(SkGlyphCache*, const char**);
45
46#define kBicubicFilterBitmap_Flag kHighQualityFilterBitmap_Flag
47
48/** \class SkPaint
49
50    The SkPaint class holds the style and color information about how to draw
51    geometries, text and bitmaps.
52*/
53
54class SK_API SkPaint {
55    enum {
56        // DEPRECATED -- use setFilterLevel instead
57        kFilterBitmap_Flag    = 0x02, // temporary flag
58        // DEPRECATED -- use setFilterLevel instead
59        kHighQualityFilterBitmap_Flag = 0x4000, // temporary flag
60        // DEPRECATED -- use setFilterLevel instead
61        kHighQualityDownsampleBitmap_Flag = 0x8000, // temporary flag
62    };
63public:
64    SkPaint();
65    SkPaint(const SkPaint& paint);
66    ~SkPaint();
67
68    SkPaint& operator=(const SkPaint&);
69
70    SK_API friend bool operator==(const SkPaint& a, const SkPaint& b);
71    friend bool operator!=(const SkPaint& a, const SkPaint& b) {
72        return !(a == b);
73    }
74
75    void flatten(SkFlattenableWriteBuffer&) const;
76    void unflatten(SkFlattenableReadBuffer&);
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     *  DEPRECATED: use setFilterLevel instead.
308     *  If the predicate is true, set the filterLevel to Low, else set it to
309     *  None.
310     */
311    void setFilterBitmap(bool doFilter) {
312        this->setFilterLevel(doFilter ? kLow_FilterLevel : kNone_FilterLevel);
313    }
314
315    /**
316     *  DEPRECATED: call getFilterLevel() instead.
317     *  Returns true if getFilterLevel() returns anything other than None.
318     */
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    bool isNoDrawAnnotation() const {
643        return SkToBool(fPrivFlags & kNoDrawAnnotation_PrivFlag);
644    }
645
646    /**
647     *  Return the paint's SkDrawLooper (if any). Does not affect the looper's
648     *  reference count.
649     */
650    SkDrawLooper* getLooper() const { return fLooper; }
651
652    /**
653     *  Set or clear the looper object.
654     *  <p />
655     *  Pass NULL to clear any previous looper.
656     *  As a convenience, the parameter passed is also returned.
657     *  If a previous looper exists in the paint, its reference count is
658     *  decremented. If looper is not NULL, its reference count is
659     *  incremented.
660     *  @param looper May be NULL. The new looper to be installed in the paint.
661     *  @return looper
662     */
663    SkDrawLooper* setLooper(SkDrawLooper* looper);
664
665    enum Align {
666        kLeft_Align,
667        kCenter_Align,
668        kRight_Align,
669    };
670    enum {
671        kAlignCount = 3
672    };
673
674    /** Return the paint's Align value for drawing text.
675        @return the paint's Align value for drawing text.
676    */
677    Align   getTextAlign() const { return (Align)fTextAlign; }
678
679    /** Set the paint's text alignment.
680        @param align set the paint's Align value for drawing text.
681    */
682    void    setTextAlign(Align align);
683
684    /** Return the paint's text size.
685        @return the paint's text size.
686    */
687    SkScalar getTextSize() const { return fTextSize; }
688
689    /** Set the paint's text size. This value must be > 0
690        @param textSize set the paint's text size.
691    */
692    void setTextSize(SkScalar textSize);
693
694    /** Return the paint's horizontal scale factor for text. The default value
695        is 1.0.
696        @return the paint's scale factor in X for drawing/measuring text
697    */
698    SkScalar getTextScaleX() const { return fTextScaleX; }
699
700    /** Set the paint's horizontal scale factor for text. The default value
701        is 1.0. Values > 1.0 will stretch the text wider. Values < 1.0 will
702        stretch the text narrower.
703        @param scaleX   set the paint's scale factor in X for drawing/measuring
704                        text.
705    */
706    void setTextScaleX(SkScalar scaleX);
707
708    /** Return the paint's horizontal skew factor for text. The default value
709        is 0.
710        @return the paint's skew factor in X for drawing text.
711    */
712    SkScalar getTextSkewX() const { return fTextSkewX; }
713
714    /** Set the paint's horizontal skew factor for text. The default value
715        is 0. For approximating oblique text, use values around -0.25.
716        @param skewX set the paint's skew factor in X for drawing text.
717    */
718    void setTextSkewX(SkScalar skewX);
719
720#ifdef SK_SUPPORT_HINTING_SCALE_FACTOR
721    /** Return the paint's scale factor used for correctly rendering
722        glyphs in high DPI mode without text subpixel positioning.
723        @return the scale factor used for rendering glyphs in high DPI mode.
724    */
725    SkScalar getHintingScaleFactor() const { return fHintingScaleFactor; }
726
727    /** Set the paint's scale factor used for correctly rendering
728        glyphs in high DPI mode without text subpixel positioning.
729        @param the scale factor used for rendering glyphs in high DPI mode.
730    */
731    void setHintingScaleFactor(SkScalar hintingScaleFactor);
732#endif
733
734    /** Describes how to interpret the text parameters that are passed to paint
735        methods like measureText() and getTextWidths().
736    */
737    enum TextEncoding {
738        kUTF8_TextEncoding,     //!< the text parameters are UTF8
739        kUTF16_TextEncoding,    //!< the text parameters are UTF16
740        kUTF32_TextEncoding,    //!< the text parameters are UTF32
741        kGlyphID_TextEncoding   //!< the text parameters are glyph indices
742    };
743
744    TextEncoding getTextEncoding() const { return (TextEncoding)fTextEncoding; }
745
746    void setTextEncoding(TextEncoding encoding);
747
748    struct FontMetrics {
749        SkScalar    fTop;       //!< The greatest distance above the baseline for any glyph (will be <= 0)
750        SkScalar    fAscent;    //!< The recommended distance above the baseline (will be <= 0)
751        SkScalar    fDescent;   //!< The recommended distance below the baseline (will be >= 0)
752        SkScalar    fBottom;    //!< The greatest distance below the baseline for any glyph (will be >= 0)
753        SkScalar    fLeading;   //!< The recommended distance to add between lines of text (will be >= 0)
754        SkScalar    fAvgCharWidth;  //!< the average charactor width (>= 0)
755        SkScalar    fMaxCharWidth;  //!< the max charactor width (>= 0)
756        SkScalar    fXMin;      //!< The minimum bounding box x value for all glyphs
757        SkScalar    fXMax;      //!< The maximum bounding box x value for all glyphs
758        SkScalar    fXHeight;   //!< the height of an 'x' in px, or 0 if no 'x' in face
759    };
760
761    /** Return the recommend spacing between lines (which will be
762        fDescent - fAscent + fLeading).
763        If metrics is not null, return in it the font metrics for the
764        typeface/pointsize/etc. currently set in the paint.
765        @param metrics      If not null, returns the font metrics for the
766                            current typeface/pointsize/etc setting in this
767                            paint.
768        @param scale        If not 0, return width as if the canvas were scaled
769                            by this value
770        @param return the recommended spacing between lines
771    */
772    SkScalar getFontMetrics(FontMetrics* metrics, SkScalar scale = 0) const;
773
774    /** Return the recommend line spacing. This will be
775        fDescent - fAscent + fLeading
776    */
777    SkScalar getFontSpacing() const { return this->getFontMetrics(NULL, 0); }
778
779    /** Convert the specified text into glyph IDs, returning the number of
780        glyphs ID written. If glyphs is NULL, it is ignore and only the count
781        is returned.
782    */
783    int textToGlyphs(const void* text, size_t byteLength,
784                     uint16_t glyphs[]) const;
785
786    /** Return true if all of the specified text has a corresponding non-zero
787        glyph ID. If any of the code-points in the text are not supported in
788        the typeface (i.e. the glyph ID would be zero), then return false.
789
790        If the text encoding for the paint is kGlyph_TextEncoding, then this
791        returns true if all of the specified glyph IDs are non-zero.
792     */
793    bool containsText(const void* text, size_t byteLength) const;
794
795    /** Convert the glyph array into Unichars. Unconvertable glyphs are mapped
796        to zero. Note: this does not look at the text-encoding setting in the
797        paint, only at the typeface.
798    */
799    void glyphsToUnichars(const uint16_t glyphs[], int count,
800                          SkUnichar text[]) const;
801
802    /** Return the number of drawable units in the specified text buffer.
803        This looks at the current TextEncoding field of the paint. If you also
804        want to have the text converted into glyph IDs, call textToGlyphs
805        instead.
806    */
807    int countText(const void* text, size_t byteLength) const {
808        return this->textToGlyphs(text, byteLength, NULL);
809    }
810
811    /** Return the width of the text. This will return the vertical measure
812     *  if isVerticalText() is true, in which case the returned value should
813     *  be treated has a height instead of a width.
814     *
815     *  @param text         The text to be measured
816     *  @param length       Number of bytes of text to measure
817     *  @param bounds       If not NULL, returns the bounds of the text,
818     *                      relative to (0, 0).
819     *  @param scale        If not 0, return width as if the canvas were scaled
820     *                      by this value
821     *  @return             The advance width of the text
822     */
823    SkScalar measureText(const void* text, size_t length,
824                         SkRect* bounds, SkScalar scale = 0) const;
825
826    /** Return the width of the text. This will return the vertical measure
827     *  if isVerticalText() is true, in which case the returned value should
828     *  be treated has a height instead of a width.
829     *
830     *  @param text     Address of the text
831     *  @param length   Number of bytes of text to measure
832     *  @return         The advance width of the text
833     */
834    SkScalar measureText(const void* text, size_t length) const {
835        return this->measureText(text, length, NULL, 0);
836    }
837
838    /** Specify the direction the text buffer should be processed in breakText()
839    */
840    enum TextBufferDirection {
841        /** When measuring text for breakText(), begin at the start of the text
842            buffer and proceed forward through the data. This is the default.
843        */
844        kForward_TextBufferDirection,
845        /** When measuring text for breakText(), begin at the end of the text
846            buffer and proceed backwards through the data.
847        */
848        kBackward_TextBufferDirection
849    };
850
851    /** Return the number of bytes of text that were measured. If
852     *  isVerticalText() is true, then the vertical advances are used for
853     *  the measurement.
854     *
855     *  @param text     The text to be measured
856     *  @param length   Number of bytes of text to measure
857     *  @param maxWidth Maximum width. Only the subset of text whose accumulated
858     *                  widths are <= maxWidth are measured.
859     *  @param measuredWidth Optional. If non-null, this returns the actual
860     *                  width of the measured text.
861     *  @param tbd      Optional. The direction the text buffer should be
862     *                  traversed during measuring.
863     *  @return         The number of bytes of text that were measured. Will be
864     *                  <= length.
865     */
866    size_t  breakText(const void* text, size_t length, SkScalar maxWidth,
867                      SkScalar* measuredWidth = NULL,
868                      TextBufferDirection tbd = kForward_TextBufferDirection)
869                      const;
870
871    /** Return the advances for the text. These will be vertical advances if
872     *  isVerticalText() returns true.
873     *
874     *  @param text         the text
875     *  @param byteLength   number of bytes to of text
876     *  @param widths       If not null, returns the array of advances for
877     *                      the glyphs. If not NULL, must be at least a large
878     *                      as the number of unichars in the specified text.
879     *  @param bounds       If not null, returns the bounds for each of
880     *                      character, relative to (0, 0)
881     *  @return the number of unichars in the specified text.
882     */
883    int getTextWidths(const void* text, size_t byteLength, SkScalar widths[],
884                      SkRect bounds[] = NULL) const;
885
886    /** Return the path (outline) for the specified text.
887        Note: just like SkCanvas::drawText, this will respect the Align setting
888              in the paint.
889    */
890    void getTextPath(const void* text, size_t length, SkScalar x, SkScalar y,
891                     SkPath* path) const;
892
893    void getPosTextPath(const void* text, size_t length,
894                        const SkPoint pos[], SkPath* path) const;
895
896#ifdef SK_BUILD_FOR_ANDROID
897    const SkGlyph& getUnicharMetrics(SkUnichar, const SkMatrix*);
898    const SkGlyph& getGlyphMetrics(uint16_t, const SkMatrix*);
899    const void* findImage(const SkGlyph&, const SkMatrix*);
900
901    uint32_t getGenerationID() const;
902    void setGenerationID(uint32_t generationID);
903
904    /** Returns the base glyph count for the strike associated with this paint
905    */
906    unsigned getBaseGlyphCount(SkUnichar text) const;
907
908    const SkPaintOptionsAndroid& getPaintOptionsAndroid() const {
909        return fPaintOptionsAndroid;
910    }
911    void setPaintOptionsAndroid(const SkPaintOptionsAndroid& options);
912#endif
913
914    // returns true if the paint's settings (e.g. xfermode + alpha) resolve to
915    // mean that we need not draw at all (e.g. SrcOver + 0-alpha)
916    bool nothingToDraw() const;
917
918    ///////////////////////////////////////////////////////////////////////////
919    // would prefer to make these private...
920
921    /** Returns true if the current paint settings allow for fast computation of
922     bounds (i.e. there is nothing complex like a patheffect that would make
923     the bounds computation expensive.
924     */
925    bool canComputeFastBounds() const {
926        if (this->getLooper()) {
927            return this->getLooper()->canComputeFastBounds(*this);
928        }
929        return !this->getRasterizer();
930    }
931
932    /** Only call this if canComputeFastBounds() returned true. This takes a
933     raw rectangle (the raw bounds of a shape), and adjusts it for stylistic
934     effects in the paint (e.g. stroking). If needed, it uses the storage
935     rect parameter. It returns the adjusted bounds that can then be used
936     for quickReject tests.
937
938     The returned rect will either be orig or storage, thus the caller
939     should not rely on storage being set to the result, but should always
940     use the retured value. It is legal for orig and storage to be the same
941     rect.
942
943     e.g.
944     if (paint.canComputeFastBounds()) {
945     SkRect r, storage;
946     path.computeBounds(&r, SkPath::kFast_BoundsType);
947     const SkRect& fastR = paint.computeFastBounds(r, &storage);
948     if (canvas->quickReject(fastR, ...)) {
949     // don't draw the path
950     }
951     }
952     */
953    const SkRect& computeFastBounds(const SkRect& orig, SkRect* storage) const {
954        SkPaint::Style style = this->getStyle();
955        // ultra fast-case: filling with no effects that affect geometry
956        if (kFill_Style == style) {
957            uintptr_t effects = reinterpret_cast<uintptr_t>(this->getLooper());
958            effects |= reinterpret_cast<uintptr_t>(this->getMaskFilter());
959            effects |= reinterpret_cast<uintptr_t>(this->getPathEffect());
960            if (!effects) {
961                return orig;
962            }
963        }
964
965        return this->doComputeFastBounds(orig, storage, style);
966    }
967
968    const SkRect& computeFastStrokeBounds(const SkRect& orig,
969                                          SkRect* storage) const {
970        return this->doComputeFastBounds(orig, storage, kStroke_Style);
971    }
972
973    // Take the style explicitly, so the caller can force us to be stroked
974    // without having to make a copy of the paint just to change that field.
975    const SkRect& doComputeFastBounds(const SkRect& orig, SkRect* storage,
976                                      Style) const;
977
978    /**
979     *  Return a matrix that applies the paint's text values: size, scale, skew
980     */
981    static SkMatrix* SetTextMatrix(SkMatrix* matrix, SkScalar size,
982                                   SkScalar scaleX, SkScalar skewX) {
983        matrix->setScale(size * scaleX, size);
984        if (skewX) {
985            matrix->postSkew(skewX, 0);
986        }
987        return matrix;
988    }
989
990    SkMatrix* setTextMatrix(SkMatrix* matrix) const {
991        return SetTextMatrix(matrix, fTextSize, fTextScaleX, fTextSkewX);
992    }
993
994    SkDEVCODE(void toString(SkString*) const;)
995
996private:
997    SkTypeface*     fTypeface;
998    SkScalar        fTextSize;
999    SkScalar        fTextScaleX;
1000    SkScalar        fTextSkewX;
1001#ifdef SK_SUPPORT_HINTING_SCALE_FACTOR
1002    SkScalar        fHintingScaleFactor;
1003#endif
1004
1005    SkPathEffect*   fPathEffect;
1006    SkShader*       fShader;
1007    SkXfermode*     fXfermode;
1008    SkMaskFilter*   fMaskFilter;
1009    SkColorFilter*  fColorFilter;
1010    SkRasterizer*   fRasterizer;
1011    SkDrawLooper*   fLooper;
1012    SkImageFilter*  fImageFilter;
1013    SkAnnotation*   fAnnotation;
1014
1015    SkColor         fColor;
1016    SkScalar        fWidth;
1017    SkScalar        fMiterLimit;
1018    // all of these bitfields should add up to 32
1019    unsigned        fFlags : 16;
1020    unsigned        fTextAlign : 2;
1021    unsigned        fCapType : 2;
1022    unsigned        fJoinType : 2;
1023    unsigned        fStyle : 2;
1024    unsigned        fTextEncoding : 2;  // 3 values
1025    unsigned        fHinting : 2;
1026    unsigned        fPrivFlags : 4; // these are not flattened/unflattened
1027
1028    enum PrivFlags {
1029        kNoDrawAnnotation_PrivFlag  = 1 << 0,
1030    };
1031
1032    SkDrawCacheProc    getDrawCacheProc() const;
1033    SkMeasureCacheProc getMeasureCacheProc(TextBufferDirection dir,
1034                                           bool needFullMetrics) const;
1035
1036    SkScalar measure_text(SkGlyphCache*, const char* text, size_t length,
1037                          int* count, SkRect* bounds) const;
1038
1039    SkGlyphCache* detachCache(const SkDeviceProperties* deviceProperties, const SkMatrix*) const;
1040
1041    void descriptorProc(const SkDeviceProperties* deviceProperties, const SkMatrix* deviceMatrix,
1042                        void (*proc)(SkTypeface*, const SkDescriptor*, void*),
1043                        void* context, bool ignoreGamma = false) const;
1044
1045    static void Term();
1046
1047    enum {
1048        /*  This is the size we use when we ask for a glyph's path. We then
1049         *  post-transform it as we draw to match the request.
1050         *  This is done to try to re-use cache entries for the path.
1051         *
1052         *  This value is somewhat arbitrary. In theory, it could be 1, since
1053         *  we store paths as floats. However, we get the path from the font
1054         *  scaler, and it may represent its paths as fixed-point (or 26.6),
1055         *  so we shouldn't ask for something too big (might overflow 16.16)
1056         *  or too small (underflow 26.6).
1057         *
1058         *  This value could track kMaxSizeForGlyphCache, assuming the above
1059         *  constraints, but since we ask for unhinted paths, the two values
1060         *  need not match per-se.
1061         */
1062        kCanonicalTextSizeForPaths  = 64,
1063
1064        /*
1065         *  Above this size (taking into account CTM and textSize), we never use
1066         *  the cache for bits or metrics (we might overflow), so we just ask
1067         *  for a caononical size and post-transform that.
1068         */
1069        kMaxSizeForGlyphCache       = 256,
1070    };
1071
1072    static bool TooBigToUseCache(const SkMatrix& ctm, const SkMatrix& textM);
1073
1074    bool tooBigToUseCache() const;
1075    bool tooBigToUseCache(const SkMatrix& ctm) const;
1076
1077    // Set flags/hinting/textSize up to use for drawing text as paths.
1078    // Returns scale factor to restore the original textSize, since will will
1079    // have change it to kCanonicalTextSizeForPaths.
1080    SkScalar setupForAsPaths();
1081
1082    static SkScalar MaxCacheSize2() {
1083        static const SkScalar kMaxSize = SkIntToScalar(kMaxSizeForGlyphCache);
1084        static const SkScalar kMag2Max = kMaxSize * kMaxSize;
1085        return kMag2Max;
1086    }
1087
1088    friend class SkAutoGlyphCache;
1089    friend class SkCanvas;
1090    friend class SkDraw;
1091    friend class SkGraphics; // So Term() can be called.
1092    friend class SkPDFDevice;
1093    friend class SkTextToPathIter;
1094    friend class SkCanonicalizePaint;
1095
1096#ifdef SK_BUILD_FOR_ANDROID
1097    SkPaintOptionsAndroid fPaintOptionsAndroid;
1098
1099    // In order for the == operator to work properly this must be the last field
1100    // in the struct so that we can do a memcmp to this field's offset.
1101    uint32_t        fGenerationID;
1102#endif
1103};
1104
1105#endif
1106