Change-Id: I4b6259590fa0693ee0522b4999a1c0fe250b173d Reviewed-on: https://skia-review.googlesource.com/c/skia/+/212504 Reviewed-by: Mike Reed <reed@google.com> Commit-Queue: Ben Wagner <bungeman@google.com>
54 KiB
SkFont Reference
class SkFont { // SkFont interface };
Font_Size adjusts the overall text size in points. Font_Size can be set to any positive value or zero. Font_Size defaults to 12. Font_Size
Font_Scale_X adjusts the text horizontal scale. Text scaling approximates condensed and expanded type faces when the actual face is not available. Font_Scale_X can be set to any value. Font_Scale_X defaults to 1.
Font_Skew_X adjusts the text horizontal slant. Text skewing approximates italic and oblique type faces when the actual face is not available. Font_Skew_X can be set to any value. Font_Skew_X defaults to 0.
Font_Embolden 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 Font_Manager.
Use Font_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 SkPaint::Style to SkPaint::kStrokeAndFill_Style as needed.
Font_Embolden is disabled by default.
If Hinting is set to SkFontHinting::kFull, Hinting_Spacing adjusts the character spacing by the difference of the hinted and unhinted Left_Side_Bearing and Right_Side_Bearing. Hinting_Spacing only applies to platforms that use FreeType as their Font_Engine.
Hinting_Spacing is not related to text kerning, where the space between a specific pair of characters is adjusted using data in the font kerning tables.
Font_Linear selects whether text is rendered as a Glyph or as a Path. If Font_Linear is set, it has the same effect as setting Hinting to SkFontHinting::kNormal. If Font_Linear is clear, it is the same as setting Hinting to SkFontHinting::kNone.
Font_Subpixel 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.
When set, Anti_Alias positions glyphs within a pixel, using alpha and possibly RGB striping. It can take advantage of the organization of RGB stripes that create a color, and relies on the small size of the stripe and visual perception to make the color fringing imperceptible.
Anti_Alias can be enabled on devices that orient stripes horizontally or vertically, and that order the color components as RGB or BGR. Internally, the glyph cache may store multiple copies of the same glyph with different sub-pixel positions, requiring more memory.
If Hinting is set to SkFontHinting::kNormal or SkFontHinting::kFull, Force_Hinting instructs the Font_Manager to always hint Glyphs. Force_Hinting has no effect if Hinting is set to SkFontHinting::kNone or SkFontHinting::kSlight.
Force_Hinting only affects platforms that use FreeType as the Font_Manager.
Embedded_Bitmaps allows selecting custom sized bitmap Glyphs. Embedded_Bitmaps 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 Embedded_Bitmaps is set, and selects the outline glyph if Embedded_Bitmaps is clear. Windows may select the bitmap glyph but is not required to do so. OS_X and iOS do not support this option.
SkFont controls options applied when drawing and measuring text.
class SkFont { enum class Edging { kAlias, kAntiAlias, kSubpixelAntiAlias, }; SkFont(); SkFont(sk_sp<SkTypeface> typeface, SkScalar size); SkFont(sk_sp<SkTypeface> typeface, SkScalar size, SkScalar scaleX, SkScalar skewX); bool operator==(const SkFont& font) const; bool isForceAutoHinting() const; bool isEmbeddedBitmaps() const; bool isSubpixel() const; bool isLinearMetrics() const; bool isEmbolden() const; void setForceAutoHinting(bool forceAutoHinting); void setEmbeddedBitmaps(bool embeddedBitmaps); void setSubpixel(bool subpixel); void setLinearMetrics(bool linearMetrics); void setEmbolden(bool embolden); Edging getEdging() const; void setEdging(Edging edging); void setHinting(SkFontHinting hintingLevel); SkFontHinting getHinting() const; SkFont makeWithSize(SkScalar size) const; SkTypeface* getTypeface() const; SkScalar getSize() const; SkScalar getScaleX() const; SkScalar getSkewX() const; sk_sp<SkTypeface> refTypeface() const; void setTypeface(sk_sp<SkTypeface> tf); void setSize(SkScalar textSize); void setScaleX(SkScalar scaleX); void setSkewX(SkScalar skewX); int textToGlyphs(const void* text, size_t byteLength, SkTextEncoding encoding, SkGlyphID glyphs[], int maxGlyphCount) const; uint16_t unicharToGlyph(SkUnichar uni) const; int countText(const void* text, size_t byteLength, SkTextEncoding encoding) const; bool containsText(const void* text, size_t byteLength, SkTextEncoding encoding) const; size_t breakText(const void* text, size_t length, SkTextEncoding encoding, SkScalar maxWidth, SkScalar* measuredWidth = nullptr) const; SkScalar measureText(const void* text, size_t byteLength, SkTextEncoding encoding, SkRect* bounds = nullptr) const; bool getPath(uint16_t glyphID, SkPath* path) const; void getPaths(const uint16_t glyphIDs[], int count, void (*glyphPathProc)(const SkPath* pathOrNull, const SkMatrix& mx, void* ctx), void* ctx) const; SkScalar getMetrics(SkFontMetrics* metrics) const; SkScalar getSpacing() const; };
enum class Edging { kAlias, kAntiAlias, kSubpixelAntiAlias, };
Whether edge pixels draw opaque or with partial transparency.
Constants
Const | Value | Description |
---|---|---|
SkFont::Edging::kAlias |
no transparent pixels on glyph edges | |
SkFont::Edging::kAntiAlias |
may have transparent pixels on glyph edges | |
SkFont::Edging::kSubpixelAntiAlias |
glyph positioned in pixel using transparency |
Example
See Also
incomplete
SkFont()
Constructs SkFont with default values.
Return Value
default initialized SkFont
Example
See Also
incomplete
SkFont(sk_sp<SkTypeface> typeface, SkScalar size)
Constructs SkFont with default values with SkTypeface and size in points.
Parameters
typeface |
font and style used to draw and measure text |
size |
typographic height of text |
Return Value
initialized SkFont
Example
See Also
incomplete
SkFont(sk_sp<SkTypeface> typeface, SkScalar size, SkScalar scaleX, SkScalar skewX)
Constructs SkFont with default values with SkTypeface and size in points, horizontal scale, and horizontal skew. Horizontal scale emulates condensed and expanded fonts. Horizontal skew emulates oblique fonts.
Parameters
typeface |
font and style used to draw and measure text |
size |
typographic height of text |
scaleX |
text horizontal scale |
skewX |
additional shear on x-axis relative to y-axis |
Return Value
initialized SkFont
Example
See Also
incomplete
bool operator==(const SkFont& font)const
Compares SkFont and font, and returns true if they are equivalent. May return false if SkTypeface has identical contents but different pointers.
Parameters
font |
font to compare |
Return Value
true if SkFont pair are equivalent
Example
See Also
incomplete
bool isForceAutoHinting()const
If true, instructs the font manager to always hint glyphs. Returned value is only meaningful if platform uses FreeType as the font manager.
Return Value
true if all glyphs are hinted
Example
See Also
incomplete
bool isEmbeddedBitmaps()const
Returns true if font engine may return glyphs from font bitmaps instead of from outlines.
Return Value
true if glyphs may be font bitmaps
Example
See Also
incomplete
bool isSubpixel()const
Returns true if glyphs at different sub-pixel positions may differ on pixel edge coverage.
Return Value
true if glyph positioned in pixel using transparency
Example
See Also
incomplete
bool isLinearMetrics()const
Returns true if text is converted to SkPath before drawing and measuring.
Return Value
true glyph hints are never applied
Example
See Also
incomplete
bool isEmbolden()const
Returns true if bold is approximated by increasing the stroke width when creating glyph bitmaps from outlines.
Return Value
bold is approximated through stroke width
Example
See Also
incomplete
void setForceAutoHinting(bool forceAutoHinting)
Sets whether to always hint glyphs. If forceAutoHinting is set, instructs the font manager to always hint glyphs.
Only affects platforms that use FreeType as the font manager.
Parameters
forceAutoHinting |
setting to always hint glyphs |
Example
See Also
incomplete
void setEmbeddedBitmaps(bool embeddedBitmaps)
Requests, but does not require, to use bitmaps in fonts instead of outlines.
Parameters
embeddedBitmaps |
setting to use bitmaps in fonts |
Example
See Also
incomplete
void setSubpixel(bool subpixel)
Requests, but does not require, that glyphs respect sub-pixel positioning.
Parameters
subpixel |
setting for sub-pixel positioning |
Example
See Also
incomplete
void setLinearMetrics(bool linearMetrics)
Requests, but does not require, that glyphs are converted to SkPath before drawing and measuring.
Parameters
linearMetrics |
setting for converting glyphs to paths |
Example
See Also
incomplete
void setEmbolden(bool embolden)
Increases stroke width when creating glyph bitmaps to approximate a bold typeface.
Parameters
embolden |
setting for bold approximation |
Example
See Also
incomplete
Edging getEdging()const
Whether edge pixels draw opaque or with partial transparency.
Return Value
one of: Edging::kAlias, Edging::kAntiAlias, Edging::kSubpixelAntiAlias
Example
See Also
incomplete
void setEdging(Edging edging)
Requests, but does not require, that edge pixels draw opaque or with partial transparency.
Parameters
edging |
one of: Edging::kAlias, Edging::kAntiAlias, Edging::kSubpixelAntiAlias |
Example
See Also
incomplete
void setHinting(SkFontHinting hintingLevel)
Sets level of glyph outline adjustment. Does not check for valid values of hintingLevel.
Parameters
hintingLevel |
one of: SkFontHinting::kNone, SkFontHinting::kSlight, |
SkFontHinting::kNormal, SkFontHinting::kFull
Example
See Also
incomplete
SkFontHinting getHinting()const
Returns level of glyph outline adjustment.
Return Value
one of: SkFontHinting::kNone, SkFontHinting::kSlight, SkFontHinting::kNormal,
Example
See Also
incomplete
SkFont makeWithSize(SkScalar size)const
Returns a font with the same attributes of this font, but with the specified size. Returns nullptr if size is less than zero, infinite, or NaN.
Parameters
size |
typographic height of text |
Return Value
initialized SkFont
Example
See Also
incomplete
SkTypeface* getTypeface()const
Returns SkTypeface if set, or nullptr. Does not alter SkTypeface SkRefCnt.
Return Value
SkTypeface if previously set, nullptr otherwise
Example
See Also
incomplete
SkScalar getSize()const
Return Value
typographic height of text
Example
See Also
incomplete
SkScalar getScaleX()const
Returns text scale on x-axis. Default value is 1.
Return Value
text horizontal scale
Example
See Also
incomplete
SkScalar getSkewX()const
Returns text skew on x-axis. Default value is zero.
Return Value
additional shear on x-axis relative to y-axis
Example
See Also
incomplete
sk_sp<SkTypeface> refTypeface()const
Increases SkTypeface SkRefCnt by one.
Return Value
SkTypeface if previously set, nullptr otherwise
Example
See Also
incomplete
void setTypeface(sk_sp<SkTypeface> tf)
Sets SkTypeface to typeface, decreasing SkRefCnt of the previous SkTypeface. Pass nullptr to clear SkTypeface and use the default typeface. Increments tf SkRefCnt by one.
Parameters
tf |
font and style used to draw text |
Example
See Also
incomplete
void setSize(SkScalar textSize)
Sets text size in points. Has no effect if textSize is not greater than or equal to zero.
Parameters
textSize |
typographic height of text |
Example
See Also
incomplete
void setScaleX(SkScalar scaleX)
Sets text scale on x-axis. Default value is 1.
Parameters
scaleX |
text horizontal scale |
Example
See Also
incomplete
void setSkewX(SkScalar skewX)
Sets text skew on x-axis. Default value is zero.
Parameters
skewX |
additional shear on x-axis relative to y-axis |
Example
See Also
incomplete
int textToGlyphs(const void* text, size_t byteLength, SkTextEncoding encoding, SkGlyphID glyphs[], int maxGlyphCount)const
Converts text into glyph indices. Returns the number of glyph indices represented by text. SkTextEncoding specifies how text represents characters or glyphs. glyphs may be nullptr, to compute the glyph count.
Does not check text for valid character codes or valid glyph indices.
If byteLength equals zero, returns zero. If byteLength includes a partial character, the partial character is ignored.
If encoding is SkTextEncoding::kUTF8 and text contains an invalid UTF-8 sequence, zero is returned.
If maxGlyphCount is not sufficient to store all the glyphs, no glyphs are copied. The total glyph count is returned for subsequent buffer reallocation.
Parameters
text |
character storage encoded with SkTextEncoding |
byteLength |
length of character storage in bytes |
encoding |
one of: SkTextEncoding::kUTF8, SkTextEncoding::kUTF16, |
SkTextEncoding::kUTF32, SkTextEncoding::kGlyphID
Parameters
glyphs |
storage for glyph indices; may be nullptr |
maxGlyphCount |
storage capacity |
Return Value
number of glyphs represented by text of length byteLength
Example
See Also
incomplete
uint16_t unicharToGlyph(SkUnichar uni)const
Returns glyph index for Unicode character.
Parameters
uni |
Unicode character |
Return Value
glyph index
Example
See Also
incomplete
int countText(const void* text, size_t byteLength, SkTextEncoding encoding)const
Returns number of glyphs represented by text.
Parameters
text |
character storage encoded with SkTextEncoding |
byteLength |
length of character storage in bytes |
encoding |
one of: SkTextEncoding::kUTF8, SkTextEncoding::kUTF16, |
SkTextEncoding::kUTF32, SkTextEncoding::kGlyphID
Return Value
number of glyphs represented by text of length byteLength
Example
See Also
incomplete
bool containsText(const void* text, size_t byteLength, SkTextEncoding encoding)const
Returns true if all text corresponds to a non-zero glyph index. Returns false if any characters in text are not supported in SkTypeface.
If SkTextEncoding is SkTextEncoding::kGlyphID, returns true if all glyph indices in text are non-zero; does not check to see if text contains valid glyph indices for SkTypeface.
Returns true if byteLength is zero.
Parameters
text |
array of characters or glyphs |
byteLength |
number of bytes in text array |
encoding |
text encoding |
Return Value
true if all text corresponds to a non-zero glyph index
Example
See Also
incomplete
size_t breakText(const void* text, size_t length, SkTextEncoding encoding, SkScalar maxWidth, SkScalar* measuredWidth = nullptr)const
Returns the bytes of text that fit within maxWidth. The text fragment fits if its advance width 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 encoding to decode text, SkTypeface to get the font metrics, and text size to scale the metrics. Does not scale the advance or bounds by fake bold.
Parameters
text |
character codes or glyph indices to be measured |
length |
number of bytes of text to measure |
encoding |
text encoding |
maxWidth |
advance limit; text is measured while advance is less than maxWidth |
measuredWidth |
returns the width of the text less than or equal to maxWidth |
Return Value
bytes of text that fit, always less than or equal to length
Example
See Also
incomplete
SkScalar measureText(const void* text, size_t byteLength, SkTextEncoding encoding, SkRect* bounds = nullptr)const
Returns the advance width of text. The advance is the normal distance to move before drawing additional text. Returns the bounding box of text if bounds is not nullptr.
Parameters
text |
character storage encoded with SkTextEncoding |
byteLength |
length of character storage in bytes |
encoding |
one of: SkTextEncoding::kUTF8, SkTextEncoding::kUTF16, |
SkTextEncoding::kUTF32, SkTextEncoding::kGlyphID
Parameters
bounds |
returns bounding box relative to (0, 0) if not nullptr |
Return Value
number of glyphs represented by text of length byteLength
Example
See Also
incomplete
bool getPath(uint16_t glyphID, SkPath* path)const
Returns path corresponding to glyph outline. If glyph has an outline, copies outline to path and returns true. path returned may be empty. If glyph is described by a bitmap, returns false and ignores path parameter.
Parameters
glyphID |
index of glyph |
path |
pointer to existing SkPath |
Return Value
true if glyphID is described by path
Example
See Also
incomplete
void getPaths(const uint16_t glyphIDs[], int count, void (*glyphPathProc) (const SkPath* pathOrNull, const SkMatrix& mx, void* ctx) , void* ctx)const
Returns path corresponding to glyph array.
Parameters
glyphIDs |
array of glyph indices |
count |
number of glyphs |
glyphPathProc |
function returning one glyph description as path |
ctx |
function context |
Example
See Also
incomplete
SkScalar getMetrics(SkFontMetrics* metrics)const
Returns SkFontMetrics associated with SkTypeface. The return value is the recommended spacing between lines: the sum of metrics descent, ascent, and leading. If metrics is not nullptr, SkFontMetrics is copied to metrics. Results are scaled by text size but does not take into account dimensions required by text scale, text skew, fake bold, style stroke, and SkPathEffect.
Parameters
metrics |
storage for SkFontMetrics; may be nullptr |
Return Value
recommended spacing between lines
Example
See Also
incomplete
SkScalar getSpacing()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 SkPathEffect. Returns the same result as getMetrics().
Return Value
recommended spacing between lines
Example
See Also
incomplete