﻿#Topic Paint
#Alias Paint_Reference

#Class SkPaint

Paint controls options applied when drawing and measuring. Paint collects all
options outside of the Canvas_Clip and Canvas_Matrix.

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

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

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

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

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

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

#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            # Approximate 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 Device.   ##
# getColor              # Returns Color_Alpha and Color_RGB, one drawing color. ##
# getColorFilter        # Returns Color_Filter, how colors are altered.         ##
# getDrawLooper         # Returns Draw_Looper, multiple layers.                 ##
# getFillPath           # Returns fill path equivalent to stroke.               ##
# getFilterQuality      # Returns Filter_Quality, image filtering level.        ##
# getFlags              # Returns Flags stored in a bit field.                  ##
# getFontBounds         # Returns union all glyph bounds.                       ##
# getFontMetrics        # Returns Typeface metrics scaled by text size.         ##
# getFontSpacing        # Returns recommended spacing between lines.            ##
# getHash               # Returns a shallow hash for equality checks.           ##
# getHinting            # Returns Hinting, glyph outline adjustment level.      ##
# getImageFilter        # Returns Image_Filter, alter pixels; blur.             ##
# getMaskFilter         # Returns Mask_Filter, alterations to Mask_Alpha.       ##
# getPathEffect         # Returns Path_Effect, modifications to path geometry; dashing. ##
# getPosTextPath        # Returns Path equivalent to positioned text.           ##
# getPosTextIntercepts  # Returns where lines intersect positioned text; underlines. ##
# getPosTextHIntercepts # Returns where lines intersect horizontally positioned text; underlines. ##
# getRasterizer         # Returns Rasterizer, Mask_Alpha generation from Path.  ##
# getShader             # Returns Shader, multiple drawing colors; gradients.   ##  
# getStrokeCap          # Returns Cap, the area drawn at path ends.             ##
# getStrokeJoin         # Returns Join, geometry on path corners.               ##
# getStrokeMiter        # Returns Miter_Limit, angles with sharp corners.       ##
# getStrokeWidth        # Returns thickness of the stroke.                      ##
# getStyle              # Returns Style: stroke, fill, or both.                 ##
# getTextAlign          # Returns Align: left, center, or right.                ##
# getTextBlobIntercepts # Returns where lines intersect Text_Blob; underlines.  ##
# getTextEncoding       # Returns character or glyph 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 readable form.              ##
# 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. Objects containing Reference_Count increment
their references by one.

The referenced objects Path_Effect, Shader, Mask_Filter, Color_Filter, Rasterizer,
Draw_Looper, and Image_Filter cannot be modified after they are created.
This prevents objects with Reference_Count from being modified once Paint refers to them.

#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 increasing the reference counts
    of objects referenced by the paint.

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

    #Param paint  original to move ##

    #Return  content of paint ##

    #Example
        SkPaint paint;
        float intervals[] = { 5, 5 };
        paint.setPathEffect(SkDashPathEffect::Make(intervals, SK_ARRAY_COUNT(intervals), 2.5f));
        SkPaint dashed(std::move(paint));
        SkDebugf("path effect unique: %s\n", dashed.getPathEffect()->unique() ? "true" : "false");

        #StdOut
            path effect unique: true
        ##
    ##

##

# ------------------------------------------------------------------------------

#Method void reset()

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 containing Reference_Count go 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. Objects containing Reference_Count in the
prior destination are decreased by one, and the referenced objects are deleted if the
resulting count is zero. Objects containing Reference_Count in the parameter paint
are increased by one. paint is unmodified.

#Param paint  original to copy ##

#Return  content of paint ##

#Example
    SkPaint paint1, paint2;
    paint1.setColor(SK_ColorRED);
    paint2 = paint1;
    SkDebugf("SK_ColorRED %c= paint1.getColor()\n", SK_ColorRED == paint1.getColor() ? '=' : '!');
    SkDebugf("SK_ColorRED %c= paint2.getColor()\n", SK_ColorRED == paint2.getColor() ? '=' : '!');

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

##

# ------------------------------------------------------------------------------

#Method SkPaint& operator=(SkPaint&& paint)

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

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

    #Param paint  original to move ##

    #Return  content of paint ##

#Example
    SkPaint paint1, paint2;
    paint1.setColor(SK_ColorRED);
    paint2 = std::move(paint1);
    SkDebugf("SK_ColorRED == paint2.getColor()\n", SK_ColorRED == paint2.getColor() ? '=' : '!');

    #StdOut
        SK_ColorRED == paint2.getColor()
    ##
##

##

# ------------------------------------------------------------------------------

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

    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 describing Paint content ##

# 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 contrast ##
    # kNormal_Hinting # 2 # modifies glyph outlines to improve contrast ##
    # kFull_Hinting   # 3 # modifies glyph outlines for maximum contrast ## 
    ##

    #Param hintingLevel  one of: kNo_Hinting, kSlight_Hinting, kNormal_Hinting, kFull_Hinting ##

    #Example
        SkPaint paint1, paint2;
        paint2.setHinting(SkPaint::kNormal_Hinting);
        SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : ':');

        #StdOut
        paint1 == paint2
        ##
    ##
##

#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 Bitmap, then drawn magnified to make the
        Aliasing easier to see.
    ##

    void draw(SkCanvas* canvas) {
        SkBitmap bitmap;
        bitmap.allocN32Pixels(50, 50);
        SkCanvas offscreen(bitmap);
        SkPaint paint;
        paint.setStyle(SkPaint::kStroke_Style);
        paint.setStrokeWidth(10);
        for (bool antialias : { false, true }) {
            paint.setColor(antialias ? SK_ColorRED : SK_ColorBLUE);
            paint.setAntiAlias(antialias);
            bitmap.eraseColor(0);
            offscreen.drawLine(5, 5, 15, 30, paint);
            canvas->drawLine(5, 5, 15, 30, paint);
            canvas->save();
            canvas->scale(10, 10);
            canvas->drawBitmap(bitmap, antialias ? 12 : 0, 0);
            canvas->restore();
            canvas->translate(15, 0);
        }
    }
    ##

#Method bool isAntiAlias() const

    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 adjacent pixels. 
This can help to smooth color transitions and reducing banding in gradients.
Dithering lessens visible banding from kRGB_565_SkColorType
and kRGBA_8888_SkColorType gradients, 
and improves rendering into a kRGB_565_SkColorType Surface.

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

Dither is disabled by default.
Dither can be enabled by default by setting SkPaintDefaults_Flags to kDither_Flag
at compile time.

Some platform implementations may ignore dithering. Set

#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 imperceptible.
LCD_Text can be enabled on devices that orient stripes horizontally or vertically, and that order
the color components as Color_RGB or Color_RBG.

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

Either or both techniques can be enabled.
kLCDRenderText_Flag and kSubpixelText_Flag are clear by default.
LCD_Text or Subpixel_Text can be enabled by default by setting SkPaintDefaults_Flags to 
kLCDRenderText_Flag or kSubpixelText_Flag (or both) at compile time.

#Example
    #Description
        Four commas are drawn normally and with combinations of LCD_Text and Subpixel_Text.
        When Subpixel_Text is disabled, the comma Glyphs are identical, but not evenly spaced.
        When Subpixel_Text is enabled, the comma Glyphs are unique, but appear evenly spaced.
    ##

    SkBitmap bitmap;
    bitmap.allocN32Pixels(24, 33);
    SkCanvas offscreen(bitmap);
    offscreen.clear(SK_ColorWHITE);
    SkPaint paint;
    paint.setAntiAlias(true);
    paint.setTextSize(20);
    for (bool lcd : { false, true }) {
        paint.setLCDRenderText(lcd);
        for (bool subpixel : { false, true }) {
            paint.setSubpixelText(subpixel);
            offscreen.drawString(",,,,", 0, 4, paint);
            offscreen.translate(0, 7);
        }
    }
    canvas->drawBitmap(bitmap, 4, 12);
    canvas->scale(9, 9);
    canvas->drawBitmap(bitmap, 4, -1);
##

#Subtopic 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 is 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 imperceptible.
LCD_Text can be enabled on devices that orient stripes horizontally or vertically, and that order
the color components as Color_RGB or Color_RBG.

#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.

    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 preceding glyph. Vertical_Text sets successive
Glyphs to position below the preceding glyph.

Skia can translate text character codes as a series of Glyphs, but does not implement
font substitution, 
textual substitution, line layout, or contextual spacing like Kerning pairs. Use
a text shaping engine like
#A HarfBuzz # 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 a bold typeface.

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

    #Param fakeBoldText  setting for kFakeBoldText_Flag ##

    #Example
        SkPaint paint1, paint2;
        paint1.setFakeBoldText(true);
        paint2.setFlags(paint2.getFlags() | SkPaint::kFakeBoldText_Flag);
        SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');

        #StdOut
            paint1 == paint2
        ##
    ##

##

#Topic ##

# ------------------------------------------------------------------------------
#Topic Full_Hinting_Spacing
#Alias Full_Hinting_Spacing # long winded enough -- maybe things with two underscores auto-aliased?

if Hinting is set to kFull_Hinting, Full_Hinting_Spacing adjusts the character
spacing by the difference of the hinted and Unhinted Left_Side_Bearing and
Right_Side_Bearing. Full_Hinting_Spacing only applies to platforms that use
FreeType as their Font_Engine.

Full_Hinting_Spacing is not related to text Kerning, where the space between
a specific pair of characters is adjusted using data in the font'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 drawn without scaling, the Filter_Quality choice will not result
in a noticeable difference.

Filter_Quality is used in Paint passed as a parameter to
#List
# SkCanvas::drawBitmap ##
# SkCanvas::drawBitmapRect ##
# SkCanvas::drawImage ##
# SkCanvas::drawImageRect ##
  #ToDo probably more... ##
#List ##
and when Paint has a Shader specialization that uses Image or Bitmap.

Filter_Quality is kNone_SkFilterQuality by default.

#Example
#Image 3
void draw(SkCanvas* canvas) {
    SkPaint paint;
    canvas->scale(.2f, .2f);
    for (SkFilterQuality q : { kNone_SkFilterQuality, kLow_SkFilterQuality, 
                               kMedium_SkFilterQuality, kHigh_SkFilterQuality } ) {
        paint.setFilterQuality(q);
        canvas->drawImage(image.get(), 0, 0, &paint);
        canvas->translate(550, 0);
        if (kLow_SkFilterQuality == q) canvas->translate(-1100, 550);
    }
}
##

#Method SkFilterQuality getFilterQuality() const

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.
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 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 Alpha and Color_RGB used when stroking and filling. The color is a 32-bit value,
    Unpremultiplied, packing 8-bit components for Alpha, Red, Blue, and Green. 

    #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 Alpha from the Color used when stroking and filling.

    #Return  Alpha ranging from zero, fully transparent, to 255, fully opaque ##

    #Example
        SkPaint paint;
        SkDebugf("255 %c= paint.getAlpha()\n", 255 == paint.getAlpha() ? '=' : '!');

        #StdOut
            255 == paint.getAlpha()
        ##
    ##

##

#Method void setAlpha(U8CPU a)

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

    #Param a    Alpha component of Color ##

    #Example
        SkPaint paint;
        paint.setColor(0x00112233);
        paint.setAlpha(0x44);
        SkDebugf("0x44112233 %c= paint.getColor()\n", 0x44112233 == paint.getColor() ? '=' : '!');

        #StdOut
            0x44112233 == paint.getColor()
        ##
    ##

##

#Subtopic ##

#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; 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, Circles, Ovals, Path, and Text. 
    Bitmap, Image, Patches, Region, Sprites, and Vertices are painted as if
    kFill_Style is set, and ignore the set Style.
    The Path_Fill_Type specifies additional rules to fill the area outside the path edge,
    and to create an unfilled hole inside the shape.
    Style is set to kFill_Style by default.
##

#Const kStroke_Style 1
    Set to stroke geometry.
    Applies to Rect, Region, Round_Rect, Arcs, Circles, Ovals, Path, and Text. 
    Arcs, Lines, and Points, are always drawn as if kStroke_Style is set,
    and ignore the set Style.
    The stroke construction is unaffected by the Path_Fill_Type.
##

#Const kStrokeAndFill_Style 2
    Set to stroke and fill geometry.
    Applies to Rect, Region, Round_Rect, Circles, Ovals, Path, and Text.
    Path is treated as if it is set to SkPath::kWinding_FillType,
    and the set Path_Fill_Type is ignored. 
##

#Enum ##

#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. Join
affects the four corners of a stroked rectangle, and the connected segments in a
stroked path.

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

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

#Const kMiter_Join 0
    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, 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, decreasing Reference_Count of the previous Shader.
    Increments shader Reference_Count by one.

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

    #Example
    #Height 64
        void draw(SkCanvas* canvas) {
            SkPaint paint;
            paint.setColor(SK_ColorBLUE);
            paint.setShader(SkShader::MakeColorShader(SK_ColorRED));
            canvas->drawRect(SkRect::MakeWH(40, 40), paint);
            paint.setShader(nullptr);
            canvas->translate(50, 0);
            canvas->drawRect(SkRect::MakeWH(40, 40), paint);
        }
    ##

##

#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, decreasing Reference_Count of the previous
Color_Filter. Pass nullptr to clear Color_Filter.

Increments filter Reference_Count by one.

    #Param colorFilter  Color_Filter to apply to subsequent draw ##

    #Example
    #Height 64
        void draw(SkCanvas* canvas) {
           SkPaint paint;
           paint.setColorFilter(SkColorFilter::MakeModeFilter(SK_ColorLTGRAY, SkBlendMode::kSrcIn));
           canvas->drawRect(SkRect::MakeWH(50, 50), paint);
           paint.setColorFilter(nullptr);
           canvas->translate(70, 0);
           canvas->drawRect(SkRect::MakeWH(50, 50), paint);
        }
    ##

##

#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, 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, decreasing Reference_Count of the previous
Path_Effect. Pass nullptr to leave the path geometry unaltered.

Increments pathEffect Reference_Count by one.

    #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 coverage of the shape drawn to create Mask_Alpha.
Mask_Filter operates at a lower level than Rasterizer; Mask_Filter takes a Mask,
and returns a Mask.

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

#Example
    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, decreasing Reference_Count of the previous
Mask_Filter. Pass nullptr to clear Mask_Filter and leave Mask_Filter effect on
Mask_Alpha unaltered.

Does not affect Rasterizer.
Increments maskFilter Reference_Count by one.

    #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.
    Increments Typeface Reference_Count by one.
    
    #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, decreasing Reference_Count of the previous Typeface. 
Pass nullptr to clear Typeface and use the default typeface. Increments
typeface Reference_Count by one.

    #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, Arcs, Circles, Ovals,
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, decreasing Reference_Count of the previous
Rasterizer. Pass nullptr to clear Rasterizer and leave Rasterizer effect on
Mask_Alpha unaltered.

Does not affect Mask_Filter.
Increments rasterizer Reference_Count by one.

    #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 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, decreasing Reference_Count of the previous
Image_Filter. Pass nullptr to clear Image_Filter, and remove Image_Filter effect
on drawing.

Does not affect Rasterizer or Mask_Filter.
Increments imageFilter Reference_Count by one.

    #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, decreasing Reference_Count of the previous
drawLooper.  Pass nullptr to clear Draw_Looper and leave Draw_Looper effect on
drawing unaltered.

Increments drawLooper Reference_Count by one.

    #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 encodings 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 ##
 encodes each character as one or more 8-bit bytes.

#A UTF-16 (RFC 2781) # https://tools.ietf.org/html/rfc2781 ##
 encodes each character as one or two 16-bit words.

#A UTF-32 # http://www.unicode.org/versions/Unicode5.0.0/ch03.pdf ##
 encodes each character as one 32-bit word.

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

TextEncoding is set to kUTF8_TextEncoding by default.

#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 
    #Param ##

    #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

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

    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.

#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;
    };
##

    #Enum FontMetricsFlags

    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.

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

        #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 the underline thickness is not valid,
        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 the underline position is not valid,
        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 the underline thickness is not valid,
        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 the underline position is not valid,
        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.
    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. Includes Text_Size, Text_Scale_X,
and Text_Skew_X, but not Fake_Bold or Path_Effect.

If Text_Size is large, Text_Scale_X is one, and Text_Skew_X is zero,
returns the same bounds as Font_Metrics { FontMetrics::fXMin, 
FontMetrics::fTop, FontMetrics::fXMax, FontMetrics::fBottom }.

#Return  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, 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 storage 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 storage 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,
    returns true if all glyph indices in text are non-zero;
    does not check to see if text contains valid glyph indices for Typeface.

    Returns true if byteLength is zero.

    #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 = nullptr) const

    Returns the bytes of text that fit within maxWidth.
    If kVerticalText_Flag is clear, the text fragment fits if its advance width is less than or
    equal to maxWidth.
    If kVerticalText_Flag is set, the text fragment fits if its advance height is less than or
    equal to maxWidth.
    Measures only while the advance is less than or equal to maxWidth.
    Returns the advance or the text fragment in measuredWidth if it not nullptr.
    Uses Text_Encoding to decode text, Typeface to get the font metrics,
    and Text_Size to scale the metrics.
    Does not scale the advance or bounds by Fake_Bold or Path_Effect.

    #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[] = nullptr) const

    Retrieves the advance and bounds for each glyph in text, and returns
    the glyph count in text.
    Both widths and bounds may be nullptr.
    If widths is not nullptr, widths must be an array of glyph count entries.
    if bounds is not nullptr, bounds must be an array of glyph count entries. 
    If kVerticalText_Flag is clear, widths returns the horizontal advance.
    If kVerticalText_Flag is set, widths returns the vertical advance.
    Uses Text_Encoding to decode text, Typeface to get the font metrics,
    and Text_Size to scale the widths and bounds.
    Does not scale the advance by Fake_Bold or Path_Effect.
    Does include Fake_Bold and Path_Effect in the bounds.
   
    #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.
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              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 run 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;
    otherwise, the Paint may or may not allow drawing.

    Returns true if, for example, Blend_Mode combined with Color_Alpha computes a
    new Alpha of zero.

    #Return  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
    parameter. It returns the adjusted bounds that can then be used
    for SkCanvas::quickReject tests.

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

    #Private  
    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)
    ##

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

    #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;
##

Creates string representation of Paint. The representation is read by
internal debugging tools. The interface and implementation may be
suppressed by defining SK_IGNORE_TO_STRING.

#Param str  storage for string representation of 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 ##