diff options
| author | Cary Clark <caryclark@skia.org> | 2017-07-28 15:18:29 -0400 |
|---|---|---|
| committer | Skia Commit-Bot <skia-commit-bot@chromium.org> | 2017-07-28 19:25:53 +0000 |
| commit | 12799e17d55c09d322bc49bfd9f1247c03f3c0b2 (patch) | |
| tree | eeceb48d3c31aefe1c96ebc22726df31e6fd34ab /docs/SkPaint_Reference.bmh | |
| parent | 293d9bd3c2f5a10734bdfb755d4853c57632ac08 (diff) | |
| download | skqp-12799e17d55c09d322bc49bfd9f1247c03f3c0b2.tar.gz | |
bookmaker generated site docs
The documents were generated by running
tools/bookmaker against docs/*.bmh
No-Try: true
Docs-Preview: https://skia.org/?cl=28002
Change-Id: I7d7dd73cdea4a234c6175646d5b8938e1af3117a
Reviewed-on: https://skia-review.googlesource.com/28002
Reviewed-by: Cary Clark <caryclark@skia.org>
Commit-Queue: Cary Clark <caryclark@skia.org>
Diffstat (limited to 'docs/SkPaint_Reference.bmh')
| -rw-r--r-- | docs/SkPaint_Reference.bmh | 5281 |
1 files changed, 5281 insertions, 0 deletions
diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh new file mode 100644 index 0000000000..0e4fcf53b1 --- /dev/null +++ b/docs/SkPaint_Reference.bmh @@ -0,0 +1,5281 @@ +#Topic Paint +#Alias Paint_Reference + +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 SkPaint::kAntiAlias_Flag setting. + +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. + +#Class SkPaint + +#Topic Overview + +#Subtopic Subtopics +#ToDo not all methods are in topics ## +#ToDo subtopics are not in topics ## +#Table +#Legend +# topics # description ## +#Legend ## +# 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 # Appproxiate area required by Paint. ## +#Table ## +#Subtopic ## + +#Subtopic Constants +#Table +#Legend +# constants # description ## +#Legend ## +# 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 encoding size. ## +#Table ## +#Subtopic ## + +#Subtopic Structs +#Table +#Legend +# struct # description ## +#Legend ## +# FontMetrics # Typeface values. ## +#Table ## +#Subtopic ## + +#Subtopic Constructors +#Table +#Legend +# # description ## +#Legend ## +# SkPaint() # Constructs with default values. ## +# SkPaint(const SkPaint& paint) # Makes a shallow copy. ## +# SkPaint(SkPaint&& paint) # Moves paint without copying it. ## +# ~SkPaint() # Decreases Reference_Count of owned objects. ## +#Table ## +#Subtopic ## + +#Subtopic Operators +#Table +#Legend +# operator # description ## +#Legend ## +# 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. ## +#Table ## +#Subtopic ## + +#Subtopic Member_Functions +#Table +#Legend +# function # description ## +#Legend ## +# 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 dest. ## +# 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 encoding size. ## +# 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 encoding 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 parsable form (Developer_Mode) ## +# unflatten() # Populates from a serialized stream. ## +#Table ## +#Subtopic ## + +#Topic Overview ## + +# ------------------------------------------------------------------------------ +#Topic Initializers + +#Method SkPaint() + +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 ## +# 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 ## +#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) + +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. These objects' Reference_Count are increased. + +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. + +#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) + + Implements a move constructor to avoid incrementing 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() + +Sets all paint's contents to their initial values. This is equivalent to replacing +the 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 + ## +## + +## + +#Topic ## + +# ------------------------------------------------------------------------------ +#Topic Destructor + +#Method ~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' reference count goes to zero, they are deleted. + +#NoExample +## + +## + +## +# ------------------------------------------------------------------------------ +#Topic Management + +#Method 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. The objects' Reference_Count are in the +prior destination are decreased by one, and the referenced objects are deleted if the +resulting count is zero. The objects' 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) + +Moves the paint to avoid incrementing the reference counts +of objects referenced by the paint parameter. The objects' Reference_Count are in the +prior destination are decreased by one, and the referenced 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) + + 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. + + #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 + ## + ## + +## + +# ------------------------------------------------------------------------------ + +#Method 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. + + #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 + ## +## + +## + +# ------------------------------------------------------------------------------ + +#Method 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 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() + ## +## + +## + +# ------------------------------------------------------------------------------ + +#Method void flatten(SkWriteBuffer& buffer) const + +Serializes Paint into a buffer. A companion unflatten() call +can reconstitute the paint at a later time. + +#Param buffer Write_Buffer receiving the flattened Paint data ## + +#Example + class PaintDumper : public SkWriteBuffer { + public: + bool isCrossProcess() const override { return false; }; + void writeByteArray(const void* data, size_t size) override {} + void writeBool(bool value) override {} + void writeScalar(SkScalar value) override {} + void writeScalarArray(const SkScalar* value, uint32_t count) override {} + void writeInt(int32_t value) override {} + void writeIntArray(const int32_t* value, uint32_t count) override {} + void writeUInt(uint32_t value) override {} + void writeString(const char* value) override {} + void writeFlattenable(const SkFlattenable* flattenable) override {} + void writeColorArray(const SkColor* color, uint32_t count) override {} + void writeColor4f(const SkColor4f& color) override {} + void writeColor4fArray(const SkColor4f* color, uint32_t count) override {} + void writePoint(const SkPoint& point) override {} + void writePointArray(const SkPoint* point, uint32_t count) override {} + void writeMatrix(const SkMatrix& matrix) override {} + void writeIRect(const SkIRect& rect) override {} + void writeRect(const SkRect& rect) override {} + void writeRegion(const SkRegion& region) override {} + void writePath(const SkPath& path) override {} + size_t writeStream(SkStream* stream, size_t length) override { return 0; } + void writeBitmap(const SkBitmap& bitmap) override {} + void writeImage(const SkImage*) override {} + void writeTypeface(SkTypeface* typeface) override {} + void writePaint(const SkPaint& paint) override {} + + void writeColor(SkColor color) override { + SkDebugf("color = 0x%08x\n", color); + } + } dumper; + + SkPaint paint; + paint.setColor(SK_ColorRED); + paint.flatten(dumper); + + #StdOut + color = 0xffff0000 + ## +## + +## + +# ------------------------------------------------------------------------------ + +#Method 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. + +#Param buffer serialized data to unflatten ## + +# why is unflatten() public? +#Bug 6172 ## + +#NoExample +## + +#ToDo incomplete ## + +## + +#Topic Management ## + +# ------------------------------------------------------------------------------ +#Topic Hinting + +#Enum Hinting + +#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 + 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 + 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 + 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 + Modifies glyph outlines for maxiumum 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. +## + +#Track +#File SkFontHost_mac.cpp:1777,1806 +#Time 2013-03-03 07:16:29 +0000 +#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 gray scale output. +Normal hinting uses Core_Text LCD output. If kLCDRenderText_Flag is clear, +the LCD output is reduced to a single grayscale channel. +#Track ## + +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 + + 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) + + 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 constrast ## + # kNormal_Hinting # 2 # modifies glyph outlines to improve constrast ## + # kFull_Hinting # 3 # modifies glyph outlines for maxiumum constrast ## + ## + + #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 + ## + ## +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic Flags + +#Enum Flags + +#Code + 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. + + #Const kAntiAlias_Flag 0x0001 + mask for setting Anti-alias + ## + #Const kDither_Flag 0x0004 + mask for setting Dither + ## + + #Const kFakeBoldText_Flag 0x0020 + mask for setting Fake_Bold + ## + #Const kLinearText_Flag 0x0040 + mask for setting Linear_Text + ## + #Const kSubpixelText_Flag 0x0080 + mask for setting Subpixel_Text + ## + #Const kDevKernText_Flag 0x0100 + mask for setting Full_Hinting_Spacing + ## + #Const kLCDRenderText_Flag 0x0200 + mask for setting LCD_Text + ## + #Const kEmbeddedBitmapText_Flag 0x0400 + mask for setting Font_Embedded_Bitmaps + ## + #Const kAutoHinting_Flag 0x0800 + mask for setting Automatic_Hinting + ## + #Const kVerticalText_Flag 0x1000 + mask for setting Vertical_Text + ## + #Const kGenA8FromLCD_Flag 0x2000 + #Private + Hack for GDI -- do not use if you can help it + ## + not intended for public use + ## + #Const kAllFlags 0xFFFF + 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 + +#Private +To be deprecated; only valid for Android framework. +## + +#Code + enum ReserveFlags { + kUnderlineText_ReserveFlag = 0x08, + kStrikeThruText_ReserveFlag = 0x10, + }; +## + + #Const kUnderlineText_ReserveFlag 0x0008 + mask for underline text + ## + #Const kStrikeThruText_ReserveFlag 0x0010 + mask for strike-thru text + ## + +#ToDo incomplete ## + +#Enum ## + +#Method uint32_t getFlags() const + +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) + +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() + ## +## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic Anti-alias +#Alias Anti-alias # permit hyphen in topic name, should probably not substitute hyphen with _ + +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 an offscreen bitmap, then drawn magified 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 + + 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) + + 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 + ## + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic Dither + +Dither increases fidelity by adjusting the color of adjcent 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 + +#Define 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 + + 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) + + 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 Color_RGB-565 + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 inperceptible. +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 + #Description + Four commas are drawn normally and with combinations of LCD_Text and Subpixel_Text. + When Subpixel_Text is disabled, the comma glyphs are indentical, 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 Linear_Text +#Alias Linear_Text # makes this a top level name, since it is under subtopic Device_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's the same as setting Hinting to kNo_Hinting. + +#Method bool isLinearText() const + + 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) + + 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 ## + +#Subtopic Subpixel_Text +#Alias Subpixel_Text # makes this a top level name, since it is under subtopic Device_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. + +#Method 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 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) + + 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 ## + +#Subtopic LCD_Text +#Alias LCD_Text # makes this a top level name, since it is under subtopic Device_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 inperceptible. +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. + +#Method bool isLCDRenderText() const + + 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) + + 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 ## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic Font_Embedded_Bitmaps +#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 + + 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) + + 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 + ## + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic Automatic_Hinting +#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 + + 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) + + 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. + + setAutohinted 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 + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 preceeding glyph. Vertical_Text sets successive +glyphs to position below the preceeding 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 # http://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 + + 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) + + 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 + ## + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ + +#Topic 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's 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 + + 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) + + Use increased stroke width when creating glyph bitmaps to approximate bolding. + + 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 + ## + ## + +## + +#Topic ## + +# ------------------------------------------------------------------------------ +#Topic Full_Hinting_Spacing +#Alias Full_Hinting_Spacing # long winded enough -- maybe things with two underscores auto-aliased? + +Full_Hinting_Spacing adjusts the character spacing by the difference of the +hinted and unhinted left and right side bearings, +if Hinting is set to kFull_Hinting. 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's kerning tables. + +#Method bool isDevKernText() const + + Returns if character spacing may be adjusted by the hinting difference. + + Equivalent to getFlags masked with kDevKernText_Flag. + + #Return kDevKernText_Flag state ## + + #Example + SkPaint paint; + SkDebugf("paint.isDevKernText() %c= !!(paint.getFlags() & SkPaint::kDevKernText_Flag)\n", + paint.isDevKernText() == !!(paint.getFlags() & SkPaint::kDevKernText_Flag) ? '=' : '!'); + paint.setDevKernText(true); + SkDebugf("paint.isDevKernText() %c= !!(paint.getFlags() & SkPaint::kDevKernText_Flag)\n", + paint.isDevKernText() == !!(paint.getFlags() & SkPaint::kDevKernText_Flag) ? '=' : '!'); + ## + +## + +#Method 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. + + #Param devKernText setting for devKernText ## + + #Example + SkPaint paint1, paint2; + paint1.setDevKernText(true); + paint2.setFlags(paint2.getFlags() | SkPaint::kDevKernText_Flag); + SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!'); + + #StdOut + paint1 == paint2 + ## + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 unscaled, the Filter_Quality choice will not result in a noticable +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 + +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) + +Sets Filter_Quality, the image filtering level. A lower setting +draws faster; a higher setting looks better when the image is scaled. +setFilterQuality 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 + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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. + +#Table +#Legend +# bit positions # Color_Alpha # Color_RGB_Red # Color_RGB_Blue # Color_RGB_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 + + Retrieves Color_Alpha and Color_RGB, unpremultiplied, packed into 32 bits. + Use helpers SkColorGetA, SkColorGetR, SkColorGetG, and SkColorGetB to extract + a color component. + + #Return Unpremultiplied Color_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) + + Sets Color_Alpha and Color_RGB used when stroking and filling. The color is a 32-bit value, + unpremutiplied, packing 8-bit components for Color_Alpha, Color_RGB_Red, Color_RGB_Blue, and Color_RGB_Green. + + #Param color Unpremultiplied Color_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 Alpha_Methods + +Color_Alpha sets the transparency independent of Color_RGB: Color_RGB_Red, Color_RGB_Blue, and Color_RGB_Green. + +#Method uint8_t getAlpha() const + + Retrieves Color_Alpha from the Color used when stroking and filling. + + #Return Color_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) + + Replaces Color_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. + + #Param a Color_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 ## + +#Method 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; + Color_Alpha sets the transparency independent of Color_RGB. + + #Param a amount of Color_Alpha, from fully transparent (0) to fully opaque (255) ## + #Param r amount of Color_RGB_Red, from no red (0) to full red (255) ## + #Param g amount of Color_RGB_Green, from no green (0) to full green (255) ## + #Param b amount of Color_RGB_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 + +## + +#Topic Color_Methods ## + +# ------------------------------------------------------------------------------ +#Topic 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. + +# ------------------------------------------------------------------------------ +#Subtopic Fill + +#ToDo write up whatever generalities make sense to describe filling ## + +#SeeAlso Path_Fill_Type +#Subtopic ## + +#Subtopic Stroke +The stroke covers the area described by following the shape's 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's 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 ## + +#Subtopic Hairline +#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 ## + +#Enum Style + +#Code + 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. + +#Const kFill_Style 0 + Set to fill geometry. + Applies to Rect, Region, Round_Rect, Circle, Oval, Path, and Text. + Bitmap, Image, Patch, Region, Sprite, 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 + Set to stroke geometry. + Applies to Rect, Region, Round_Rect, Arc, Circle, Oval, + Path, and Text. + Arc, Line, Point, and Point_Array 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 + Set to stroke and fill geometry. + Applies to Rect, Region, Round_Rect, Circle, Oval, Path, and Text. + Path is treated as if it is set to SkPath::kWinding_FillType, + and the set Path_Fill_Type is ignored. +## + +#Enum ## + +#Enum + +#Code + enum { + kStyleCount = kStrokeAndFill_Style + 1 + }; +## + +#Const kStyleCount 3 +The number of different Style values defined. +May be used to verify that Style is a legal value. +## + +#Enum ## + +#Method Style getStyle() const + + 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) + + 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 +#Topic Style ## + +# ------------------------------------------------------------------------------ +#Topic Stroke_Width + +Stroke_Width sets the width for stroking. The width is the thickness +of the stroke perpendicular to the path's direction when the paint's 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's 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's 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 + + 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) + + 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() + ## + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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: + +#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 + + 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) + + 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 + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic Stroke_Cap + +#Enum Cap + +#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 + Does not extend the stroke past the beginning or the end. + ## + #Const kRound_Cap 1 + Adds a circle with a diameter equal to Stroke_Width at the beginning + and end. + ## + #Const kSquare_Cap 2 + Adds a square with sides equal to Stroke_Width at the beginning + and end. The square sides are parallel to the initial and final direction + of the stroke. + ## + #Const kLast_Cap 2 + Equivalent to the largest value for Stroke_Cap. + ## + #Const kDefault_Cap 0 + Equivalent to kButt_Cap. + Stroke_Cap is set to kButt_Cap by default. + ## + + #Const kCapCount 3 + The 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 contours's 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 + 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 + + 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) + + 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 +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 contours's 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 + SkPaint paint; + paint.setStyle(SkPaint::kStroke_Style); + paint.setStrokeWidth(20); + SkPath path; + path.moveTo(30, 30); + path.lineTo(40, 50); + path.conicTo(70, 30, 100, 30, .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 +#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. The paint's Join setting +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 + 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 + Adds a circle with a diameter of Stroke_Width at the sharp corner. +## + +#Const kBevel_Join 2 + Connects the outside edges of the sharp corner. +## + +#Const kLast_Join 2 + Equivalent to the largest value for Stroke_Join. +## + +#Const kDefault_Join 1 + Equivalent to kMiter_Join. + Stroke_Join is set to kMiter_Join by default. +## + +#Const kJoinCount 3 + The 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 + + 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) + + The geometry drawn at the corners of strokes. + + #Param join one of: kMiter_Join, kRound_Join, kBevel_Join; + otherwise, setStrokeJoin 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 + +#Topic Stroke_Join ## +# ------------------------------------------------------------------------------ +#Topic 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. + +#Method bool getFillPath(const SkPath& src, SkPath* dst, const SkRect* cullRect, + SkScalar resScale = 1) const + + 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 + + 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 + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 +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 + + 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 + + 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) + + Optional colors used when filling a path, such as a gradient. + + Sets Shader to shader, decrementing Reference_Count of the previous Shader. + Does not alter shader Reference_Count. + + #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); + } + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 +#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 + + 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 + + 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) + + Sets Color_Filter to filter, decrementing Reference_Count of the previous Color_Filter. + Pass nullptr to clear Color_Filter. + Does not alter filter Reference_Count. + + #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); + } + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 +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); + } +} +## + +#SeeAlso Blend_Mode + +#Method SkBlendMode getBlendMode() const + + Returns Blend_Mode. + By default, getBlendMode returns SkBlendMode::kSrcOver. + + #Return mode used to combine source color with destination color ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint; + SkDebugf("kSrcOver %c= getBlendMode\n", + SkBlendMode::kSrcOver == paint.getBlendMode() ? '=' : '!'); + paint.setBlendMode(SkBlendMode::kSrc); + SkDebugf("kSrcOver %c= getBlendMode\n", + SkBlendMode::kSrcOver == paint.getBlendMode() ? '=' : '!'); + } + + #StdOut + kSrcOver == getBlendMode + kSrcOver != getBlendMode + ## + ## + +## + +#Method bool isSrcOver() const + + Returns true if Blend_Mode is SkBlendMode::kSrcOver, the default. + + #Return true if Blend_Mode is SkBlendMode::kSrcOver ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint; + SkDebugf("isSrcOver %c= true\n", paint.isSrcOver() ? '=' : '!'); + paint.setBlendMode(SkBlendMode::kSrc); + SkDebugf("isSrcOver %c= true\n", paint.isSrcOver() ? '=' : '!'); + } + + #StdOut + isSrcOver == true + isSrcOver != true + ## + ## + +## + +#Method void setBlendMode(SkBlendMode mode) + + Sets Blend_Mode to mode. + Does not check for valid input. + + #Param mode SkBlendMode used to combine source color and destination ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint; + SkDebugf("isSrcOver %c= true\n", paint.isSrcOver() ? '=' : '!'); + paint.setBlendMode(SkBlendMode::kSrc); + SkDebugf("isSrcOver %c= true\n", paint.isSrcOver() ? '=' : '!'); + } + + #StdOut + isSrcOver == true + isSrcOver != true + ## + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 +#Height 160 + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setStyle(SkPaint::kStroke_Style); + paint.setStrokeWidth(16); + SkScalar intervals[] = {30, 10}; + paint.setPathEffect(SkDashPathEffect::Make(intervals, SK_ARRAY_COUNT(intervals), 1)); + canvas->drawRoundRect({20, 20, 120, 120}, 20, 20, paint); + } +## + +#SeeAlso Path_Effect + +#Method SkPathEffect* getPathEffect() const + + Returns Path_Effect if set, or nullptr. + Does not alter Path_Effect Reference_Count. + + #Return Path_Effect if previously set, nullptr otherwise ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint; + SkDebugf("nullptr %c= path effect\n", paint.getPathEffect() ? '!' : '='); + paint.setPathEffect(SkCornerPathEffect::Make(10)); + SkDebugf("nullptr %c= path effect\n", paint.getPathEffect() ? '!' : '='); + } + + #StdOut + nullptr == path effect + nullptr != path effect + ## + ## + +## + + +#Method sk_sp<SkPathEffect> refPathEffect() const + + Returns Path_Effect if set, or nullptr. + Increases Path_Effect Reference_Count by one. + + #Return Path_Effect if previously set, nullptr otherwise ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint1, paint2; + paint1.setPathEffect(SkArcToPathEffect::Make(10)); + SkDebugf("path effect unique: %s\n", paint1.getPathEffect()->unique() ? "true" : "false"); + paint2.setPathEffect(paint1.refPathEffect()); + SkDebugf("path effect unique: %s\n", paint1.getPathEffect()->unique() ? "true" : "false"); + } + + #StdOut + path effect unique: true + path effect unique: false + ## + ## + +## + + +#Method void setPathEffect(sk_sp<SkPathEffect> pathEffect) + + Sets Path_Effect to pathEffect, + decrementing Reference_Count of the previous Path_Effect. + Pass nullptr to leave the path geometry unaltered. + Does not alter pathEffect Reference_Count. + + #Param pathEffect replace Path with a modification when drawn ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setPathEffect(SkDiscretePathEffect::Make(3, 5)); + canvas->drawRect(SkRect::MakeXYWH(40, 40, 175, 175), paint); + } + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic Mask_Filter_Methods + +Mask_Filter uses Color_Alpha 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 + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setMaskFilter(SkBlurMaskFilter::Make(kSolid_SkBlurStyle, 3)); + canvas->drawRect(SkRect::MakeXYWH(40, 40, 175, 175), paint); + } +## + +#Method SkMaskFilter* getMaskFilter() const + + Returns Mask_Filter if set, or nullptr. + Does not alter Mask_Filter Reference_Count. + + #Return Mask_Filter if previously set, nullptr otherwise ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint; + SkDebugf("nullptr %c= mask filter\n", paint.getMaskFilter() ? '!' : '='); + paint.setMaskFilter(SkBlurMaskFilter::Make(kOuter_SkBlurStyle, 3)); + SkDebugf("nullptr %c= mask filter\n", paint.getMaskFilter() ? '!' : '='); + } + + #StdOut + nullptr == mask filter + nullptr != mask filter + ## + ## + +## + +#Method sk_sp<SkMaskFilter> refMaskFilter() const + + Returns Mask_Filter if set, or nullptr. + Increases Mask_Filter Reference_Count by one. + + #Return Mask_Filter if previously set, nullptr otherwise ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint1, paint2; + paint1.setMaskFilter(SkBlurMaskFilter::Make(kNormal_SkBlurStyle, 1)); + SkDebugf("mask filter unique: %s\n", paint1.getMaskFilter()->unique() ? "true" : "false"); + paint2.setMaskFilter(paint1.refMaskFilter()); + SkDebugf("mask filter unique: %s\n", paint1.getMaskFilter()->unique() ? "true" : "false"); + } + + #StdOut + mask filter unique: true + mask filter unique: false + ## + ## + +## + +#Method void setMaskFilter(sk_sp<SkMaskFilter> maskFilter) + + Sets Mask_Filter to maskFilter, + decrementing 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. + Does not alter maskFilter Reference_Count. + + #Param maskFilter modifies clipping mask generated from drawn geometry ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setStyle(SkPaint::kStroke_Style); + paint.setStrokeWidth(10); + paint.setMaskFilter(SkBlurMaskFilter::Make(kNormal_SkBlurStyle, 10)); + canvas->drawRect(SkRect::MakeXYWH(40, 40, 175, 175), paint); + } + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 +#Height 100 + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setTypeface(SkTypeface::MakeDefault(SkTypeface::kBold)); + paint.setAntiAlias(true); + paint.setTextSize(36); + canvas->drawString("A Big Hello!", 10, 40, paint); + paint.setTypeface(nullptr); + paint.setFakeBoldText(true); + canvas->drawString("A Big Hello!", 10, 80, paint); + } +## + +#Method SkTypeface* getTypeface() const + + Returns Typeface if set, or nullptr. + Does not alter Typeface Reference_Count. + + #Return Typeface if previously set, nullptr otherwise ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint; + SkDebugf("nullptr %c= typeface\n", paint.getTypeface() ? '!' : '='); + paint.setTypeface(SkTypeface::MakeFromName("Times New Roman", SkFontStyle())); + SkDebugf("nullptr %c= typeface\n", paint.getTypeface() ? '!' : '='); + } + + #StdOut + nullptr == typeface + nullptr != typeface + ## + ## + +## + +#Method sk_sp<SkTypeface> refTypeface() const + + Increases Typeface Reference_Count by one. + + #Return Typeface if previously set, nullptr otherwise ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint1, paint2; + paint1.setTypeface(SkTypeface::MakeFromName("Times New Roman", + SkFontStyle(SkFontStyle::kNormal_Weight, SkFontStyle::kNormal_Width, + SkFontStyle::kItalic_Slant))); + SkDebugf("typeface1 %c= typeface2\n", + paint1.getTypeface() == paint2.getTypeface() ? '=' : '!'); + paint2.setTypeface(paint1.refTypeface()); + SkDebugf("typeface1 %c= typeface2\n", + paint1.getTypeface() == paint2.getTypeface() ? '=' : '!'); + } + + #StdOut + typeface1 != typeface2 + typeface1 == typeface2 + ## + ## + +## + +#Method void setTypeface(sk_sp<SkTypeface> typeface) + + Sets Typeface to typeface, + decrementing Reference_Count of the previous Typeface. + Pass nullptr to clear Typeface and use the default typeface. + Does not alter typeface Reference_Count. + + #Param typeface font and style used to draw text ## + + #Example + #Height 64 + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setTypeface(SkTypeface::MakeFromName("Courier New", SkFontStyle())); + canvas->drawString("Courier New", 10, 30, paint); + paint.setTypeface(nullptr); + canvas->drawString("default", 10, 50, paint); + } + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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, Arc, Circle, Oval, +Path, and Text. + +#Example +#Height 64 + void draw(SkCanvas* canvas) { + SkLayerRasterizer::Builder layerBuilder; + SkPaint paint; + paint.setAntiAlias(true); + paint.setStyle(SkPaint::kStroke_Style); + paint.setStrokeWidth(1); + layerBuilder.addLayer(paint); + paint.setAlpha(0x10); + paint.setStyle(SkPaint::kFill_Style); + paint.setBlendMode(SkBlendMode::kSrc); + layerBuilder.addLayer(paint); + paint.reset(); + paint.setAntiAlias(true); + paint.setTextSize(50); + paint.setRasterizer(layerBuilder.detach()); + canvas->drawString("outline", 10, 50, paint); + } +## + +#Method SkRasterizer* getRasterizer() const + + Returns Rasterizer if set, or nullptr. + Does not alter Rasterizer Reference_Count. + + #Return Rasterizer if previously set, nullptr otherwise ## + + #Example + #Function + class DummyRasterizer : public SkRasterizer { + public: + SK_DECLARE_PUBLIC_FLATTENABLE_DESERIALIZATION_PROCS(DummyRasterizer) + }; + + sk_sp<SkFlattenable> DummyRasterizer::CreateProc(SkReadBuffer&) { + return sk_make_sp<DummyRasterizer>(); + } + + #Function ## + void draw(SkCanvas* canvas) { + SkPaint paint; + DummyRasterizer dummy; + SkDebugf("nullptr %c= rasterizer\n", paint.getRasterizer() ? '!' : '='); + paint.setRasterizer(sk_make_sp<DummyRasterizer>()); + SkDebugf("nullptr %c= rasterizer\n", paint.getRasterizer() ? '!' : '='); + } + + #StdOut + nullptr == rasterizer + nullptr != rasterizer + ## + ## + +## + +#Method sk_sp<SkRasterizer> refRasterizer() const + + Returns Rasterizer if set, or nullptr. + Increases Rasterizer Reference_Count by one. + + #Return Rasterizer if previously set, nullptr otherwise ## + + #Example + void draw(SkCanvas* canvas) { + SkLayerRasterizer::Builder layerBuilder; + SkPaint paint1, paint2; + layerBuilder.addLayer(paint2); + paint1.setRasterizer(layerBuilder.detach()); + SkDebugf("rasterizer unique: %s\n", paint1.getRasterizer()->unique() ? "true" : "false"); + paint2.setRasterizer(paint1.refRasterizer()); + SkDebugf("rasterizer unique: %s\n", paint1.getRasterizer()->unique() ? "true" : "false"); + } + + #StdOut + rasterizer unique: true + rasterizer unique: false + ## + ## + +## + +#Method void setRasterizer(sk_sp<SkRasterizer> rasterizer) + + Sets Rasterizer to rasterizer, + decrementing Reference_Count of the previous Rasterizer. + Pass nullptr to clear Rasterizer and leave Rasterizer effect on Mask_Alpha unaltered. + Does not affect Mask_Filter. + Does not alter rasterizer Reference_Count. + + #Param rasterizer how geometry is converted to Mask_Alpha ## + + #Example + #Height 64 + SkLayerRasterizer::Builder layerBuilder; + SkPaint paint; + paint.setAntiAlias(true); + paint.setStyle(SkPaint::kStroke_Style); + paint.setStrokeWidth(2); + layerBuilder.addLayer(paint); + paint.reset(); + paint.setAntiAlias(true); + paint.setTextSize(50); + paint.setMaskFilter(SkBlurMaskFilter::Make(kNormal_SkBlurStyle, 3)); + paint.setRasterizer(layerBuilder.detach()); + canvas->drawString("blurry out", 0, 50, paint); + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 Color_Alpha only. +Image_Filter operates independently of and can be used in combination with +Mask_Filter and Rasterizer. + +#Example + #ToDo explain why the two draws are so different ## + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setStyle(SkPaint::kStroke_Style); + paint.setStrokeWidth(2); + SkRegion region; + region.op( 10, 10, 50, 50, SkRegion::kUnion_Op); + region.op( 10, 50, 90, 90, SkRegion::kUnion_Op); + paint.setImageFilter(SkImageFilter::MakeBlur(5.0f, 5.0f, nullptr)); + canvas->drawRegion(region, paint); + paint.setImageFilter(nullptr); + paint.setMaskFilter(SkBlurMaskFilter::Make(kNormal_SkBlurStyle, 5)); + canvas->translate(100, 100); + canvas->drawRegion(region, paint); + } +## + +#Method SkImageFilter* getImageFilter() const + + Returns Image_Filter if set, or nullptr. + Does not alter Image_Filter Reference_Count. + + #Return Image_Filter if previously set, nullptr otherwise ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint; + SkDebugf("nullptr %c= image filter\n", paint.getImageFilter() ? '!' : '='); + paint.setImageFilter(SkImageFilter::MakeBlur(kOuter_SkBlurStyle, 3, nullptr, nullptr)); + SkDebugf("nullptr %c= image filter\n", paint.getImageFilter() ? '!' : '='); + } + + #StdOut + nullptr == image filter + nullptr != image filter + ## + ## + +## + +#Method sk_sp<SkImageFilter> refImageFilter() const + + Returns Image_Filter if set, or nullptr. + Increases Image_Filter Reference_Count by one. + + #Return Image_Filter if previously set, nullptr otherwise ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint1, paint2; + paint1.setImageFilter(SkOffsetImageFilter::Make(25, 25, nullptr)); + SkDebugf("image filter unique: %s\n", paint1.getImageFilter()->unique() ? "true" : "false"); + paint2.setImageFilter(paint1.refImageFilter()); + SkDebugf("image filter unique: %s\n", paint1.getImageFilter()->unique() ? "true" : "false"); + } + + #StdOut + image filter unique: true + image filter unique: false + ## + ## + +## + +#Method void setImageFilter(sk_sp<SkImageFilter> imageFilter) + + Sets Image_Filter to imageFilter, + decrementing 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. + Does not alter imageFilter Reference_Count. + + #Param imageFilter how Image is sampled when transformed ## + + #Example + #Height 160 + void draw(SkCanvas* canvas) { + SkBitmap bitmap; + bitmap.allocN32Pixels(100, 100); + SkCanvas offscreen(bitmap); + SkPaint paint; + paint.setAntiAlias(true); + paint.setColor(SK_ColorWHITE); + paint.setTextSize(96); + offscreen.clear(0); + offscreen.drawString("e", 20, 70, paint); + paint.setImageFilter( + SkLightingImageFilter::MakePointLitDiffuse(SkPoint3::Make(80, 100, 10), + SK_ColorWHITE, 1, 2, nullptr, nullptr)); + canvas->drawBitmap(bitmap, 0, 0, &paint); + } + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 +#Height 128 + void draw(SkCanvas* canvas) { + SkLayerDrawLooper::LayerInfo info; + info.fPaintBits = (SkLayerDrawLooper::BitFlags) SkLayerDrawLooper::kColorFilter_Bit; + info.fColorMode = SkBlendMode::kSrc; + SkLayerDrawLooper::Builder looperBuilder; + SkPaint* loopPaint = looperBuilder.addLayer(info); + loopPaint->setColor(SK_ColorRED); + info.fOffset.set(20, 20); + loopPaint = looperBuilder.addLayer(info); + loopPaint->setColor(SK_ColorBLUE); + SkPaint paint; + paint.setDrawLooper(looperBuilder.detach()); + canvas->drawCircle(50, 50, 50, paint); + } + +## + +#Method SkDrawLooper* getDrawLooper() const + + Returns Draw_Looper if set, or nullptr. + Does not alter Draw_Looper Reference_Count. + + #Return Draw_Looper if previously set, nullptr otherwise ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint; + SkDebugf("nullptr %c= draw looper\n", paint.getDrawLooper() ? '!' : '='); + SkLayerDrawLooper::Builder looperBuilder; + paint.setDrawLooper(looperBuilder.detach()); + SkDebugf("nullptr %c= draw looper\n", paint.getDrawLooper() ? '!' : '='); + } + + #StdOut + nullptr == draw looper + nullptr != draw looper + ## + ## + +## + +#Method sk_sp<SkDrawLooper> refDrawLooper() const + + Returns Draw_Looper if set, or nullptr. + Increases Draw_Looper Reference_Count by one. + + #Return Draw_Looper if previously set, nullptr otherwise ## + + #Example + void draw(SkCanvas* canvas) { + SkPaint paint1, paint2; + SkLayerDrawLooper::Builder looperBuilder; + paint1.setDrawLooper(looperBuilder.detach()); + SkDebugf("draw looper unique: %s\n", paint1.getDrawLooper()->unique() ? "true" : "false"); + paint2.setDrawLooper(paint1.refDrawLooper()); + SkDebugf("draw looper unique: %s\n", paint1.getDrawLooper()->unique() ? "true" : "false"); + } + + #StdOut + draw looper unique: true + draw looper unique: false + ## + ## + +## + +#Method SkDrawLooper* getLooper() const + +Deprecated. + +#Deprecated +(see bug.skia.org/6259) +#Deprecated ## + +#Return Draw_Looper if previously set, nullptr otherwise ## +## + +#Method void setDrawLooper(sk_sp<SkDrawLooper> drawLooper) + + Sets Draw_Looper to drawLooper, + decrementing Reference_Count of the previous drawLooper. + Pass nullptr to clear Draw_Looper and leave Draw_Looper effect on drawing unaltered. + setDrawLooper does not alter drawLooper Reference_Count. + + #Param drawLooper Iterates through drawing one or more time, altering Paint ## + + #Example + #Height 128 + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setDrawLooper(SkBlurDrawLooper::Make(0x7FFF0000, 4, -5, -10)); + paint.setStyle(SkPaint::kStroke_Style); + paint.setStrokeWidth(10); + paint.setAntiAlias(true); + paint.setColor(0x7f0000ff); + canvas->drawCircle(70, 70, 50, paint); + } + ## + +## + +#Method void setLooper(sk_sp<SkDrawLooper> drawLooper) + +Deprecated. + +#Deprecated +(see bug.skia.org/6259) +#Deprecated ## + +#Param drawLooper sets Draw_Looper to drawLooper ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic Text_Align + +#Enum Align +#Code + 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. + +#Const kLeft_Align 0 + Leaves the glyph at the position computed by the font offset by the text position. +## + +#Const kCenter_Align 1 + Moves the glyph half its width if Flags has kVerticalText_Flag clear, and + half its height if Flags has kVerticalText_Flag set. +## + +#Const kRight_Align 2 + Moves the glyph by its width if Flags has kVerticalText_Flag clear, + and by its height if Flags has kVerticalText_Flag set. +## + +#Enum ## + +#Enum + +#Code + enum { + kAlignCount = 3 + }; +## + +#Const kAlignCount 3 + The number of different Text_Align values defined. +## + +#Enum ## + +#Example + #Height 160 + #Description + Each position separately moves the glyph in drawPosText. + ## + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setTextSize(40); + SkPoint position[] = {{100, 50}, {150, 40}}; + for (SkPaint::Align a : { SkPaint::kLeft_Align, + SkPaint::kCenter_Align, + SkPaint::kRight_Align}) { + paint.setTextAlign(a); + canvas->drawPosText("Aa", 2, position, paint); + canvas->translate(0, 50); + } + } +## + +#Example + #Height 160 + #Description + Vertical_Text treats kLeft_Align as top align, and kRight_Align as bottom align. + ## + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setTextSize(40); + paint.setVerticalText(true); + for (SkPaint::Align a : { SkPaint::kLeft_Align, + SkPaint::kCenter_Align, + SkPaint::kRight_Align }) { + paint.setTextAlign(a); + canvas->drawString("Aa", 50, 80, paint); + canvas->translate(50, 0); + } + } +## + +#Method Align getTextAlign() const + + Returns Text_Align. + Returns kLeft_Align if Text_Align has not been set. + + #Return text placement relative to position ## + + #Example + SkPaint paint; + SkDebugf("kLeft_Align %c= default\n", SkPaint::kLeft_Align == paint.getTextAlign() ? '=' : '!'); + + #StdOut + kLeft_Align == default + ## + ## +## + +#Method void setTextAlign(Align align) + + Sets Text_Align to align. + Has no effect if align is an invalid value. + + #Param align text placement relative to position ## + + #Example + #Height 160 + #Description + Text is left-aligned by default, and then set to center. Setting the + alignment out of range has no effect. + ## + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setTextSize(40); + canvas->drawString("Aa", 100, 50, paint); + paint.setTextAlign(SkPaint::kCenter_Align); + canvas->drawString("Aa", 100, 100, paint); + paint.setTextAlign((SkPaint::Align) SkPaint::kAlignCount); + canvas->drawString("Aa", 100, 150, paint); + } + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic Text_Size + +Text_Size adjusts the overall text size in points. +Text_Size can be set to any positive value or zero. +Text_Size defaults to 12. +Set SkPaintDefaults_TextSize at compile time to change the default setting. + +#Example +#Height 135 + void draw(SkCanvas* canvas) { + SkPaint paint; + canvas->drawString("12 point", 10, 20, paint); + paint.setTextSize(24); + canvas->drawString("24 point", 10, 60, paint); + paint.setTextSize(48); + canvas->drawString("48 point", 10, 120, paint); + } +## + +#Method SkScalar getTextSize() const + + Returns Text_Size in points. + + #Return typographic height of text ## + + #Example + SkPaint paint; + SkDebugf("12 %c= default text size\n", 12 == paint.getTextSize() ? '=' : '!'); + ## + +## + +#Method void setTextSize(SkScalar textSize) + + Sets Text_Size in points. + Has no effect if textSize is not greater than or equal to zero. + + #Param textSize typographic height of text ## + + #Example + SkPaint paint; + SkDebugf("12 %c= text size\n", 12 == paint.getTextSize() ? '=' : '!'); + paint.setTextSize(-20); + SkDebugf("12 %c= text size\n", 12 == paint.getTextSize() ? '=' : '!'); + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 +#Height 128 + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setAntiAlias(true); + paint.setTextSize(24); + paint.setTextScaleX(.8f); + canvas->drawString("narrow", 10, 20, paint); + paint.setTextScaleX(1); + canvas->drawString("normal", 10, 60, paint); + paint.setTextScaleX(1.2f); + canvas->drawString("wide", 10, 100, paint); + } +## + +#Method SkScalar getTextScaleX() const + + Returns Text_Scale_X. + Default value is 1. + + #Return text horizontal scale ## + + #Example + SkPaint paint; + SkDebugf("1 %c= default text scale x\n", 1 == paint.getTextScaleX() ? '=' : '!'); + ## + +## + + +#Method void setTextScaleX(SkScalar scaleX) + + Sets Text_Scale_X. + Default value is 1. + + #Param scaleX text horizontal scale ## + + #Example + SkPaint paint; + paint.setTextScaleX(0.f / 0.f); + SkDebugf("text scale %s-a-number\n", SkScalarIsNaN(paint.getTextScaleX()) ? "not" : "is"); + ## + +## + +#Topic ## + +#Topic 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 +#Height 128 + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setAntiAlias(true); + paint.setTextSize(24); + paint.setTextSkewX(-.25f); + canvas->drawString("right-leaning", 10, 100, paint); + paint.setTextSkewX(0); + canvas->drawString("normal", 10, 60, paint); + paint.setTextSkewX(.25f); + canvas->drawString("left-leaning", 10, 20, paint); + } +## + +#Method SkScalar getTextSkewX() const + + Returns Text_Skew_X. + Default value is zero. + + #Return additional shear in x-axis relative to y-axis ## + + #Example + SkPaint paint; + SkDebugf("0 %c= default text skew x\n", 0 == paint.getTextSkewX() ? '=' : '!'); + ## + +## + +#Method void setTextSkewX(SkScalar skewX) + + Sets Text_Skew_X. + Default value is zero. + + #Param skewX additional shear in x-axis relative to y-axis ## + + #Example + SkPaint paint; + paint.setTextScaleX(1.f / 0.f); + SkDebugf("text scale %s-finite\n", SkScalarIsFinite(paint.getTextScaleX()) ? "is" : "not"); + ## + +## + +#Topic ## + +# ------------------------------------------------------------------------------ +#Topic Text_Encoding + +#Enum TextEncoding + +#Code + enum TextEncoding { + kUTF8_TextEncoding, + kUTF16_TextEncoding, + kUTF32_TextEncoding, + kGlyphID_TextEncoding + }; +## + +TextEncoding determines whether text specifies character codes and their encoded size, +or glyph indices. Character codes use the encoding specified by the +#A Unicode standard # http://unicode.org/standard/standard.html ##. +Character codes encoded size are specified by UTF-8, UTF-16, or UTF-32. +All character encoding are able to represent all of Unicode, differing only +in the total storage required. + +#A UTF-8 (RFC 3629) # https://tools.ietf.org/html/rfc3629 ## is made up of 8-bit bytes, +and is a superset of ASCII. +#A UTF-16 (RFC 2781) # https://tools.ietf.org/html/rfc2781 ## is made up of 16-bit words, +and is a superset of Unicode ranges 0x0000 to 0xD7FF and 0xE000 to 0xFFFF. +#A UTF-32 # http://www.unicode.org/versions/Unicode5.0.0/ch03.pdf ## is +made up of 32-bit words, and is a superset of Unicode. + +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. + +#Const kUTF8_TextEncoding 0 +Uses bytes to represent UTF-8 or ASCII. +## +#Const kUTF16_TextEncoding 1 +Uses two byte words to represent most of Unicode. +## +#Const kUTF32_TextEncoding 2 +Uses four byte words to represent all of Unicode. +## +#Const kGlyphID_TextEncoding 3 +Uses two byte words to represent glyph indices. +## + +#Enum ## + +#Example +#Height 128 +#Description +First line has UTF-8 encoding. +Second line has UTF-16 encoding. +Third line has UTF-32 encoding. +Fourth line has 16 bit glyph indices. +## +void draw(SkCanvas* canvas) { + SkPaint paint; + const char hello8[] = "Hello" "\xE2" "\x98" "\xBA"; + const uint16_t hello16[] = { 'H', 'e', 'l', 'l', 'o', 0x263A }; + const uint32_t hello32[] = { 'H', 'e', 'l', 'l', 'o', 0x263A }; + paint.setTextSize(24); + canvas->drawText(hello8, sizeof(hello8) - 1, 10, 30, paint); + paint.setTextEncoding(SkPaint::kUTF16_TextEncoding); + canvas->drawText(hello16, sizeof(hello16), 10, 60, paint); + paint.setTextEncoding(SkPaint::kUTF32_TextEncoding); + canvas->drawText(hello32, sizeof(hello32), 10, 90, paint); + uint16_t glyphs[SK_ARRAY_COUNT(hello32)]; + paint.textToGlyphs(hello32, sizeof(hello32), glyphs); + paint.setTextEncoding(SkPaint::kGlyphID_TextEncoding); + canvas->drawText(glyphs, sizeof(glyphs), 10, 120, paint); +} +## + +#Method TextEncoding getTextEncoding() const + + Returns Text_Encoding. + Text_Encoding determines how character code points are mapped to font glyph indices. + + #Return one of: kUTF8_TextEncoding, kUTF16_TextEncoding, kUTF32_TextEncoding, or + kGlyphID_TextEncoding + ## + + #Example + SkPaint paint; + SkDebugf("kUTF8_TextEncoding %c= text encoding\n", + SkPaint::kUTF8_TextEncoding == paint.getTextEncoding() ? '=' : '!'); + paint.setTextEncoding(SkPaint::kGlyphID_TextEncoding); + SkDebugf("kGlyphID_TextEncoding %c= text encoding\n", + SkPaint::kGlyphID_TextEncoding == paint.getTextEncoding() ? '=' : '!'); + + #StdOut + kUTF8_TextEncoding == text encoding + kGlyphID_TextEncoding == text encoding + ## + ## + +## + + +#Method 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. + + #Param encoding one of: kUTF8_TextEncoding, kUTF16_TextEncoding, kUTF32_TextEncoding, or + kGlyphID_TextEncoding ## + + #Example + SkPaint paint; + paint.setTextEncoding((SkPaint::TextEncoding) 4); + SkDebugf("4 %c= text encoding\n", 4 == paint.getTextEncoding() ? '=' : '!'); + + #StdOut + 4 != text encoding + ## + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic 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 +#Width 512 +void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setAntiAlias(true); + paint.setTextSize(120); + SkPaint::FontMetrics fm; + SkScalar lineHeight = paint.getFontMetrics(&fm); + SkPoint pt = { 70, 180 }; + canvas->drawString("M", pt.fX, pt.fY, paint); + canvas->drawLine(pt.fX, pt.fY, pt.fX, pt.fY + fm.fTop, paint); + SkScalar ascent = pt.fY + fm.fAscent; + canvas->drawLine(pt.fX - 25, ascent, pt.fX - 25, ascent + lineHeight, paint); + canvas->drawLine(pt.fX - 50, pt.fY, pt.fX - 50, pt.fY + fm.fDescent, paint); + canvas->drawLine(pt.fX + 100, pt.fY, pt.fX + 100, pt.fY + fm.fAscent, paint); + canvas->drawLine(pt.fX + 125, pt.fY, pt.fX + 125, pt.fY - fm.fXHeight, paint); + canvas->drawLine(pt.fX + 150, pt.fY, pt.fX + 150, pt.fY - fm.fCapHeight, paint); + canvas->drawLine(pt.fX + 5, pt.fY, pt.fX + 5, pt.fY + fm.fBottom, paint); + SkScalar xmin = pt.fX + fm.fXMin; + canvas->drawLine(xmin, pt.fY + 60, xmin + fm.fMaxCharWidth, pt.fY + 60, paint); + canvas->drawLine(xmin, pt.fY - 145, pt.fX, pt.fY - 145, paint); + canvas->drawLine(pt.fX + fm.fXMax, pt.fY - 160, pt.fX, pt.fY - 160, paint); + SkScalar upos = pt.fY + fm.fUnderlinePosition; + canvas->drawLine(pt.fX + 25, upos, pt.fX + 130, upos, paint); + SkScalar urad = fm.fUnderlineThickness / 2; + canvas->drawLine(pt.fX + 130, upos - urad, pt.fX + 160, upos - urad, paint); + canvas->drawLine(pt.fX + 130, upos + urad, pt.fX + 160, upos + urad, paint); + paint.setTextSize(12); + canvas->drawString("x-min", pt.fX - 50, pt.fY - 148, paint); + canvas->drawString("x-max", pt.fX + 140, pt.fY - 150, paint); + canvas->drawString("max char width", pt.fX + 120, pt.fY + 57, paint); + canvas->drawString("underline position", pt.fX + 30, pt.fY + 22, paint); + canvas->drawString("underline thickness", pt.fX + 162, pt.fY + 13, paint); + canvas->rotate(-90); + canvas->drawString("descent", -pt.fY - 30, pt.fX - 54, paint); + canvas->drawString("line height", -pt.fY, pt.fX - 29, paint); + canvas->drawString("top", -pt.fY + 30, pt.fX - 4, paint); + canvas->drawString("ascent", -pt.fY, pt.fX + 110, paint); + canvas->drawString("x-height", -pt.fY, pt.fX + 135, paint); + canvas->drawString("cap-height", -pt.fY, pt.fX + 160, paint); + canvas->drawString("bottom", -pt.fY - 50, pt.fX + 15, paint); +} +## + +#Struct FontMetrics + +#Code + 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 availble. + + fUnderlineThickness and fUnderlinePosition have a bit set in fFlags if their values + are valid, since their value may be zero. + + fStrikeoutThickness and fStrikeoutPosition have a bit set in fFlags if their values + are valid, since their value may be zero. + + #Enum FontMetricsFlags + #Code + 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. + + #Const kUnderlineThicknessIsValid_Flag 0x0001 + Set if fUnderlineThickness is valid. + ## + #Const kUnderlinePositionIsValid_Flag 0x0002 + Set if fUnderlinePosition is valid. + ## + #Const kStrikeoutThicknessIsValid_Flag 0x0004 + Set if fStrikeoutThickness is valid. + ## + #Const kStrikeoutPositionIsValid_Flag 0x0008 + Set if fStrikeoutPosition is valid. + ## + + #Enum ## + + #Member uint32_t fFlags + fFlags is set when underline metrics are valid. + ## + + #Member SkScalar fTop + Largest height for any glyph. + A measure from the baseline, and is less than or equal to zero. + ## + + #Member SkScalar fAscent + Recommended distance above the baseline to reserve for a line of text. + A measure from the baseline, and is less than or equal to zero. + ## + + #Member SkScalar fDescent + Recommended distance below the baseline to reserve for a line of text. + A measure from the baseline, and is greater than or equal to zero. + ## + + #Member SkScalar fBottom + Greatest extent below the baseline for any glyph. + A measure from the baseline, and is greater than or equal to zero. + ## + + #Member SkScalar fLeading + Recommended distance to add between lines of text. + Greater than or equal to zero. + ## + + #Member SkScalar fAvgCharWidth + Average character width, if it is available. + Zero if no average width is stored in the font. + ## + + #Member SkScalar fMaxCharWidth + Maximum character width. + ## + + #Member SkScalar fXMin + Minimum bounding box x value for all glyphs. + Typically less than zero. + ## + + #Member SkScalar fXMax + Maximum bounding box x value for all glyphs. + Typically greater than zero. + ## + + #Member SkScalar fXHeight + Height of a lower-case 'x'. + May be zero if no lower-case height is stored in the font. + ## + + #Member SkScalar fCapHeight + Height of an upper-case letter. + May be zero if no upper-case height is stored in the font. + ## + + #Member SkScalar fUnderlineThickness + Underline thickness. If the metric + is valid, the kUnderlineThicknessIsValid_Flag is set in fFlags. + If kUnderlineThicknessIsValid_Flag is clear, fUnderlineThickness is zero. + ## + + #Member SkScalar fUnderlinePosition + Underline position relative to the baseline. + It may be negative, to draw the underline above the baseline, zero + to draw the underline on the baseline, or positive to draw the underline + below the baseline. + + If the metric is valid, the kUnderlinePositionIsValid_Flag is set in fFlags. + If kUnderlinePositionIsValid_Flag is clear, fUnderlinePosition is zero. + ## + + #Member SkScalar fStrikeoutThickness + Strikeout thickness. If the metric + is valid, the kStrikeoutThicknessIsValid_Flag is set in fFlags. + If kStrikeoutThicknessIsValid_Flag is clear, fStrikeoutThickness is zero. + ## + + #Member SkScalar fStrikeoutPosition + Strikeout position relative to the baseline. + It may be negative, to draw the strikeout above the baseline, zero + to draw the strikeout on the baseline, or positive to draw the strikeout + below the baseline. + + If the metric is valid, the kStrikeoutPositionIsValid_Flag is set in fFlags. + If kStrikeoutPositionIsValid_Flag is clear, fStrikeoutPosition is zero. + ## + + #Method bool hasUnderlineThickness(SkScalar* thickness) const + + If Font_Metrics has a valid underline thickness, return true, and set + thickness to that value. If it doesn't, return false, and ignore + thickness. + + #Param thickness storage for underline width ## + + #Return true if font specifies underline width ## + + #NoExample + ## + ## + + #Method bool hasUnderlinePosition(SkScalar* position) const + + If Font_Metrics has a valid underline position, return true, and set + position to that value. If it doesn't, return false, and ignore + position. + + #Param position storage for underline position ## + + #Return true if font specifies underline position ## + + #NoExample + ## + ## + + #Method bool hasStrikeoutThickness(SkScalar* thickness) const + + If Font_Metrics has a valid strikeout thickness, return true, and set + thickness to that value. If it doesn't, return false, and ignore + thickness. + + #Param thickness storage for strikeout width ## + + #Return true if font specifies strikeout width ## + + #NoExample + ## + ## + + #Method bool hasStrikeoutPosition(SkScalar* position) const + + If Font_Metrics has a valid strikeout position, return true, and set + position to that value. If it doesn't, return false, and ignore + position. + + #Param position storage for strikeout position ## + + #Return true if font specifies strikeout position ## + + #NoExample + ## + ## + +#Struct ## + +#Method 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. + + #Param metrics storage for Font_Metrics from Typeface; may be nullptr ## + #Param scale additional multiplier for returned values ## + + #Return recommended spacing between lines ## + + #Example + #Height 128 + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setTextSize(32); + SkScalar lineHeight = paint.getFontMetrics(nullptr); + canvas->drawString("line 1", 10, 40, paint); + canvas->drawString("line 2", 10, 40 + lineHeight, paint); + paint.setStyle(SkPaint::kStroke_Style); + paint.setStrokeWidth(10); + lineHeight = paint.getFontMetrics(nullptr, 1.10f); // account for stroke height + canvas->drawString("line 3", 120, 40, paint); + canvas->drawString("line 4", 120, 40 + lineHeight, paint); + } + ## + + #SeeAlso Text_Size Typeface Typeface_Methods + +## + + +#Method 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. + getFontSpacing returns the same result as getFontMetrics. + + #Return recommended spacing between lines ## + + #Example + SkPaint paint; + for (SkScalar textSize : { 12, 18, 24, 32 } ) { + paint.setTextSize(textSize); + SkDebugf("textSize: %g fontSpacing: %g\n", textSize, paint.getFontSpacing()); + } + + #StdOut + textSize: 12 fontSpacing: 13.9688 + textSize: 18 fontSpacing: 20.9531 + textSize: 24 fontSpacing: 27.9375 + textSize: 32 fontSpacing: 37.25 + ## + ## + +## + + +#Method SkRect getFontBounds() const + +Returns the union of bounds of all glyphs. +Returned dimensions are computed by Font_Manager from font data, +ignoring Hinting. getFontBounds 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, +getFontBounds returns the same bounds as Font_Metrics { FontMetrics::fXMin, +FontMetrics::fTop, FontMetrics::fXMax, FontMetrics::fBottom }. + +#Return union of bounds of all glyphs ## + +#Example + SkPaint paint; + SkPaint::FontMetrics fm; + paint.getFontMetrics(&fm); + SkRect fb = paint.getFontBounds(); + SkDebugf("metrics bounds = { %g, %g, %g, %g }\n", fm.fXMin, fm.fTop, fm.fXMax, fm.fBottom ); + SkDebugf("font bounds = { %g, %g, %g, %g }\n", fb.fLeft, fb.fTop, fb.fRight, fm.fBottom ); + + #StdOut + metrics bounds = { -12.2461, -14.7891, 21.5215, 5.55469 } + font bounds = { -12.2461, -14.7891, 21.5215, 5.55469 } + ## +## + +## + +#Topic ## +# ------------------------------------------------------------------------------ + +#Method 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 encoding or valid +glyph indices. + +If byteLength equals zero, textToGlyphs 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. + +#Param text character stroage encoded with Text_Encoding ## +#Param byteLength length of character storage in bytes ## +#Param glyphs storage for glyph indices; may be nullptr ## + +#Return number of glyphs represented by text of length byteLength ## + + #Example + #Height 64 + void draw(SkCanvas* canvas) { + SkPaint paint; + const uint8_t utf8[] = { 0x24, 0xC2, 0xA2, 0xE2, 0x82, 0xAC, 0xC2, 0xA5, 0xC2, 0xA3 }; + std::vector<SkGlyphID> glyphs; + int count = paint.textToGlyphs(utf8, sizeof(utf8), nullptr); + glyphs.resize(count); + (void) paint.textToGlyphs(utf8, sizeof(utf8), &glyphs.front()); + paint.setTextEncoding(SkPaint::kGlyphID_TextEncoding); + paint.setTextSize(32); + canvas->drawText(&glyphs.front(), glyphs.size() * sizeof(SkGlyphID), 10, 40, paint); + } + ## + +## + +#Method 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. + +#Param text character stroage encoded with Text_Encoding ## +#Param byteLength length of character storage in bytes ## + +#Return number of glyphs represented by text of length byteLength ## + + #Example + SkPaint paint; + const uint8_t utf8[] = { 0x24, 0xC2, 0xA2, 0xE2, 0x82, 0xAC, 0xC2, 0xA5, 0xC2, 0xA3 }; + SkDebugf("count = %d\n", paint.countText(utf8, sizeof(utf8))); + + #StdOut + count = 5 + ## + ## +## + +# ------------------------------------------------------------------------------ + +#Method 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, containsText + returns true if all glyph indices in text are non-zero; containsText + does not check to see if text contains valid glyph indices for Typeface. + + Returns true if bytelength is zero. + + #Param text array of characters or glyphs ## + #Param byteLength number of bytes in text array ## + + #Return true if all text corresponds to a non-zero glyph index ## + + #Example + #Description + containsText succeeds for degree symbol, but cannot find a glyph index + corresponding to the Unicode surrogate code point. + ## + SkPaint paint; + const uint16_t goodChar = 0x00B0; // degree symbol + const uint16_t badChar = 0xD800; // Unicode surrogate + paint.setTextEncoding(SkPaint::kUTF16_TextEncoding); + SkDebugf("0x%04x %c= has char\n", goodChar, + paint.containsText(&goodChar, 2) ? '=' : '!'); + SkDebugf("0x%04x %c= has char\n", badChar, + paint.containsText(&badChar, 2) ? '=' : '!'); + + #StdOut + 0x00b0 == has char + 0xd800 != has char + ## + ## + + #Example + #Description + containsText returns true that glyph index is greater than zero, not + that it corresponds to an entry in Typeface. + ## + SkPaint paint; + const uint16_t goodGlyph = 511; + const uint16_t zeroGlyph = 0; + const uint16_t badGlyph = 65535; // larger than glyph count in font + paint.setTextEncoding(SkPaint::kGlyphID_TextEncoding); + SkDebugf("0x%04x %c= has glyph\n", goodGlyph, + paint.containsText(&goodGlyph, 2) ? '=' : '!'); + SkDebugf("0x%04x %c= has glyph\n", zeroGlyph, + paint.containsText(&zeroGlyph, 2) ? '=' : '!'); + SkDebugf("0x%04x %c= has glyph\n", badGlyph, + paint.containsText(&badGlyph, 2) ? '=' : '!'); + + #StdOut + 0x01ff == has glyph + 0x0000 != has glyph + 0xffff == has glyph + ## + ## + +#SeeAlso setTextEncoding Typeface + +## + +# ------------------------------------------------------------------------------ + +#Method 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. + + #Param glyphs array of indices into font ## + #Param count length of glyph array ## + #Param text storage for character codes, one per glyph ## + + #Example + #Height 64 + #Description + Convert UTF-8 text to glyphs; then convert glyphs to Unichar code points. + ## + void draw(SkCanvas* canvas) { + SkPaint paint; + const char hello[] = "Hello!"; + const int count = sizeof(hello) - 1; + SkGlyphID glyphs[count]; + if (count != paint.textToGlyphs(hello, count, glyphs)) { + return; + } + SkUnichar unichars[count]; + paint.glyphsToUnichars(glyphs, count, unichars); + paint.setTextEncoding(SkPaint::kUTF32_TextEncoding); + canvas->drawText(unichars, sizeof(unichars), 10, 30, paint); + } + ## + +## + +# ------------------------------------------------------------------------------ +#Topic Measure_Text + +#Method 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. + + #Param text character codes or glyph indices to be measured ## + #Param length number of bytes of text to measure ## + #Param bounds returns bounding box relative to (0, 0) if not nullptr ## + + #Return advance width or height ## + + #Example + #Height 64 + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setAntiAlias(true); + paint.setTextSize(50); + const char str[] = "ay^jZ"; + const int count = sizeof(str) - 1; + canvas->drawText(str, count, 25, 50, paint); + SkRect bounds; + paint.measureText(str, count, &bounds); + canvas->translate(25, 50); + paint.setStyle(SkPaint::kStroke_Style); + canvas->drawRect(bounds, paint); + } + ## + +## + +#Method 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. + + #Param text character codes or glyph indices to be measured ## + #Param length number of bytes of text to measure ## + + #Return advance width or height ## + + #Example + SkPaint paint; + SkDebugf("default width = %g\n", paint.measureText("!", 1)); + paint.setTextSize(paint.getTextSize() * 2); + SkDebugf("double width = %g\n", paint.measureText("!", 1)); + + #StdOut + default width = 5 + double width = 10 + ## + ## + +## + +#Method size_t breakText(const void* text, size_t length, SkScalar maxWidth, + SkScalar* measuredWidth = NULL) 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. + + #Param text character codes or glyph indices to be measured ## + #Param length number of bytes of text to measure ## + #Param maxWidth advance limit; text is measured while advance is less than maxWidth ## + #Param measuredWidth returns the width of the text less than or equal to maxWidth ## + #Return bytes of text that fit, always less than or equal to length ## + + #Example + #Description + Line under "Breakfast" shows desired width, shorter than available characters. + Line under "Bre" shows measured width after breaking text. + ## + #Height 128 + #Width 280 + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setAntiAlias(true); + paint.setTextSize(50); + const char str[] = "Breakfast"; + const int count = sizeof(str) - 1; + canvas->drawText(str, count, 25, 50, paint); + SkScalar measuredWidth; + int partialBytes = paint.breakText(str, count, 100, &measuredWidth); + canvas->drawText(str, partialBytes, 25, 100, paint); + canvas->drawLine(25, 60, 25 + 100, 60, paint); + canvas->drawLine(25, 110, 25 + measuredWidth, 110, paint); + } + ## + +## + +#Method int getTextWidths(const void* text, size_t byteLength, SkScalar widths[], + SkRect bounds[] = NULL) 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. + + #Param text character codes or glyph indices to be measured ## + #Param byteLength number of bytes of text to measure ## + #Param widths returns text advances for each glyph; may be nullptr ## + #Param bounds returns bounds for each glyph relative to (0, 0); may be nullptr ## + + #Return glyph count in text ## + + #Example + #Height 160 + #Description + 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 draw(SkCanvas* canvas) { + SkPaint paint; + paint.setAntiAlias(true); + paint.setTextSize(50); + const char str[] = "abc"; + const int bytes = sizeof(str) - 1; + int count = paint.getTextWidths(str, bytes, nullptr); + std::vector<SkScalar> widths; + std::vector<SkRect> bounds; + widths.resize(count); + bounds.resize(count); + for (int loop = 0; loop < 2; ++loop) { + (void) paint.getTextWidths(str, count, &widths.front(), &bounds.front()); + SkPoint loc = { 25, 50 }; + canvas->drawText(str, bytes, loc.fX, loc.fY, paint); + paint.setStyle(SkPaint::kStroke_Style); + paint.setStrokeWidth(0); + SkScalar advanceY = loc.fY + 10; + for (int index = 0; index < count; ++index) { + bounds[index].offset(loc.fX, loc.fY); + canvas->drawRect(bounds[index], paint); + canvas->drawLine(loc.fX, advanceY, loc.fX + widths[index], advanceY, paint); + loc.fX += widths[index]; + advanceY += 5; + } + canvas->translate(0, 80); + paint.setStrokeWidth(3); + } + } + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic Text_Path + +Text_Path describes the geometry of glyphs used to draw text. + +#Method 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. +getTextPath uses x, y, and Text_Align to position path. + + #Param text character codes or glyph indices ## + #Param length number of bytes of text ## + #Param x x-coordinate of the origin of the text ## + #Param y y-coordinate of the origin of the text ## + #Param path geometry of the glyphs ## + + #Example + #Description + Text is added to Path, offset, and subtracted from Path, then added at + the offset location. The result is rendered with one draw call. + ## + #Height 128 + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setTextSize(80); + SkPath path, path2; + paint.getTextPath("ABC", 3, 20, 80, &path); + path.offset(20, 20, &path2); + Op(path, path2, SkPathOp::kDifference_SkPathOp, &path); + path.addPath(path2); + paint.setStyle(SkPaint::kStroke_Style); + canvas->drawPath(path, paint); + } + ## + +## + +#Method 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. + + #Param text character codes or glyph indices ## + #Param length number of bytes of text ## + #Param pos positions of each glyph ## + #Param path geometry of the glyphs ## + + #Example + #Height 85 + #Description + Simplifies three glyphs to eliminate overlaps, and strokes the result. + ## + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setTextSize(80); + SkPath path, path2; + SkPoint pos[] = {{20, 60}, {30, 70}, {40, 80}}; + paint.getPosTextPath("ABC", 3, pos, &path); + Simplify(path, &path); + paint.setStyle(SkPaint::kStroke_Style); + canvas->drawPath(path, paint); + } + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ +#Topic Text_Intercepts + +Text_Intercepts describe the intersection of drawn text glyphs with a pair +of lines parallel to the text advance. Text_Intercepts permits creating a +underline that skips descenders. + +#Method 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. + + #Param text character codes or glyph indices ## + #Param length number of bytes of text ## + #Param x x-coordinate of the origin of the text ## + #Param y y-coordinate of the origin of the text ## + #Param bounds lower and upper line parallel to the advance ## + #Param intervals returned intersections; may be nullptr ## + + #Return number of intersections; may be zero ## + +#Example +#Height 128 +#Description +Underline uses intercepts to draw on either side of the glyph descender. +## +void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setTextSize(120); + SkPoint textOrigin = { 20, 100 }; + SkScalar bounds[] = { 100, 108 }; + int count = paint.getTextIntercepts("y", 1, textOrigin.fX, textOrigin.fY, bounds, nullptr); + std::vector<SkScalar> intervals; + intervals.resize(count); + (void) paint.getTextIntercepts("y", 1, textOrigin.fX, textOrigin.fY, bounds, + &intervals.front()); + canvas->drawString("y", textOrigin.fX, textOrigin.fY, paint); + paint.setColor(SK_ColorRED); + SkScalar x = textOrigin.fX; + for (int i = 0; i < count; i += 2) { + canvas->drawRect({x, bounds[0], intervals[i], bounds[1]}, paint); + x = intervals[i + 1]; + } + canvas->drawRect({intervals[count - 1], bounds[0], + textOrigin.fX + paint.measureText("y", 1), bounds[1]}, paint); +} +## + +## + +#Method 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. + + #Param text character codes or glyph indices ## + #Param length number of bytes of text ## + #Param pos positions of each glyph ## + #Param bounds lower and upper line parallel to the advance ## + #Param intervals returned intersections; may be nullptr ## + + #Return The number of intersections; may be zero ## + + #Example + #Description + Text intercepts draw on either side of, but not inside, glyphs in a run. + ## + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setTextSize(120); + paint.setVerticalText(true); + SkPoint textPos[] = {{ 60, 40 }, { 60, 140 }}; + SkScalar bounds[] = { 56, 64 }; + const char str[] = "A-"; + int len = sizeof(str) - 1; + int count = paint.getPosTextIntercepts(str, len, textPos, bounds, nullptr); + std::vector<SkScalar> intervals; + intervals.resize(count); + (void) paint.getPosTextIntercepts(str, len, textPos, bounds, &intervals.front()); + canvas->drawPosText(str, len, textPos, paint); + paint.setColor(SK_ColorRED); + SkScalar y = textPos[0].fY; + for (int i = 0; i < count; i+= 2) { + canvas->drawRect({bounds[0], y, bounds[1], intervals[i]}, paint); + y = intervals[i + 1]; + } + canvas->drawRect({bounds[0], intervals[count - 1], bounds[1], 240}, paint); + } + ## + +## + +#Method 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. + + #Param text character codes or glyph indices ## + #Param length number of bytes of text ## + #Param xpos positions of each glyph in x ## + #Param constY position of each glyph in y ## + #Param bounds lower and upper line parallel to the advance ## + #Param intervals returned intersections; may be nullptr ## + + #Return number of intersections; may be zero ## + + #Example + #Height 128 + #Description + Text intercepts do not take stroke thickness into consideration. + ## + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setTextSize(120); + paint.setStyle(SkPaint::kStroke_Style); + paint.setStrokeWidth(4); + SkScalar textPosH[] = { 20, 80, 140 }; + SkScalar y = 100; + SkScalar bounds[] = { 56, 78 }; + const char str[] = "\\-/"; + int len = sizeof(str) - 1; + int count = paint.getPosTextHIntercepts(str, len, textPosH, y, bounds, nullptr); + std::vector<SkScalar> intervals; + intervals.resize(count); + (void) paint.getPosTextHIntercepts(str, len, textPosH, y, bounds, &intervals.front()); + canvas->drawPosTextH(str, len, textPosH, y, paint); + paint.setColor(0xFFFF7777); + paint.setStyle(SkPaint::kFill_Style); + SkScalar x = textPosH[0]; + for (int i = 0; i < count; i+= 2) { + canvas->drawRect({x, bounds[0], intervals[i], bounds[1]}, paint); + x = intervals[i + 1]; + } + canvas->drawRect({intervals[count - 1], bounds[0], 180, bounds[1]}, paint); + } + ## + +## + + +#Method 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 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. + + #Param blob glyphs, positions, and text paint attributes ## + #Param bounds lower and upper line parallel to the advance ## + #Param intervals returned intersections; may be nullptr ## + + #Return number of intersections; may be zero ## + + #Example + #Height 143 + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setTextSize(120); + SkPoint textPos = { 20, 110 }; + int len = 3; + SkTextBlobBuilder textBlobBuilder; + const SkTextBlobBuilder::RunBuffer& run = + textBlobBuilder.allocRun(paint, len, textPos.fX, textPos.fY); + run.glyphs[0] = 10; + run.glyphs[1] = 20; + run.glyphs[2] = 30; + sk_sp<const SkTextBlob> blob = textBlobBuilder.make(); + canvas->drawTextBlob(blob.get(), textPos.fX, textPos.fY, paint); + SkScalar bounds[] = { 116, 134 }; + int count = paint.getTextBlobIntercepts(blob.get(), bounds, nullptr); + std::vector<SkScalar> intervals; + intervals.resize(count); + (void) paint.getTextBlobIntercepts(blob.get(), bounds, &intervals.front()); + canvas->drawTextBlob(blob.get(), 0, 0, paint); + paint.setColor(0xFFFF7777); + SkScalar x = textPos.fX; + for (int i = 0; i < count; i+= 2) { + canvas->drawRect({x, bounds[0], intervals[i], bounds[1]}, paint); + x = intervals[i + 1]; + } + canvas->drawRect({intervals[count - 1], bounds[0], 180, bounds[1]}, paint); + } + ## + +## + +#Topic ## +# ------------------------------------------------------------------------------ + +#Method bool nothingToDraw() const + + Returns true if Paint prevents all drawing. + If nothingToDraw returns false, the Paint may or may not allow drawing. + + Returns true if Blend_Mode and Color_Alpha are enabled, + and computed Color_Alpha is zero. + + #Return true if Paint prevents all drawing ## + + #Example + void draw(SkCanvas* canvas) { + auto debugster = [](const char* prefix, const SkPaint& p) -> void { + SkDebugf("%s nothing to draw: %s\n", prefix, + p.nothingToDraw() ? "true" : "false"); + }; + SkPaint paint; + debugster("initial", paint); + paint.setBlendMode(SkBlendMode::kDst); + debugster("blend dst", paint); + paint.setBlendMode(SkBlendMode::kSrcOver); + debugster("blend src over", paint); + paint.setAlpha(0); + debugster("alpha 0", paint); + } + + #StdOut + initial nothing to draw: false + blend dst nothing to draw: true + blend src over nothing to draw: false + alpha 0 nothing to draw: true + #StdOut ## + ## + +## + +# ------------------------------------------------------------------------------ +#Topic Fast_Bounds + #Private + To be made private. + ## + +Fast_Bounds methods conservatively outset a drawing bounds by additional area +Paint may draw to. + +#Method bool canComputeFastBounds() const + #Private + (to be made private) + ## + + Returns true if Paint does not include elements requiring extensive computation + to compute Device bounds of drawn geometry. For instance, Paint with Path_Effect + always returns false. + + #Return true if Paint allows for fast computation of bounds ## +## + +#Method const SkRect& computeFastBounds(const SkRect& orig, SkRect* storage) const + #Private + (to be made private) + ## + + Only call this if canComputeFastBounds returned true. This takes a + raw rectangle (the raw bounds of a shape), and adjusts it for stylistic + effects in the paint (e.g. stroking). If needed, it uses the storage + rect 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 retured value. It is legal for orig and storage to be the same + rect. + + #Private + e.g. + if (paint.canComputeFastBounds()) { + SkRect r, storage; + path.computeBounds(&r, SkPath::kFast_BoundsType); + const SkRect& fastR = paint.computeFastBounds(r, &storage); + if (canvas->quickReject(fastR, ...)) { + // don't draw the path + } + } + ## + + #Param orig geometry modified by Paint when drawn ## + #Param storage computed bounds of geometry; may not be nullptr ## + + #Return fast computed bounds ## +## + +#Method const SkRect& computeFastStrokeBounds(const SkRect& orig, + SkRect* storage) const + #Private + (to be made private) + ## + + #Param orig geometry modified by Paint when drawn ## + #Param storage computed bounds of geometry ## + + #Return fast computed bounds ## +## + +#Method const SkRect& doComputeFastBounds(const SkRect& orig, SkRect* storage, + Style style) const + #Private + (to be made private) + ## + + Take the style explicitly, so the caller can force us to be stroked + without having to make a copy of the paint just to change that field. + + #Param orig geometry modified by Paint when drawn ## + #Param storage computed bounds of geometry ## + #Param style overrides Style ## + + #Return fast computed bounds ## +## + +#Topic Fast_Bounds ## + +# ------------------------------------------------------------------------------ +#Method void toString(SkString* str) const; + +#DefinedBy SK_TO_STRING_NONVIRT() ## + +#Private +macro expands to: void toString(SkString* str) const; +## + +Converts Paint to machine parsable form in developer mode. + +#Param str storage for string containing parsable Paint ## + +#Example + SkPaint paint; + SkString str; + paint.toString(&str); + const char textSize[] = "TextSize:"; + const int trailerSize = strlen("</dd><dt>"); + int textSizeLoc = str.find(textSize) + strlen(textSize) + trailerSize; + const char* sizeStart = &str.c_str()[textSizeLoc]; + int textSizeEnd = SkStrFind(sizeStart, "</dd>"); + SkDebugf("text size = %.*s\n", textSizeEnd, sizeStart); + + #StdOut + text size = 12 + ## + +## + +#ToDo incomplete ## + +## + +# ------------------------------------------------------------------------------ + +#Class SkPaint ## + +#Topic Paint ## |