skia2/site/user/api/SkPaint_Reference.md
skia-bookmaker f1ec391853 Update markdown files
Automatic commit by the Housekeeper-Nightly-Bookmaker bot.

TBR=rmistry@google.com
NO_MERGE_BUILDS

Change-Id: I4cf4db316b2d1a483957a885d9929e3c8f3f06bd
Reviewed-on: https://skia-review.googlesource.com/c/168051
Reviewed-by: <skia-bookmaker@skia-swarming-bots.iam.gserviceaccount.com>
Commit-Queue: <skia-bookmaker@skia-swarming-bots.iam.gserviceaccount.com>
2018-11-03 06:16:35 +00:00

230 KiB

SkPaint Reference


class SkPaint {
public:
    SkPaint();
    SkPaint(const SkPaint& paint);
    SkPaint(SkPaint&& paint);
    ~SkPaint();
    SkPaint& operator=(const SkPaint& paint);
    SkPaint& operator=(SkPaint&& paint);
    friend bool operator==(const SkPaint& a, const SkPaint& b);
    friend bool operator!=(const SkPaint& a, const SkPaint& b);
    uint32_t getHash() const;
    void reset();

    enum Hinting {
        kNo_Hinting = 0,
        kSlight_Hinting = 1,
        kNormal_Hinting = 2,
        kFull_Hinting = 3,
    };

    Hinting getHinting() const;
    void setHinting(Hinting hintingLevel);

    enum Flags {
        kAntiAlias_Flag = 0x01,
        kDither_Flag = 0x04,
        kFakeBoldText_Flag = 0x20,
        kLinearText_Flag = 0x40,
        kSubpixelText_Flag = 0x80,
        kLCDRenderText_Flag = 0x200,
        kEmbeddedBitmapText_Flag = 0x400,
        kAutoHinting_Flag = 0x800,
        kAllFlags = 0xFFFF,
    };

    enum ReserveFlags {
        kUnderlineText_ReserveFlag = 0x08,
        kStrikeThruText_ReserveFlag = 0x10,
    };

    uint32_t getFlags() const;
    void setFlags(uint32_t flags);
    bool isAntiAlias() const;
    void setAntiAlias(bool aa);
    bool isDither() const;
    void setDither(bool dither);
    bool isLinearText() const;
    void setLinearText(bool linearText);
    bool isSubpixelText() const;
    void setSubpixelText(bool subpixelText);
    bool isLCDRenderText() const;
    void setLCDRenderText(bool lcdText);
    bool isEmbeddedBitmapText() const;
    void setEmbeddedBitmapText(bool useEmbeddedBitmapText);
    bool isAutohinted() const;
    void setAutohinted(bool useAutohinter);
    bool isFakeBoldText() const;
    void setFakeBoldText(bool fakeBoldText);
    bool isDevKernText() const;
    void setDevKernText(bool);
    SkFilterQuality getFilterQuality() const;
    void setFilterQuality(SkFilterQuality quality);

    enum Style {
        kFill_Style,
        kStroke_Style,
        kStrokeAndFill_Style,
    };

    static constexpr int kStyleCount = kStrokeAndFill_Style + 1;

    Style getStyle() const;
    void setStyle(Style style);
    SkColor getColor() const;
    SkColor4f getColor4f() const;
    void setColor(SkColor color);
    void setColor4f(const SkColor4f& color, SkColorSpace* colorSpace);
    uint8_t getAlpha() const;
    void setAlpha(U8CPU a);
    void setARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b);
    SkScalar getStrokeWidth() const;
    void setStrokeWidth(SkScalar width);
    SkScalar getStrokeMiter() const;
    void setStrokeMiter(SkScalar miter);

    enum Cap {
        kButt_Cap,
        kRound_Cap,
        kSquare_Cap,
        kLast_Cap = kSquare_Cap,
        kDefault_Cap = kButt_Cap,
    };

    static constexpr int kCapCount = kLast_Cap + 1;

    enum Join {
        kMiter_Join,
        kRound_Join,
        kBevel_Join,
        kLast_Join = kBevel_Join,
        kDefault_Join = kMiter_Join,
    };

    static constexpr int kJoinCount = kLast_Join + 1;

    Cap getStrokeCap() const;
    void setStrokeCap(Cap cap);
    Join getStrokeJoin() const;
    void setStrokeJoin(Join join);
    bool getFillPath(const SkPath& src, SkPath* dst, const SkRect* cullRect,
                     SkScalar resScale = 1) const;
    bool getFillPath(const SkPath& src, SkPath* dst) const;
    SkShader* getShader() const;
    sk_sp<SkShader> refShader() const;
    void setShader(sk_sp<SkShader> shader);
    SkColorFilter* getColorFilter() const;
    sk_sp<SkColorFilter> refColorFilter() const;
    void setColorFilter(sk_sp<SkColorFilter> colorFilter);
    SkBlendMode getBlendMode() const;
    bool isSrcOver() const;
    void setBlendMode(SkBlendMode mode);
    SkPathEffect* getPathEffect() const;
    sk_sp<SkPathEffect> refPathEffect() const;
    void setPathEffect(sk_sp<SkPathEffect> pathEffect);
    SkMaskFilter* getMaskFilter() const;
    sk_sp<SkMaskFilter> refMaskFilter() const;
    void setMaskFilter(sk_sp<SkMaskFilter> maskFilter);
    SkTypeface* getTypeface() const;
    sk_sp<SkTypeface> refTypeface() const;
    void setTypeface(sk_sp<SkTypeface> typeface);
    SkImageFilter* getImageFilter() const;
    sk_sp<SkImageFilter> refImageFilter() const;
    void setImageFilter(sk_sp<SkImageFilter> imageFilter);
    SkDrawLooper* getDrawLooper() const;
    sk_sp<SkDrawLooper> refDrawLooper() const;
    SkDrawLooper* getLooper() const;
    void setDrawLooper(sk_sp<SkDrawLooper> drawLooper);
    void setLooper(sk_sp<SkDrawLooper> drawLooper);
    SkScalar getTextSize() const;
    void setTextSize(SkScalar textSize);
    SkScalar getTextScaleX() const;
    void setTextScaleX(SkScalar scaleX);
    SkScalar getTextSkewX() const;
    void setTextSkewX(SkScalar skewX);

    enum TextEncoding {
        kUTF8_TextEncoding,
        kUTF16_TextEncoding,
        kUTF32_TextEncoding,
        kGlyphID_TextEncoding,
    };

    TextEncoding getTextEncoding() const;
    void setTextEncoding(TextEncoding encoding);

    struct FontMetrics {

        enum FontMetricsFlags {
            kUnderlineThicknessIsValid_Flag = 1 << 0,
            kUnderlinePositionIsValid_Flag = 1 << 1,
            kStrikeoutThicknessIsValid_Flag = 1 << 2,
            kStrikeoutPositionIsValid_Flag = 1 << 3,
        };

        uint32_t fFlags;
        SkScalar fTop;
        SkScalar fAscent;
        SkScalar fDescent;
        SkScalar fBottom;
        SkScalar fLeading;
        SkScalar fAvgCharWidth;
        SkScalar fMaxCharWidth;
        SkScalar fXMin;
        SkScalar fXMax;
        SkScalar fXHeight;
        SkScalar fCapHeight;
        SkScalar fUnderlineThickness;
        SkScalar fUnderlinePosition;
        SkScalar fStrikeoutThickness;
        SkScalar fStrikeoutPosition;
        bool hasUnderlineThickness(SkScalar* thickness) const;
        bool hasUnderlinePosition(SkScalar* position) const;
        bool hasStrikeoutThickness(SkScalar* thickness) const;
        bool hasStrikeoutPosition(SkScalar* position) const;
    };

    SkScalar getFontMetrics(FontMetrics* metrics) const;
    SkScalar getFontSpacing() const;
    int textToGlyphs(const void* text, size_t byteLength,
                     SkGlyphID glyphs[]) const;
    bool containsText(const void* text, size_t byteLength) const;
    void glyphsToUnichars(const SkGlyphID glyphs[], int count, SkUnichar text[]) const;
    int countText(const void* text, size_t byteLength) const;
    SkScalar measureText(const void* text, size_t length, SkRect* bounds) const;
    SkScalar measureText(const void* text, size_t length) const;
    size_t breakText(const void* text, size_t length, SkScalar maxWidth,
                      SkScalar* measuredWidth = nullptr) const;
    int getTextWidths(const void* text, size_t byteLength, SkScalar widths[],
                      SkRect bounds[] = nullptr) const;
    void getTextPath(const void* text, size_t length, SkScalar x, SkScalar y,
                     SkPath* path) const;
    void getPosTextPath(const void* text, size_t length,
                        const SkPoint pos[], SkPath* path) const;
    int getTextIntercepts(const void* text, size_t length, SkScalar x, SkScalar y,
                          const SkScalar bounds[2], SkScalar* intervals) const;
    int getPosTextIntercepts(const void* text, size_t length, const SkPoint pos[],
                             const SkScalar bounds[2], SkScalar* intervals) const;
    int getPosTextHIntercepts(const void* text, size_t length, const SkScalar xpos[],
                              SkScalar constY, const SkScalar bounds[2], SkScalar* intervals) const;
    int getTextBlobIntercepts(const SkTextBlob* blob, const SkScalar bounds[2],
                              SkScalar* intervals) const;
    SkRect getFontBounds() const;
    bool nothingToDraw() const;
    bool canComputeFastBounds() const;
    const SkRect& computeFastBounds(const SkRect& orig, SkRect* storage) const;
    const SkRect& computeFastStrokeBounds(const SkRect& orig,
                                          SkRect* storage) const;
    const SkRect& doComputeFastBounds(const SkRect& orig, SkRect* storage,
                                      Style style) const;
};

Paint controls options applied when drawing and measuring. Paint collects all options outside of the Canvas Clip and Canvas Matrix.

Various options apply to text, strokes and fills, and images.

Some options may not be implemented on all platforms; in these cases, setting the option has no effect. Some options are conveniences that duplicate Canvas functionality; for instance, text size is identical to matrix scale.

Paint options are rarely exclusive; each option modifies a stage of the drawing pipeline and multiple pipeline stages may be affected by a single Paint.

Paint collects effects and filters that describe single-pass and multiple-pass algorithms that alter the drawing geometry, color, and transparency. For instance, Paint does not directly implement dashing or blur, but contains the objects that do so.

The objects contained by Paint are opaque, and cannot be edited outside of the Paint to affect it. The implementation is free to defer computations associated with the Paint, or ignore them altogether. For instance, some GPU implementations draw all Path geometries with Anti Aliasing, regardless of how SkPaint::kAntiAlias Flag is set in Paint.

Paint describes a single color, a single font, a single image quality, and so on. Multiple colors are drawn either by using multiple paints or with objects like Shader attached to Paint.


SkPaint()

Constructs Paint with default values.

attribute default value
Anti Alias false
Blend Mode SkBlendMode::kSrcOver
Color SK ColorBLACK
Color Alpha 255
Color Filter nullptr
Dither false
Draw Looper nullptr
Fake Bold false
Filter Quality kNone_SkFilterQuality
Font Embedded Bitmaps false
Automatic Hinting false
Full Hinting Spacing false
Hinting kNormal Hinting
Image Filter nullptr
LCD Text false
Linear Text false
Miter Limit 4
Mask Filter nullptr
Path Effect nullptr
Shader nullptr
Style kFill Style
Text Encoding kUTF8 TextEncoding
Text Scale X 1
Text Size 12
Text Skew X 0
Typeface nullptr
Stroke Cap kButt Cap
Stroke Join kMiter Join
Stroke Width 0
Subpixel Text false

The flags, text size, hinting, and miter limit may be overridden at compile time by defining paint default values. The overrides may be included in "SkUserConfig.h" or predefined by the build system.

Return Value

default initialized Paint

Example


SkPaint(const SkPaint& paint)

Makes a shallow copy of SkPaint. SkTypeface, SkPathEffect, SkShader, SkMaskFilter, SkColorFilter, SkDrawLooper, and SkImageFilter are shared between the original paint and the copy. Objects containing SkRefCnt increment their references by one.

The referenced objects SkPathEffect, SkShader, SkMaskFilter, SkColorFilter, SkDrawLooper, and SkImageFilter cannot be modified after they are created. This prevents objects with SkRefCnt from being modified once SkPaint refers to them.

Parameters

paint original to copy

Return Value

shallow copy of paint

Example

Example Output

SK_ColorRED == paint1.getColor()
SK_ColorBLUE == paint2.getColor()


SkPaint(SkPaint&& paint)

Implements a move constructor to avoid increasing the reference counts of objects referenced by the paint.

After the call, paint is undefined, and can be safely destructed.

Parameters

paint original to move

Return Value

content of paint

Example

Example Output

path effect unique: true


void reset()

Sets all SkPaint contents to their initial values. This is equivalent to replacing SkPaint with the result of SkPaint().

Example

Example Output

paint1 == paint2


~SkPaint()

Decreases SkPaint SkRefCnt of owned objects: SkTypeface, SkPathEffect, SkShader, SkMaskFilter, SkColorFilter, SkDrawLooper, and SkImageFilter. If the objects containing SkRefCnt go to zero, they are deleted.


SkPaint& operator=(const SkPaint& paint)

Makes a shallow copy of SkPaint. SkTypeface, SkPathEffect, SkShader, SkMaskFilter, SkColorFilter, SkDrawLooper, and SkImageFilter are shared between the original paint and the copy. Objects containing SkRefCnt in the prior destination are decreased by one, and the referenced objects are deleted if the resulting count is zero. Objects containing SkRefCnt in the parameter paint are increased by one. paint is unmodified.

Parameters

paint original to copy

Return Value

content of paint

Example

Example Output

SK_ColorRED == paint1.getColor()
SK_ColorRED == paint2.getColor()


SkPaint& operator=(SkPaint&& paint)

Moves the paint to avoid increasing the reference counts of objects referenced by the paint parameter. Objects containing SkRefCnt in the prior destination are decreased by one; those objects are deleted if the resulting count is zero.

After the call, paint is undefined, and can be safely destructed.

Parameters

paint original to move

Return Value

content of paint

Example

Example Output

SK_ColorRED == paint2.getColor()


bool operator==(const SkPaint& a, const SkPaint& b)

Compares a and b, and returns true if a and b are equivalent. May return false if SkTypeface, SkPathEffect, SkShader, SkMaskFilter, SkColorFilter, SkDrawLooper, or SkImageFilter have identical contents but different pointers.

Parameters

a SkPaint to compare
b SkPaint to compare

Return Value

true if SkPaint pair are equivalent

Example

Example Output

paint1 == paint2
paint1 != paint2

See Also

operator!=(const SkPaint& a, const SkPaint& b)


bool operator!=(const SkPaint& a, const SkPaint& b)

Compares a and b, and returns true if a and b are not equivalent. May return true if SkTypeface, SkPathEffect, SkShader, SkMaskFilter, SkColorFilter, SkDrawLooper, or SkImageFilter have identical contents but different pointers.

Parameters

a SkPaint to compare
b SkPaint to compare

Return Value

true if SkPaint pair are not equivalent

Example

Example Output

paint1 == paint2
paint1 == paint2

See Also

operator==(const SkPaint& a, const SkPaint& b)


uint32_t getHash() const

Returns a hash generated from SkPaint values and pointers. Identical hashes guarantee that the paints are equivalent, but differing hashes do not guarantee that the paints have differing contents.

If operator==(const SkPaint& a, const SkPaint& b) returns true for two paints, their hashes are also equal.

The hash returned is platform and implementation specific.

Return Value

a shallow hash

Example

Example Output

paint1 == paint2
paint1.getHash() == paint2.getHash()


    enum Hinting {
        kNo_Hinting = 0,
        kSlight_Hinting = 1,
        kNormal_Hinting = 2,
        kFull_Hinting = 3,
    };

Hinting adjusts the glyph outlines so that the shape provides a uniform look at a given point size on font engines that support it. Hinting may have a muted effect or no effect at all depending on the platform.

The four levels roughly control corresponding features on platforms that use FreeType as the Font Engine.

Constants

Const Value Description
SkPaint::kNo_Hinting 0 Leaves glyph outlines unchanged from their native representation. With FreeType, this is equivalent to the FT_LOAD_NO_HINTING bit-field constant supplied to FT_Load_Glyph, which indicates that the vector outline being loaded should not be fitted to the pixel grid but simply scaled to 26.6 fractional pixels.
SkPaint::kSlight_Hinting 1 Modifies glyph outlines minimally to improve constrast. With FreeType, this is equivalent in spirit to the FT_LOAD_TARGET_LIGHT value supplied to FT_Load_Glyph. It chooses a lighter hinting algorithm for non-monochrome modes. Generated Glyphs may be fuzzy but better resemble their original shape.
SkPaint::kNormal_Hinting 2 Modifies glyph outlines to improve constrast. This is the default. With FreeType, this supplies FT_LOAD_TARGET_NORMAL to FT_Load_Glyph, choosing the default hinting algorithm, which is optimized for standard gray-level rendering.
SkPaint::kFull_Hinting 3 Modifies glyph outlines for maximum constrast. With FreeType, this selects FT_LOAD_TARGET_LCD or FT_LOAD_TARGET_LCD_V if kLCDRenderText Flag is set. FT_LOAD_TARGET_LCD is a variant of FT_LOAD_TARGET_NORMAL optimized for horizontally decimated LCD displays; FT_LOAD_TARGET_LCD_V is a variant of FT_LOAD_TARGET_NORMAL optimized for vertically decimated LCD displays.

On OS X and iOS, hinting controls whether Core Graphics dilates the font outlines to account for LCD text. No hinting uses Core Text grayscale output. Normal hinting uses Core Text LCD output. If kLCDRenderText Flag is clear, the LCD output is reduced to a single grayscale channel.

On Windows with DirectWrite, Hinting has no effect.

Hinting defaults to kNormal Hinting. Set SkPaintDefaults Hinting at compile time to change the default setting.


Hinting getHinting() const

Returns level of glyph outline adjustment.

Return Value

one of: kNo_Hinting, kSlight_Hinting, kNormal_Hinting, kFull_Hinting

Example

Example Output

SkPaint::kNormal_Hinting == paint.getHinting()


void setHinting(Hinting hintingLevel)

Sets level of glyph outline adjustment. Does not check for valid values of hintingLevel.

Hinting value effect on generated glyph outlines
kNo Hinting 0 leaves glyph outlines unchanged from their native representation
kSlight Hinting 1 modifies glyph outlines minimally to improve contrast
kNormal Hinting 2 modifies glyph outlines to improve contrast
kFull Hinting 3 modifies glyph outlines for maximum contrast

Parameters

hintingLevel one of: kNo Hinting, kSlight Hinting, kNormal Hinting, kFull Hinting

Example

Example Output

paint1 == paint2


    enum Flags {
        kAntiAlias_Flag = 0x01,
        kDither_Flag = 0x04,
        kFakeBoldText_Flag = 0x20,
        kLinearText_Flag = 0x40,
        kSubpixelText_Flag = 0x80,
        kLCDRenderText_Flag = 0x200,
        kEmbeddedBitmapText_Flag = 0x400,
        kAutoHinting_Flag = 0x800,
        kAllFlags = 0xFFFF,
    };

The bit values stored in Flags. The default value for Flags, normally zero, can be changed at compile time with a custom definition of SkPaintDefaults Flags. All flags can be read and written explicitly; Flags allows manipulating multiple settings at once.

Constants

Flags default to all flags clear, disabling the associated feature.
Const Value Description
SkPaint::kAntiAlias_Flag 0x0001 mask for setting Anti_Alias
SkPaint::kDither_Flag 0x0004 mask for setting Dither
SkPaint::kFakeBoldText_Flag 0x0020 mask for setting Fake_Bold
SkPaint::kLinearText_Flag 0x0040 mask for setting Linear_Text
SkPaint::kSubpixelText_Flag 0x0080 mask for setting Subpixel_Text
SkPaint::kLCDRenderText_Flag 0x0200 mask for setting LCD_Text
SkPaint::kEmbeddedBitmapText_Flag 0x0400 mask for setting Font_Embedded_Bitmaps
SkPaint::kAutoHinting_Flag 0x0800 mask for setting Automatic_Hinting
SkPaint::kAllFlags 0xFFFF mask of all Flags, including private flags and flags reserved for future use


To be deprecated soon.

Only valid for Android framework.

    enum ReserveFlags {
        kUnderlineText_ReserveFlag = 0x08,
        kStrikeThruText_ReserveFlag = 0x10,
    };

Constants

Const Value Description
SkPaint::kUnderlineText_ReserveFlag 0x0008 To be deprecated soon.
SkPaint::kStrikeThruText_ReserveFlag 0x0010 To be deprecated soon.


uint32_t getFlags() const

Returns paint settings described by SkPaint::Flags. Each setting uses one bit, and can be tested with SkPaint::Flags members.

Return Value

zero, one, or more bits described by SkPaint::Flags

Example

Example Output

(SkPaint::kAntiAlias_Flag & paint.getFlags()) != 0


void setFlags(uint32_t flags)

Replaces SkPaint::Flags with flags, the union of the SkPaint::Flags members. All SkPaint::Flags members may be cleared, or one or more may be set.

Parameters

flags union of SkPaint::Flags for SkPaint

Example

Example Output

paint.isAntiAlias()
paint.isDither()


Anti Alias drawing approximates partial pixel coverage with transparency. If kAntiAlias Flag is clear, pixel centers contained by the shape edge are drawn opaque. If kAntiAlias Flag is set, pixels are drawn with Color Alpha equal to their coverage.

The rule for Aliased pixels is inconsistent across platforms. A shape edge passing through the pixel center may, but is not required to, draw the pixel.

Raster Engine draws Aliased pixels whose centers are on or to the right of the start of an active Path edge, and whose center is to the left of the end of the active Path edge.

A platform may only support Anti Aliased drawing. Some GPU-backed platforms use Supersampling to Anti Alias all drawing, and have no mechanism to selectively Alias.

The amount of coverage computed for Anti Aliased pixels also varies across platforms.

Anti Alias is disabled by default. Anti Alias can be enabled by default by setting SkPaintDefaults Flags to kAntiAlias Flag at compile time.

Example

A red line is drawn with transparency on the edges to make it look smoother. A blue line draws only where the pixel centers are contained. The lines are drawn into Bitmap, then drawn magnified to make the Aliasing easier to see.


bool isAntiAlias() const

Returns true if pixels on the active edges of SkPath may be drawn with partial transparency.

Equivalent to getFlags() masked with kAntiAlias_Flag.

Return Value

kAntiAlias_Flag state

Example

Example Output

paint.isAntiAlias() == !!(paint.getFlags() & SkPaint::kAntiAlias_Flag)
paint.isAntiAlias() == !!(paint.getFlags() & SkPaint::kAntiAlias_Flag)


void setAntiAlias(bool aa)

Requests, but does not require, that SkPath edge pixels draw opaque or with partial transparency.

Sets kAntiAlias_Flag if aa is true. Clears kAntiAlias_Flag if aa is false.

Parameters

aa setting for kAntiAlias_Flag

Example

Example Output

paint1 == paint2


Dither increases fidelity by adjusting the color of adjacent pixels. This can help to smooth color transitions and reducing banding in gradients. Dithering lessens visible banding from kRGB_565_SkColorType and kRGBA_8888_SkColorType gradients, and improves rendering into a kRGB_565_SkColorType Surface.

Dithering is always enabled for linear gradients drawing into kRGB_565_SkColorType Surface and kRGBA_8888_SkColorType Surface. Dither cannot be enabled for kAlpha_8_SkColorType Surface and kRGBA_F16_SkColorType Surface.

Dither is disabled by default. Dither can be enabled by default by setting SkPaintDefaults Flags to kDither Flag at compile time.

Some platform implementations may ignore dithering. Set SK_IGNORE_GPU_DITHERto ignore Dither on GPU Surface.

Example

Dithering in the bottom half more closely approximates the requested color by alternating nearby colors from pixel to pixel.

Example

Dithering introduces subtle adjustments to color to smooth gradients. Drawing the gradient repeatedly with SkBlendMode::kPlus exaggerates the dither, making it easier to see.

See Also

Gradient kRGB_565_SkColorType


bool isDither() const

Returns true if color error may be distributed to smooth color transition.

Equivalent to getFlags() masked with kDither_Flag.

Return Value

kDither_Flag state

Example

Example Output

paint.isDither() == !!(paint.getFlags() & SkPaint::kDither_Flag)
paint.isDither() == !!(paint.getFlags() & SkPaint::kDither_Flag)


void setDither(bool dither)

Requests, but does not require, to distribute color error.

Sets kDither_Flag if dither is true. Clears kDither_Flag if dither is false.

Parameters

dither setting for kDither_Flag

Example

Example Output

paint1 == paint2

See Also

kRGB_565_SkColorType


LCD Text and Subpixel Text increase the precision of glyph position.

When set, Flags kLCDRenderText Flag takes advantage of the organization of RGB stripes that create a color, and relies on the small size of the stripe and visual perception to make the color fringing imperceptible. LCD Text can be enabled on devices that orient stripes horizontally or vertically, and that order the color components as RGB or BGR.

Flags kSubpixelText Flag uses the pixel transparency to represent a fractional offset. As the opaqueness of the color increases, the edge of the glyph appears to move towards the outside of the pixel.

Either or both techniques can be enabled. kLCDRenderText Flag and kSubpixelText Flag are clear by default. LCD Text or Subpixel Text can be enabled by default by setting SkPaintDefaults Flags to kLCDRenderText Flag or kSubpixelText Flag (or both) at compile time.

Example

Four commas are drawn normally and with combinations of LCD Text and Subpixel Text. When Subpixel Text is disabled, the comma Glyphs are identical, but not evenly spaced. When Subpixel Text is enabled, the comma Glyphs are unique, but appear evenly spaced.

Linear Text selects whether text is rendered as a Glyph or as a Path. If kLinearText Flag is set, it has the same effect as setting Hinting to kNormal Hinting. If kLinearText Flag is clear, it is the same as setting Hinting to kNo Hinting.


bool isLinearText() const

Returns true if text is converted to SkPath before drawing and measuring.

Equivalent to getFlags() masked with kLinearText_Flag.

Return Value

kLinearText_Flag state

Example

See Also

setLinearText Hinting


void setLinearText(bool linearText)

Returns true if text is converted to SkPath before drawing and measuring. By default, kLinearText_Flag is clear.

Sets kLinearText_Flag if linearText is true. Clears kLinearText_Flag if linearText is false.

Parameters

linearText setting for kLinearText_Flag

Example

See Also

isLinearText Hinting

Flags kSubpixelText Flag uses the pixel transparency to represent a fractional offset. As the opaqueness of the color increases, the edge of the glyph appears to move towards the outside of the pixel.


bool isSubpixelText() const

Returns true if glyphs at different sub-pixel positions may differ on pixel edge coverage.

Equivalent to getFlags() masked with kSubpixelText_Flag.

Return Value

kSubpixelText_Flag state

Example

Example Output

paint.isSubpixelText() == !!(paint.getFlags() & SkPaint::kSubpixelText_Flag)
paint.isSubpixelText() == !!(paint.getFlags() & SkPaint::kSubpixelText_Flag)


void setSubpixelText(bool subpixelText)

Requests, but does not require, that glyphs respect sub-pixel positioning.

Sets kSubpixelText_Flag if subpixelText is true. Clears kSubpixelText_Flag if subpixelText is false.

Parameters

subpixelText setting for kSubpixelText_Flag

Example

Example Output

paint1 == paint2

When set, Flags kLCDRenderText Flag takes advantage of the organization of RGB stripes that create a color, and relies on the small size of the stripe and visual perception to make the color fringing imperceptible. LCD Text can be enabled on devices that orient stripes horizontally or vertically, and that order the color components as RGB or BGR.


bool isLCDRenderText() const

Returns true if glyphs may use LCD striping to improve glyph edges.

Returns true if SkPaint::Flags kLCDRenderText_Flag is set.

Return Value

kLCDRenderText_Flag state

Example

Example Output

paint.isLCDRenderText() == !!(paint.getFlags() & SkPaint::kLCDRenderText_Flag)
paint.isLCDRenderText() == !!(paint.getFlags() & SkPaint::kLCDRenderText_Flag)


void setLCDRenderText(bool lcdText)

Requests, but does not require, that glyphs use LCD striping for glyph edges.

Sets kLCDRenderText_Flag if lcdText is true. Clears kLCDRenderText_Flag if lcdText is false.

Parameters

lcdText setting for kLCDRenderText_Flag

Example

Example Output

paint1 == paint2


Font Embedded Bitmaps allows selecting custom sized bitmap Glyphs. Flags kEmbeddedBitmapText Flag when set chooses an embedded bitmap glyph over an outline contained in a font if the platform supports this option.

FreeType selects the bitmap glyph if available when kEmbeddedBitmapText Flag is set, and selects the outline glyph if kEmbeddedBitmapText Flag is clear. Windows may select the bitmap glyph but is not required to do so. OS X and iOS do not support this option.

Font Embedded Bitmaps is disabled by default. Font Embedded Bitmaps can be enabled by default by setting SkPaintDefaults Flags to kEmbeddedBitmapText Flag at compile time.

Example

The "hintgasp" TrueType font in the Skia resources/fonts directory includes an embedded bitmap Glyph at odd font sizes. This example works on platforms that use FreeType as their Font_Engine. Windows may, but is not required to, return a bitmap glyph if kEmbeddedBitmapText_Flag is set.
SkBitmap bitmap; bitmap.allocN32Pixels(30, 15); bitmap.eraseColor(0); SkCanvas offscreen(bitmap); SkPaint paint; paint.setAntiAlias(true); paint.setTextSize(13); paint.setTypeface(MakeResourceAsTypeface("fonts/hintgasp.ttf")); for (bool embedded : { false, true}) { paint.setEmbeddedBitmapText(embedded); offscreen.drawString("A", embedded ? 5 : 15, 15, paint); } canvas->drawBitmap(bitmap, 0, 0); canvas->scale(10, 10); canvas->drawBitmap(bitmap, -2, 1);


bool isEmbeddedBitmapText() const

Returns true if font engine may return glyphs from font bitmaps instead of from outlines.

Equivalent to getFlags() masked with kEmbeddedBitmapText_Flag.

Return Value

kEmbeddedBitmapText_Flag state

Example

Example Output

paint.isEmbeddedBitmapText() == !!(paint.getFlags() & SkPaint::kEmbeddedBitmapText_Flag)
paint.isEmbeddedBitmapText() == !!(paint.getFlags() & SkPaint::kEmbeddedBitmapText_Flag)


void setEmbeddedBitmapText(bool useEmbeddedBitmapText)

Requests, but does not require, to use bitmaps in fonts instead of outlines.

Sets kEmbeddedBitmapText_Flag if useEmbeddedBitmapText is true. Clears kEmbeddedBitmapText_Flag if useEmbeddedBitmapText is false.

Parameters

useEmbeddedBitmapText setting for kEmbeddedBitmapText_Flag

Example

Example Output

paint1 == paint2

If Hinting is set to kNormal Hinting or kFull Hinting, Automatic Hinting instructs the Font Manager to always hint Glyphs. Automatic Hinting has no effect if Hinting is set to kNo Hinting or kSlight Hinting.

Automatic Hinting only affects platforms that use FreeType as the Font Manager.


bool isAutohinted() const

Returns true if SkPaint::Hinting is set to kNormal_Hinting or kFull_Hinting, and if platform uses FreeType as the font manager. If true, instructs the font manager to always hint glyphs.

Equivalent to getFlags() masked with kAutoHinting_Flag.

Return Value

kAutoHinting_Flag state

Example

Example Output

paint.isAutohinted() == !!(paint.getFlags() & SkPaint::kAutoHinting_Flag)
paint.isAutohinted() == !!(paint.getFlags() & SkPaint::kAutoHinting_Flag)

See Also

setAutohinted Hinting


void setAutohinted(bool useAutohinter)

Sets whether to always hint glyphs. If SkPaint::Hinting is set to kNormal_Hinting or kFull_Hinting and useAutohinter is set, instructs the font manager to always hint glyphs. auto-hinting has no effect if SkPaint::Hinting is set to kNo_Hinting or kSlight_Hinting.

Only affects platforms that use FreeType as the font manager.

Sets kAutoHinting_Flag if useAutohinter is true. Clears kAutoHinting_Flag if useAutohinter is false.

Parameters

useAutohinter setting for kAutoHinting_Flag

Example

See Also

isAutohinted Hinting


Fake Bold approximates the bold font style accompanying a normal font when a bold font face is not available. Skia does not provide font substitution; it is up to the client to find the bold font face using the platform Font Manager.

Use Text Skew X to approximate an italic font style when the italic font face is not available.

A FreeType based port may define SK_USE_FREETYPE_EMBOLDEN at compile time to direct the font engine to create the bold Glyphs. Otherwise, the extra bold is computed by increasing the stroke width and setting the Style to kStrokeAndFill Style as needed.

Fake Bold is disabled by default.

Example


bool isFakeBoldText() const

Returns true if approximate bold by increasing the stroke width when creating glyph bitmaps from outlines.

Equivalent to getFlags() masked with kFakeBoldText_Flag.

Return Value

kFakeBoldText_Flag state

Example

Example Output

paint.isFakeBoldText() == !!(paint.getFlags() & SkPaint::kFakeBoldText_Flag)
paint.isFakeBoldText() == !!(paint.getFlags() & SkPaint::kFakeBoldText_Flag)


void setFakeBoldText(bool fakeBoldText)

Increases stroke width when creating glyph bitmaps to approximate a bold typeface.

Sets kFakeBoldText_Flag if fakeBoldText is true. Clears kFakeBoldText_Flag if fakeBoldText is false.

Parameters

fakeBoldText setting for kFakeBoldText_Flag

Example

Example Output

paint1 == paint2

if Hinting is set to kFull Hinting, Full Hinting Spacing adjusts the character spacing by the difference of the hinted and unhinted Left Side Bearing and Right Side Bearing. Full Hinting Spacing only applies to platforms that use FreeType as their Font Engine.

Full Hinting Spacing is not related to text kerning, where the space between a specific pair of characters is adjusted using data in the font kerning tables.


bool isDevKernText() const

Deprecated.


void setDevKernText(bool)

Deprecated.


Filter Quality trades speed for image filtering when the image is scaled. A lower Filter Quality draws faster, but has less fidelity. A higher Filter Quality draws slower, but looks better. If the image is drawn without scaling, the Filter Quality choice will not result in a noticeable difference.

Filter Quality is used in Paint passed as a parameter to

SkCanvas::drawBitmap
SkCanvas::drawBitmapRect
SkCanvas::drawImage
SkCanvas::drawImageRect

and when Paint has a Shader specialization that uses Image or Bitmap.

Filter Quality is kNone_SkFilterQuality by default.

Example


SkFilterQuality getFilterQuality() const

Returns SkFilterQuality, the image filtering level. A lower setting draws faster; a higher setting looks better when the image is scaled.

Return Value

one of: kNone_SkFilterQuality, kLow_SkFilterQuality,

kMedium_SkFilterQuality, kHigh_SkFilterQuality

Example

Example Output

kNone_SkFilterQuality == paint.getFilterQuality()


void setFilterQuality(SkFilterQuality quality)

Sets SkFilterQuality, the image filtering level. A lower setting draws faster; a higher setting looks better when the image is scaled. Does not check to see if quality is valid.

Parameters

quality one of: kNone_SkFilterQuality, kLow_SkFilterQuality,

kMedium_SkFilterQuality, kHigh_SkFilterQuality

Example

Example Output

kHigh_SkFilterQuality == paint.getFilterQuality()

See Also

SkFilterQuality Image Scaling


name description
getColor returns Color Alpha and RGB, one drawing color
setColor sets Color Alpha and RGB, one drawing color

Color specifies the red, blue, green, and Color Alpha values used to draw a filled or stroked shape in a 32-bit value. Each component occupies 8-bits, ranging from zero: no contribution; to 255: full intensity. All values in any combination are valid.

Color is not Premultiplied; Color Alpha sets the transparency independent of RGB: red, blue, and green.

The bit positions of Color Alpha and RGB are independent of the bit positions on the output device, which may have more or fewer bits, and may have a different arrangement.

bit positions Color Alpha red blue green
31 - 24 23 - 16 15 - 8 7 - 0

Example


SkColor getColor() const

Retrieves alpha and RGB, unpremultiplied, packed into 32 bits. Use helpers SkColorGetA(), SkColorGetR(), SkColorGetG(), and SkColorGetB() to extract a color component.

Return Value

unpremultiplied ARGB

Example

Example Output

Yellow is 100% red, 100% green, and 0% blue.

See Also

getColor4f SkColor


SkColor4f getColor4f() const

Retrieves alpha and RGB, unpremultiplied, as four floating point values. RGB are are extended sRGB values (sRGB gamut, and encoded with the sRGB transfer function).

Return Value

unpremultiplied RGBA

Example

Example Output

Yellow is 100% red, 100% green, and 0% blue.

See Also

getColor SkColor


void setColor(SkColor color)

Sets alpha and RGB used when stroking and filling. The color is a 32-bit value, unpremultiplied, packing 8-bit components for alpha, red, blue, and green.

Parameters

color unpremultiplied ARGB

Example

Example Output

green1 == green2

See Also

SkColor setColor4f setARGB SkColorSetARGB


void setColor4f(const SkColor4f& color, SkColorSpace* colorSpace)

Sets alpha and RGB used when stroking and filling. The color is four floating point values, unpremultiplied. The color values are interpreted as being in the colorSpace. If colorSpace is nullptr, then color is assumed to be in the sRGB color space.

Parameters

color unpremultiplied RGBA
colorSpace SkColorSpace describing the encoding of color

Example

Example Output

green1 == green2

See Also

SkColor setColor setARGB SkColorSetARGB

Color Alpha sets the transparency independent of RGB: red, blue, and green.


uint8_t getAlpha() const

Retrieves alpha from the color used when stroking and filling.

Return Value

alpha ranging from zero, fully transparent, to 255, fully opaque

Example

Example Output

255 == paint.getAlpha()


void setAlpha(U8CPU a)

Replaces alpha, leaving RGB unchanged. An out of range value triggers an assert in the debug build. a is a value from zero to 255. a set to zero makes color fully transparent; a set to 255 makes color fully opaque.

Parameters

a alpha component of color

Example

Example Output

0x44112233 == paint.getColor()


void setARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b)

Sets color used when drawing solid fills. The color components range from 0 to 255. The color is unpremultiplied; alpha sets the transparency independent of RGB.

Parameters

a amount of alpha, from fully transparent (0) to fully opaque (255)
r amount of red, from no red (0) to full red (255)
g amount of green, from no green (0) to full green (255)
b amount of blue, from no blue (0) to full blue (255)

Example

Example Output

transRed1 == transRed2

See Also

setColor SkColorSetARGB


Style specifies if the geometry is filled, stroked, or both filled and stroked. Some shapes ignore Style and are always drawn filled or stroked.

Set Style to kFill Style to fill the shape. The fill covers the area inside the geometry for most shapes.

Set Style to kStroke Style to stroke the shape.

The stroke covers the area described by following the shape edge with a pen or brush of Stroke Width. The area covered where the shape starts and stops is described by Stroke Cap. The area covered where the shape turns a corner is described by Stroke Join. The stroke is centered on the shape; it extends equally on either side of the shape edge.As Stroke Width gets smaller, the drawn path frame is thinner. Stroke Width less than one may have gaps, and if kAntiAlias Flag is set, Color Alpha will increase to visually decrease coverage.

See Also

Path Fill Type Path Effect Style Fill Style Stroke


Stroke Width of zero has a special meaning and switches drawing to use Hairline. Hairline draws the thinnest continuous frame. If kAntiAlias Flag is clear, adjacent pixels flow horizontally, vertically,or diagonally.

Path drawing with Hairline may hit the same pixel more than once. For instance, Path containing two lines in one Path Contour will draw the corner point once, but may both lines may draw the adjacent pixel. If kAntiAlias Flag is set, transparency is applied twice, resulting in a darker pixel. Some GPU-backed implementations apply transparency at a later drawing stage, avoiding double hit pixels while stroking.

See Also

Path Fill Type Path Effect Style Fill Style Stroke


    enum Style {
        kFill_Style,
        kStroke_Style,
        kStrokeAndFill_Style,
    };
    static constexpr int kStyleCount = kStrokeAndFill_Style + 1;

Set Style to fill, stroke, or both fill and stroke geometry. The stroke and fill share all paint attributes; for instance, they are drawn with the same color.

Use kStrokeAndFill Style to avoid hitting the same pixels twice with a stroke draw and a fill draw.

Constants

Const Value Description
SkPaint::kFill_Style 0 Applies to Rect, Region, Round Rect, Circles, Ovals, Path, and Text. Bitmap, Image, Patches, Region, Sprites, and Vertices are painted as if kFill Style is set, and ignore the set Style. The Path Fill Type specifies additional rules to fill the area outside the path edge, and to create an unfilled hole inside the shape. Style is set to kFill Style by default.
SkPaint::kStroke_Style 1 Applies to Rect, Region, Round Rect, Arcs, Circles, Ovals, Path, and Text. Arcs, Lines, and points, are always drawn as if kStroke Style is set, and ignore the set Style. The stroke construction is unaffected by the Path Fill Type.
SkPaint::kStrokeAndFill_Style 2 Applies to Rect, Region, Round Rect, Circles, Ovals, Path, and Text. Path is treated as if it is set to SkPath::kWinding FillType, and the set Path Fill Type is ignored.
SkPaint::kStyleCount 3 May be used to verify that Style is a legal value.


Style getStyle() const

Returns whether the geometry is filled, stroked, or filled and stroked.

Return Value

one of:kFill_Style, kStroke_Style, kStrokeAndFill_Style

Example

Example Output

SkPaint::kFill_Style == paint.getStyle()

See Also

Style setStyle


void setStyle(Style style)

Sets whether the geometry is filled, stroked, or filled and stroked. Has no effect if style is not a legal SkPaint::Style value.

Parameters

style one of: kFill_Style, kStroke_Style, kStrokeAndFill_Style

Example

See Also

Style getStyle


Stroke Width sets the width for stroking. The width is the thickness of the stroke perpendicular to the path direction when the paint style is set to kStroke Style or kStrokeAndFill Style.

When width is greater than zero, the stroke encompasses as many pixels partially or fully as needed. When the width equals zero, the paint enables hairlines; the stroke is always one pixel wide.

The stroke dimensions are scaled by the canvas matrix, but Hairline stroke remains one pixel wide regardless of scaling.

The default width for the paint is zero.

Example

The pixels hit to represent thin lines vary with the angle of the line and the platform implementation.


SkScalar getStrokeWidth() const

Returns the thickness of the pen used by SkPaint to outline the shape.

Return Value

zero for hairline, greater than zero for pen thickness

Example

Example Output

0 == paint.getStrokeWidth()


void setStrokeWidth(SkScalar width)

Sets the thickness of the pen used by the paint to outline the shape. Has no effect if width is less than zero.

Parameters

width zero thickness for hairline; greater than zero for pen thickness

Example

Example Output

5 == paint.getStrokeWidth()


Miter Limit specifies the maximum miter length, relative to the stroke width.

Miter Limit is used when the Stroke Join is set to kMiter Join, and the Style is either kStroke Style or kStrokeAndFill Style.

If the miter at a corner exceeds this limit, kMiter Join is replaced with kBevel Join.

Miter Limit can be computed from the corner angle using: miter limit = 1 / sin ( angle / 2 ).

Miter Limit default value is 4. The default may be changed at compile time by setting SkPaintDefaults MiterLimit in "SkUserConfig.h" or as a define supplied by the build environment.

Here are some miter limits and the angles that triggers them.

miter limit angle in degrees
10 11.48
9 12.76
8 14.36
7 16.43
6 19.19
5 23.07
4 28.96
3 38.94
2 60
1 180

Example

This example draws a stroked corner and the miter length beneath. When the miter limit is decreased slightly, the miter join is replaced by a bevel join.


SkScalar getStrokeMiter() const

Returns the limit at which a sharp corner is drawn beveled.

Return Value

zero and greater miter limit

Example

Example Output

default miter limit == 4

See Also

Miter Limit setStrokeMiter Join


void setStrokeMiter(SkScalar miter)

Sets the limit at which a sharp corner is drawn beveled. Valid values are zero and greater. Has no effect if miter is less than zero.

Parameters

miter zero and greater miter limit

Example

Example Output

default miter limit == 8

See Also

Miter Limit getStrokeMiter Join


    enum Cap {
        kButt_Cap,
        kRound_Cap,
        kSquare_Cap,
        kLast_Cap = kSquare_Cap,
        kDefault_Cap = kButt_Cap,
    };
    static constexpr int kCapCount = kLast_Cap + 1;

Stroke Cap draws at the beginning and end of an open Path Contour.

Constants

Const Value Description
SkPaint::kButt_Cap 0 Does not extend the stroke past the beginning or the end.
SkPaint::kRound_Cap 1 Adds a circle with a diameter equal to Stroke Width at the beginning and end.
SkPaint::kSquare_Cap 2 Adds a square with sides equal to Stroke Width at the beginning and end. The square sides are parallel to the initial and final direction of the stroke.
SkPaint::kLast_Cap 2 Equivalent to the largest value for Stroke Cap.
SkPaint::kDefault_Cap 0 Stroke Cap is set to kButt Cap by default.
SkPaint::kCapCount 3 May be used to verify that Stroke Cap is a legal value.

Stroke describes the area covered by a pen of Stroke Width as it follows the Path Contour, moving parallel to the contour direction.

If the Path Contour is not terminated by SkPath::kClose Verb, the contour has a visible beginning and end.

Path Contour may start and end at the same point; defining Zero Length Contour.

kButt Cap and Zero Length Contour is not drawn. kRound Cap and Zero Length Contour draws a circle of diameter Stroke Width at the contour point. kSquare Cap and Zero Length Contour draws an upright square with a side of Stroke Width at the contour point.

Stroke Cap is kButt Cap by default.

Example


Cap getStrokeCap() const

Returns the geometry drawn at the beginning and end of strokes.

Return Value

one of: kButt_Cap, kRound_Cap, kSquare_Cap

Example

Example Output

kButt_Cap == default stroke cap

See Also

Stroke Cap setStrokeCap


void setStrokeCap(Cap cap)

Sets the geometry drawn at the beginning and end of strokes.

Parameters

cap one of: kButt_Cap, kRound_Cap, kSquare_Cap;

has no effect if cap is not valid

Example

Example Output

kRound_Cap == paint.getStrokeCap()

See Also

Stroke Cap getStrokeCap

Stroke Join draws at the sharp corners of an open or closed Path Contour.

Stroke describes the area covered by a pen of Stroke Width as it follows the Path Contour, moving parallel to the contour direction.

If the contour direction changes abruptly, because the tangent direction leading to the end of a curve within the contour does not match the tangent direction of the following curve, the pair of curves meet at Stroke Join.

Example


    enum Join {
        kMiter_Join,
        kRound_Join,
        kBevel_Join,
        kLast_Join = kBevel_Join,
        kDefault_Join = kMiter_Join,
    };
    static constexpr int kJoinCount = kLast_Join + 1;

Join specifies how corners are drawn when a shape is stroked. Join affects the four corners of a stroked rectangle, and the connected segments in a stroked path.

Choose miter join to draw sharp corners. Choose round join to draw a circle with a radius equal to the stroke width on top of the corner. Choose bevel join to minimally connect the thick strokes.

The fill path constructed to describe the stroked path respects the join setting but may not contain the actual join. For instance, a fill path constructed with round joins does not necessarily include circles at each connected segment.

Constants

Const Value Description
SkPaint::kMiter_Join 0 Extends the outside corner to the extent allowed by Miter Limit. If the extension exceeds Miter Limit, kBevel Join is used instead.
SkPaint::kRound_Join 1 Adds a circle with a diameter of Stroke Width at the sharp corner.
SkPaint::kBevel_Join 2 Connects the outside edges of the sharp corner.
SkPaint::kLast_Join 2 equivalent to the largest value for Stroke_Join
SkPaint::kDefault_Join 1 Stroke Join is set to kMiter Join by default.
SkPaint::kJoinCount 3 May be used to verify that Stroke Join is a legal value.

Example

See Also

setStrokeJoin getStrokeJoin setStrokeMiter getStrokeMiter


Join getStrokeJoin() const

Returns the geometry drawn at the corners of strokes.

Return Value

one of: kMiter_Join, kRound_Join, kBevel_Join

Example

Example Output

kMiter_Join == default stroke join

See Also

Stroke Join setStrokeJoin


void setStrokeJoin(Join join)

Sets the geometry drawn at the corners of strokes.

Parameters

join one of: kMiter_Join, kRound_Join, kBevel_Join;

otherwise, has no effect

Example

Example Output

kMiter_Join == paint.getStrokeJoin()

See Also

Stroke Join getStrokeJoin

See Also

Miter Limit


Fill Path creates a Path by applying the Path Effect, followed by the Style Stroke.

If Paint contains Path Effect, Path Effect operates on the source Path; the result replaces the destination Path. Otherwise, the source Path is replaces the destination Path.

Fill Path can request the Path Effect to restrict to a culling rectangle, but the Path Effect is not required to do so.

If Style is kStroke Style or kStrokeAndFill Style, and Stroke Width is greater than zero, the Stroke Width, Stroke Cap, Stroke Join, and Miter Limit operate on the destination Path, replacing it.

Fill Path can specify the precision used by Stroke Width to approximate the stroke geometry.

If the Style is kStroke Style and the Stroke Width is zero, getFillPath returns false since Hairline has no filled equivalent.

See Also

Style Stroke Stroke Width Path Effect


bool getFillPath(const SkPath& src, SkPath* dst, const SkRect* cullRect, SkScalar resScale = 1) const

Returns the filled equivalent of the stroked path.

Parameters

src SkPath read to create a filled version
dst resulting SkPath; may be the same as src, but may not be nullptr
cullRect optional limit passed to SkPathEffect
resScale if > 1, increase precision, else if (0 < resScale < 1) reduce precision

to favor speed and size

Return Value

true if the path represents style fill, or false if it represents hairline

Example

A very small Quad stroke is turned into a filled path with increasing levels of precision. At the lowest precision, the Quad stroke is approximated by a rectangle. At the highest precision, the filled path has high fidelity compared to the original stroke.


bool getFillPath(const SkPath& src, SkPath* dst) const

Returns the filled equivalent of the stroked path.

Replaces dst with the src path modified by SkPathEffect and style stroke. SkPathEffect, if any, is not culled. stroke width is created with default precision.

Parameters

src SkPath read to create a filled version
dst resulting SkPath dst may be the same as src, but may not be nullptr

Return Value

true if the path represents style fill, or false if it represents hairline

Example


Shader defines the colors used when drawing a shape. Shader may be an image, a gradient, or a computed fill. If Paint has no Shader, then Color fills the shape.

Shader is modulated by Color Alpha component of Color. If Shader object defines only Color Alpha, then Color modulated by Color Alpha describes the fill.

The drawn transparency can be modified without altering Shader, by changing Color Alpha.

Example

If Shader generates only Color Alpha then all components of Color modulate the output.

Example


SkShader* getShader() const

Returns optional colors used when filling a path, such as a gradient.

Does not alter SkShader SkRefCnt.

Return Value

SkShader if previously set, nullptr otherwise

Example

Example Output

nullptr == shader
nullptr != shader


sk sp<SkShader> refShader() const

Returns optional colors used when filling a path, such as a gradient.

Increases SkShader SkRefCnt by one.

Return Value

SkShader if previously set, nullptr otherwise

Example

Example Output

shader unique: true
shader unique: false


void setShader(sk sp<SkShader> shader)

Sets optional colors used when filling a path, such as a gradient.

Sets SkShader to shader, decreasing SkRefCnt of the previous SkShader. Increments shader SkRefCnt by one.

Parameters

shader how geometry is filled with color; if nullptr, color is used instead

Example


Color Filter alters the color used when drawing a shape. Color Filter may apply Blend Mode, transform the color through a matrix, or composite multiple filters. If Paint has no Color Filter, the color is unaltered.

The drawn transparency can be modified without altering Color Filter, by changing Color Alpha.

Example


SkColorFilter* getColorFilter() const

Returns SkColorFilter if set, or nullptr. Does not alter SkColorFilter SkRefCnt.

Return Value

SkColorFilter if previously set, nullptr otherwise

Example

Example Output

nullptr == color filter
nullptr != color filter


sk sp<SkColorFilter> refColorFilter() const

Returns SkColorFilter if set, or nullptr. Increases SkColorFilter SkRefCnt by one.

Return Value

SkColorFilter if set, or nullptr

Example

Example Output

color filter unique: true
color filter unique: false


void setColorFilter(sk sp<SkColorFilter> colorFilter)

Sets SkColorFilter to filter, decreasing SkRefCnt of the previous SkColorFilter. Pass nullptr to clear SkColorFilter.

Increments filter SkRefCnt by one.

Parameters

colorFilter SkColorFilter to apply to subsequent draw

Example


Blend Mode describes how Color combines with the destination color. The default setting, SkBlendMode::kSrcOver, draws the source color over the destination color.

Example

See Also

Blend Mode


SkBlendMode getBlendMode() const

Returns SkBlendMode. By default, returns SkBlendMode::kSrcOver.

Return Value

mode used to combine source color with destination color

Example

Example Output

kSrcOver == getBlendMode
kSrcOver != getBlendMode


bool isSrcOver() const

Returns true if SkBlendMode is SkBlendMode::kSrcOver, the default.

Return Value

true if SkBlendMode is SkBlendMode::kSrcOver

Example

Example Output

isSrcOver == true
isSrcOver != true


void setBlendMode(SkBlendMode mode)

Sets SkBlendMode to mode. Does not check for valid input.

Parameters

mode SkBlendMode used to combine source color and destination

Example

Example Output

isSrcOver == true
isSrcOver != true


Path Effect modifies the path geometry before drawing it. Path Effect may implement dashing, custom fill effects and custom stroke effects. If Paint has no Path Effect, the path geometry is unaltered when filled or stroked.

Example

See Also

Path Effect


SkPathEffect* getPathEffect() const

Returns SkPathEffect if set, or nullptr. Does not alter SkPathEffect SkRefCnt.

Return Value

SkPathEffect if previously set, nullptr otherwise

Example

Example Output

nullptr == path effect
nullptr != path effect


sk sp<SkPathEffect> refPathEffect() const

Returns SkPathEffect if set, or nullptr. Increases SkPathEffect SkRefCnt by one.

Return Value

SkPathEffect if previously set, nullptr otherwise

Example

Example Output

path effect unique: true
path effect unique: false


void setPathEffect(sk sp<SkPathEffect> pathEffect)

Sets SkPathEffect to pathEffect, decreasing SkRefCnt of the previous SkPathEffect. Pass nullptr to leave the path geometry unaltered.

Increments pathEffect SkRefCnt by one.

Parameters

pathEffect replace SkPath with a modification when drawn

Example


Mask Filter uses coverage of the shape drawn to create Mask Alpha. Mask Filter takes a Mask, and returns a Mask.

Mask Filter may change the geometry and transparency of the shape, such as creating a blur effect. Set Mask Filter to nullptr to prevent Mask Filter from modifying the draw.

Example


SkMaskFilter* getMaskFilter() const

Returns SkMaskFilter if set, or nullptr. Does not alter SkMaskFilter SkRefCnt.

Return Value

SkMaskFilter if previously set, nullptr otherwise

Example

Example Output

nullptr == mask filter
nullptr != mask filter


sk sp<SkMaskFilter> refMaskFilter() const

Returns SkMaskFilter if set, or nullptr.

Increases SkMaskFilter SkRefCnt by one.

Return Value

SkMaskFilter if previously set, nullptr otherwise

Example

Example Output

mask filter unique: true
mask filter unique: false


void setMaskFilter(sk sp<SkMaskFilter> maskFilter)

Sets SkMaskFilter to maskFilter, decreasing SkRefCnt of the previous SkMaskFilter. Pass nullptr to clear SkMaskFilter and leave SkMaskFilter effect on mask alpha unaltered.

Increments maskFilter SkRefCnt by one.

Parameters

maskFilter modifies clipping mask generated from drawn geometry

Example


Typeface identifies the font used when drawing and measuring text. Typeface may be specified by name, from a file, or from a data stream. The default Typeface defers to the platform-specific default font implementation.

Example


SkTypeface* getTypeface() const

Returns SkTypeface if set, or nullptr. Does not alter SkTypeface SkRefCnt.

Return Value

SkTypeface if previously set, nullptr otherwise

Example

Example Output

nullptr == typeface
nullptr != typeface


sk sp<SkTypeface> refTypeface() const

Increases SkTypeface SkRefCnt by one.

Return Value

SkTypeface if previously set, nullptr otherwise

Example

Example Output

typeface1 != typeface2
typeface1 == typeface2


void setTypeface(sk sp<SkTypeface> typeface)

Sets SkTypeface to typeface, decreasing SkRefCnt of the previous SkTypeface. Pass nullptr to clear SkTypeface and use the default typeface. Increments typeface SkRefCnt by one.

Parameters

typeface font and style used to draw text

Example


Image Filter operates on the pixel representation of the shape, as modified by Paint with Blend Mode set to SkBlendMode::kSrcOver. Image Filter creates a new bitmap, which is drawn to the device using the set Blend Mode.

Image Filter is higher level than Mask Filter; for instance, an Image Filter can operate on all channels of Color, while Mask Filter generates Alpha only. Image Filter operates independently of and can be used in combination with Mask Filter.

Example


SkImageFilter* getImageFilter() const

Returns SkImageFilter if set, or nullptr. Does not alter SkImageFilter SkRefCnt.

Return Value

SkImageFilter if previously set, nullptr otherwise

Example

Example Output

nullptr == image filter
nullptr != image filter


sk sp<SkImageFilter> refImageFilter() const

Returns SkImageFilter if set, or nullptr. Increases SkImageFilter SkRefCnt by one.

Return Value

SkImageFilter if previously set, nullptr otherwise

Example

Example Output

image filter unique: true
image filter unique: false


void setImageFilter(sk sp<SkImageFilter> imageFilter)

Sets SkImageFilter to imageFilter, decreasing SkRefCnt of the previous SkImageFilter. Pass nullptr to clear SkImageFilter, and remove SkImageFilter effect on drawing.

Increments imageFilter SkRefCnt by one.

Parameters

imageFilter how SkImage is sampled when transformed

Example


Draw Looper sets a modifier that communicates state from one Draw Layer to another to construct the draw.

Draw Looper draws one or more times, modifying the canvas and paint each time. Draw Looper may be used to draw multiple colors or create a colored shadow. Set Draw Looper to nullptr to prevent Draw Looper from modifying the draw.

Example


SkDrawLooper* getDrawLooper() const

Returns SkDrawLooper if set, or nullptr. Does not alter SkDrawLooper SkRefCnt.

Return Value

SkDrawLooper if previously set, nullptr otherwise

Example

Example Output

nullptr == draw looper
nullptr != draw looper


sk sp<SkDrawLooper> refDrawLooper() const

Returns SkDrawLooper if set, or nullptr. Increases SkDrawLooper SkRefCnt by one.

Return Value

SkDrawLooper if previously set, nullptr otherwise

Example

Example Output

draw looper unique: true
draw looper unique: false


SkDrawLooper* getLooper() const

Deprecated.


void setDrawLooper(sk sp<SkDrawLooper> drawLooper)

Sets SkDrawLooper to drawLooper, decreasing SkRefCnt of the previous drawLooper. Pass nullptr to clear SkDrawLooper and leave SkDrawLooper effect on drawing unaltered.

Increments drawLooper SkRefCnt by one.

Parameters

drawLooper iterates through drawing one or more time, altering SkPaint

Example


void setLooper(sk sp<SkDrawLooper> drawLooper)

Deprecated.


Text Size adjusts the overall text size in points. Text Size can be set to any positive value or zero. Text Size defaults to 12. Set SkPaintDefaults TextSize at compile time to change the default setting.

Example


SkScalar getTextSize() const

Returns text size in points.

Return Value

typographic height of text

Example


void setTextSize(SkScalar textSize)

Sets text size in points. Has no effect if textSize is not greater than or equal to zero.

Parameters

textSize typographic height of text

Example


Text Scale X adjusts the text horizontal scale. Text scaling approximates condensed and expanded type faces when the actual face is not available. Text Scale X can be set to any value. Text Scale X defaults to 1.

Example


SkScalar getTextScaleX() const

Returns text scale on x-axis. Default value is 1.

Return Value

text horizontal scale

Example


void setTextScaleX(SkScalar scaleX)

Sets text scale on x-axis. Default value is 1.

Parameters

scaleX text horizontal scale

Example


Text Skew X adjusts the text horizontal slant. Text skewing approximates italic and oblique type faces when the actual face is not available. Text Skew X can be set to any value. Text Skew X defaults to 0.

Example


SkScalar getTextSkewX() const

Returns text skew on x-axis. Default value is zero.

Return Value

additional shear on x-axis relative to y-axis

Example


void setTextSkewX(SkScalar skewX)

Sets text skew on x-axis. Default value is zero.

Parameters

skewX additional shear on x-axis relative to y-axis

Example



    enum TextEncoding {
        kUTF8_TextEncoding,
        kUTF16_TextEncoding,
        kUTF32_TextEncoding,
        kGlyphID_TextEncoding,
    };

TextEncoding determines whether text specifies character codes and their encoded size, or glyph indices. Characters are encoded as specified by the Unicode standard .

Character codes encoded size are specified by UTF-8, UTF-16, or UTF-32. All character code formats are able to represent all of Unicode, differing only in the total storage required.

UTF-8 (RFC 3629) encodes each character as one or more 8-bit bytes.

UTF-16 (RFC 2781) encodes each character as one or two 16-bit words.

UTF-32 encodes each character as one 32-bit word.

Font Manager uses font data to convert character code points into glyph indices. A glyph index is a 16-bit word.

TextEncoding is set to kUTF8 TextEncoding by default.

Constants

Const Value Description
SkPaint::kUTF8_TextEncoding 0 uses bytes to represent UTF-8 or ASCII
SkPaint::kUTF16_TextEncoding 1 uses two byte words to represent most of Unicode
SkPaint::kUTF32_TextEncoding 2 uses four byte words to represent all of Unicode
SkPaint::kGlyphID_TextEncoding 3 uses two byte words to represent glyph indices

Example

First line is encoded in UTF-8. Second line is encoded in UTF-16. Third line is encoded in UTF-32. Fourth line has 16-bit glyph indices.


TextEncoding getTextEncoding() const

Returns SkPaint::TextEncoding. SkPaint::TextEncoding determines how character code points are mapped to font glyph indices.

Return Value

one of: kUTF8_TextEncoding, kUTF16_TextEncoding, kUTF32_TextEncoding, or

kGlyphID_TextEncoding

Example

Example Output

kUTF8_TextEncoding == text encoding
kGlyphID_TextEncoding == text encoding


void setTextEncoding(TextEncoding encoding)

Sets SkPaint::TextEncoding to encoding. SkPaint::TextEncoding determines how character code points are mapped to font glyph indices. Invalid values for encoding are ignored.

Parameters

encoding one of: kUTF8_TextEncoding, kUTF16_TextEncoding, kUTF32_TextEncoding, or

kGlyphID_TextEncoding

Example

Example Output

4 != text encoding


Font Metrics describe dimensions common to the Glyphs in Typeface. The dimensions are computed by Font Manager from font data and do not take Paint settings other than Text Size into account.

Font dimensions specify the anchor to the left of the glyph at baseline as the origin. X-axis values to the left of the glyph are negative, and to the right of the left glyph edge are positive. Y-axis values above the baseline are negative, and below the baseline are positive.

Example


    struct FontMetrics {
        enum FontMetricsFlags {
            kUnderlineThicknessIsValid_Flag = 1 << 0,
            kUnderlinePositionIsValid_Flag = 1 << 1,
            kStrikeoutThicknessIsValid_Flag = 1 << 2,
            kStrikeoutPositionIsValid_Flag = 1 << 3,
        };

        uint32_t fFlags;
        SkScalar fTop;
        SkScalar fAscent;
        SkScalar fDescent;
        SkScalar fBottom;
        SkScalar fLeading;
        SkScalar fAvgCharWidth;
        SkScalar fMaxCharWidth;
        SkScalar fXMin;
        SkScalar fXMax;
        SkScalar fXHeight;
        SkScalar fCapHeight;
        SkScalar fUnderlineThickness;
        SkScalar fUnderlinePosition;
        SkScalar fStrikeoutThickness;
        SkScalar fStrikeoutPosition;

        bool hasUnderlineThickness(SkScalar* thickness) const;
        bool hasUnderlinePosition(SkScalar* position) const;
        bool hasStrikeoutThickness(SkScalar* thickness) const;
        bool hasStrikeoutPosition(SkScalar* position) const;
    };

FontMetrics is filled out by getFontMetrics. FontMetrics contents reflect the values computed by Font Manager using Typeface. Values are set to zero if they are not available.

All vertical values are relative to the baseline, on a y-axis pointing down. Zero is on the baseline, negative values are above the baseline, and positive values are below the baseline.

fUnderlineThickness and fUnderlinePosition have a bit set in fFlags if their values are valid, since their value may be zero.

fStrikeoutThickness and fStrikeoutPosition have a bit set in fFlags if their values are valid, since their value may be zero.


        enum FontMetricsFlags {
            kUnderlineThicknessIsValid_Flag = 1 << 0,
            kUnderlinePositionIsValid_Flag = 1 << 1,
            kStrikeoutThicknessIsValid_Flag = 1 << 2,
            kStrikeoutPositionIsValid_Flag = 1 << 3,
        };

FontMetricsFlags are set in fFlags when underline and strikeout metrics are valid; the underline or strikeout metric may be valid and zero. Fonts with embedded bitmaps may not have valid underline or strikeout metrics.

Constants

Const Value Description
SkPaint::FontMetrics::kUnderlineThicknessIsValid_Flag 0x0001 set if fUnderlineThickness is valid
SkPaint::FontMetrics::kUnderlinePositionIsValid_Flag 0x0002 set if fUnderlinePosition is valid
SkPaint::FontMetrics::kStrikeoutThicknessIsValid_Flag 0x0004 set if fStrikeoutThickness is valid
SkPaint::FontMetrics::kStrikeoutPositionIsValid_Flag 0x0008 set if fStrikeoutPosition is valid
Type Member Description
uint32_t fFlags is set to FontMetricsFlags when metrics are valid
SkScalar fTop Greatest extent above the baseline for any glyph. Typically less than zero.
SkScalar fAscent Recommended distance above the baseline to reserve for a line of text. Typically less than zero.
SkScalar fDescent Recommended distance below the baseline to reserve for a line of text. Typically greater than zero.
SkScalar fBottom Greatest extent below the baseline for any glyph. Typically greater than zero.
SkScalar fLeading Recommended distance to add between lines of text. Typically greater than or equal to zero.
SkScalar fAvgCharWidth Average character width, if it is available. Zero if no average width is stored in the font.
SkScalar fMaxCharWidth maximum character width
SkScalar fXMin Minimum bounding box x-axis value for all Glyphs. Typically less than zero.
SkScalar fXMax Maximum bounding box x-axis value for all Glyphs. Typically greater than zero.
SkScalar fXHeight May be zero if no lower-case height is stored in the font.
SkScalar fCapHeight May be zero if no upper-case height is stored in the font.
SkScalar fUnderlineThickness If the metric is valid, the kUnderlineThicknessIsValid Flag is set in fFlags. If kUnderlineThicknessIsValid Flag is clear, fUnderlineThickness is zero.
SkScalar fUnderlinePosition Position of the top of the underline stroke relative to the baseline. Typically positive when valid.

If the metric is valid, the kUnderlinePositionIsValid Flag is set in fFlags. If kUnderlinePositionIsValid Flag is clear, fUnderlinePosition is zero.

SkScalar fStrikeoutThickness If the metric is valid, the kStrikeoutThicknessIsValid Flag is set in fFlags. If kStrikeoutThicknessIsValid Flag is clear, fStrikeoutThickness is zero.
SkScalar fStrikeoutPosition Position of the bottom of the strikeout stroke relative to the baseline. Typically negative when valid.

If the metric is valid, the kStrikeoutPositionIsValid Flag is set in fFlags. If kStrikeoutPositionIsValid Flag is clear, fStrikeoutPosition is zero.


bool hasUnderlineThickness(SkScalar* thickness) const

Returns true if SkPaint::FontMetrics has a valid underline thickness, and sets thickness to that value. If the underline thickness is not valid, return false, and ignore thickness.

Parameters

thickness storage for underline width

Return Value

true if font specifies underline width


bool hasUnderlinePosition(SkScalar* position) const

Returns true if SkPaint::FontMetrics has a valid underline position, and sets position to that value. If the underline position is not valid, return false, and ignore position.

Parameters

position storage for underline position

Return Value

true if font specifies underline position


bool hasStrikeoutThickness(SkScalar* thickness) const

Returns true if SkPaint::FontMetrics has a valid strikeout thickness, and sets thickness to that value. If the underline thickness is not valid, return false, and ignore thickness.

Parameters

thickness storage for strikeout width

Return Value

true if font specifies strikeout width


bool hasStrikeoutPosition(SkScalar* position) const

Returns true if SkPaint::FontMetrics has a valid strikeout position, and sets position to that value. If the underline position is not valid, return false, and ignore position.

Parameters

position storage for strikeout position

Return Value

true if font specifies strikeout position


SkScalar getFontMetrics(FontMetrics* metrics) const

Returns SkPaint::FontMetrics associated with SkTypeface. The return value is the recommended spacing between lines: the sum of metrics descent, ascent, and leading. If metrics is not nullptr, SkPaint::FontMetrics is copied to metrics. Results are scaled by text size but does not take into account dimensions required by text scale x, text skew x, fake bold, style stroke, and SkPathEffect.

Parameters

metrics storage for SkPaint::FontMetrics from SkTypeface; may be nullptr

Return Value

recommended spacing between lines

Example

See Also

Text Size Typeface Typeface Methods


SkScalar getFontSpacing() const

Returns the recommended spacing between lines: the sum of metrics descent, ascent, and leading. Result is scaled by text size but does not take into account dimensions required by stroking and SkPathEffect. Returns the same result as getFontMetrics().

Return Value

recommended spacing between lines

Example

Example Output

textSize: 12 fontSpacing: 13.9688
textSize: 18 fontSpacing: 20.9531
textSize: 24 fontSpacing: 27.9375
textSize: 32 fontSpacing: 37.25


SkRect getFontBounds() const

Returns the union of bounds of all glyphs. Returned dimensions are computed by font manager from font data, ignoring SkPaint::Hinting. Includes text size, text scale x, and text skew x, but not fake bold or SkPathEffect.

If text size is large, text scale x is one, and text skew x is zero, returns the same bounds as: { FontMetrics::fXMin, FontMetrics::fTop, FontMetrics::fXMax, FontMetrics::fBottom }.

Return Value

union of bounds of all glyphs

Example

Example Output

metrics bounds = { -12.2461, -14.7891, 21.5215, 5.55469 }
font bounds    = { -12.2461, -14.7891, 21.5215, 5.55469 }


int textToGlyphs(const void* text, size_t byteLength, SkGlyphID glyphs[]) const

Converts text into glyph indices. Returns the number of glyph indices represented by text. SkPaint::TextEncoding specifies how text represents characters or glyphs. glyphs may be nullptr, to compute the glyph count.

Does not check text for valid character codes or valid glyph indices.

If byteLength equals zero, returns zero. If byteLength includes a partial character, the partial character is ignored.

If SkPaint::TextEncoding is kUTF8_TextEncoding and text contains an invalid UTF-8 sequence, zero is returned.

Parameters

text character storage encoded with SkPaint::TextEncoding
byteLength length of character storage in bytes
glyphs storage for glyph indices; may be nullptr

Return Value

number of glyphs represented by text of length byteLength

Example


int countText(const void* text, size_t byteLength) const

Returns the number of glyphs in text. Uses SkPaint::TextEncoding to count the glyphs. Returns the same result as textToGlyphs().

Parameters

text character storage encoded with SkPaint::TextEncoding
byteLength length of character storage in bytes

Return Value

number of glyphs represented by text of length byteLength

Example

Example Output

count = 5


bool containsText(const void* text, size_t byteLength) const

Returns true if all text corresponds to a non-zero glyph index. Returns false if any characters in text are not supported in SkTypeface.

If SkPaint::TextEncoding is kGlyphID_TextEncoding, returns true if all glyph indices in text are non-zero; does not check to see if text contains valid glyph indices for SkTypeface.

Returns true if byteLength is zero.

Parameters

text array of characters or glyphs
byteLength number of bytes in text array

Return Value

true if all text corresponds to a non-zero glyph index

containsText succeeds for degree symbol, but cannot find a glyph index corresponding to the Unicode surrogate code point.

Example Output

0x00b0 == has char
0xd800 != has char

Example

containsText returns true that glyph index is greater than zero, not that it corresponds to an entry in Typeface.

Example Output

0x01ff == has glyph
0x0000 != has glyph
0xffff == has glyph

See Also

setTextEncoding Typeface


void glyphsToUnichars(const SkGlyphID glyphs[], int count, SkUnichar text[]) const

Converts glyphs into text if possible. Glyph values without direct Unicode equivalents are mapped to zero. Uses the SkTypeface, but is unaffected by SkPaint::TextEncoding; the text values returned are equivalent to kUTF32_TextEncoding.

Only supported on platforms that use FreeType as the font engine.

Parameters

glyphs array of indices into font
count length of glyph array
text storage for character codes, one per glyph

Example

Convert UTF-8 text to glyphs; then convert glyphs to Unichar code points.


SkScalar measureText(const void* text, size_t length, SkRect* bounds) const

Returns the advance width of text. The advance is the normal distance to move before drawing additional text. Uses SkPaint::TextEncoding to decode text, SkTypeface to get the font metrics, and text size, text scale x, text skew x, stroke width, and SkPathEffect to scale the metrics and bounds. Returns the bounding box of text if bounds is not nullptr. The bounding box is computed as if the text was drawn at the origin.

Parameters

text character codes or glyph indices to be measured
length number of bytes of text to measure
bounds returns bounding box relative to (0, 0) if not nullptr

Return Value

advance width or height

Example


SkScalar measureText(const void* text, size_t length) const

Returns the advance width of text. The advance is the normal distance to move before drawing additional text. Uses SkPaint::TextEncoding to decode text, SkTypeface to get the font metrics, and text size to scale the metrics. Does not scale the advance or bounds by fake bold or SkPathEffect.

Parameters

text character codes or glyph indices to be measured
length number of bytes of text to measure

Return Value

advance width or height

Example

Example Output

default width = 5
double width = 10


size_t breakText(const void* text, size_t length, SkScalar maxWidth,
                 SkScalar* measuredWidth = nullptr) const

Returns the bytes of text that fit within maxWidth. The text fragment fits if its advance width is less than or equal to maxWidth. Measures only while the advance is less than or equal to maxWidth. Returns the advance or the text fragment in measuredWidth if it not nullptr. Uses SkPaint::TextEncoding to decode text, SkTypeface to get the font metrics, and text size to scale the metrics. Does not scale the advance or bounds by fake bold or SkPathEffect.

Parameters

text character codes or glyph indices to be measured
length number of bytes of text to measure
maxWidth advance limit; text is measured while advance is less than maxWidth
measuredWidth returns the width of the text less than or equal to maxWidth

Return Value

bytes of text that fit, always less than or equal to length

Example

Line under "" shows desired width, shorter than available characters. Line under "" shows measured width after breaking text.


int getTextWidths(const void* text, size_t byteLength, SkScalar widths[], SkRect bounds[] = nullptr) const

Retrieves the advance and bounds for each glyph in text, and returns the glyph count in text. Both widths and bounds may be nullptr. If widths is not nullptr, widths must be an array of glyph count entries. if bounds is not nullptr, bounds must be an array of glyph count entries. Uses SkPaint::TextEncoding to decode text, SkTypeface to get the font metrics, and text size to scale the widths and bounds. Does not scale the advance by fake bold or SkPathEffect. Does include fake bold and SkPathEffect in the bounds.

Parameters

text character codes or glyph indices to be measured
byteLength number of bytes of text to measure
widths returns text advances for each glyph; may be nullptr
bounds returns bounds for each glyph relative to (0, 0); may be nullptr

Return Value

glyph count in text

Example

Bounds of Glyphs increase for stroked text, but text advance remains the same. The underlines show the text advance, spaced to keep them distinct.

Text Path describes the geometry of Glyphs used to draw text.


void getTextPath(const void* text, size_t length, SkScalar x, SkScalar y, SkPath* path) const

Returns the geometry as SkPath equivalent to the drawn text. Uses SkPaint::TextEncoding to decode text, SkTypeface to get the glyph paths, and text size, fake bold, and SkPathEffect to scale and modify the glyph paths. All of the glyph paths are stored in path. Uses x, y, to position path.

Parameters

text character codes or glyph indices
length number of bytes of text
x x-axis value of the origin of the text
y y-axis value of the origin of the text
path geometry of the glyphs

Example

Text is added to Path, offset, and subtracted from Path, then added at the offset location. The result is rendered with one draw call.


void getPosTextPath(const void* text, size_t length, const SkPoint pos[], SkPath* path) const

Returns the geometry as SkPath equivalent to the drawn text. Uses SkPaint::TextEncoding to decode text, SkTypeface to get the glyph paths, and text size, fake bold, and SkPathEffect to scale and modify the glyph paths. All of the glyph paths are stored in path. Uses pos array to position path. pos contains a position for each glyph.

Parameters

text character codes or glyph indices
length number of bytes of text
pos positions of each glyph
path geometry of the glyphs

Example

Simplifies three Glyphs to eliminate overlaps, and strokes the result.

Text Intercepts describe the intersection of drawn text Glyphs with a pair of lines parallel to the text advance. Text Intercepts permits creating a underline that skips Descenders.


int getTextIntercepts(const void* text, size_t length, SkScalar x, SkScalar y,
                      const SkScalar bounds[2], SkScalar* intervals) const

Returns the number of intervals that intersect bounds. bounds describes a pair of lines parallel to the text advance. The return count is zero or a multiple of two, and is at most twice the number of glyphs in the string. Uses SkPaint::TextEncoding to decode text, SkTypeface to get the glyph paths, and text size, fake bold, and SkPathEffect to scale and modify the glyph paths. Uses x, y to position intervals.

Pass nullptr for intervals to determine the size of the interval array.

intervals are cached to improve performance for multiple calls.

Parameters

text character codes or glyph indices
length number of bytes of text
x x-axis value of the origin of the text
y y-axis value of the origin of the text
bounds lower and upper line parallel to the advance
intervals returned intersections; may be nullptr

Return Value

number of intersections; may be zero

Example

Underline uses intercepts to draw on either side of the glyph Descender.


int getPosTextIntercepts(const void* text, size_t length, const SkPoint pos[],
                         const SkScalar bounds[2], SkScalar* intervals) const

Returns the number of intervals that intersect bounds. bounds describes a pair of lines parallel to the text advance. The return count is zero or a multiple of two, and is at most twice the number of glyphs in the string. Uses SkPaint::TextEncoding to decode text, SkTypeface to get the glyph paths, and text size, fake bold, and SkPathEffect to scale and modify the glyph paths. Uses pos array to position intervals.

Pass nullptr for intervals to determine the size of the interval array.

intervals are cached to improve performance for multiple calls.

Parameters

text character codes or glyph indices
length number of bytes of text
pos positions of each glyph
bounds lower and upper line parallel to the advance
intervals returned intersections; may be nullptr

Return Value

number of intersections; may be zero

Example

Text intercepts draw on either side of, but not inside, Glyphs in a run.


int getPosTextHIntercepts(const void* text, size_t length, const SkScalar xpos[], SkScalar constY,
                          const SkScalar bounds[2], SkScalar* intervals) const

Returns the number of intervals that intersect bounds. bounds describes a pair of lines parallel to the text advance. The return count is zero or a multiple of two, and is at most twice the number of glyphs in the string. Uses SkPaint::TextEncoding to decode text, SkTypeface to get the glyph paths, and text size, fake bold, and SkPathEffect to scale and modify the glyph paths. Uses xpos array, constY to position intervals.

Pass nullptr for intervals to determine the size of the interval array.

intervals are cached to improve performance for multiple calls.

Parameters

text character codes or glyph indices
length number of bytes of text
xpos positions of each glyph on x-axis
constY position of each glyph on y-axis
bounds lower and upper line parallel to the advance
intervals returned intersections; may be nullptr

Return Value

number of intersections; may be zero

Example

Text intercepts do not take stroke thickness into consideration.


int getTextBlobIntercepts(const SkTextBlob* blob, const SkScalar bounds[2], SkScalar* intervals) const

Returns the number of intervals that intersect bounds. bounds describes a pair of lines parallel to the text advance. The return count is zero or a multiple of two, and is at most twice the number of glyphs in the string. Uses SkTypeface to get the glyph paths, and text size, fake bold, and SkPathEffect to scale and modify the glyph paths. Uses run array to position intervals.

SkPaint::TextEncoding must be set to SkPaint::kGlyphID_TextEncoding.

Pass nullptr for intervals to determine the size of the interval array.

intervals are cached to improve performance for multiple calls.

Parameters

blob glyphs, positions, and text paint attributes
bounds lower and upper line parallel to the advance
intervals returned intersections; may be nullptr

Return Value

number of intersections; may be zero

Example


bool nothingToDraw() const

Returns true if SkPaint prevents all drawing; otherwise, the SkPaint may or may not allow drawing.

Returns true if, for example, SkBlendMode combined with alpha computes a new alpha of zero.

Return Value

true if SkPaint prevents all drawing

Example

Example Output

initial nothing to draw: false
blend dst nothing to draw: true
blend src over nothing to draw: false
alpha 0 nothing to draw: true

Private: To be made private.

Fast Bounds functions conservatively outset a drawing bounds by additional area Paint may draw to.


bool canComputeFastBounds() const

Private: (to be made private)

Returns true if Paint does not include elements requiring extensive computation to compute Device bounds of drawn geometry. For instance, Paint with Path Effect always returns false.

Return Value

true if Paint allows for fast computation of bounds


const SkRect& computeFastBounds(const SkRect& orig, SkRect* storage) const

Private: (to be made private)

Only call this if canComputeFastBounds returned true. This takes a raw rectangle (the raw bounds of a shape), and adjusts it for stylistic effects in the paint (e.g. stroking). If needed, it uses the storage parameter. It returns the adjusted bounds that can then be used for SkCanvas::quickReject tests.

The returned Rect will either be orig or storage, thus the caller should not rely on storage being set to the result, but should always use the returned value. It is legal for orig and storage to be the same Rect.

Private: For example: if (!path.isInverseFillType() && paint.canComputeFastBounds()) { SkRect storage; if (canvas->quickReject(paint.computeFastBounds(path.getBounds(), &storage))) { return; // do not draw the path } } // draw the path

Parameters

orig geometry modified by Paint when drawn
storage computed bounds of geometry; may not be nullptr

Return Value

fast computed bounds


const SkRect& computeFastStrokeBounds(const SkRect& orig, SkRect* storage) const

Private: (to be made private)

Parameters

orig geometry modified by Paint when drawn
storage computed bounds of geometry

Return Value

fast computed bounds


const SkRect& doComputeFastBounds(const SkRect& orig, SkRect* storage, Style style) const

Private: (to be made private)

Computes the bounds, overriding the Paint Style. This can be used to account for additional width required by stroking orig, without altering Style set to fill.

Parameters

orig geometry modified by Paint when drawn
storage computed bounds of geometry
style overrides Style

Return Value

fast computed bounds