From 682c58da482155213e8cd2834b57bc6541e510a0 Mon Sep 17 00:00:00 2001 From: Cary Clark Date: Wed, 16 May 2018 07:07:07 -0400 Subject: Documentation refresh - add links to types within methods - add check to see that all references and definitions match - add style to tables to make them easier to read - use https everywhere - remove trailing spaces - move overview inside class - split class and struct in summary tables - add missing #Line - clean up SkImageInfo constant documentation - work on SkColor documentation - allow common phrases to take different parameters - add more flexibility to generated tables - tighten token parent requirements - generalize deprecated and example interfaces - detect inner constructors R=caryclark@google.com Docs-Preview: https://skia.org/?cl=121799 Bug: skia:6898 Change-Id: Ia75a23740b80259460916890b310e2a9f024962a Reviewed-on: https://skia-review.googlesource.com/121799 Commit-Queue: Cary Clark Auto-Submit: Cary Clark Reviewed-by: Cary Clark --- docs/SkPaint_Reference.bmh | 144 ++++++++++++++++++++++++++------------------- 1 file changed, 83 insertions(+), 61 deletions(-) (limited to 'docs/SkPaint_Reference.bmh') diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh index e07999a434..6fdf2a0e89 100644 --- a/docs/SkPaint_Reference.bmh +++ b/docs/SkPaint_Reference.bmh @@ -1,12 +1,6 @@ #Topic Paint #Alias Paint_Reference -#Subtopic Overview - #Subtopic Subtopic - #Populate - ## -## - #Class SkPaint Paint controls options applied when drawing and measuring. Paint collects all @@ -35,6 +29,10 @@ Paint describes a single color, a single font, a single image quality, and so on Multiple colors are drawn either by using multiple paints or with objects like Shader attached to Paint. +#Subtopic Overview +#Populate +## + #Subtopic Related_Function #Populate ## @@ -43,7 +41,7 @@ Shader attached to Paint. #Populate ## -#Subtopic Class_or_Struct +#Subtopic Struct #Populate ## @@ -419,6 +417,7 @@ The four levels roughly control corresponding features on platforms that use Fre as the Font_Engine. #Const kNo_Hinting 0 +#Line # glyph outlines unchanged ## Leaves glyph outlines unchanged from their native representation. With FreeType, this is equivalent to the FT_LOAD_NO_HINTING bit-field constant supplied to FT_Load_Glyph, which indicates that the vector @@ -426,6 +425,7 @@ as the Font_Engine. to 26.6 fractional pixels. ## #Const kSlight_Hinting 1 +#Line # minimal modification to improve constrast ## Modifies glyph outlines minimally to improve constrast. With FreeType, this is equivalent in spirit to the FT_LOAD_TARGET_LIGHT value supplied to FT_Load_Glyph. It chooses a @@ -433,12 +433,14 @@ as the Font_Engine. Generated Glyphs may be fuzzy but better resemble their original shape. ## #Const kNormal_Hinting 2 +#Line # glyph outlines modified to improve constrast ## Modifies glyph outlines to improve constrast. This is the default. With FreeType, this supplies FT_LOAD_TARGET_NORMAL to FT_Load_Glyph, choosing the default hinting algorithm, which is optimized for standard gray-level rendering. ## #Const kFull_Hinting 3 +#Line # modifies glyph outlines for maxiumum constrast ## 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 @@ -446,15 +448,11 @@ as the Font_Engine. 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. @@ -548,34 +546,34 @@ All flags can be read and written explicitly; Flags allows manipulating multiple settings at once. #Const kAntiAlias_Flag 0x0001 - mask for setting Anti-alias + #Line # mask for setting Anti-alias ## ## #Const kDither_Flag 0x0004 - mask for setting Dither + #Line # mask for setting Dither ## ## - #Const kFakeBoldText_Flag 0x0020 - mask for setting Fake_Bold + #Line # mask for setting Fake_Bold ## ## #Const kLinearText_Flag 0x0040 - mask for setting Linear_Text + #Line # mask for setting Linear_Text ## ## #Const kSubpixelText_Flag 0x0080 - mask for setting Subpixel_Text + #Line # mask for setting Subpixel_Text ## ## #Const kLCDRenderText_Flag 0x0200 - mask for setting LCD_Text + #Line # mask for setting LCD_Text ## ## #Const kEmbeddedBitmapText_Flag 0x0400 - mask for setting Font_Embedded_Bitmaps + #Line # mask for setting Font_Embedded_Bitmaps ## ## #Const kAutoHinting_Flag 0x0800 - mask for setting Automatic_Hinting + #Line # mask for setting Automatic_Hinting ## ## #Const kVerticalText_Flag 0x1000 - mask for setting Vertical_Text + #Line # mask for setting Vertical_Text ## ## #Const kAllFlags 0xFFFF + #Line # mask of all Flags ## mask of all Flags, including private flags and flags reserved for future use ## @@ -652,6 +650,8 @@ All Flags members may be cleared, or one or more may be set. # ------------------------------------------------------------------------------ #Subtopic Anti-alias #Alias Anti-alias # permit hyphen in topic name, should probably not substitute hyphen with _ +#Alias Anti-aliased +#Alias Anti-aliasing #In Related_Function #Line # approximating coverage with transparency ## @@ -1342,7 +1342,7 @@ Skia can translate text character codes as a series of Glyphs, but does not impl font substitution, textual substitution, line layout, or contextual spacing like Kerning pairs. Use a text shaping engine like -#A HarfBuzz # http://harfbuzz.org/ ## +#A HarfBuzz # https://harfbuzz.org/ ## to translate text runs into glyph series. @@ -1868,7 +1868,7 @@ Use kStrokeAndFill_Style to avoid hitting the same pixels twice with a stroke dr a fill draw. #Const kFill_Style 0 - Set to fill geometry. +#Line # set to fill geometry ## Applies to Rect, Region, Round_Rect, Circles, Ovals, Path, and Text. Bitmap, Image, Patches, Region, Sprites, and Vertices are painted as if kFill_Style is set, and ignore the set Style. @@ -1878,7 +1878,7 @@ a fill draw. ## #Const kStroke_Style 1 - Set to stroke geometry. +#Line # set to stroke geometry ## Applies to Rect, Region, Round_Rect, Arcs, Circles, Ovals, Path, and Text. Arcs, Lines, and points, are always drawn as if kStroke_Style is set, and ignore the set Style. @@ -1886,14 +1886,14 @@ a fill draw. ## #Const kStrokeAndFill_Style 2 - Set to stroke and fill geometry. +#Line # sets to stroke and fill geometry ## Applies to Rect, Region, Round_Rect, Circles, Ovals, Path, and Text. Path is treated as if it is set to SkPath::kWinding_FillType, and the set Path_Fill_Type is ignored. ## #Const kStyleCount 3 -The number of different Style values defined. +#Line # number of different Style values defined ## May be used to verify that Style is a legal value. ## @@ -2200,27 +2200,31 @@ Here are some miter limits and the angles that triggers them. Stroke_Cap draws at the beginning and end of an open Path_Contour. #Const kButt_Cap 0 + #Line # no stroke extension ## Does not extend the stroke past the beginning or the end. ## #Const kRound_Cap 1 + #Line # adds circle ## Adds a circle with a diameter equal to Stroke_Width at the beginning and end. ## #Const kSquare_Cap 2 + #Line # adds square ## Adds a square with sides equal to Stroke_Width at the beginning and end. The square sides are parallel to the initial and final direction of the stroke. ## #Const kLast_Cap 2 + #Line # largest Stroke_Cap value ## Equivalent to the largest value for Stroke_Cap. ## #Const kDefault_Cap 0 - Equivalent to kButt_Cap. + #Line # equivalent to kButt_Cap ## Stroke_Cap is set to kButt_Cap by default. ## #Const kCapCount 3 - The number of different Stroke_Cap values defined. + #Line # number of different Stroke_Cap values defined ## May be used to verify that Stroke_Cap is a legal value. ## #Enum ## @@ -2362,29 +2366,32 @@ not contain the actual join. For instance, a fill path constructed with round jo not necessarily include circles at each connected segment. #Const kMiter_Join 0 +#Line # extends to Miter_Limit ## Extends the outside corner to the extent allowed by Miter_Limit. If the extension exceeds Miter_Limit, kBevel_Join is used instead. ## #Const kRound_Join 1 +#Line # adds circle ## Adds a circle with a diameter of Stroke_Width at the sharp corner. ## #Const kBevel_Join 2 +#Line # connects outside edges ## Connects the outside edges of the sharp corner. ## #Const kLast_Join 2 - Equivalent to the largest value for Stroke_Join. +#Line # equivalent to the largest value for Stroke_Join ## ## #Const kDefault_Join 1 - Equivalent to kMiter_Join. +#Line # equivalent to kMiter_Join ## Stroke_Join is set to kMiter_Join by default. ## #Const kJoinCount 3 - The number of different Stroke_Join values defined. +#Line # number of different Stroke_Join values defined ## May be used to verify that Stroke_Join is a legal value. ## @@ -3466,21 +3473,24 @@ using the metrics returned by the font. Align defaults to kLeft_Align. #Const kLeft_Align 0 +#Line # positions glyph by computed font offset ## Leaves the glyph at the position computed by the font offset by the text position. ## #Const kCenter_Align 1 +#Line # centers line of glyphs by its width or height ## 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 +#Line # moves lines of glyphs by its width or height ## Moves the glyph by its width if Flags has kVerticalText_Flag clear, and by its height if Flags has kVerticalText_Flag set. ## #Const kAlignCount 3 - The number of different Text_Align values defined. +#Line # number of different Text_Align values defined ## ## #Enum ## @@ -3765,7 +3775,7 @@ Text_Skew_X defaults to 0. TextEncoding determines whether text specifies character codes and their encoded size, or glyph indices. Characters are encoded as specified by the -#A Unicode standard # http://unicode.org/standard/standard.html ## +#A Unicode standard # https://unicode.org/standard/standard.html ## . Character codes encoded size are specified by UTF-8, UTF-16, or UTF-32. @@ -3778,7 +3788,7 @@ in the total storage required. #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 ## +#A UTF-32 # https://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. @@ -3787,16 +3797,16 @@ 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. +#Line # uses bytes to represent UTF-8 or ASCII ## ## #Const kUTF16_TextEncoding 1 -Uses two byte words to represent most of Unicode. +#Line # uses two byte words to represent most of Unicode ## ## #Const kUTF32_TextEncoding 2 -Uses four byte words to represent all of Unicode. +#Line # uses four byte words to represent all of Unicode ## ## #Const kGlyphID_TextEncoding 3 -Uses two byte words to represent glyph indices. +#Line # uses two byte words to represent glyph indices ## ## #Enum ## @@ -3807,7 +3817,7 @@ Uses two byte words to represent glyph indices. First line is encoded in UTF-8. Second line is encoded in UTF-16. Third line is encoded in UTF-32. -Fourth line has 16 bit glyph indices. +Fourth line has 16-bit glyph indices. ## void draw(SkCanvas* canvas) { SkPaint paint; @@ -3987,7 +3997,7 @@ void draw(SkCanvas* canvas) { are valid, since their value may be zero. #Enum FontMetricsFlags -#Line # valid Font_Metrics ## + #Line # valid Font_Metrics ## #Code enum FontMetricsFlags { @@ -4003,86 +4013,94 @@ void draw(SkCanvas* canvas) { Fonts with embedded bitmaps may not have valid underline or strikeout metrics. #Const kUnderlineThicknessIsValid_Flag 0x0001 - Set if fUnderlineThickness is valid. + #Line # set if fUnderlineThickness is valid ## ## #Const kUnderlinePositionIsValid_Flag 0x0002 - Set if fUnderlinePosition is valid. + #Line # set if fUnderlinePosition is valid ## ## #Const kStrikeoutThicknessIsValid_Flag 0x0004 - Set if fStrikeoutThickness is valid. + #Line # set if fStrikeoutThickness is valid ## ## #Const kStrikeoutPositionIsValid_Flag 0x0008 - Set if fStrikeoutPosition is valid. + #Line # set if fStrikeoutPosition is valid ## ## #Enum ## #Member uint32_t fFlags - fFlags is set when underline metrics are valid. + #Line # is set to FontMetricsFlags when metrics are valid ## ## #Member SkScalar fTop + #Line # extent above baseline ## Greatest extent above the baseline for any glyph. Typically less than zero. ## #Member SkScalar fAscent + #Line # distance to reserve above baseline ## Recommended distance above the baseline to reserve for a line of text. Typically less than zero. ## #Member SkScalar fDescent + #Line # distance to reserve below baseline ## Recommended distance below the baseline to reserve for a line of text. Typically greater than zero. ## #Member SkScalar fBottom + #Line # extent below baseline ## Greatest extent below the baseline for any glyph. Typically greater than zero. ## #Member SkScalar fLeading + #Line # distance to add between lines ## Recommended distance to add between lines of text. Typically greater than or equal to zero. ## #Member SkScalar fAvgCharWidth + #Line # average character width ## Average character width, if it is available. Zero if no average width is stored in the font. ## #Member SkScalar fMaxCharWidth - Maximum character width. + #Line # maximum character width ## ## #Member SkScalar fXMin - Minimum bounding box x value for all Glyphs. + #Line # minimum x ## + Minimum bounding box x-value for all Glyphs. Typically less than zero. ## #Member SkScalar fXMax + #Line # maximum x ## Maximum bounding box x value for all Glyphs. Typically greater than zero. ## #Member SkScalar fXHeight - Height of a lower-case 'x'. + #Line # height of 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. + #Line # height of an upper-case letter ## May be zero if no upper-case height is stored in the font. ## #Member SkScalar fUnderlineThickness - Underline thickness. - + #Line # 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 + #Line # underline position relative to baseline ## Position of the top of the underline stroke relative to the baseline. Typically positive when valid. @@ -4091,13 +4109,14 @@ void draw(SkCanvas* canvas) { ## #Member SkScalar fStrikeoutThickness - Strikeout thickness. + #Line # 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 + #Line # strikeout position relative to baseline ## Position of the bottom of the strikeout stroke relative to the baseline. Typically negative when valid. @@ -4106,6 +4125,7 @@ void draw(SkCanvas* canvas) { ## #Method bool hasUnderlineThickness(SkScalar* thickness) const + #Line # returns underline thickness if set ## If Font_Metrics has a valid underline thickness, return true, and set thickness to that value. If the underline thickness is not valid, @@ -4120,6 +4140,7 @@ void draw(SkCanvas* canvas) { ## #Method bool hasUnderlinePosition(SkScalar* position) const + #Line # returns underline position if set ## If Font_Metrics has a valid underline position, return true, and set position to that value. If the underline position is not valid, @@ -4134,6 +4155,7 @@ void draw(SkCanvas* canvas) { ## #Method bool hasStrikeoutThickness(SkScalar* thickness) const + #Line # returns strikeout thickness if set ## If Font_Metrics has a valid strikeout thickness, return true, and set thickness to that value. If the underline thickness is not valid, @@ -4148,6 +4170,7 @@ void draw(SkCanvas* canvas) { ## #Method bool hasStrikeoutPosition(SkScalar* position) const + #Line # returns strikeout position if set ## If Font_Metrics has a valid strikeout position, return true, and set position to that value. If the underline position is not valid, @@ -4985,7 +5008,7 @@ void draw(SkCanvas* canvas) { To be made private. ## -Fast_Bounds methods conservatively outset a drawing bounds by additional area +Fast_Bounds functions conservatively outset a drawing bounds by additional area Paint may draw to. #Method bool canComputeFastBounds() const @@ -5023,15 +5046,14 @@ Paint may draw to. 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 - } + For example: + if (!path.isInverseFillType() && paint.canComputeFastBounds()) { + SkRect storage; + if (canvas->quickReject(paint.computeFastBounds(path.getBounds(), &storage))) { + return; // don't draw the path + } } + // draw the path ## #Param orig geometry modified by Paint when drawn ## -- cgit v1.2.3