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>
diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh
new file mode 100644
index 0000000..0e4fcf5
--- /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 ##