SkPaint Reference
===
# Paint
# Class SkPaint
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.
# Overview
## Subtopics
| topics | description |
| --- | --- |
| Initializers | Constructors and initialization. |
| Destructor | Paint termination. |
| Management | Paint copying, moving, comparing. |
| Hinting | Glyph outline adjustment. |
| Flags | Attributes represented by single bits. |
| Anti-alias | Approximating coverage with transparency. |
| Dither | Distributing color error. |
| Device Text | Increase precision of glyph position. |
| Font Embedded Bitmaps | Custom sized bitmap Glyphs. |
| Automatic Hinting | Always adjust glyph paths. |
| Vertical Text | Orient text from top to bottom. |
| Fake Bold | Approximate font styles. |
| Full Hinting Spacing | Glyph spacing affected by hinting. |
| Filter Quality Methods | Get and set Filter Quality. |
| Color Methods | Get and set Color. |
| Style | Geometry filling, stroking. |
| Stroke Width | Thickness perpendicular to geometry. |
| Miter Limit | Maximum length of stroked corners. |
| Stroke Cap | Decorations at ends of open strokes. |
| Stroke Join | Decoration at corners of strokes. |
| Fill Path | Make Path from Path Effect, stroking. |
| Shader Methods | Get and set Shader. |
| Color Filter Methods | Get and set Color Filter. |
| Blend Mode Methods | Get and set Blend Mode. |
| Path Effect Methods | Get and set Path Effect. |
| Mask Filter Methods | Get and set Mask Filter. |
| Typeface Methods | Get and set Typeface. |
| Rasterizer Methods | Get and set Rasterizer. |
| Image Filter Methods | Get and set Image Filter. |
| Draw Looper Methods | Get and set Draw Looper. |
| Text Align | Text placement relative to position. |
| Text Size | Overall height in points. |
| Text Scale X | Text horizontal scale. |
| Text Skew X | Text horizontal slant. |
| Text Encoding | Text encoded as characters or Glyphs. |
| Font Metrics | Common glyph dimensions. |
| Measure Text | Width, height, bounds of text. |
| Text Path | Geometry of Glyphs. |
| Text Intercepts | Advanced underline, strike through. |
| Fast Bounds | Approximate area required by Paint. |
## Constants
| constants | description |
| --- | --- |
| Align | Glyph locations relative to text position. |
| Cap | Start and end geometry on stroked shapes. |
| Flags | Values described by bits and masks. |
| FontMetrics::FontMetricsFlags | Valid Font Metrics. |
| Hinting | Level of glyph outline adjustment. |
| Join | Corner geometry on stroked shapes. |
| Style | Stroke, fill, or both. |
| TextEncoding | Character or glyph encoded size. |
## Structs
| struct | description |
| --- | --- |
| FontMetrics | Typeface values. |
## Constructors
| | description |
| --- | --- |
| SkPaint() | Constructs with default values. |
| SkPaint(const SkPaint& paint) | Makes a shallow copy. |
| SkPaint(SkPaint&& paint) | Moves paint without copying it. |
| | Decreases Reference Count of owned objects. |
## Operators
| operator | description |
| --- | --- |
| operator=(const SkPaint& paint) | Makes a shallow copy. |
| operator=(SkPaint&& paint) | Moves paint without copying it. |
| operator==(const SkPaint& a, const SkPaint& b) | Compares paints for equality. |
| operator!=(const SkPaint& a, const SkPaint& b) | Compares paints for inequality. |
## Member Functions
| function | description |
| --- | --- |
| breakText | Returns text that fits in a width. |
| canComputeFastBounds | Returns true if settings allow for fast bounds computation. |
| computeFastBounds | Returns fill bounds for quick reject tests. |
| computeFastStrokeBounds | Returns stroke bounds for quick reject tests. |
| containsText | Returns if all text corresponds to Glyphs. |
| countText | Returns number of Glyphs in text. |
| doComputeFastBounds | Returns bounds for quick reject tests. |
| flatten | Serializes into a buffer. |
| getAlpha | Returns Color Alpha, color opacity. |
| getBlendMode | Returns Blend Mode, how colors combine with Device. |
| getColor | Returns Color Alpha and Color RGB, one drawing color. |
| getColorFilter | Returns Color Filter, how colors are altered. |
| getDrawLooper | Returns Draw Looper, multiple layers. |
| getFillPath | Returns fill path equivalent to stroke. |
| getFilterQuality | Returns Filter Quality, image filtering level. |
| getFlags | Returns Flags stored in a bit field. |
| getFontBounds | Returns union all glyph bounds. |
| getFontMetrics | Returns Typeface metrics scaled by text size. |
| getFontSpacing | Returns recommended spacing between lines. |
| getHash | Returns a shallow hash for equality checks. |
| getHinting | Returns Hinting, glyph outline adjustment level. |
| getImageFilter | Returns Image Filter, alter pixels; blur. |
| getMaskFilter | Returns Mask Filter, alterations to Mask Alpha. |
| getPathEffect | Returns Path Effect, modifications to path geometry; dashing. |
| getPosTextPath | Returns Path equivalent to positioned text. |
| getPosTextIntercepts | Returns where lines intersect positioned text; underlines. |
| getPosTextHIntercepts | Returns where lines intersect horizontally positioned text; underlines. |
| getRasterizer | Returns Rasterizer, Mask Alpha generation from Path. |
| getShader | Returns Shader, multiple drawing colors; gradients. |
| getStrokeCap | Returns Cap, the area drawn at path ends. |
| getStrokeJoin | Returns Join, geometry on path corners. |
| getStrokeMiter | Returns Miter Limit, angles with sharp corners. |
| getStrokeWidth | Returns thickness of the stroke. |
| getStyle | Returns Style: stroke, fill, or both. |
| getTextAlign | Returns Align: left, center, or right. |
| getTextBlobIntercepts | Returns where lines intersect Text Blob; underlines. |
| getTextEncoding | Returns character or glyph encoded size. b |
| getTextIntercepts | Returns where lines intersect text; underlines. |
| getTextPath | Returns Path equivalent to text. |
| getTextScaleX | Returns the text horizontal scale; condensed text. |
| getTextSkewX | Returns the text horizontal skew; oblique text. |
| getTextSize | Returns text size in points. |
| getTextWidths | Returns advance and bounds for each glyph in text. |
| getTypeface | Returns Typeface, font description. |
| glyphsToUnichars | Converts Glyphs into text. |
| isAntiAlias | Returns true if Anti-alias is set. |
| isAutohinted | Returns true if Glyphs are always hinted. |
| isDevKernText | Returns true if Full Hinting Spacing is set. |
| isDither | Returns true if Dither is set. |
| isEmbeddedBitmapText | Returns true if Font Embedded Bitmaps is set. |
| isFakeBoldText | Returns true if Fake Bold is set. |
| isLCDRenderText | Returns true if LCD Text is set. |
| isSrcOver | Returns true if Blend Mode is SkBlendMode::kSrcOver. |
| isSubpixelText | Returns true if Subpixel Text is set. |
| isVerticalText | Returns true if Vertical Text is set. |
| measureText | Returns advance width and bounds of text. |
| nothingToDraw | Returns true if Paint prevents all drawing. |
| refColorFilter | References Color Filter, how colors are altered. |
| refDrawLooper | References Draw Looper, multiple layers. |
| refImageFilter | References Image Filter, alter pixels; blur. |
| refMaskFilter | References Mask Filter, alterations to Mask Alpha. |
| refPathEffect | References Path Effect, modifications to path geometry; dashing. |
| refRasterizer | References Rasterizer, mask generation from path. |
| refShader | References Shader, multiple drawing colors; gradients. |
| refTypeface | References Typeface, font description. |
| reset | Sets to default values. |
| setAlpha | Sets Color Alpha, color opacity. |
| setAntiAlias | Sets or clears Anti-alias. |
| setARGB | Sets color by component. |
| setAutohinted | Sets Glyphs to always be hinted. |
| setBlendMode | Sets Blend Mode, how colors combine with destination. |
| setColor | Sets Color Alpha and Color RGB, one drawing color. |
| setColorFilter | Sets Color Filter, alters color. |
| setDevKernText | Sets or clears Full Hinting Spacing. |
| setDither | Sets or clears Dither. |
| setDrawLooper | Sets Draw Looper, multiple layers. |
| setEmbeddedBitmapText | Sets or clears Font Embedded Bitmaps. |
| setFakeBoldText | Sets or clears Fake Bold. |
| setFilterQuality | Sets Filter Quality, the image filtering level. |
| setFlags | Sets multiple Flags in a bit field. |
| setHinting | Sets Hinting, glyph outline adjustment level. |
| setLCDRenderText | Sets or clears LCD Text. |
| setMaskFilter | Sets Mask Filter, alterations to Mask Alpha. |
| setPathEffect | Sets Path Effect, modifications to path geometry; dashing. |
| setRasterizer | Sets Rasterizer, Mask Alpha generation from Path. |
| setImageFilter | Sets Image Filter, alter pixels; blur. |
| setShader | Sets Shader, multiple drawing colors; gradients. |
| setStrokeCap | Sets Cap, the area drawn at path ends. |
| setStrokeJoin | Sets Join, geometry on path corners. |
| setStrokeMiter | Sets Miter Limit, angles with sharp corners. |
| setStrokeWidth | Sets thickness of the stroke. |
| setStyle | Sets Style: stroke, fill, or both. |
| setSubpixelText | Sets or clears Subpixel Text. |
| setTextAlign | Sets Align: left, center, or right. |
| setTextEncoding | Sets character or glyph encoded size. |
| setTextScaleX | Sets the text horizontal scale; condensed text. |
| setTextSkewX | Sets the text horizontal skew; oblique text. |
| setTextSize | Sets text size in points. |
| setTypeface | Sets Typeface, font description. |
| setVerticalText | Sets or clears Vertical Text. |
| textToGlyphs | Converts text into glyph indices. |
| toString | Converts Paint to machine readable form. |
| unflatten | Populates from a serialized stream. |
# Initializers
## SkPaint
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 |
| Rasterizer | nullptr |
| Shader | nullptr |
| Style | kFill Style |
| Text Align | kLeft Align |
| 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 |
| Vertical 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
SkPaint(const SkPaint& paint)
Makes a shallow copy of Paint. Typeface, Path Effect, Shader,
Mask Filter, Color Filter, Rasterizer, Draw Looper, and Image Filter are shared
between the original paint and the copy. Objects containing Reference Count increment
their references by one.
The referenced objects Path Effect, Shader, Mask Filter, Color Filter, Rasterizer,
Draw Looper, and Image Filter cannot be modified after they are created.
This prevents objects with Reference Count from being modified once Paint refers to them.
### Parameters
### Return Value
shallow copy of paint
### Example
#### Example Output
~~~~
SK_ColorRED == paint1.getColor()
SK_ColorBLUE == paint2.getColor()
~~~~
---
## SkPaint
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
### Return Value
content of paint
### Example
#### Example Output
~~~~
path effect unique: true
~~~~
---
## reset
void reset()
Sets all Paint contents to their initial values. This is equivalent to replacing
Paint with the result of SkPaint().
### Example
#### Example Output
~~~~
paint1 == paint2
~~~~
---
# Destructor
## ~SkPaint
~SkPaint()
Decreases Paint Reference Count of owned objects: Typeface, Path Effect, Shader,
Mask Filter, Color Filter, Rasterizer, Draw Looper, and Image Filter. If the
objects containing Reference Count go to zero, they are deleted.
---
# Management
## operator=
SkPaint& operator=(const SkPaint& paint)
Makes a shallow copy of Paint. Typeface, Path Effect, Shader,
Mask Filter, Color Filter, Rasterizer, Draw Looper, and Image Filter are shared
between the original paint and the copy. Objects containing Reference Count in the
prior destination are decreased by one, and the referenced objects are deleted if the
resulting count is zero. Objects containing Reference Count in the parameter paint
are increased by one. paint is unmodified.
### Parameters
### Return Value
content of paint
### Example
#### Example Output
~~~~
SK_ColorRED == paint1.getColor()
SK_ColorRED == paint2.getColor()
~~~~
---
## operator=
SkPaint& operator=(SkPaint&& paint)
Moves the paint to avoid increasing the reference counts
of objects referenced by the paint parameter. Objects containing Reference Count 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
### Return Value
content of paint
### Example
#### Example Output
~~~~
SK_ColorRED == paint2.getColor()
~~~~
---
## operator==
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 Typeface, Path Effect, Shader, Mask Filter, Color Filter, Rasterizer,
Draw Looper, or Image Filter have identical contents but different pointers.
### Parameters
### Return Value
true if Paint pair are equivalent
### Example
#### Example Output
~~~~
paint1 == paint2
paint1 != paint2
~~~~
---
## operator!=
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 Typeface, Path Effect, Shader, Mask Filter, Color Filter, Rasterizer,
Draw Looper, or Image Filter have identical contents but different pointers.
### Parameters
### Return Value
true if Paint pair are not equivalent
### Example
#### Example Output
~~~~
paint1 == paint2
paint1 == paint2
~~~~
---
## getHash
uint32_t getHash() const
Returns a hash generated from Paint 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()
~~~~
---
## flatten
void flatten(SkWriteBuffer& buffer) const
Serializes Paint into a buffer. A companion unflatten call
can reconstitute the paint at a later time.
### Parameters
### Example
#### Example Output
~~~~
color = 0xffff0000
~~~~
---
## unflatten
void unflatten(SkReadBuffer& buffer)
Populates Paint, typically from a serialized stream, created by calling
flatten at an earlier time.
SkReadBuffer class is not public, so unflatten cannot be meaningfully called
by the client.
### Parameters
### See Also
SkReadBuffer
---
# Hinting
## Enum SkPaint::Hinting
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
On Windows with DirectWrite, Hinting has no effect.
Hinting defaults to kNormal Hinting.
Set SkPaintDefaults Hinting at compile time to change the default setting.
## getHinting
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()
~~~~
---
## setHinting
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
### Example
#### Example Output
~~~~
paint1 == paint2
~~~~
---
# Flags
## Enum SkPaint::Flags
enum Flags {
kAntiAlias Flag = 0x01,
kDither Flag = 0x04,
kFakeBoldText Flag = 0x20,
kLinearText Flag = 0x40,
kSubpixelText Flag = 0x80,
kDevKernText Flag = 0x100,
kLCDRenderText Flag = 0x200,
kEmbeddedBitmapText Flag = 0x400,
kAutoHinting Flag = 0x800,
kVerticalText Flag = 0x1000,
kGenA8FromLCD Flag = 0x2000,
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
## Enum SkPaint::ReserveFlags
enum ReserveFlags {
kUnderlineText ReserveFlag = 0x08,
kStrikeThruText ReserveFlag = 0x10,
};
### Constants
### See Also
Flags getFlags
## getFlags
uint32_t getFlags() const
Returns paint settings described by Flags. Each setting uses one
bit, and can be tested with Flags members.
### Return Value
zero, one, or more bits described by Flags
### Example
#### Example Output
~~~~
(SkPaint::kAntiAlias_Flag & paint.getFlags()) != 0
~~~~
---
## setFlags
void setFlags(uint32_t flags)
Replaces Flags with flags, the union of the Flags members.
All Flags members may be cleared, or one or more may be set.
### Parameters
### Example
#### Example Output
~~~~
paint.isAntiAlias()
paint.isDither()
~~~~
---
# Anti-alias
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
If true, pixels on the active edges of Path 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)
~~~~
---
## setAntiAlias
void setAntiAlias(bool aa)
Requests, but does not require, that Path edge pixels draw opaque or with
partial transparency.
Sets kAntiAlias Flag if aa is true.
Clears kAntiAlias Flag if aa is false.
### Parameters
### Example
#### Example Output
~~~~
paint1 == paint2
~~~~
---
# Dither
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. Setto 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.
Dithering introduces subtle adjustments to color to smooth gradients.
Drawing the gradient repeatedly with
SkBlendMode::kPlus exaggerates the
dither, making it easier to see.
bool isDither() const
If true, 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)
~~~~
---
## setDither
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
### Example
#### Example Output
~~~~
paint1 == paint2
~~~~
### See Also
kRGB 565 SkColorType
---
### See Also
Gradient Color RGB-565
# Device Text
LCD Text and Subpixel Text increase the precision of glyph position.
When set, Flags kLCDRenderText Flag takes advantage of the organization of Color 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 Color RGB or Color RBG.
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
## Linear Text
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.
## isLinearText
bool isLinearText() const
If true, text is converted to Path before drawing and measuring.
Equivalent to getFlags masked with kLinearText Flag.
### Return Value
kLinearText Flag state
### Example
### See Also
setLinearText Hinting
---
## setLinearText
void setLinearText(bool linearText)
If true, text is converted to Path 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
### Example
### See Also
isLinearText Hinting
---
## Subpixel Text
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.
## isSubpixelText
bool isSubpixelText() const
If true, 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)
~~~~
---
## setSubpixelText
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
### Example
#### Example Output
~~~~
paint1 == paint2
~~~~
---
## LCD Text
When set, Flags kLCDRenderText Flag takes advantage of the organization of Color 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 Color RGB or Color RBG.
## isLCDRenderText
bool isLCDRenderText() const
If true, Glyphs may use LCD striping to improve glyph edges.
Returns true if 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)
~~~~
---
## setLCDRenderText
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
### Example
#### Example Output
~~~~
paint1 == paint2
~~~~
---
# Font Embedded Bitmaps
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
void draw(SkCanvas* canvas) {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);
}
## isEmbeddedBitmapText
bool isEmbeddedBitmapText() const
If true, 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)
~~~~
---
## setEmbeddedBitmapText
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
### Example
#### Example Output
~~~~
paint1 == paint2
~~~~
---
# Automatic Hinting
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.
## isAutohinted
bool isAutohinted() const
If true, and if Hinting is set to kNormal Hinting or kFull Hinting, and if
platform uses FreeType as the Font Manager, instruct 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
---
## setAutohinted
void setAutohinted(bool useAutohinter)
If Hinting is set to kNormal Hinting or kFull Hinting and useAutohinter is set,
instruct the Font Manager to always hint Glyphs.
Automatic Hinting has no effect if 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
### Example
### See Also
isAutohinted Hinting
---
# Vertical Text
Text may be drawn by positioning each glyph, or by positioning the first glyph and
using Font Advance to position subsequent Glyphs. By default, each successive glyph
is positioned to the right of the preceding glyph. Vertical Text sets successive
Glyphs to position below the preceding glyph.
Skia can translate text character codes as a series of Glyphs, but does not implement
font substitution,
textual substitution, line layout, or contextual spacing like Kerning pairs. Use
a text shaping engine likeHarfBuzzto translate text runs
into glyph series.
Vertical Text is clear if text is drawn left to right or set if drawn from top to bottom.
Flags kVerticalText Flag if clear draws text left to right.
Flags kVerticalText Flag if set draws text top to bottom.
Vertical Text is clear by default.
Vertical Text can be set by default by setting SkPaintDefaults Flags to
kVerticalText Flag at compile time.
### Example
## isVerticalText
bool isVerticalText() const
If true, Glyphs are drawn top to bottom instead of left to right.
Equivalent to getFlags masked with kVerticalText Flag.
### Return Value
kVerticalText Flag state
### Example
#### Example Output
~~~~
paint.isVerticalText() == !!(paint.getFlags() & SkPaint::kVerticalText_Flag)
paint.isVerticalText() == !!(paint.getFlags() & SkPaint::kVerticalText_Flag)
~~~~
---
## setVerticalText
void setVerticalText(bool verticalText)
If true, text advance positions the next glyph below the previous glyph instead of to the
right of previous glyph.
Sets kVerticalText Flag if vertical is true.
Clears kVerticalText Flag if vertical is false.
### Parameters
### Example
#### Example Output
~~~~
paint1 == paint2
~~~~
---
# Fake Bold
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
## isFakeBoldText
bool isFakeBoldText() const
If true, 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)
~~~~
---
## setFakeBoldText
void setFakeBoldText(bool fakeBoldText)
Use increased 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
### Example
#### Example Output
~~~~
paint1 == paint2
~~~~
---
# Full Hinting Spacing
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.
## isDevKernText
bool isDevKernText() const
Returns if character spacing may be adjusted by the hinting difference.
Equivalent to getFlags masked with kDevKernText Flag.
### Return Value
kDevKernText Flag state
### Example
---
## setDevKernText
void setDevKernText(bool devKernText)
Requests, but does not require, to use hinting to adjust glyph spacing.
Sets kDevKernText Flag if devKernText is true.
Clears kDevKernText Flag if devKernText is false.
### Parameters
### Example
#### Example Output
~~~~
paint1 == paint2
~~~~
---
# Filter Quality Methods
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
and when Paint has a Shader specialization that uses Image or Bitmap.
Filter Quality is kNone SkFilterQuality by default.
### Example
## getFilterQuality
SkFilterQuality getFilterQuality() const
Returns Filter Quality, 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()
~~~~
---
## setFilterQuality
void setFilterQuality(SkFilterQuality quality)
Sets Filter Quality, 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
### Example
#### Example Output
~~~~
kHigh_SkFilterQuality == paint.getFilterQuality()
~~~~
### See Also
SkFilterQuality Image Scaling
---
# Color Methods
Color specifies the Color RGB Red, Color RGB Blue, Color RGB 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 Color RGB: Color RGB Red, Color RGB Blue, and Color RGB Green.
The bit positions of Color Alpha and Color 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 | Color RGB Red | Color RGB Blue | Color RGB Green |
| --- | --- | --- | --- | --- |
| | 31 - 24 | 23 - 16 | 15 - 8 | 7 - 0 |
### Example
## getColor
SkColor getColor() const
Retrieves Alpha and Color RGB, Unpremultiplied, packed into 32 bits.
Use helpers SkColorGetA, SkColorGetR, SkColorGetG, and SkColorGetB to extract
a color component.
### Return Value
Unpremultiplied Color ARGB
### Example
#### Example Output
~~~~
Yellow is 100% red, 100% green, and 0% blue.
~~~~
### See Also
SkColor
---
## setColor
void setColor(SkColor color)
Sets Alpha and Color 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
### Example
#### Example Output
~~~~
green1 == green2
~~~~
### See Also
SkColor setARGB SkColorSetARGB
---
## Alpha Methods
Color Alpha sets the transparency independent of Color RGB: Color RGB Red, Color RGB Blue, and Color RGB Green.
## getAlpha
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()
~~~~
---
## setAlpha
void setAlpha(U8CPU a)
Replaces Alpha, leaving Color 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
### Example
#### Example Output
~~~~
0x44112233 == paint.getColor()
~~~~
---
## setARGB
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 Color RGB.
### Parameters
### Example
#### Example Output
~~~~
transRed1 == transRed2
~~~~
### See Also
setColor SkColorSetARGB
---
# Style
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.
## Fill
### See Also
Path Fill Type
## Stroke
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.
## Hairline
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.
## Enum SkPaint::Style
enum Style {
kFill Style,
kStroke Style,
kStrokeAndFill Style,
};
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
SkPaint::kFill_Style | 0 | Set to fill geometry.
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 | Set to stroke geometry.
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 | Set to stroke and fill geometry.
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. |
## Enum SkPaint::_anonymous
enum {
kStyleCount = kStrokeAndFill Style + 1,
};
### Constants
## getStyle
Style getStyle() const
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
---
## 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 Style value.
### Parameters
### Example
### See Also
Style getStyle
---
### See Also
Path Fill Type Path Effect Style Fill Style Stroke
# Stroke Width
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 Paint to
outline the shape.
### Return Value
zero for Hairline, greater than zero for pen thickness
### Example
#### Example Output
~~~~
0 == paint.getStrokeWidth()
~~~~
---
## setStrokeWidth
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
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:
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
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
---
## setStrokeMiter
void setStrokeMiter(SkScalar miter)
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
### Example
#### Example Output
~~~~
default miter limit == 8
~~~~
### See Also
Miter Limit getStrokeMiter Join
---
# Stroke Cap
## Enum SkPaint::Cap
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
### Example
## getStrokeCap
Cap getStrokeCap() const
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
---
## setStrokeCap
void setStrokeCap(Cap cap)
The geometry drawn at the beginning and end of strokes.
### Parameters
### Example
#### Example Output
~~~~
kRound_Cap == paint.getStrokeCap()
~~~~
### See Also
Stroke Cap getStrokeCap
---
# Stroke Join
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 SkPaint::Join
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
### Example
### See Also
setStrokeJoin getStrokeJoin setStrokeMiter getStrokeMiter
## getStrokeJoin
Join getStrokeJoin() const
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
---
## setStrokeJoin
void setStrokeJoin(Join join)
The geometry drawn at the corners of strokes.
### Parameters
### Example
#### Example Output
~~~~
kMiter_Join == paint.getStrokeJoin()
~~~~
### See Also
Stroke Join getStrokeJoin
---
### See Also
Miter Limit
# Fill Path
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.
## getFillPath
bool getFillPath(const SkPath& src, SkPath* dst, const SkRect* cullRect, SkScalar resScale = 1) const
The filled equivalent of the stroked path.
### Parameters
src |
Path read to create a filled version |
dst |
resulting Path; may be the same as src, but may not be nullptr |
cullRect |
optional limit passed to Path Effect |
resScale |
if > 1, increase precision, else if (0 < res < 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
The filled equivalent of the stroked path.
Replaces dst with the src path modified by Path Effect and Style Stroke.
Path Effect, if any, is not culled. Stroke Width is created with default precision.
### Parameters
src |
Path read to create a filled version |
dst |
resulting Path 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
---
### See Also
Style Stroke Stroke Width Path Effect
# Shader Methods
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
## getShader
SkShader* getShader() const
Optional colors used when filling a path, such as a gradient.
Does not alter Shader Reference Count.
### Return Value
Shader if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
nullptr == shader
nullptr != shader
~~~~
---
## refShader
sk_sp<SkShader> refShader() const
Optional colors used when filling a path, such as a gradient.
Increases Shader Reference Count by one.
### Return Value
Shader if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
shader unique: true
shader unique: false
~~~~
---
## setShader
void setShader(sk_sp<SkShader> shader)
Optional colors used when filling a path, such as a gradient.
Sets Shader to shader, decreasing Reference Count of the previous Shader.
Increments shader Reference Count by one.
### Parameters
shader |
how geometry is filled with color; if nullptr, Color is used instead |
### Example
---
# Color Filter Methods
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
## getColorFilter
SkColorFilter* getColorFilter() const
Returns Color Filter if set, or nullptr.
Does not alter Color Filter Reference Count.
### Return Value
Color Filter if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
nullptr == color filter
nullptr != color filter
~~~~
---
## refColorFilter
sk_sp<SkColorFilter> refColorFilter() const
Returns Color Filter if set, or nullptr.
Increases Color Filter Reference Count by one.
### Return Value
Color Filter if set, or nullptr
### Example
#### Example Output
~~~~
color filter unique: true
color filter unique: false
~~~~
---
## setColorFilter
void setColorFilter(sk_sp<SkColorFilter> colorFilter)
Sets Color Filter to filter, decreasing Reference Count of the previous
Color Filter. Pass nullptr to clear Color Filter.
Increments filter Reference Count by one.
### Parameters
### Example
---
# Blend Mode Methods
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
## getBlendMode
SkBlendMode getBlendMode() const
Returns Blend Mode.
By default, returns SkBlendMode::kSrcOver.
### Return Value
mode used to combine source color with destination color
### Example
#### Example Output
~~~~
kSrcOver == getBlendMode
kSrcOver != getBlendMode
~~~~
---
## isSrcOver
bool isSrcOver() const
Returns true if Blend Mode is SkBlendMode::kSrcOver, the default.
### Return Value
true if Blend Mode is SkBlendMode::kSrcOver
### Example
#### Example Output
~~~~
isSrcOver == true
isSrcOver != true
~~~~
---
## setBlendMode
void setBlendMode(SkBlendMode mode)
Sets Blend Mode to mode.
Does not check for valid input.
### Parameters
### Example
#### Example Output
~~~~
isSrcOver == true
isSrcOver != true
~~~~
---
# Path Effect Methods
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
## getPathEffect
SkPathEffect* getPathEffect() const
Returns Path Effect if set, or nullptr.
Does not alter Path Effect Reference Count.
### Return Value
Path Effect if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
nullptr == path effect
nullptr != path effect
~~~~
---
## refPathEffect
sk_sp<SkPathEffect> refPathEffect() const
Returns Path Effect if set, or nullptr.
Increases Path Effect Reference Count by one.
### Return Value
Path Effect if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
path effect unique: true
path effect unique: false
~~~~
---
## setPathEffect
void setPathEffect(sk_sp<SkPathEffect> pathEffect)
Sets Path Effect to pathEffect, decreasing Reference Count of the previous
Path Effect. Pass nullptr to leave the path geometry unaltered.
Increments pathEffect Reference Count by one.
### Parameters
### Example
---
# Mask Filter Methods
Mask Filter uses coverage of the shape drawn to create Mask Alpha.
Mask Filter operates at a lower level than Rasterizer; 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
## getMaskFilter
SkMaskFilter* getMaskFilter() const
Returns Mask Filter if set, or nullptr.
Does not alter Mask Filter Reference Count.
### Return Value
Mask Filter if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
nullptr == mask filter
nullptr != mask filter
~~~~
---
## refMaskFilter
sk_sp<SkMaskFilter> refMaskFilter() const
Returns Mask Filter if set, or nullptr.
Increases Mask Filter Reference Count by one.
### Return Value
Mask Filter if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
mask filter unique: true
mask filter unique: false
~~~~
---
## setMaskFilter
void setMaskFilter(sk_sp<SkMaskFilter> maskFilter)
Sets Mask Filter to maskFilter, decreasing Reference Count of the previous
Mask Filter. Pass nullptr to clear Mask Filter and leave Mask Filter effect on
Mask Alpha unaltered.
Does not affect Rasterizer.
Increments maskFilter Reference Count by one.
### Parameters
maskFilter |
modifies clipping mask generated from drawn geometry |
### Example
---
# Typeface Methods
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
## getTypeface
SkTypeface* getTypeface() const
Returns Typeface if set, or nullptr.
Increments Typeface Reference Count by one.
### Return Value
Typeface if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
nullptr == typeface
nullptr != typeface
~~~~
---
## refTypeface
sk_sp<SkTypeface> refTypeface() const
Increases Typeface Reference Count by one.
### Return Value
Typeface if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
typeface1 != typeface2
typeface1 == typeface2
~~~~
---
## setTypeface
void setTypeface(sk_sp<SkTypeface> typeface)
Sets Typeface to typeface, decreasing Reference Count of the previous Typeface.
Pass nullptr to clear Typeface and use the default typeface. Increments
typeface Reference Count by one.
### Parameters
typeface |
font and style used to draw text |
### Example
---
# Rasterizer Methods
Rasterizer controls how shapes are converted to Mask Alpha.
Rasterizer operates at a higher level than Mask Filter; Rasterizer takes a Path,
and returns a Mask.
Rasterizer may change the geometry and transparency of the shape, such as
creating a shadow effect. Rasterizer forms the base of Rasterizer Layer, which
creates effects like embossing and outlining.
Rasterizer applies to Rect, Region, Round Rect, Arcs, Circles, Ovals,
Path, and Text.
### Example
## getRasterizer
SkRasterizer* getRasterizer() const
Returns Rasterizer if set, or nullptr.
Does not alter Rasterizer Reference Count.
### Return Value
Rasterizer if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
nullptr == rasterizer
nullptr != rasterizer
~~~~
---
## refRasterizer
sk_sp<SkRasterizer> refRasterizer() const
Returns Rasterizer if set, or nullptr.
Increases Rasterizer Reference Count by one.
### Return Value
Rasterizer if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
rasterizer unique: true
rasterizer unique: false
~~~~
---
## setRasterizer
void setRasterizer(sk_sp<SkRasterizer> rasterizer)
Sets Rasterizer to rasterizer, decreasing Reference Count of the previous
Rasterizer. Pass nullptr to clear Rasterizer and leave Rasterizer effect on
Mask Alpha unaltered.
Does not affect Mask Filter.
Increments rasterizer Reference Count by one.
### Parameters
### Example
---
# Image Filter Methods
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 and Rasterizer.
### Example
## getImageFilter
SkImageFilter* getImageFilter() const
Returns Image Filter if set, or nullptr.
Does not alter Image Filter Reference Count.
### Return Value
Image Filter if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
nullptr == image filter
nullptr != image filter
~~~~
---
## refImageFilter
sk_sp<SkImageFilter> refImageFilter() const
Returns Image Filter if set, or nullptr.
Increases Image Filter Reference Count by one.
### Return Value
Image Filter if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
image filter unique: true
image filter unique: false
~~~~
---
## setImageFilter
void setImageFilter(sk_sp<SkImageFilter> imageFilter)
Sets Image Filter to imageFilter, decreasing Reference Count of the previous
Image Filter. Pass nullptr to clear Image Filter, and remove Image Filter effect
on drawing.
Does not affect Rasterizer or Mask Filter.
Increments imageFilter Reference Count by one.
### Parameters
### Example
---
# Draw Looper Methods
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
## getDrawLooper
SkDrawLooper* getDrawLooper() const
Returns Draw Looper if set, or nullptr.
Does not alter Draw Looper Reference Count.
### Return Value
Draw Looper if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
nullptr == draw looper
nullptr != draw looper
~~~~
---
## refDrawLooper
sk_sp<SkDrawLooper> refDrawLooper() const
Returns Draw Looper if set, or nullptr.
Increases Draw Looper Reference Count by one.
### Return Value
Draw Looper if previously set, nullptr otherwise
### Example
#### Example Output
~~~~
draw looper unique: true
draw looper unique: false
~~~~
---
## getLooper
SkDrawLooper* getLooper() const
Deprecated.
(see bug.skia.org/6259)
### Return Value
Draw Looper if previously set, nullptr otherwise
---
## setDrawLooper
void setDrawLooper(sk_sp<SkDrawLooper> drawLooper)
Sets Draw Looper to drawLooper, decreasing Reference Count of the previous
drawLooper. Pass nullptr to clear Draw Looper and leave Draw Looper effect on
drawing unaltered.
Increments drawLooper Reference Count by one.
### Parameters
### Example
---
## setLooper
void setLooper(sk_sp<SkDrawLooper> drawLooper)
Deprecated.
(see bug.skia.org/6259)
### Parameters
# Text Align
## Enum SkPaint::Align
enum Align {
kLeft Align,
kCenter Align,
kRight Align,
};
Align adjusts the text relative to the text position.
Align affects Glyphs drawn with: SkCanvas::drawText, SkCanvas::drawPosText,
SkCanvas::drawPosTextH, SkCanvas::drawTextOnPath,
SkCanvas::drawTextOnPathHV, SkCanvas::drawTextRSXform, SkCanvas::drawTextBlob,
and SkCanvas::drawString;
as well as calls that place text Glyphs like getTextWidths and getTextPath.
The text position is set by the font for both horizontal and vertical text.
Typically, for horizontal text, the position is to the left side of the glyph on the
base line; and for vertical text, the position is the horizontal center of the glyph
at the caps height.
Align adjusts the glyph position to center it or move it to abut the position
using the metrics returned by the font.
Align defaults to kLeft Align.
### Constants
## Enum SkPaint::_anonymous_2
enum {
kAlignCount = 3,
};
### Constants
### Example
Each position separately moves the glyph in drawPosText.
Align getTextAlign() const
Returns Text Align.
Returns kLeft Align if Text Align has not been set.
### Return Value
text placement relative to position
### Example
#### Example Output
~~~~
kLeft_Align == default
~~~~
---
## setTextAlign
void setTextAlign(Align align)
Sets Text Align to align.
Has no effect if align is an invalid value.
### Parameters
align |
text placement relative to position |
### Example
Text is left-aligned by default, and then set to center. Setting the
alignment out of range has no effect.
## getTextSize
SkScalar getTextSize() const
Returns Text Size in points.
### Return Value
typographic height of text
### Example
---
## setTextSize
void setTextSize(SkScalar textSize)
Sets Text Size in points.
Has no effect if textSize is not greater than or equal to zero.
### Parameters
### Example
---
# Text Scale X
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
## getTextScaleX
SkScalar getTextScaleX() const
Returns Text Scale X.
Default value is 1.
### Return Value
text horizontal scale
### Example
---
## setTextScaleX
void setTextScaleX(SkScalar scaleX)
Sets Text Scale X.
Default value is 1.
### Parameters
### Example
---
# Text Skew X
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
## getTextSkewX
SkScalar getTextSkewX() const
Returns Text Skew X.
Default value is zero.
### Return Value
additional shear in x-axis relative to y-axis
### Example
---
## setTextSkewX
void setTextSkewX(SkScalar skewX)
Sets Text Skew X.
Default value is zero.
### Parameters
skewX |
additional shear in x-axis relative to y-axis |
### Example
---
# Text Encoding
## Enum SkPaint::TextEncoding
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 theUnicode 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-32encodes 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
### 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 Text Encoding.
Text Encoding 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
~~~~
---
## setTextEncoding
void setTextEncoding(TextEncoding encoding)
Sets Text Encoding to encoding.
Text Encoding determines how character code points are mapped to font glyph indices.
Invalid values for encoding are ignored.
### Parameters
### Example
#### Example Output
~~~~
4 != text encoding
~~~~
---
# Font Metrics
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 SkPaint::FontMetrics
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 relative to the baseline are given y-down. As such, 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 SkPaint::FontMetrics::FontMetricsFlags
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
uint32_t fFlags
fFlags is set when underline 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 value for all Glyphs.
Typically less than zero.
SkScalar fXMax
Maximum bounding box x value for all Glyphs.
Typically greater than zero.
SkScalar fXHeight
Height of a lower-case 'x'.
May be zero if no lower-case height is stored in the font.
SkScalar fCapHeight
Height of an upper-case letter.
May be zero if no upper-case height is stored in the font.
SkScalar fUnderlineThickness
Underline thickness.
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
Strikeout thickness.
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.
## hasUnderlineThickness
bool hasUnderlineThickness(SkScalar* thickness) const
If Font Metrics has a valid underline thickness, return true, and set
thickness to that value. If the underline thickness is not valid,
return false, and ignore thickness.
### Parameters
### Return Value
true if font specifies underline width
---
## hasUnderlinePosition
bool hasUnderlinePosition(SkScalar* position) const
If Font Metrics has a valid underline position, return true, and set
position to that value. If the underline position is not valid,
return false, and ignore position.
### Parameters
### Return Value
true if font specifies underline position
---
## hasStrikeoutThickness
bool hasStrikeoutThickness(SkScalar* thickness) const
If Font Metrics has a valid strikeout thickness, return true, and set
thickness to that value. If the underline thickness is not valid,
return false, and ignore thickness.
### Parameters
### Return Value
true if font specifies strikeout width
---
## hasStrikeoutPosition
bool hasStrikeoutPosition(SkScalar* position) const
If Font Metrics has a valid strikeout position, return true, and set
position to that value. If the underline position is not valid,
return false, and ignore position.
### Parameters
### Return Value
true if font specifies strikeout position
---
## getFontMetrics
SkScalar getFontMetrics(FontMetrics* metrics, SkScalar scale = 0) const
Returns Font Metrics associated with Typeface.
The return value is the recommended spacing between lines: the sum of metrics
descent, ascent, and leading.
If metrics is not nullptr, Font Metrics 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 Path Effect.
Results can be additionally scaled by scale; a scale of zero
is ignored.
### Parameters
### Return Value
recommended spacing between lines
### Example
### See Also
Text Size Typeface Typeface Methods
---
## getFontSpacing
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 Path Effect.
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
~~~~
---
## getFontBounds
SkRect getFontBounds() const
Returns the union of bounds of all Glyphs.
Returned dimensions are computed by Font Manager from font data,
ignoring Hinting. Includes Text Size, Text Scale X,
and Text Skew X, but not Fake Bold or Path Effect.
If Text Size is large, Text Scale X is one, and Text Skew X is zero,
returns the same bounds as Font Metrics { 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 }
~~~~
---
## textToGlyphs
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.
Text Encoding 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 Text Encoding is kUTF8 TextEncoding and
text contains an invalid UTF-8 sequence, zero is returned.
### Parameters
### Return Value
number of glyphs represented by text of length byteLength
### Example
---
## countText
int countText(const void* text, size_t byteLength) const
Returns the number of Glyphs in text.
Uses Text Encoding to count the Glyphs.
Returns the same result as textToGlyphs.
### Parameters
### Return Value
number of Glyphs represented by text of length byteLength
### Example
#### Example Output
~~~~
count = 5
~~~~
---
## containsText
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
Typeface.
If Text Encoding 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 Typeface.
Returns true if byteLength is zero.
### Parameters
### Return Value
true if all text corresponds to a non-zero glyph index
### Example
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
~~~~
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
~~~~
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 Typeface, but is unaffected
by Text Encoding; 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
---
# Measure Text
## measureText
SkScalar measureText(const void* text, size_t length, SkRect* bounds) const
Returns the advance width of text if kVerticalText Flag is clear,
and the height of text if kVerticalText Flag is set.
The advance is the normal distance to move before drawing additional text.
Uses Text Encoding to decode text, Typeface to get the font metrics,
and Text Size, Text Scale X, Text Skew X, Stroke Width, and
Path Effect 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 if kVerticalText Flag is clear,
and the height of text if kVerticalText Flag is set.
The advance is the normal distance to move before drawing additional text.
Uses Text Encoding to decode text, Typeface to get the font metrics,
and Text Size to scale the metrics.
Does not scale the advance or bounds by Fake Bold or Path Effect.
### 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
~~~~
---
## breakText
size_t breakText(const void* text, size_t length, SkScalar maxWidth,
SkScalar* measuredWidth = nullptr) const
Returns the bytes of text that fit within maxWidth.
If kVerticalText Flag is clear, the text fragment fits if its advance width is less than or
equal to maxWidth.
If kVerticalText Flag is set, the text fragment fits if its advance height 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 Text Encoding to decode text, Typeface to get the font metrics,
and Text Size to scale the metrics.
Does not scale the advance or bounds by Fake Bold or Path Effect.
### Parameters
### 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.
If kVerticalText Flag is clear, widths returns the horizontal advance.
If kVerticalText Flag is set, widths returns the vertical advance.
Uses Text Encoding to decode text, Typeface to get the font metrics,
and Text Size to scale the widths and bounds.
Does not scale the advance by Fake Bold or Path Effect.
Does include Fake Bold and Path Effect 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.
void getTextPath(const void* text, size_t length, SkScalar x, SkScalar y, SkPath* path) const
Returns the geometry as Path equivalent to the drawn text.
Uses Text Encoding to decode text, Typeface to get the glyph paths,
and Text Size, Fake Bold, and Path Effect to scale and modify the glyph paths.
All of the glyph paths are stored in path.
Uses x, y, and Text Align to position path.
### Parameters
### 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 Path equivalent to the drawn text.
Uses Text Encoding to decode text, Typeface to get the glyph paths,
and Text Size, Fake Bold, and Path Effect to scale and modify the glyph paths.
All of the glyph paths are stored in path.
Uses pos array and Text Align to position path.
pos contains a position for each glyph.
### Parameters
### Example
Simplifies three
Glyphs to eliminate overlaps, and strokes the result.
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 Text Encoding to decode text, Typeface to get the glyph paths,
and Text Size, Fake Bold, and Path Effect to scale and modify the glyph paths.
Uses x, y, and Text Align 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-coordinate of the origin of the text |
y |
y-coordinate 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 Text Encoding to decode text, Typeface to get the glyph paths,
and Text Size, Fake Bold, and Path Effect to scale and modify the glyph paths.
Uses pos array and Text Align 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 Text Encoding to decode text, Typeface to get the glyph paths,
and Text Size, Fake Bold, and Path Effect to scale and modify the glyph paths.
Uses xpos array, constY, and Text Align 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 in x |
constY |
position of each glyph in y |
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 Typeface to get the glyph paths,
and Text Size, Fake Bold, and Path Effect to scale and modify the glyph paths.
Uses run array and Text Align to position intervals.
Text Encoding 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
---
## nothingToDraw
bool nothingToDraw() const
Returns true if Paint prevents all drawing;
otherwise, the Paint may or may not allow drawing.
Returns true if, for example, Blend Mode combined with Color Alpha computes a
new Alpha of zero.
### Return Value
true if Paint 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
~~~~
---
# Fast Bounds
Fast Bounds methods conservatively outset a drawing bounds by additional area
Paint may draw to.
## canComputeFastBounds
bool canComputeFastBounds() const
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
---
## computeFastBounds
const SkRect& computeFastBounds(const SkRect& orig, SkRect* storage) const
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.
### Parameters
orig |
geometry modified by Paint when drawn |
storage |
computed bounds of geometry; may not be nullptr |
### Return Value
fast computed bounds
---
## computeFastStrokeBounds
const SkRect& computeFastStrokeBounds(const SkRect& orig, SkRect* storage) const
### Parameters
### Return Value
fast computed bounds
---
## doComputeFastBounds
const SkRect& doComputeFastBounds(const SkRect& orig, SkRect* storage, Style style) const
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
### Return Value
fast computed bounds
---
## toString
void toString(SkString* str) const;
Creates string representation of Paint. The representation is read by
internal debugging tools. The interface and implementation may be
suppressed by defining SK IGNORE TO STRING.
### Parameters
str |
storage for string representation of Paint |
### Example
#### Example Output
~~~~
text size = 12
~~~~
### See Also
SkPathEffect::toString SkMaskFilter::toString SkColorFilter::toString SkImageFilter::toString
---