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