Update doc and example for SkPaint::FontMetrics.
The underline position is actually the top of the underline. Also
clarify that the strike through position is the bottom of the strike
through.
This adds documentation that the values are always y-down in a way that
will end up in the SkPaint header file for those who look for
information there.
Change-Id: I40281c0e47557d23291b6a91474e2d3e3b37f09f
Docs-Preview: https://skia.org/user/api/SkPaint_Reference?cl=69361#FontMetrics
Reviewed-on: https://skia-review.googlesource.com/69361
Reviewed-by: Cary Clark <caryclark@google.com>
Commit-Queue: Ben Wagner <bungeman@google.com>
diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh
index 075fa78..e9f568d 100644
--- a/docs/SkPaint_Reference.bmh
+++ b/docs/SkPaint_Reference.bmh
@@ -4132,7 +4132,7 @@
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) {
@@ -4156,10 +4156,9 @@
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);
+ canvas->drawLine(pt.fX + 25, upos, pt.fX + 160, upos, paint);
+ SkScalar ut = fm.fUnderlineThickness;
+ canvas->drawLine(pt.fX + 130, upos + ut, pt.fX + 160, upos + ut, 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);
@@ -4216,9 +4215,13 @@
computed by Font_Manager using Typeface. Values are set to zero if they are
not available.
+ All vertical values relative to the baseline are given y-down. As such, zero is on the
+ baseline, negative values are above the baseline, and positive values are below the
+ baseline.
+
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.
@@ -4255,96 +4258,94 @@
#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.
+ Greatest extent above the baseline for any glyph.
+ Typically less than 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.
+ Typically less than 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.
+ Typically greater than 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.
+ Greatest extent below the baseline for any glyph.
+ Typically greater than zero.
##
-
+
#Member SkScalar fLeading
Recommended distance to add between lines of text.
- Greater than or equal to zero.
+ Typically 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.
+ 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.
+ 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.
+ Position of the top of the underline stroke relative to the baseline.
+ Typically positive when valid.
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.
+ 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.
+ Position of the bottom of the strikeout stroke relative to the baseline.
+ Typically negative when valid.
- If the metric is valid, the kStrikeoutPositionIsValid_Flag is set in fFlags.
- If kStrikeoutPositionIsValid_Flag is clear, fStrikeoutPosition is zero.
+ 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
+ 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.
@@ -4358,7 +4359,7 @@
#Method bool hasUnderlinePosition(SkScalar* position) const
- If Font_Metrics has a valid underline position, return true, and set
+ 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.
@@ -4372,7 +4373,7 @@
#Method bool hasStrikeoutThickness(SkScalar* thickness) const
- If Font_Metrics has a valid strikeout thickness, return true, and set
+ 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.
@@ -4386,7 +4387,7 @@
#Method bool hasStrikeoutPosition(SkScalar* position) const
- If Font_Metrics has a valid strikeout position, return true, and set
+ 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.
diff --git a/include/core/SkPaint.h b/include/core/SkPaint.h
index 83d5502..adc15fd 100644
--- a/include/core/SkPaint.h
+++ b/include/core/SkPaint.h
@@ -1110,6 +1110,10 @@
computed by font manager using SkTypeface. Values are set to zero if they are
not available.
+ All vertical values relative to the baseline are given y-down. As such, zero is on the
+ baseline, negative values are above the baseline, and positive values are below the
+ baseline.
+
fUnderlineThickness and fUnderlinePosition have a bit set in fFlags if their values
are valid, since their value may be zero.
@@ -1132,28 +1136,28 @@
uint32_t fFlags; //!< fFlags is set when underline metrics are valid.
- /** Largest height for any glyph.
- A measure from the baseline, and is less than or equal to zero.
+ /** Greatest extent above the baseline for any glyph.
+ Typically less than zero.
*/
SkScalar fTop;
/** 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.
+ Typically less than zero.
*/
SkScalar fAscent;
/** 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.
+ Typically greater than zero.
*/
SkScalar fDescent;
/** Greatest extent below the baseline for any glyph.
- A measure from the baseline, and is greater than or equal to zero.
+ Typically greater than zero.
*/
SkScalar fBottom;
/** Recommended distance to add between lines of text.
- Greater than or equal to zero.
+ Typically greater than or equal to zero.
*/
SkScalar fLeading;
@@ -1184,32 +1188,30 @@
*/
SkScalar fCapHeight;
- /** Underline thickness. If the metric
- is valid, the kUnderlineThicknessIsValid_Flag is set in fFlags.
+ /** Underline thickness.
+
+ If the metric is valid, the kUnderlineThicknessIsValid_Flag is set in fFlags.
If kUnderlineThicknessIsValid_Flag is clear, fUnderlineThickness is zero.
*/
SkScalar fUnderlineThickness;
- /** 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.
+ /** Position of the top of the underline stroke relative to the baseline.
+ Typically positive when valid.
If the metric is valid, the kUnderlinePositionIsValid_Flag is set in fFlags.
If kUnderlinePositionIsValid_Flag is clear, fUnderlinePosition is zero.
*/
SkScalar fUnderlinePosition;
- /** Strikeout thickness. If the metric
- is valid, the kStrikeoutThicknessIsValid_Flag is set in fFlags.
+ /** Strikeout thickness.
+
+ If the metric is valid, the kStrikeoutThicknessIsValid_Flag is set in fFlags.
If kStrikeoutThicknessIsValid_Flag is clear, fStrikeoutThickness is zero.
*/
SkScalar fStrikeoutThickness;
- /** 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.
+ /** Position of the bottom of the strikeout stroke relative to the baseline.
+ Typically negative when valid.
If the metric is valid, the kStrikeoutPositionIsValid_Flag is set in fFlags.
If kStrikeoutPositionIsValid_Flag is clear, fStrikeoutPosition is zero.
diff --git a/site/user/api/SkPaint_Reference.md b/site/user/api/SkPaint_Reference.md
index acd01b9..c3c4063 100644
--- a/site/user/api/SkPaint_Reference.md
+++ b/site/user/api/SkPaint_Reference.md
@@ -4080,7 +4080,7 @@
### Example
-<div><fiddle-embed name="b5b76e0a15da0c3530071186a9006498"></fiddle-embed></div>
+<div><fiddle-embed name="2bfa3783719fcd769af177a1b244e171"></fiddle-embed></div>
# <a name="SkPaint_FontMetrics"></a> Struct SkPaint::FontMetrics
@@ -4120,8 +4120,13 @@
computed by <a href="undocumented#Font_Manager">Font Manager</a> using <a href="undocumented#Typeface">Typeface</a>. Values are set to zero if they are
not available.
+All vertical values relative to the baseline are given y-down. As such, zero is on the
+baseline, negative values are above the baseline, and positive values are below the
+baseline.
+
<a href="#SkPaint_FontMetrics_fUnderlineThickness">fUnderlineThickness</a> and <a href="#SkPaint_FontMetrics_fUnderlinePosition">fUnderlinePosition</a> have a bit set in <a href="#SkPaint_FontMetrics_fFlags">fFlags</a> if their values
are valid, since their value may be zero.
+
<a href="#SkPaint_FontMetrics_fStrikeoutThickness">fStrikeoutThickness</a> and <a href="#SkPaint_FontMetrics_fStrikeoutPosition">fStrikeoutPosition</a> have a bit set in <a href="#SkPaint_FontMetrics_fFlags">fFlags</a> if their values
are valid, since their value may be zero.
@@ -4163,28 +4168,28 @@
<a name="SkPaint_FontMetrics_fTop"> <code><strong>SkScalar fTop</strong></code> </a>
-Largest height for any glyph.
-A measure from the baseline, and is less than or equal to zero.
+Greatest extent above the baseline for any glyph.
+Typically less than zero.
<a name="SkPaint_FontMetrics_fAscent"> <code><strong>SkScalar fAscent</strong></code> </a>
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.
+Typically less than zero.
<a name="SkPaint_FontMetrics_fDescent"> <code><strong>SkScalar fDescent</strong></code> </a>
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.
+Typically greater than zero.
<a name="SkPaint_FontMetrics_fBottom"> <code><strong>SkScalar fBottom</strong></code> </a>
-Greatest extent below the baseline for any glyph.
-A measure from the baseline, and is greater than or equal to zero.
+Greatest extent below the baseline for any glyph.
+Typically greater than zero.
<a name="SkPaint_FontMetrics_fLeading"> <code><strong>SkScalar fLeading</strong></code> </a>
Recommended distance to add between lines of text.
-Greater than or equal to zero.
+Typically greater than or equal to zero.
<a name="SkPaint_FontMetrics_fAvgCharWidth"> <code><strong>SkScalar fAvgCharWidth</strong></code> </a>
@@ -4197,7 +4202,7 @@
<a name="SkPaint_FontMetrics_fXMin"> <code><strong>SkScalar fXMin</strong></code> </a>
-Minimum bounding box x value for all <a href="#Glyph">Glyphs</a>.
+Minimum bounding box x value for all <a href="#Glyph">Glyphs</a>.
Typically less than zero.
<a name="SkPaint_FontMetrics_fXMax"> <code><strong>SkScalar fXMax</strong></code> </a>
@@ -4217,32 +4222,30 @@
<a name="SkPaint_FontMetrics_fUnderlineThickness"> <code><strong>SkScalar fUnderlineThickness</strong></code> </a>
-Underline thickness. If the metric
-is valid, the <a href="#SkPaint_FontMetrics_kUnderlineThicknessIsValid_Flag">kUnderlineThicknessIsValid Flag</a> is set in <a href="#SkPaint_FontMetrics_fFlags">fFlags</a>.
+Underline thickness.
+
+If the metric is valid, the <a href="#SkPaint_FontMetrics_kUnderlineThicknessIsValid_Flag">kUnderlineThicknessIsValid Flag</a> is set in <a href="#SkPaint_FontMetrics_fFlags">fFlags</a>.
If <a href="#SkPaint_FontMetrics_kUnderlineThicknessIsValid_Flag">kUnderlineThicknessIsValid Flag</a> is clear, <a href="#SkPaint_FontMetrics_fUnderlineThickness">fUnderlineThickness</a> is zero.
<a name="SkPaint_FontMetrics_fUnderlinePosition"> <code><strong>SkScalar fUnderlinePosition</strong></code> </a>
-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.
+Position of the top of the underline stroke relative to the baseline.
+Typically positive when valid.
If the metric is valid, the <a href="#SkPaint_FontMetrics_kUnderlinePositionIsValid_Flag">kUnderlinePositionIsValid Flag</a> is set in <a href="#SkPaint_FontMetrics_fFlags">fFlags</a>.
If <a href="#SkPaint_FontMetrics_kUnderlinePositionIsValid_Flag">kUnderlinePositionIsValid Flag</a> is clear, <a href="#SkPaint_FontMetrics_fUnderlinePosition">fUnderlinePosition</a> is zero.
<a name="SkPaint_FontMetrics_fStrikeoutThickness"> <code><strong>SkScalar fStrikeoutThickness</strong></code> </a>
-Strikeout thickness. If the metric
-is valid, the <a href="#SkPaint_FontMetrics_kStrikeoutThicknessIsValid_Flag">kStrikeoutThicknessIsValid Flag</a> is set in <a href="#SkPaint_FontMetrics_fFlags">fFlags</a>.
+Strikeout thickness.
+
+If the metric is valid, the <a href="#SkPaint_FontMetrics_kStrikeoutThicknessIsValid_Flag">kStrikeoutThicknessIsValid Flag</a> is set in <a href="#SkPaint_FontMetrics_fFlags">fFlags</a>.
If <a href="#SkPaint_FontMetrics_kStrikeoutThicknessIsValid_Flag">kStrikeoutThicknessIsValid Flag</a> is clear, <a href="#SkPaint_FontMetrics_fStrikeoutThickness">fStrikeoutThickness</a> is zero.
<a name="SkPaint_FontMetrics_fStrikeoutPosition"> <code><strong>SkScalar fStrikeoutPosition</strong></code> </a>
-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.
+Position of the bottom of the strikeout stroke relative to the baseline.
+Typically negative when valid.
If the metric is valid, the <a href="#SkPaint_FontMetrics_kStrikeoutPositionIsValid_Flag">kStrikeoutPositionIsValid Flag</a> is set in <a href="#SkPaint_FontMetrics_fFlags">fFlags</a>.
If <a href="#SkPaint_FontMetrics_kStrikeoutPositionIsValid_Flag">kStrikeoutPositionIsValid Flag</a> is clear, <a href="#SkPaint_FontMetrics_fStrikeoutPosition">fStrikeoutPosition</a> is zero.
@@ -4254,7 +4257,7 @@
bool hasUnderlineThickness(SkScalar* thickness) const
</pre>
-If <a href="#Font_Metrics">Font Metrics</a> has a valid underline <a href="#SkPaint_FontMetrics_hasUnderlineThickness_thickness">thickness</a>, return true, and set
+If <a href="#Font_Metrics">Font Metrics</a> has a valid underline <a href="#SkPaint_FontMetrics_hasUnderlineThickness_thickness">thickness</a>, return true, and set
<a href="#SkPaint_FontMetrics_hasUnderlineThickness_thickness">thickness</a> to that value. If the underline <a href="#SkPaint_FontMetrics_hasUnderlineThickness_thickness">thickness</a> is not valid,
return false, and ignore <a href="#SkPaint_FontMetrics_hasUnderlineThickness_thickness">thickness</a>.
@@ -4278,7 +4281,7 @@
bool hasUnderlinePosition(SkScalar* position) const
</pre>
-If <a href="#Font_Metrics">Font Metrics</a> has a valid underline <a href="#SkPaint_FontMetrics_hasUnderlinePosition_position">position</a>, return true, and set
+If <a href="#Font_Metrics">Font Metrics</a> has a valid underline <a href="#SkPaint_FontMetrics_hasUnderlinePosition_position">position</a>, return true, and set
<a href="#SkPaint_FontMetrics_hasUnderlinePosition_position">position</a> to that value. If the underline <a href="#SkPaint_FontMetrics_hasUnderlinePosition_position">position</a> is not valid,
return false, and ignore <a href="#SkPaint_FontMetrics_hasUnderlinePosition_position">position</a>.
@@ -4302,7 +4305,7 @@
bool hasStrikeoutThickness(SkScalar* thickness) const
</pre>
-If <a href="#Font_Metrics">Font Metrics</a> has a valid strikeout <a href="#SkPaint_FontMetrics_hasStrikeoutThickness_thickness">thickness</a>, return true, and set
+If <a href="#Font_Metrics">Font Metrics</a> has a valid strikeout <a href="#SkPaint_FontMetrics_hasStrikeoutThickness_thickness">thickness</a>, return true, and set
<a href="#SkPaint_FontMetrics_hasStrikeoutThickness_thickness">thickness</a> to that value. If the underline <a href="#SkPaint_FontMetrics_hasStrikeoutThickness_thickness">thickness</a> is not valid,
return false, and ignore <a href="#SkPaint_FontMetrics_hasStrikeoutThickness_thickness">thickness</a>.
@@ -4326,7 +4329,7 @@
bool hasStrikeoutPosition(SkScalar* position) const
</pre>
-If <a href="#Font_Metrics">Font Metrics</a> has a valid strikeout <a href="#SkPaint_FontMetrics_hasStrikeoutPosition_position">position</a>, return true, and set
+If <a href="#Font_Metrics">Font Metrics</a> has a valid strikeout <a href="#SkPaint_FontMetrics_hasStrikeoutPosition_position">position</a>, return true, and set
<a href="#SkPaint_FontMetrics_hasStrikeoutPosition_position">position</a> to that value. If the underline <a href="#SkPaint_FontMetrics_hasStrikeoutPosition_position">position</a> is not valid,
return false, and ignore <a href="#SkPaint_FontMetrics_hasStrikeoutPosition_position">position</a>.