blob: 9b9d001750a7e937c45948b54affb27e0a6c56ee [file] [log] [blame]
#Topic Paint
#Alias Paint_Reference ##
#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.
#Subtopic Overview
#Populate
##
#Subtopic Related_Function
#Populate
##
#Subtopic Constant
#Populate
##
#Subtopic Struct
#Populate
##
#Subtopic Constructor
#Populate
##
#Subtopic Operator
#Populate
##
#Subtopic Member_Function
#Populate
##
# ------------------------------------------------------------------------------
#Subtopic Initializers
#Line # constructors and initialization ##
#Method SkPaint()
#In Initializers
#Line # constructs with default values ##
Constructs Paint with default values.
#Table
#Legend
# attribute # default value ##
#Legend ##
# 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_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 ##
#Table ##
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 default initialized Paint ##
#Example
#ToDo mark this as no output ##
#Height 1
###$ $ redefine markup character so preprocessor commands appear normally
#ifndef SkUserConfig_DEFINED
#define SkUserConfig_DEFINED
#define SkPaintDefaults_Flags 0x01 // always enable antialiasing
#define SkPaintDefaults_TextSize 24.f // double default font size
#define SkPaintDefaults_Hinting 3 // use full hinting
#define SkPaintDefaults_MiterLimit 10.f // use HTML Canvas miter limit setting
#endif
$$$# # restore original markup character
##
##
#Method SkPaint(const SkPaint& paint)
#In Initializers
#Line # makes a shallow copy ##
Makes a shallow copy of Paint. Typeface, Path_Effect, Shader,
Mask_Filter, Color_Filter, 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,
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.
#Param paint original to copy ##
#Return shallow copy of paint ##
#Example
#ToDo why is this double-spaced on Fiddle? ##
SkPaint paint1;
paint1.setColor(SK_ColorRED);
SkPaint paint2(paint1);
paint2.setColor(SK_ColorBLUE);
SkDebugf("SK_ColorRED %c= paint1.getColor()\n", SK_ColorRED == paint1.getColor() ? '=' : '!');
SkDebugf("SK_ColorBLUE %c= paint2.getColor()\n", SK_ColorBLUE == paint2.getColor() ? '=' : '!');
#StdOut
SK_ColorRED == paint1.getColor()
SK_ColorBLUE == paint2.getColor()
##
##
##
#Method SkPaint(SkPaint&& paint)
#In Initializers
#Line # moves paint without copying it ##
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.
#Param paint original to move ##
#Return content of paint ##
#Example
SkPaint paint;
float intervals[] = { 5, 5 };
paint.setPathEffect(SkDashPathEffect::Make(intervals, SK_ARRAY_COUNT(intervals), 2.5f));
SkPaint dashed(std::move(paint));
SkDebugf("path effect unique: %s\n", dashed.getPathEffect()->unique() ? "true" : "false");
#StdOut
path effect unique: true
##
##
##
# ------------------------------------------------------------------------------
#Method void reset()
#In Initializers
#Line # sets to default values ##
Sets all Paint contents to their initial values. This is equivalent to replacing
Paint with the result of SkPaint().
#Example
SkPaint paint1, paint2;
paint1.setColor(SK_ColorRED);
paint1.reset();
SkDebugf("paint1 %c= paint2", paint1 == paint2 ? '=' : '!');
#StdOut
paint1 == paint2
##
##
##
#Subtopic Initializers ##
# ------------------------------------------------------------------------------
#Method ~SkPaint()
#Line # decreases Reference_Count of owned objects ##
Decreases Paint Reference_Count of owned objects: Typeface, Path_Effect, Shader,
Mask_Filter, Color_Filter, Draw_Looper, and Image_Filter. If the
objects containing Reference_Count go to zero, they are deleted.
#NoExample
##
##
# ------------------------------------------------------------------------------
#Subtopic Management
#Line # paint copying, moving, comparing ##
#Method SkPaint& operator=(const SkPaint& paint)
#In Management
#Line # makes a shallow copy ##
Makes a shallow copy of Paint. Typeface, Path_Effect, Shader,
Mask_Filter, Color_Filter, 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.
#Param paint original to copy ##
#Return content of paint ##
#Example
SkPaint paint1, paint2;
paint1.setColor(SK_ColorRED);
paint2 = paint1;
SkDebugf("SK_ColorRED %c= paint1.getColor()\n", SK_ColorRED == paint1.getColor() ? '=' : '!');
SkDebugf("SK_ColorRED %c= paint2.getColor()\n", SK_ColorRED == paint2.getColor() ? '=' : '!');
#StdOut
SK_ColorRED == paint1.getColor()
SK_ColorRED == paint2.getColor()
##
##
##
# ------------------------------------------------------------------------------
#Method SkPaint& operator=(SkPaint&& paint)
#In Management
#Line # moves paint without copying it ##
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.
#Param paint original to move ##
#Return content of paint ##
#Example
SkPaint paint1, paint2;
paint1.setColor(SK_ColorRED);
paint2 = std::move(paint1);
SkDebugf("SK_ColorRED == paint2.getColor()\n", SK_ColorRED == paint2.getColor() ? '=' : '!');
#StdOut
SK_ColorRED == paint2.getColor()
##
##
##
# ------------------------------------------------------------------------------
#Method bool operator==(const SkPaint& a, const SkPaint& b)
#In Management
#Line # compares paints for equality ##
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,
Draw_Looper, or Image_Filter have identical contents but different pointers.
#Param a Paint to compare ##
#Param b Paint to compare ##
#Return true if Paint pair are equivalent ##
#Example
SkPaint paint1, paint2;
paint1.setColor(SK_ColorRED);
paint2.setColor(0xFFFF0000);
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');
float intervals[] = { 5, 5 };
paint1.setPathEffect(SkDashPathEffect::Make(intervals, 2, 2.5f));
paint2.setPathEffect(SkDashPathEffect::Make(intervals, 2, 2.5f));
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');
#StdOut
paint1 == paint2
paint1 != paint2
##
##
#SeeAlso operator!=(const SkPaint& a, const SkPaint& b)
##
# ------------------------------------------------------------------------------
#Method bool operator!=(const SkPaint& a, const SkPaint& b)
#In Management
#Line # compares paints for inequality ##
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,
Draw_Looper, or Image_Filter have identical contents but different pointers.
#Param a Paint to compare ##
#Param b Paint to compare ##
#Return true if Paint pair are not equivalent ##
#Example
SkPaint paint1, paint2;
paint1.setColor(SK_ColorRED);
paint2.setColor(0xFFFF0000);
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');
SkDebugf("paint1 %c= paint2\n", paint1 != paint2 ? '!' : '=');
#StdOut
paint1 == paint2
paint1 == paint2
##
##
#SeeAlso operator==(const SkPaint& a, const SkPaint& b)
##
# ------------------------------------------------------------------------------
#Method uint32_t getHash() const
#In Management
#Line # returns a shallow hash for equality checks ##
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 a shallow hash ##
#Example
SkPaint paint1, paint2;
paint1.setColor(SK_ColorRED);
paint2.setColor(0xFFFF0000);
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');
SkDebugf("paint1.getHash() %c= paint2.getHash()\n",
paint1.getHash() == paint2.getHash() ? '=' : '!');
#StdOut
paint1 == paint2
paint1.getHash() == paint2.getHash()
##
##
##
#Subtopic Management ##
# ------------------------------------------------------------------------------
#Subtopic Hinting
#Line # glyph outline adjustment ##
#Enum Hinting
#Line # level of glyph outline adjustment ##
#Code
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.
#Const kNo_Hinting 0
#Line # glyph outlines unchanged ##
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.
##
#Const kSlight_Hinting 1
#Line # minimal modification to improve constrast ##
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.
##
#Const kNormal_Hinting 2
#Line # glyph outlines modified to improve constrast ##
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.
##
#Const kFull_Hinting 3
#Line # modifies glyph outlines for maximum constrast ##
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.
##
#Bug 915
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.
#ToDo add an illustration? linux running GM:typefacerendering is best for this
the hinting variations are every other character horizontally
#ToDo ##
#Enum ##
#Method Hinting getHinting() const
#In Hinting
#Line # returns Hinting, glyph outline adjustment level ##
Returns level of glyph outline adjustment.
#Return one of: kNo_Hinting, kSlight_Hinting, kNormal_Hinting, kFull_Hinting ##
#Example
SkPaint paint;
SkDebugf("SkPaint::kNormal_Hinting %c= paint.getHinting()\n",
SkPaint::kNormal_Hinting == paint.getHinting() ? '=' : ':');
#StdOut
SkPaint::kNormal_Hinting == paint.getHinting()
##
##
##
#Method void setHinting(Hinting hintingLevel)
#In Hinting
#Line # sets Hinting, glyph outline adjustment level ##
Sets level of glyph outline adjustment.
Does not check for valid values of hintingLevel.
#Table
#Legend
# 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 ##
##
#Param hintingLevel one of: kNo_Hinting, kSlight_Hinting, kNormal_Hinting, kFull_Hinting ##
#Example
SkPaint paint1, paint2;
paint2.setHinting(SkPaint::kNormal_Hinting);
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : ':');
#StdOut
paint1 == paint2
##
##
##
#Subtopic Hinting ##
# ------------------------------------------------------------------------------
#Subtopic Flags
#Line # attributes represented by single bits ##
#Enum Flags
#Line # values described by bits and masks ##
#Code
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,
kVerticalText_Flag = 0x1000,
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.
#Const kAntiAlias_Flag 0x0001
#Line # mask for setting Anti_Alias ##
##
#Const kDither_Flag 0x0004
#Line # mask for setting Dither ##
##
#Const kFakeBoldText_Flag 0x0020
#Line # mask for setting Fake_Bold ##
##
#Const kLinearText_Flag 0x0040
#Line # mask for setting Linear_Text ##
##
#Const kSubpixelText_Flag 0x0080
#Line # mask for setting Subpixel_Text ##
##
#Const kLCDRenderText_Flag 0x0200
#Line # mask for setting LCD_Text ##
##
#Const kEmbeddedBitmapText_Flag 0x0400
#Line # mask for setting Font_Embedded_Bitmaps ##
##
#Const kAutoHinting_Flag 0x0800
#Line # mask for setting Automatic_Hinting ##
##
#Const kVerticalText_Flag 0x1000
#Line # mask for setting Vertical_Text ##
##
#Const kAllFlags 0xFFFF
#Line # mask of all Flags ##
mask of all Flags, including private flags and flags reserved for future use
##
Flags default to all flags clear, disabling the associated feature.
#Enum ##
#Enum ReserveFlags
#Deprecated soon
Only valid for Android framework.
#Code
enum ReserveFlags {
kUnderlineText_ReserveFlag = 0x08,
kStrikeThruText_ReserveFlag = 0x10,
};
##
#Const kUnderlineText_ReserveFlag 0x0008
#Deprecated soon
##
#Const kStrikeThruText_ReserveFlag 0x0010
#Deprecated soon
##
##
#Method uint32_t getFlags() const
#In Flags
#Line # returns Flags stored in a bit field ##
Returns paint settings described by Flags. Each setting uses one
bit, and can be tested with Flags members.
#Return zero, one, or more bits described by Flags ##
#Example
SkPaint paint;
paint.setAntiAlias(true);
SkDebugf("(SkPaint::kAntiAlias_Flag & paint.getFlags()) %c= 0\n",
SkPaint::kAntiAlias_Flag & paint.getFlags() ? '!' : '=');
#StdOut
(SkPaint::kAntiAlias_Flag & paint.getFlags()) != 0
##
##
##
#Method void setFlags(uint32_t flags)
#In Flags
#Line # sets multiple Flags in a bit field ##
Replaces Flags with flags, the union of the Flags members.
All Flags members may be cleared, or one or more may be set.
#Param flags union of Flags for Paint ##
#Example
SkPaint paint;
paint.setFlags((uint32_t) (SkPaint::kAntiAlias_Flag | SkPaint::kDither_Flag));
SkDebugf("paint.isAntiAlias()\n", paint.isAntiAlias() ? '!' : '=');
SkDebugf("paint.isDither()\n", paint.isDither() ? '!' : '=');
#StdOut
paint.isAntiAlias()
paint.isDither()
##
##
##
#Subtopic Flags ##
# ------------------------------------------------------------------------------
#Subtopic Anti_Alias
#Alias Anti_Alias
#Substitute anti-alias
##
#Alias Anti_Aliased
#Substitute anti-aliased
##
#Alias Anti_Aliasing
#Substitute anti-aliasing
##
#In Related_Function
#Line # approximating coverage with transparency ##
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.
#ToDo add illustration of raster pixels ##
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
#Width 512
#Description
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.
##
void draw(SkCanvas* canvas) {
SkBitmap bitmap;
bitmap.allocN32Pixels(50, 50);
SkCanvas offscreen(bitmap);
SkPaint paint;
paint.setStyle(SkPaint::kStroke_Style);
paint.setStrokeWidth(10);
for (bool antialias : { false, true }) {
paint.setColor(antialias ? SK_ColorRED : SK_ColorBLUE);
paint.setAntiAlias(antialias);
bitmap.eraseColor(0);
offscreen.drawLine(5, 5, 15, 30, paint);
canvas->drawLine(5, 5, 15, 30, paint);
canvas->save();
canvas->scale(10, 10);
canvas->drawBitmap(bitmap, antialias ? 12 : 0, 0);
canvas->restore();
canvas->translate(15, 0);
}
}
##
#Method bool isAntiAlias() const
#In Anti_alias
#Line # returns true if Anti_Alias is set ##
If true, pixels on the active edges of Path may be drawn with partial transparency.
Equivalent to getFlags masked with kAntiAlias_Flag.
#Return kAntiAlias_Flag state ##
#Example
SkPaint paint;
SkDebugf("paint.isAntiAlias() %c= !!(paint.getFlags() & SkPaint::kAntiAlias_Flag)\n",
paint.isAntiAlias() == !!(paint.getFlags() & SkPaint::kAntiAlias_Flag) ? '=' : '!');
paint.setAntiAlias(true);
SkDebugf("paint.isAntiAlias() %c= !!(paint.getFlags() & SkPaint::kAntiAlias_Flag)\n",
paint.isAntiAlias() == !!(paint.getFlags() & SkPaint::kAntiAlias_Flag) ? '=' : '!');
#StdOut
paint.isAntiAlias() == !!(paint.getFlags() & SkPaint::kAntiAlias_Flag)
paint.isAntiAlias() == !!(paint.getFlags() & SkPaint::kAntiAlias_Flag)
##
##
##
#Method void setAntiAlias(bool aa)
#In Anti_alias
#Line # sets or clears Anti_Alias ##
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.
#Param aa setting for kAntiAlias_Flag ##
#Example
SkPaint paint1, paint2;
paint1.setAntiAlias(true);
paint2.setFlags(paint2.getFlags() | SkPaint::kAntiAlias_Flag);
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');
#StdOut
paint1 == paint2
##
##
##
#Subtopic Anti_Alias ##
# ------------------------------------------------------------------------------
#Subtopic Dither
#Line # distributing color error ##
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
#Formula
SK_IGNORE_GPU_DITHER
##
to ignore Dither on GPU_Surface.
#Example
#Description
Dithering in the bottom half more closely approximates the requested color by
alternating nearby colors from pixel to pixel.
##
void draw(SkCanvas* canvas) {
SkBitmap bm16;
bm16.allocPixels(SkImageInfo::Make(32, 32, kRGB_565_SkColorType, kOpaque_SkAlphaType));
SkCanvas c16(bm16);
SkPaint colorPaint;
for (auto dither : { false, true } ) {
colorPaint.setDither(dither);
for (auto colors : { 0xFF333333, 0xFF666666, 0xFF999999, 0xFFCCCCCC } ) {
for (auto mask : { 0xFFFF0000, 0xFF00FF00, 0xFF0000FF, 0xFFFFFFFF } ) {
colorPaint.setColor(colors & mask);
c16.drawRect({0, 0, 8, 4}, colorPaint);
c16.translate(8, 0);
}
c16.translate(-32, 4);
}
}
canvas->scale(8, 8);
canvas->drawBitmap(bm16, 0, 0);
}
##
#Example
#Description
Dithering introduces subtle adjustments to color to smooth gradients.
Drawing the gradient repeatedly with SkBlendMode::kPlus exaggerates the
dither, making it easier to see.
##
void draw(SkCanvas* canvas) {
canvas->clear(0);
SkBitmap bm32;
bm32.allocPixels(SkImageInfo::Make(20, 10, kN32_SkColorType, kPremul_SkAlphaType));
SkCanvas c32(bm32);
SkPoint points[] = {{0, 0}, {20, 0}};
SkColor colors[] = {0xFF334455, 0xFF662211 };
SkPaint paint;
paint.setShader(SkGradientShader::MakeLinear(
points, colors, nullptr, SK_ARRAY_COUNT(colors),
SkShader::kClamp_TileMode, 0, nullptr));
paint.setDither(true);
c32.drawPaint(paint);
canvas->scale(12, 12);
canvas->drawBitmap(bm32, 0, 0);
paint.setBlendMode(SkBlendMode::kPlus);
canvas->drawBitmap(bm32, 0, 11, &paint);
canvas->drawBitmap(bm32, 0, 11, &paint);
canvas->drawBitmap(bm32, 0, 11, &paint);
}
##
#Method bool isDither() const
#In Dither
#Line # returns true if Dither is set ##
If true, color error may be distributed to smooth color transition.
Equivalent to getFlags masked with kDither_Flag.
#Return kDither_Flag state ##
#Example
SkPaint paint;
SkDebugf("paint.isDither() %c= !!(paint.getFlags() & SkPaint::kDither_Flag)\n",
paint.isDither() == !!(paint.getFlags() & SkPaint::kDither_Flag) ? '=' : '!');
paint.setDither(true);
SkDebugf("paint.isDither() %c= !!(paint.getFlags() & SkPaint::kDither_Flag)\n",
paint.isDither() == !!(paint.getFlags() & SkPaint::kDither_Flag) ? '=' : '!');
#StdOut
paint.isDither() == !!(paint.getFlags() & SkPaint::kDither_Flag)
paint.isDither() == !!(paint.getFlags() & SkPaint::kDither_Flag)
##
##
##
#Method void setDither(bool dither)
#In Dither
#Line # sets or clears Dither ##
Requests, but does not require, to distribute color error.
Sets kDither_Flag if dither is true.
Clears kDither_Flag if dither is false.
#Param dither setting for kDither_Flag ##
#Example
SkPaint paint1, paint2;
paint1.setDither(true);
paint2.setFlags(paint2.getFlags() | SkPaint::kDither_Flag);
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');
#StdOut
paint1 == paint2
##
##
#SeeAlso kRGB_565_SkColorType
##
#SeeAlso Gradient kRGB_565_SkColorType
#Subtopic Dither ##
# ------------------------------------------------------------------------------
#Subtopic Device_Text
#Line # increase precision of glyph position ##
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
#Description
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.
##
SkBitmap bitmap;
bitmap.allocN32Pixels(24, 33);
SkCanvas offscreen(bitmap);
offscreen.clear(SK_ColorWHITE);
SkPaint paint;
paint.setAntiAlias(true);
paint.setTextSize(20);
for (bool lcd : { false, true }) {
paint.setLCDRenderText(lcd);
for (bool subpixel : { false, true }) {
paint.setSubpixelText(subpixel);
offscreen.drawString(",,,,", 0, 4, paint);
offscreen.translate(0, 7);
}
}
canvas->drawBitmap(bitmap, 4, 12);
canvas->scale(9, 9);
canvas->drawBitmap(bitmap, 4, -1);
##
#Subtopic Device_Text ##
#Subtopic Linear_Text
#Alias Linear_Text ##
#Line # selects text rendering as Glyph or Path ##
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.
#Method bool isLinearText() const
#Line # returns true if text is converted to Path ##
#In Linear_Text
If true, text is converted to Path before drawing and measuring.
Equivalent to getFlags masked with kLinearText_Flag.
#Return kLinearText_Flag state ##
#Example
#Height 128
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setAntiAlias(true);
const char testStr[] = "xxxx xxxx";
for (auto linearText : { false, true } ) {
paint.setLinearText(linearText);
paint.setTextSize(24);
canvas->drawString(paint.isLinearText() ? "linear" : "hinted", 128, 30, paint);
for (SkScalar textSize = 8; textSize < 30; textSize *= 1.22f) {
paint.setTextSize(textSize);
canvas->translate(0, textSize);
canvas->drawString(testStr, 10, 0, paint);
}
}
}
##
#SeeAlso setLinearText Hinting
##
#Method void setLinearText(bool linearText)
#Line # converts to Path before draw or measure ##
#In Linear_Text
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.
#Param linearText setting for kLinearText_Flag ##
#Example
#Height 128
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setAntiAlias(true);
const char testStr[] = "abcd efgh";
for (int textSize : { 12, 24 } ) {
paint.setTextSize(textSize);
for (auto linearText : { false, true } ) {
paint.setLinearText(linearText);
SkString width;
width.appendScalar(paint.measureText(testStr, SK_ARRAY_COUNT(testStr), nullptr));
canvas->translate(0, textSize + 4);
canvas->drawString(testStr, 10, 0, paint);
canvas->drawString(width, 128, 0, paint);
}
}
}
##
#SeeAlso isLinearText Hinting
##
#Subtopic Linear_Text ##
#Subtopic Subpixel_Text
#Alias Subpixel_Text ##
#Line # uses pixel transparency to represent fractional offset ##
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.
#Method bool isSubpixelText() const
#In Subpixel_Text
#Line # returns true if Subpixel_Text is set ##
If true, Glyphs at different sub-pixel positions may differ on pixel edge coverage.
Equivalent to getFlags masked with kSubpixelText_Flag.
#Return kSubpixelText_Flag state ##
#Example
SkPaint paint;
SkDebugf("paint.isSubpixelText() %c= !!(paint.getFlags() & SkPaint::kSubpixelText_Flag)\n",
paint.isSubpixelText() == !!(paint.getFlags() & SkPaint::kSubpixelText_Flag) ? '=' : '!');
paint.setSubpixelText(true);
SkDebugf("paint.isSubpixelText() %c= !!(paint.getFlags() & SkPaint::kSubpixelText_Flag)\n",
paint.isSubpixelText() == !!(paint.getFlags() & SkPaint::kSubpixelText_Flag) ? '=' : '!');
#StdOut
paint.isSubpixelText() == !!(paint.getFlags() & SkPaint::kSubpixelText_Flag)
paint.isSubpixelText() == !!(paint.getFlags() & SkPaint::kSubpixelText_Flag)
##
##
##
#Method void setSubpixelText(bool subpixelText)
#In Subpixel_Text
#Line # sets or clears Subpixel_Text ##
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.
#Param subpixelText setting for kSubpixelText_Flag ##
#Example
SkPaint paint1, paint2;
paint1.setSubpixelText(true);
paint2.setFlags(paint2.getFlags() | SkPaint::kSubpixelText_Flag);
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');
#StdOut
paint1 == paint2
##
##
##
#Subtopic Subpixel_Text ##
#Subtopic LCD_Text
#Line # text relying on the order of RGB stripes ##
# make this a top level name, since it is under subtopic Device_Text
#Alias LCD_Text
#Substitute LCD text
##
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.
#Method bool isLCDRenderText() const
#In LCD_Text
#Line # returns true if LCD_Text is set ##
If true, Glyphs may use LCD striping to improve glyph edges.
Returns true if Flags kLCDRenderText_Flag is set.
#Return kLCDRenderText_Flag state ##
#Example
SkPaint paint;
SkDebugf("paint.isLCDRenderText() %c= !!(paint.getFlags() & SkPaint::kLCDRenderText_Flag)\n",
paint.isLCDRenderText() == !!(paint.getFlags() & SkPaint::kLCDRenderText_Flag) ? '=' : '!');
paint.setLCDRenderText(true);
SkDebugf("paint.isLCDRenderText() %c= !!(paint.getFlags() & SkPaint::kLCDRenderText_Flag)\n",
paint.isLCDRenderText() == !!(paint.getFlags() & SkPaint::kLCDRenderText_Flag) ? '=' : '!');
#StdOut
paint.isLCDRenderText() == !!(paint.getFlags() & SkPaint::kLCDRenderText_Flag)
paint.isLCDRenderText() == !!(paint.getFlags() & SkPaint::kLCDRenderText_Flag)
##
##
##
#Method void setLCDRenderText(bool lcdText)
#In LCD_Text
#Line # sets or clears LCD_Text ##
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.
#Param lcdText setting for kLCDRenderText_Flag ##
#Example
SkPaint paint1, paint2;
paint1.setLCDRenderText(true);
paint2.setFlags(paint2.getFlags() | SkPaint::kLCDRenderText_Flag);
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');
#StdOut
paint1 == paint2
##
##
##
#Subtopic LCD_Text ##
# ------------------------------------------------------------------------------
#Subtopic Font_Embedded_Bitmaps
#Line # custom sized bitmap Glyphs ##
#Alias Font_Embedded_Bitmaps ## # long-winded enough, alias so I don't type Paint_Font_...
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
#ToDo image will only output on Ubuntu ... how to handle that in fiddle? ##
#Platform !fiddle
#Description
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.
##
#Image embeddedbitmap.png
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);
##
#Method bool isEmbeddedBitmapText() const
#In Font_Embedded_Bitmaps
#Line # returns true if Font_Embedded_Bitmaps is set ##
If true, Font_Engine may return Glyphs from font bitmaps instead of from outlines.
Equivalent to getFlags masked with kEmbeddedBitmapText_Flag.
#Return kEmbeddedBitmapText_Flag state ##
#Example
SkPaint paint;
SkDebugf("paint.isEmbeddedBitmapText() %c="
" !!(paint.getFlags() & SkPaint::kEmbeddedBitmapText_Flag)\n",
paint.isEmbeddedBitmapText() ==
!!(paint.getFlags() & SkPaint::kEmbeddedBitmapText_Flag) ? '=' : '!');
paint.setEmbeddedBitmapText(true);
SkDebugf("paint.isEmbeddedBitmapText() %c="
" !!(paint.getFlags() & SkPaint::kEmbeddedBitmapText_Flag)\n",
paint.isEmbeddedBitmapText() ==
!!(paint.getFlags() & SkPaint::kEmbeddedBitmapText_Flag) ? '=' : '!');
#StdOut
paint.isEmbeddedBitmapText() == !!(paint.getFlags() & SkPaint::kEmbeddedBitmapText_Flag)
paint.isEmbeddedBitmapText() == !!(paint.getFlags() & SkPaint::kEmbeddedBitmapText_Flag)
##
##
##
#Method void setEmbeddedBitmapText(bool useEmbeddedBitmapText)
#In Font_Embedded_Bitmaps
#Line # sets or clears Font_Embedded_Bitmaps ##
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.
#Param useEmbeddedBitmapText setting for kEmbeddedBitmapText_Flag ##
#Example
SkPaint paint1, paint2;
paint1.setEmbeddedBitmapText(true);
paint2.setFlags(paint2.getFlags() | SkPaint::kEmbeddedBitmapText_Flag);
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');
#StdOut
paint1 == paint2
##
##
##
#Subtopic Font_Embedded_Bitmaps ##
# ------------------------------------------------------------------------------
#Subtopic Automatic_Hinting
#Line # always adjust glyph paths ##
#Substitute auto-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.
#Method bool isAutohinted() const
#In Automatic_Hinting
#Line # returns true if Glyphs are always hinted ##
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 kAutoHinting_Flag state ##
#Example
SkPaint paint;
for (auto forceAutoHinting : { false, true} ) {
paint.setAutohinted(forceAutoHinting);
SkDebugf("paint.isAutohinted() %c="
" !!(paint.getFlags() & SkPaint::kAutoHinting_Flag)\n",
paint.isAutohinted() ==
!!(paint.getFlags() & SkPaint::kAutoHinting_Flag) ? '=' : '!');
}
#StdOut
paint.isAutohinted() == !!(paint.getFlags() & SkPaint::kAutoHinting_Flag)
paint.isAutohinted() == !!(paint.getFlags() & SkPaint::kAutoHinting_Flag)
##
##
#SeeAlso setAutohinted Hinting
##
#Method void setAutohinted(bool useAutohinter)
#In Automatic_Hinting
#Line # sets Glyphs to always be hinted ##
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.
#Param useAutohinter setting for kAutoHinting_Flag ##
#Example
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setAntiAlias(true);
const char testStr[] = "xxxx xxxx";
for (auto forceAutoHinting : { false, true} ) {
paint.setAutohinted(forceAutoHinting);
paint.setTextSize(24);
canvas->drawString(paint.isAutohinted() ? "auto-hinted" : "default", 108, 30, paint);
for (SkScalar textSize = 8; textSize < 30; textSize *= 1.22f) {
paint.setTextSize(textSize);
canvas->translate(0, textSize);
canvas->drawString(testStr, 10, 0, paint);
}
}
}
##
#SeeAlso isAutohinted Hinting
##
#Subtopic Automatic_Hinting ##
# ------------------------------------------------------------------------------
#Subtopic Vertical_Text
#Line # orient text from top to bottom ##
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 like
#A HarfBuzz # https://harfbuzz.org/ ##
to 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
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setAntiAlias(true);
paint.setTextSize(50);
for (bool vertical : { false, true } ) {
paint.setVerticalText(vertical);
canvas->drawString("aAlL", 25, 50, paint);
}
}
##
#Method bool isVerticalText() const
#In Vertical_Text
#Line # returns true if Vertical_Text is set ##
If true, Glyphs are drawn top to bottom instead of left to right.
Equivalent to getFlags masked with kVerticalText_Flag.
#Return kVerticalText_Flag state ##
#Example
SkPaint paint;
SkDebugf("paint.isVerticalText() %c= !!(paint.getFlags() & SkPaint::kVerticalText_Flag)\n",
paint.isVerticalText() == !!(paint.getFlags() & SkPaint::kVerticalText_Flag) ? '=' : '!');
paint.setVerticalText(true);
SkDebugf("paint.isVerticalText() %c= !!(paint.getFlags() & SkPaint::kVerticalText_Flag)\n",
paint.isVerticalText() == !!(paint.getFlags() & SkPaint::kVerticalText_Flag) ? '=' : '!');
#StdOut
paint.isVerticalText() == !!(paint.getFlags() & SkPaint::kVerticalText_Flag)
paint.isVerticalText() == !!(paint.getFlags() & SkPaint::kVerticalText_Flag)
##
##
##
#Method void setVerticalText(bool verticalText)
#In Vertical_Text
#Line # sets or clears Vertical_Text ##
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.
#Param verticalText setting for kVerticalText_Flag ##
#Example
SkPaint paint1, paint2;
paint1.setVerticalText(true);
paint2.setFlags(paint2.getFlags() | SkPaint::kVerticalText_Flag);
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');
#StdOut
paint1 == paint2
##
##
##
#Subtopic Vertical_Text ##
# ------------------------------------------------------------------------------
#Subtopic Fake_Bold
#Line # approximate font styles ##
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
#Height 128
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setAntiAlias(true);
paint.setTextSize(40);
canvas->drawString("OjYy_-", 10, 35, paint);
paint.setFakeBoldText(true);
canvas->drawString("OjYy_-", 10, 75, paint);
// create a custom fake bold by varying the stroke width
paint.setFakeBoldText(false);
paint.setStyle(SkPaint::kStrokeAndFill_Style);
paint.setStrokeWidth(40.f / 48);
canvas->drawString("OjYy_-", 10, 115, paint);
}
##
#Method bool isFakeBoldText() const
#In Fake_Bold
#Line # returns true if Fake_Bold is set ##
If true, approximate bold by increasing the stroke width when creating glyph bitmaps
from outlines.
Equivalent to getFlags masked with kFakeBoldText_Flag.
#Return kFakeBoldText_Flag state ##
#Example
SkPaint paint;
SkDebugf("paint.isFakeBoldText() %c= !!(paint.getFlags() & SkPaint::kFakeBoldText_Flag)\n",
paint.isFakeBoldText() == !!(paint.getFlags() & SkPaint::kFakeBoldText_Flag) ? '=' : '!');
paint.setFakeBoldText(true);
SkDebugf("paint.isFakeBoldText() %c= !!(paint.getFlags() & SkPaint::kFakeBoldText_Flag)\n",
paint.isFakeBoldText() == !!(paint.getFlags() & SkPaint::kFakeBoldText_Flag) ? '=' : '!');
#StdOut
paint.isFakeBoldText() == !!(paint.getFlags() & SkPaint::kFakeBoldText_Flag)
paint.isFakeBoldText() == !!(paint.getFlags() & SkPaint::kFakeBoldText_Flag)
##
##
##
#Method void setFakeBoldText(bool fakeBoldText)
#In Fake_Bold
#Line # sets or clears Fake_Bold ##
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.
#Param fakeBoldText setting for kFakeBoldText_Flag ##
#Example
SkPaint paint1, paint2;
paint1.setFakeBoldText(true);
paint2.setFlags(paint2.getFlags() | SkPaint::kFakeBoldText_Flag);
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');
#StdOut
paint1 == paint2
##
##
##
#Subtopic Fake_Bold ##
# ------------------------------------------------------------------------------
#Subtopic Full_Hinting_Spacing
#Line # glyph spacing affected by hinting ##
#Alias Full_Hinting_Spacing ## # long winded enough -- maybe things with two underscores auto-aliased?
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.
#Method bool isDevKernText() const
#Deprecated
##
#Method void setDevKernText(bool)
#Deprecated
##
#Subtopic Full_Hinting_Spacing ##
# ------------------------------------------------------------------------------
#Subtopic Filter_Quality_Methods
#Line # get and set Filter_Quality ##
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
#List
# SkCanvas::drawBitmap ##
# SkCanvas::drawBitmapRect ##
# SkCanvas::drawImage ##
# SkCanvas::drawImageRect ##
#ToDo probably more... ##
#List ##
and when Paint has a Shader specialization that uses Image or Bitmap.
Filter_Quality is kNone_SkFilterQuality by default.
#Example
#Image 3
void draw(SkCanvas* canvas) {
SkPaint paint;
canvas->scale(.2f, .2f);
for (SkFilterQuality q : { kNone_SkFilterQuality, kLow_SkFilterQuality,
kMedium_SkFilterQuality, kHigh_SkFilterQuality } ) {
paint.setFilterQuality(q);
canvas->drawImage(image.get(), 0, 0, &paint);
canvas->translate(550, 0);
if (kLow_SkFilterQuality == q) canvas->translate(-1100, 550);
}
}
##
#Method SkFilterQuality getFilterQuality() const
#In Filter_Quality_Methods
#Line # returns Filter_Quality, image filtering level ##
Returns Filter_Quality, the image filtering level. A lower setting
draws faster; a higher setting looks better when the image is scaled.
#Return one of: kNone_SkFilterQuality, kLow_SkFilterQuality,
kMedium_SkFilterQuality, kHigh_SkFilterQuality
#Return ##
#Example
SkPaint paint;
SkDebugf("kNone_SkFilterQuality %c= paint.getFilterQuality()\n",
kNone_SkFilterQuality == paint.getFilterQuality() ? '=' : '!');
#StdOut
kNone_SkFilterQuality == paint.getFilterQuality()
##
##
##
#Method void setFilterQuality(SkFilterQuality quality)
#In Filter_Quality_Methods
#Line # sets Filter_Quality, the image filtering level ##
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.
#Param quality one of: kNone_SkFilterQuality, kLow_SkFilterQuality,
kMedium_SkFilterQuality, kHigh_SkFilterQuality
##
#Example
SkPaint paint;
paint.setFilterQuality(kHigh_SkFilterQuality);
SkDebugf("kHigh_SkFilterQuality %c= paint.getFilterQuality()\n",
kHigh_SkFilterQuality == paint.getFilterQuality() ? '=' : '!');
#StdOut
kHigh_SkFilterQuality == paint.getFilterQuality()
##
##
#SeeAlso SkFilterQuality Image_Scaling
##
#Subtopic Filter_Quality_Methods ##
# ------------------------------------------------------------------------------
#Subtopic Color_Methods
#Line # get and set Color ##
#Table
#Legend
# name # description ##
#Legend ##
# getColor # returns Color_Alpha and RGB, one drawing color ##
# setColor # sets Color_Alpha and RGB, one drawing color ##
#Table ##
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.
#Table
#Legend
# bit positions # Color_Alpha # red # blue # green ##
#Legend ##
# # 31 - 24 # 23 - 16 # 15 - 8 # 7 - 0 ##
#Table ##
#Example
#Height 128
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setColor(0x8000FF00); // transparent green
canvas->drawCircle(50, 50, 40, paint);
paint.setARGB(128, 255, 0, 0); // transparent red
canvas->drawCircle(80, 50, 40, paint);
paint.setColor(SK_ColorBLUE);
paint.setAlpha(0x80);
canvas->drawCircle(65, 65, 40, paint);
}
##
#Method SkColor getColor() const
#In Color_Methods
#Line # returns Color_Alpha and RGB, one drawing color ##
Retrieves Alpha and RGB, Unpremultiplied, packed into 32 bits.
Use helpers SkColorGetA, SkColorGetR, SkColorGetG, and SkColorGetB to extract
a color component.
#Return Unpremultiplied ARGB ##
#Example
SkPaint paint;
paint.setColor(SK_ColorYELLOW);
SkColor y = paint.getColor();
SkDebugf("Yellow is %d%% red, %d%% green, and %d%% blue.\n", (int) (SkColorGetR(y) / 2.55f),
(int) (SkColorGetG(y) / 2.55f), (int) (SkColorGetB(y) / 2.55f));
#StdOut
Yellow is 100% red, 100% green, and 0% blue.
##
##
#SeeAlso SkColor
##
#Method void setColor(SkColor color)
#In Color_Methods
#Line # sets Color_Alpha and RGB, one drawing 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.
#Param color Unpremultiplied ARGB ##
#Example
SkPaint green1, green2;
unsigned a = 255;
unsigned r = 0;
unsigned g = 255;
unsigned b = 0;
green1.setColor((a << 24) + (r << 16) + (g << 8) + (b << 0));
green2.setColor(0xFF00FF00);
SkDebugf("green1 %c= green2\n", green1 == green2 ? '=' : '!');
#StdOut
green1 == green2
##
##
#SeeAlso SkColor setARGB SkColorSetARGB
##
#Subtopic Color_Methods ##
#Subtopic Alpha_Methods
#Line # get and set Alpha ##
Color_Alpha sets the transparency independent of RGB: red, blue, and green.
#Method uint8_t getAlpha() const
#In Alpha_Methods
#Line # returns Color_Alpha, color opacity ##
Retrieves Alpha from the Color used when stroking and filling.
#Return Alpha ranging from zero, fully transparent, to 255, fully opaque ##
#Example
SkPaint paint;
SkDebugf("255 %c= paint.getAlpha()\n", 255 == paint.getAlpha() ? '=' : '!');
#StdOut
255 == paint.getAlpha()
##
##
##
#Method void setAlpha(U8CPU a)
#In Alpha_Methods
#Line # sets Color_Alpha, color opacity ##
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.
#Param a Alpha component of Color ##
#Example
SkPaint paint;
paint.setColor(0x00112233);
paint.setAlpha(0x44);
SkDebugf("0x44112233 %c= paint.getColor()\n", 0x44112233 == paint.getColor() ? '=' : '!');
#StdOut
0x44112233 == paint.getColor()
##
##
##
#Subtopic Alpha_Methods ##
#Method void setARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b)
#In Color_Methods
#Line # sets color by component ##
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.
#Param a amount of Color_Alpha, from fully transparent (0) to fully opaque (255) ##
#Param r amount of red, from no red (0) to full red (255) ##
#Param g amount of green, from no green (0) to full green (255) ##
#Param b amount of blue, from no blue (0) to full blue (255) ##
#Example
SkPaint transRed1, transRed2;
transRed1.setARGB(255 / 2, 255, 0, 0);
transRed2.setColor(SkColorSetARGB(255 / 2, 255, 0, 0));
SkDebugf("transRed1 %c= transRed2", transRed1 == transRed2 ? '=' : '!');
#StdOut
transRed1 == transRed2
##
##
#SeeAlso setColor SkColorSetARGB
##
# ------------------------------------------------------------------------------
#Subtopic Style
#Line # geometry filling, stroking ##
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.
# ------------------------------------------------------------------------------
#Subtopic Fill
#Line # fill and stroke ##
#ToDo write up whatever generalities make sense to describe filling ##
#SeeAlso Path_Fill_Type
#Subtopic Fill ##
#Subtopic Stroke
#Line # lines and curves with width ##
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.
#Subtopic Stroke ##
#Subtopic Hairline
#Line # lines and curves with minimal width ##
#Alias Hairline ## # maybe should be Stroke_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.
#ToDo what is the description of Anti_Aliased hairlines? ##
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.
#Subtopic Hairline ##
#Enum Style
#Line # stroke, fill, or both ##
#Code
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.
#Const kFill_Style 0
#Line # 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.
##
#Const kStroke_Style 1
#Line # 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.
##
#Const kStrokeAndFill_Style 2
#Line # sets 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.
##
#Const kStyleCount 3
#Line # number of different Style values defined ##
May be used to verify that Style is a legal value.
##
#Enum Style ##
#Method Style getStyle() const
#In Style
#Line # returns Style: stroke, fill, or both ##
Whether the geometry is filled, stroked, or filled and stroked.
#Return one of:kFill_Style, kStroke_Style, kStrokeAndFill_Style ##
#Example
SkPaint paint;
SkDebugf("SkPaint::kFill_Style %c= paint.getStyle()\n",
SkPaint::kFill_Style == paint.getStyle() ? '=' : '!');
#StdOut
SkPaint::kFill_Style == paint.getStyle()
##
##
#SeeAlso Style setStyle
##
#Method void setStyle(Style style)
#In Style
#Line # sets Style: stroke, fill, or both ##
Sets whether the geometry is filled, stroked, or filled and stroked.
Has no effect if style is not a legal Style value.
#Param style one of: kFill_Style, kStroke_Style, kStrokeAndFill_Style
##
#Example
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setStrokeWidth(5);
SkRegion region;
region.op(140, 10, 160, 30, SkRegion::kUnion_Op);
region.op(170, 40, 190, 60, SkRegion::kUnion_Op);
SkBitmap bitmap;
bitmap.setInfo(SkImageInfo::MakeA8(50, 50), 50);
uint8_t pixels[50][50];
for (int x = 0; x < 50; ++x) {
for (int y = 0; y < 50; ++y) {
pixels[y][x] = (x + y) % 5 ? 0xFF : 0x00;
}
}
bitmap.setPixels(pixels);
for (auto style : { SkPaint::kFill_Style,
SkPaint::kStroke_Style,
SkPaint::kStrokeAndFill_Style }) {
paint.setStyle(style);
canvas->drawLine(10, 10, 60, 60, paint);
canvas->drawRect({80, 10, 130, 60}, paint);
canvas->drawRegion(region, paint);
canvas->drawBitmap(bitmap, 200, 10, &paint);
canvas->translate(0, 80);
}
}
##
#SeeAlso Style getStyle
##
#SeeAlso Path_Fill_Type Path_Effect Style_Fill Style_Stroke
#Subtopic Style ##
# ------------------------------------------------------------------------------
#Subtopic Stroke_Width
#Line # thickness perpendicular to geometry ##
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
#Height 170
#Platform raster gpu
#Description
The pixels hit to represent thin lines vary with the angle of the
line and the platform implementation.
##
void draw(SkCanvas* canvas) {
SkPaint paint;
for (bool antialias : { false, true }) {
paint.setAntiAlias(antialias);
for (int width = 0; width <= 4; ++width) {
SkScalar offset = antialias * 100 + width * 20;
paint.setStrokeWidth(width * 0.25f);
canvas->drawLine(10 + offset, 10, 20 + offset, 60, paint);
canvas->drawLine(10 + offset, 110, 60 + offset, 160, paint);
}
}
}
##
#Method SkScalar getStrokeWidth() const
#In Stroke_Width
#Line # returns thickness of the stroke ##
Returns the thickness of the pen used by Paint to
outline the shape.
#Return zero for Hairline, greater than zero for pen thickness ##
#Example
SkPaint paint;
SkDebugf("0 %c= paint.getStrokeWidth()\n", 0 == paint.getStrokeWidth() ? '=' : '!');
#StdOut
0 == paint.getStrokeWidth()
##
##
##
#Method void setStrokeWidth(SkScalar width)
#In Stroke_Width
#Line # sets thickness of the stroke ##
Sets the thickness of the pen used by the paint to
outline the shape.
Has no effect if width is less than zero.
#Param width zero thickness for Hairline; greater than zero for pen thickness
##
#Example
SkPaint paint;
paint.setStrokeWidth(5);
paint.setStrokeWidth(-1);
SkDebugf("5 %c= paint.getStrokeWidth()\n", 5 == paint.getStrokeWidth() ? '=' : '!');
#StdOut
5 == paint.getStrokeWidth()
##
##
##
#Subtopic Stroke_Width ##
# ------------------------------------------------------------------------------
#Subtopic Miter_Limit
#Line # maximum length of stroked corners ##
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:
#Formula
miter limit = 1 / sin ( angle / 2 )
#Formula ##
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.
#Table
#Legend
# miter limit # angle in degrees ##
#Legend ##
# 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 ##
#Table ##
#Example
#Height 170
#Width 384
#Description
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.
##
void draw(SkCanvas* canvas) {
SkPoint pts[] = {{ 10, 50 }, { 110, 80 }, { 10, 110 }};
SkVector v[] = { pts[0] - pts[1], pts[2] - pts[1] };
SkScalar angle1 = SkScalarATan2(v[0].fY, v[0].fX);
SkScalar angle2 = SkScalarATan2(v[1].fY, v[1].fX);
const SkScalar strokeWidth = 20;
SkScalar miterLimit = 1 / SkScalarSin((angle2 - angle1) / 2);
SkScalar miterLength = strokeWidth * miterLimit;
SkPath path;
path.moveTo(pts[0]);
path.lineTo(pts[1]);
path.lineTo(pts[2]);
SkPaint paint; // set to default kMiter_Join
paint.setAntiAlias(true);
paint.setStyle(SkPaint::kStroke_Style);
paint.setStrokeMiter(miterLimit);
paint.setStrokeWidth(strokeWidth);
canvas->drawPath(path, paint);
paint.setStrokeWidth(1);
canvas->drawLine(pts[1].fX - miterLength / 2, pts[1].fY + 50,
pts[1].fX + miterLength / 2, pts[1].fY + 50, paint);
canvas->translate(200, 0);
miterLimit *= 0.99f;
paint.setStrokeMiter(miterLimit);
paint.setStrokeWidth(strokeWidth);
canvas->drawPath(path, paint);
paint.setStrokeWidth(1);
canvas->drawLine(pts[1].fX - miterLength / 2, pts[1].fY + 50,
pts[1].fX + miterLength / 2, pts[1].fY + 50, paint);
}
##
#Method SkScalar getStrokeMiter() const
#In Miter_Limit
#Line # returns Miter_Limit, angles with sharp corners ##
The limit at which a sharp corner is drawn beveled.
#Return zero and greater Miter_Limit ##
#Example
SkPaint paint;
SkDebugf("default miter limit == %g\n", paint.getStrokeMiter());
#StdOut
default miter limit == 4
##
##
#SeeAlso Miter_Limit setStrokeMiter Join
##
#Method void setStrokeMiter(SkScalar miter)
#In Miter_Limit
#Line # sets Miter_Limit, angles with sharp corners ##
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.
#Param miter zero and greater Miter_Limit
##
#Example
SkPaint paint;
paint.setStrokeMiter(8);
paint.setStrokeMiter(-1);
SkDebugf("default miter limit == %g\n", paint.getStrokeMiter());
#StdOut
default miter limit == 8
##
##
#SeeAlso Miter_Limit getStrokeMiter Join
##
#Subtopic Miter_Limit ##
# ------------------------------------------------------------------------------
#Subtopic Stroke_Cap
#Line # decorations at ends of open strokes ##
#Enum Cap
#Line # start and end geometry on stroked shapes ##
#Code
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.
#Const kButt_Cap 0
#Line # no stroke extension ##
Does not extend the stroke past the beginning or the end.
##
#Const kRound_Cap 1
#Line # adds circle ##
Adds a circle with a diameter equal to Stroke_Width at the beginning
and end.
##
#Const kSquare_Cap 2
#Line # adds square ##
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.
##
#Const kLast_Cap 2
#Line # largest Stroke_Cap value ##
Equivalent to the largest value for Stroke_Cap.
##
#Const kDefault_Cap 0
#Line # equivalent to kButt_Cap ##
Stroke_Cap is set to kButt_Cap by default.
##
#Const kCapCount 3
#Line # number of different Stroke_Cap values defined ##
May be used to verify that Stroke_Cap is a legal value.
##
#Enum ##
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
#Height 200
SkPaint paint;
paint.setStyle(SkPaint::kStroke_Style);
paint.setStrokeWidth(20);
SkPath path;
path.moveTo(30, 30);
path.lineTo(30, 30);
path.moveTo(70, 30);
path.lineTo(90, 40);
for (SkPaint::Cap c : { SkPaint::kButt_Cap, SkPaint::kRound_Cap, SkPaint::kSquare_Cap } ) {
paint.setStrokeCap(c);
canvas->drawPath(path, paint);
canvas->translate(0, 70);
}
##
#Method Cap getStrokeCap() const
#In Stroke_Cap
#Line # returns Cap, the area drawn at path ends ##
The geometry drawn at the beginning and end of strokes.
#Return one of: kButt_Cap, kRound_Cap, kSquare_Cap ##
#Example
SkPaint paint;
SkDebugf("kButt_Cap %c= default stroke cap\n",
SkPaint::kButt_Cap == paint.getStrokeCap() ? '=' : '!');
#StdOut
kButt_Cap == default stroke cap
##
##
#SeeAlso Stroke_Cap setStrokeCap
##
#Method void setStrokeCap(Cap cap)
#In Stroke_Cap
#Line # sets Cap, the area drawn at path ends ##
The geometry drawn at the beginning and end of strokes.
#Param cap one of: kButt_Cap, kRound_Cap, kSquare_Cap;
has no effect if cap is not valid
##
#Example
SkPaint paint;
paint.setStrokeCap(SkPaint::kRound_Cap);
paint.setStrokeCap((SkPaint::Cap) SkPaint::kCapCount);
SkDebugf("kRound_Cap %c= paint.getStrokeCap()\n",
SkPaint::kRound_Cap == paint.getStrokeCap() ? '=' : '!');
#StdOut
kRound_Cap == paint.getStrokeCap()
##
##
#SeeAlso Stroke_Cap getStrokeCap
##
#Subtopic Stroke_Cap ##
# ------------------------------------------------------------------------------
#Subtopic Stroke_Join
#Line # decoration at corners of strokes ##
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
#Height 200
SkPaint paint;
paint.setStyle(SkPaint::kStroke_Style);
paint.setStrokeWidth(20);
SkPath path;
path.moveTo(30, 20);
path.lineTo(40, 40);
path.conicTo(70, 20, 100, 20, .707f);
for (SkPaint::Join j : { SkPaint::kMiter_Join, SkPaint::kRound_Join, SkPaint::kBevel_Join } ) {
paint.setStrokeJoin(j);
canvas->drawPath(path, paint);
canvas->translate(0, 70);
}
##
#Enum Join
#Line # corner geometry on stroked shapes ##
#Code
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.
#Const kMiter_Join 0
#Line # extends to Miter_Limit ##
Extends the outside corner to the extent allowed by Miter_Limit.
If the extension exceeds Miter_Limit, kBevel_Join is used instead.
##
#Const kRound_Join 1
#Line # adds circle ##
Adds a circle with a diameter of Stroke_Width at the sharp corner.
##
#Const kBevel_Join 2
#Line # connects outside edges ##
Connects the outside edges of the sharp corner.
##
#Const kLast_Join 2
#Line # equivalent to the largest value for Stroke_Join ##
##
#Const kDefault_Join 1
#Line # equivalent to kMiter_Join ##
Stroke_Join is set to kMiter_Join by default.
##
#Const kJoinCount 3
#Line # number of different Stroke_Join values defined ##
May be used to verify that Stroke_Join is a legal value.
##
#Example
#Width 462
void draw(SkCanvas* canvas) {
SkPath path;
path.moveTo(10, 50);
path.quadTo(35, 110, 60, 210);
path.quadTo(105, 110, 130, 10);
SkPaint paint; // set to default kMiter_Join
paint.setAntiAlias(true);
paint.setStyle(SkPaint::kStroke_Style);
paint.setStrokeWidth(20);
canvas->drawPath(path, paint);
canvas->translate(150, 0);
paint.setStrokeJoin(SkPaint::kBevel_Join);
canvas->drawPath(path, paint);
canvas->translate(150, 0);
paint.setStrokeJoin(SkPaint::kRound_Join);
canvas->drawPath(path, paint);
}
##
#SeeAlso setStrokeJoin getStrokeJoin setStrokeMiter getStrokeMiter
#Enum ##
#Method Join getStrokeJoin() const
#In Stroke_Join
#Line # returns Join, geometry on path corners ##
The geometry drawn at the corners of strokes.
#Return one of: kMiter_Join, kRound_Join, kBevel_Join ##
#Example
SkPaint paint;
SkDebugf("kMiter_Join %c= default stroke join\n",
SkPaint::kMiter_Join == paint.getStrokeJoin() ? '=' : '!');
#StdOut
kMiter_Join == default stroke join
##
##
#SeeAlso Stroke_Join setStrokeJoin
##
#Method void setStrokeJoin(Join join)
#In Stroke_Join
#Line # sets Join, geometry on path corners ##
The geometry drawn at the corners of strokes.
#Param join one of: kMiter_Join, kRound_Join, kBevel_Join;
otherwise, has no effect
##
#Example
SkPaint paint;
paint.setStrokeJoin(SkPaint::kMiter_Join);
paint.setStrokeJoin((SkPaint::Join) SkPaint::kJoinCount);
SkDebugf("kMiter_Join %c= paint.getStrokeJoin()\n",
SkPaint::kMiter_Join == paint.getStrokeJoin() ? '=' : '!');
#StdOut
kMiter_Join == paint.getStrokeJoin()
##
##
#SeeAlso Stroke_Join getStrokeJoin
##
#SeeAlso Miter_Limit
#Subtopic Stroke_Join ##
# ------------------------------------------------------------------------------
#Subtopic Fill_Path
#Line # make Path from Path_Effect, stroking ##
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.
#Method bool getFillPath(const SkPath& src, SkPath* dst, const SkRect* cullRect,
SkScalar resScale = 1) const
#In Fill_Path
#Line # returns fill path equivalent to stroke ##
The filled equivalent of the stroked path.
#Param src Path read to create a filled version ##
#Param dst resulting Path; may be the same as src, but may not be nullptr ##
#Param cullRect optional limit passed to Path_Effect ##
#Param resScale if > 1, increase precision, else if (0 < res < 1) reduce precision
to favor speed and size
##
#Return true if the path represents Style_Fill, or false if it represents Hairline ##
#Example
#Height 192
#Description
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.
##
void draw(SkCanvas* canvas) {
SkPaint strokePaint;
strokePaint.setAntiAlias(true);
strokePaint.setStyle(SkPaint::kStroke_Style);
strokePaint.setStrokeWidth(.1f);
SkPath strokePath;
strokePath.moveTo(.08f, .08f);
strokePath.quadTo(.09f, .08f, .17f, .17f);
SkPath fillPath;
SkPaint outlinePaint(strokePaint);
outlinePaint.setStrokeWidth(2);
SkMatrix scale = SkMatrix::MakeScale(300, 300);
for (SkScalar precision : { 0.01f, .1f, 1.f, 10.f, 100.f } ) {
strokePaint.getFillPath(strokePath, &fillPath, nullptr, precision);
fillPath.transform(scale);
canvas->drawPath(fillPath, outlinePaint);
canvas->translate(60, 0);
if (1.f == precision) canvas->translate(-180, 100);
}
strokePath.transform(scale);
strokePaint.setStrokeWidth(30);
canvas->drawPath(strokePath, strokePaint);
}
##
##
#Method bool getFillPath(const SkPath& src, SkPath* dst) const
#In Fill_Path
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.
#Param src Path read to create a filled version ##
#Param dst resulting Path dst may be the same as src, but may not be nullptr ##
#Return true if the path represents Style_Fill, or false if it represents Hairline ##
#Example
#Height 128
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setStyle(SkPaint::kStroke_Style);
paint.setStrokeWidth(10);
SkPath strokePath;
strokePath.moveTo(20, 20);
strokePath.lineTo(100, 100);
canvas->drawPath(strokePath, paint);
SkPath fillPath;
paint.getFillPath(strokePath, &fillPath);
paint.setStrokeWidth(2);
canvas->translate(40, 0);
canvas->drawPath(fillPath, paint);
}
##
##
#SeeAlso Style_Stroke Stroke_Width Path_Effect
#Subtopic Fill_Path ##
# ------------------------------------------------------------------------------
#Subtopic Shader_Methods
#Line # get and set Shader ##
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
void draw(SkCanvas* canvas) {
SkPaint paint;
SkPoint center = { 50, 50 };
SkScalar radius = 50;
const SkColor colors[] = { 0xFFFFFFFF, 0xFF000000 };
paint.setShader(SkGradientShader::MakeRadial(center, radius, colors,
nullptr, SK_ARRAY_COUNT(colors), SkShader::kClamp_TileMode));
for (SkScalar a : { 0.3f, 0.6f, 1.0f } ) {
paint.setAlpha((int) (a * 255));
canvas->drawCircle(center.fX, center.fY, radius, paint);
canvas->translate(70, 70);
}
}
##
If Shader generates only Color_Alpha then all components of Color modulate the output.
#Example
void draw(SkCanvas* canvas) {
SkPaint paint;
SkBitmap bitmap;
bitmap.setInfo(SkImageInfo::MakeA8(5, 1), 5); // bitmap only contains alpha
uint8_t pixels[5] = { 0x22, 0x55, 0x88, 0xBB, 0xFF };
bitmap.setPixels(pixels);
paint.setShader(SkShader::MakeBitmapShader(bitmap,
SkShader::kMirror_TileMode, SkShader::kMirror_TileMode));
for (SkColor c : { SK_ColorRED, SK_ColorBLUE, SK_ColorGREEN } ) {
paint.setColor(c); // all components in color affect shader
canvas->drawCircle(50, 50, 50, paint);
canvas->translate(70, 70);
}
}
##
#Method SkShader* getShader() const
#In Shader_Methods
#Line # returns Shader, multiple drawing colors; gradients ##
Optional colors used when filling a path, such as a gradient.
Does not alter Shader Reference_Count.
#Return Shader if previously set, nullptr otherwise ##
#Example
void draw(SkCanvas* canvas) {
SkPaint paint;
SkDebugf("nullptr %c= shader\n", paint.getShader() ? '!' : '=');
paint.setShader(SkShader::MakeEmptyShader());
SkDebugf("nullptr %c= shader\n", paint.getShader() ? '!' : '=');
}
#StdOut
nullptr == shader
nullptr != shader
##
##
##
#Method sk_sp<SkShader> refShader() const
#In Shader_Methods
#Line # references Shader, multiple drawing colors; gradients ##
Optional colors used when filling a path, such as a gradient.
Increases Shader Reference_Count by one.
#Return Shader if previously set, nullptr otherwise ##
#Example
void draw(SkCanvas* canvas) {
SkPaint paint1, paint2;
paint1.setShader(SkShader::MakeEmptyShader());
SkDebugf("shader unique: %s\n", paint1.getShader()->unique() ? "true" : "false");
paint2.setShader(paint1.refShader());
SkDebugf("shader unique: %s\n", paint1.getShader()->unique() ? "true" : "false");
}
#StdOut
shader unique: true
shader unique: false
##
##
##
#Method void setShader(sk_sp<SkShader> shader)
#In Shader_Methods
#Line # sets Shader, multiple drawing colors; gradients ##
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.
#Param shader how geometry is filled with color; if nullptr, Color is used instead ##
#Example
#Height 64
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setColor(SK_ColorBLUE);
paint.setShader(SkShader::MakeColorShader(SK_ColorRED));
canvas->drawRect(SkRect::MakeWH(40, 40), paint);
paint.setShader(nullptr);
canvas->translate(50, 0);
canvas->drawRect(SkRect::MakeWH(40, 40), paint);
}
##
##
#Subtopic Shader_Methods ##
# ------------------------------------------------------------------------------
#Subtopic Color_Filter_Methods
#Line # get and set Color_Filter ##
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
#Height 128
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setColorFilter(SkColorMatrixFilter::MakeLightingFilter(0xFFFFFF, 0xFF0000));
for (SkColor c : { SK_ColorBLACK, SK_ColorGREEN } ) {
paint.setColor(c);
canvas->drawRect(SkRect::MakeXYWH(10, 10, 50, 50), paint);
paint.setAlpha(0x80);
canvas->drawRect(SkRect::MakeXYWH(60, 60, 50, 50), paint);
canvas->translate(100, 0);
}
}
##
#Method SkColorFilter* getColorFilter() const
#In Color_Filter_Methods
#Line # returns Color_Filter, how colors are altered ##
Returns Color_Filter if set, or nullptr.
Does not alter Color_Filter Reference_Count.
#Return Color_Filter if previously set, nullptr otherwise ##
#Example
void draw(SkCanvas* canvas) {
SkPaint paint;
SkDebugf("nullptr %c= color filter\n", paint.getColorFilter() ? '!' : '=');
paint.setColorFilter(SkColorFilter::MakeModeFilter(SK_ColorLTGRAY, SkBlendMode::kSrcIn));
SkDebugf("nullptr %c= color filter\n", paint.getColorFilter() ? '!' : '=');
}
#StdOut
nullptr == color filter
nullptr != color filter
##
##
##
#Method sk_sp<SkColorFilter> refColorFilter() const
#In Color_Filter_Methods
#Line # references Color_Filter, how colors are altered ##
Returns Color_Filter if set, or nullptr.
Increases Color_Filter Reference_Count by one.
#Return Color_Filter if set, or nullptr ##
#Example
void draw(SkCanvas* canvas) {
SkPaint paint1, paint2;
paint1.setColorFilter(SkColorFilter::MakeModeFilter(0xFFFF0000, SkBlendMode::kSrcATop));
SkDebugf("color filter unique: %s\n", paint1.getColorFilter()->unique() ? "true" : "false");
paint2.setColorFilter(paint1.refColorFilter());
SkDebugf("color filter unique: %s\n", paint1.getColorFilter()->unique() ? "true" : "false");
}
#StdOut
color filter unique: true
color filter unique: false
##
##
##
#Method void setColorFilter(sk_sp<SkColorFilter> colorFilter)
#In Color_Filter_Methods
#Line # sets Color_Filter, alters color ##
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.
#Param colorFilter Color_Filter to apply to subsequent draw ##
#Example
#Height 64
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setColorFilter(SkColorFilter::MakeModeFilter(SK_ColorLTGRAY, SkBlendMode::kSrcIn));
canvas->drawRect(SkRect::MakeWH(50, 50), paint);
paint.setColorFilter(nullptr);
canvas->translate(70, 0);
canvas->drawRect(SkRect::MakeWH(50, 50), paint);
}
##
##
#Subtopic Color_Filter_Methods ##
# ------------------------------------------------------------------------------
#Subtopic Blend_Mode_Methods
#Line # get and set Blend_Mode ##
Blend_Mode describes how Color combines with the destination color.
The default setting, SkBlendMode::kSrcOver, draws the source color
over the destination color.
#Example
void draw(SkCanvas* canvas) {
SkPaint normal, blender;
normal.setColor(0xFF58a889);
blender.setColor(0xFF8958a8);
canvas->clear(0);
for (SkBlendMode m : { SkBlendMode::kSrcOver, SkBlendMode::kSrcIn, SkBlendMode::kSrcOut } ) {
normal.setBlendMode(SkBlendMode::kSrcOver);
canvas->drawOval(SkRect::MakeXYWH(30, 30, 30, 80), normal);
blender.setBlendMode(m);
canvas->drawOval(SkRect::MakeXYWH(10, 50, 80, 30), blender);
canvas->translate(70, 70);
}
}
##