Skia
2D Graphics Library
SkFont Class Reference

SkFont controls options applied when drawing and measuring text. More...

#include <SkFont.h>

Public Types

enum  Edging { Edging::kAlias, Edging::kAntiAlias, Edging::kSubpixelAntiAlias }
 Whether edge pixels draw opaque or with partial transparency. More...
 

Public Member Functions

 SkFont ()
 Constructs SkFont with default values. More...
 
 SkFont (sk_sp< SkTypeface > typeface, SkScalar size)
 Constructs SkFont with default values with SkTypeface and size in points. More...
 
 SkFont (sk_sp< SkTypeface > typeface)
 Constructs SkFont with default values with SkTypeface. More...
 
 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. More...
 
bool operator== (const SkFont &font) const
 Compares SkFont and font, and returns true if they are equivalent. More...
 
bool operator!= (const SkFont &font) const
 Compares SkFont and font, and returns true if they are not equivalent. More...
 
bool isForceAutoHinting () const
 If true, instructs the font manager to always hint glyphs. More...
 
bool isEmbeddedBitmaps () const
 Returns true if font engine may return glyphs from font bitmaps instead of from outlines. More...
 
bool isSubpixel () const
 Returns true if glyphs may be drawn at sub-pixel offsets. More...
 
bool isLinearMetrics () const
 Returns true if font and glyph metrics are requested to be linearly scalable. More...
 
bool isEmbolden () const
 Returns true if bold is approximated by increasing the stroke width when creating glyph bitmaps from outlines. More...
 
bool isBaselineSnap () const
 Returns true if baselines will be snapped to pixel positions when the current transformation matrix is axis aligned. More...
 
void setForceAutoHinting (bool forceAutoHinting)
 Sets whether to always hint glyphs. More...
 
void setEmbeddedBitmaps (bool embeddedBitmaps)
 Requests, but does not require, to use bitmaps in fonts instead of outlines. More...
 
void setSubpixel (bool subpixel)
 Requests, but does not require, that glyphs respect sub-pixel positioning. More...
 
void setLinearMetrics (bool linearMetrics)
 Requests, but does not require, linearly scalable font and glyph metrics. More...
 
void setEmbolden (bool embolden)
 Increases stroke width when creating glyph bitmaps to approximate a bold typeface. More...
 
void setBaselineSnap (bool baselineSnap)
 Requests that baselines be snapped to pixels when the current transformation matrix is axis aligned. More...
 
Edging getEdging () const
 Whether edge pixels draw opaque or with partial transparency. More...
 
void setEdging (Edging edging)
 Requests, but does not require, that edge pixels draw opaque or with partial transparency. More...
 
void setHinting (SkFontHinting hintingLevel)
 Sets level of glyph outline adjustment. More...
 
SkFontHinting getHinting () const
 Returns level of glyph outline adjustment. More...
 
SkFont makeWithSize (SkScalar size) const
 Returns a font with the same attributes of this font, but with the specified size. More...
 
SkTypefacegetTypeface () const
 Returns SkTypeface if set, or nullptr. More...
 
SkTypefacegetTypefaceOrDefault () const
 Returns SkTypeface if set, or the default typeface. More...
 
SkScalar getSize () const
 Returns text size in points. More...
 
SkScalar getScaleX () const
 Returns text scale on x-axis. More...
 
SkScalar getSkewX () const
 Returns text skew on x-axis. More...
 
sk_sp< SkTypefacerefTypeface () const
 Increases SkTypeface SkRefCnt by one. More...
 
sk_sp< SkTypefacerefTypefaceOrDefault () const
 Increases SkTypeface SkRefCnt by one. More...
 
void setTypeface (sk_sp< SkTypeface > tf)
 Sets SkTypeface to typeface, decreasing SkRefCnt of the previous SkTypeface. More...
 
void setSize (SkScalar textSize)
 Sets text size in points. More...
 
void setScaleX (SkScalar scaleX)
 Sets text scale on x-axis. More...
 
void setSkewX (SkScalar skewX)
 Sets text skew on x-axis. More...
 
int textToGlyphs (const void *text, size_t byteLength, SkTextEncoding encoding, SkGlyphID glyphs[], int maxGlyphCount) const
 Converts text into glyph indices. More...
 
SkGlyphID unicharToGlyph (SkUnichar uni) const
 Returns glyph index for Unicode character. More...
 
void unicharsToGlyphs (const SkUnichar uni[], int count, SkGlyphID glyphs[]) const
 
int countText (const void *text, size_t byteLength, SkTextEncoding encoding) const
 Returns number of glyphs represented by text. More...
 
SkScalar measureText (const void *text, size_t byteLength, SkTextEncoding encoding, SkRect *bounds=nullptr) const
 Returns the advance width of text. More...
 
SkScalar measureText (const void *text, size_t byteLength, SkTextEncoding encoding, SkRect *bounds, const SkPaint *paint) const
 Returns the advance width of text. More...
 
void getWidths (const SkGlyphID glyphs[], int count, SkScalar widths[], SkRect bounds[]) const
 DEPRECATED Retrieves the advance and bounds for each glyph in glyphs. More...
 
void getWidths (const SkGlyphID glyphs[], int count, SkScalar widths[], std::nullptr_t) const
 
void getWidths (const SkGlyphID glyphs[], int count, SkScalar widths[]) const
 Retrieves the advance and bounds for each glyph in glyphs. More...
 
void getWidthsBounds (const SkGlyphID glyphs[], int count, SkScalar widths[], SkRect bounds[], const SkPaint *paint) const
 Retrieves the advance and bounds for each glyph in glyphs. More...
 
void getBounds (const SkGlyphID glyphs[], int count, SkRect bounds[], const SkPaint *paint) const
 Retrieves the bounds for each glyph in glyphs. More...
 
void getPos (const SkGlyphID glyphs[], int count, SkPoint pos[], SkPoint origin={0, 0}) const
 Retrieves the positions for each glyph, beginning at the specified origin. More...
 
void getXPos (const SkGlyphID glyphs[], int count, SkScalar xpos[], SkScalar origin=0) const
 Retrieves the x-positions for each glyph, beginning at the specified origin. More...
 
bool getPath (SkGlyphID glyphID, SkPath *path) const
 Modifies path to be the outline of the glyph. More...
 
void getPaths (const SkGlyphID glyphIDs[], int count, void(*glyphPathProc)(const SkPath *pathOrNull, const SkMatrix &mx, void *ctx), void *ctx) const
 Returns path corresponding to glyph array. More...
 
SkScalar getMetrics (SkFontMetrics *metrics) const
 Returns SkFontMetrics associated with SkTypeface. More...
 
SkScalar getSpacing () const
 Returns the recommended spacing between lines: the sum of metrics descent, ascent, and leading. More...
 
void dump () const
 Dumps fields of the font to SkDebugf. More...
 

Friends

class GrAtlasSubRun
 
class GrTextBlob
 
class SkFontPriv
 
class SkGlyphRunListPainter
 
class SkTextBlobCacheDiffCanvas
 
class SkStrikeSpec
 

Detailed Description

SkFont controls options applied when drawing and measuring text.

Member Enumeration Documentation

◆ Edging

enum SkFont::Edging
strong

Whether edge pixels draw opaque or with partial transparency.

Enumerator
kAlias 

no transparent pixels on glyph edges

kAntiAlias 

may have transparent pixels on glyph edges

kSubpixelAntiAlias 

glyph positioned in pixel using transparency

Constructor & Destructor Documentation

◆ SkFont() [1/4]

SkFont::SkFont ( )

Constructs SkFont with default values.

Returns
default initialized SkFont

◆ SkFont() [2/4]

SkFont::SkFont ( sk_sp< SkTypeface typeface,
SkScalar  size 
)

Constructs SkFont with default values with SkTypeface and size in points.

Parameters
typefacefont and style used to draw and measure text
sizetypographic height of text
Returns
initialized SkFont

◆ SkFont() [3/4]

SkFont::SkFont ( sk_sp< SkTypeface typeface)
explicit

Constructs SkFont with default values with SkTypeface.

Parameters
typefacefont and style used to draw and measure text
Returns
initialized SkFont

◆ SkFont() [4/4]

SkFont::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
typefacefont and style used to draw and measure text
sizetypographic height of text
scaleXtext horizontal scale
skewXadditional shear on x-axis relative to y-axis
Returns
initialized SkFont

Member Function Documentation

◆ countText()

int SkFont::countText ( const void *  text,
size_t  byteLength,
SkTextEncoding  encoding 
) const
inline

Returns number of glyphs represented by text.

If encoding is SkTextEncoding::kUTF8, SkTextEncoding::kUTF16, or SkTextEncoding::kUTF32; then each Unicode codepoint is mapped to a single glyph.

Parameters
textcharacter storage encoded with SkTextEncoding
byteLengthlength of character storage in bytes
Returns
number of glyphs represented by text of length byteLength

◆ dump()

void SkFont::dump ( ) const

Dumps fields of the font to SkDebugf.

May change its output over time, so clients should not rely on this for anything specific. Used to aid in debugging.

◆ getBounds()

void SkFont::getBounds ( const SkGlyphID  glyphs[],
int  count,
SkRect  bounds[],
const SkPaint paint 
) const
inline

Retrieves the bounds for each glyph in glyphs.

bounds must be an array of count entries. If paint is not nullptr, its stroking, SkPathEffect, and SkMaskFilter fields are respected.

Parameters
glyphsarray of glyph indices to be measured
countnumber of glyphs
boundsreturns bounds for each glyph relative to (0, 0); may be nullptr
paintoptional, specifies stroking, SkPathEffect, and SkMaskFilter

◆ getEdging()

Edging SkFont::getEdging ( ) const
inline

Whether edge pixels draw opaque or with partial transparency.

◆ getHinting()

SkFontHinting SkFont::getHinting ( ) const
inline

Returns level of glyph outline adjustment.

◆ getMetrics()

SkScalar SkFont::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
metricsstorage for SkFontMetrics; may be nullptr
Returns
recommended spacing between lines

◆ getPath()

bool SkFont::getPath ( SkGlyphID  glyphID,
SkPath path 
) const

Modifies path to be the outline of the glyph.

If the glyph has an outline, modifies path to be the glyph's outline and returns true. The glyph outline may be empty. Degenerate contours in the glyph outline will be skipped. If glyph is described by a bitmap, returns false and ignores path parameter.

Parameters
glyphIDindex of glyph
pathpointer to existing SkPath
Returns
true if glyphID is described by path

◆ getPaths()

void SkFont::getPaths ( const SkGlyphID  glyphIDs[],
int  count,
void(*)(const SkPath *pathOrNull, const SkMatrix &mx, void *ctx)  glyphPathProc,
void *  ctx 
) const

Returns path corresponding to glyph array.

Parameters
glyphIDsarray of glyph indices
countnumber of glyphs
glyphPathProcfunction returning one glyph description as path
ctxfunction context

◆ getPos()

void SkFont::getPos ( const SkGlyphID  glyphs[],
int  count,
SkPoint  pos[],
SkPoint  origin = {0, 0} 
) const

Retrieves the positions for each glyph, beginning at the specified origin.

The caller must allocated at least count number of elements in the pos[] array.

Parameters
glyphsarray of glyph indices to be positioned
countnumber of glyphs
posreturns glyphs positions
originlocation of the first glyph. Defaults to {0, 0}.

◆ getScaleX()

SkScalar SkFont::getScaleX ( ) const
inline

Returns text scale on x-axis.

Default value is 1.

Returns
text horizontal scale

◆ getSize()

SkScalar SkFont::getSize ( ) const
inline

Returns text size in points.

Returns
typographic height of text

◆ getSkewX()

SkScalar SkFont::getSkewX ( ) const
inline

Returns text skew on x-axis.

Default value is zero.

Returns
additional shear on x-axis relative to y-axis

◆ getSpacing()

SkScalar SkFont::getSpacing ( ) const
inline

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().

Returns
recommended spacing between lines

◆ getTypeface()

SkTypeface* SkFont::getTypeface ( ) const
inline

Returns SkTypeface if set, or nullptr.

Does not alter SkTypeface SkRefCnt.

Returns
SkTypeface if previously set, nullptr otherwise

◆ getTypefaceOrDefault()

SkTypeface* SkFont::getTypefaceOrDefault ( ) const

Returns SkTypeface if set, or the default typeface.

Does not alter SkTypeface SkRefCnt.

Returns
SkTypeface if previously set or, a pointer to the default typeface if not previously set.

◆ getWidths() [1/3]

void SkFont::getWidths ( const SkGlyphID  glyphs[],
int  count,
SkScalar  widths[],
SkRect  bounds[] 
) const
inline

DEPRECATED Retrieves the advance and bounds for each glyph in glyphs.

Both widths and bounds may be nullptr. If widths is not nullptr, widths must be an array of count entries. if bounds is not nullptr, bounds must be an array of count entries.

Parameters
glyphsarray of glyph indices to be measured
countnumber of glyphs
widthsreturns text advances for each glyph; may be nullptr
boundsreturns bounds for each glyph relative to (0, 0); may be nullptr

◆ getWidths() [2/3]

void SkFont::getWidths ( const SkGlyphID  glyphs[],
int  count,
SkScalar  widths[],
std::nullptr_t   
) const
inline

◆ getWidths() [3/3]

void SkFont::getWidths ( const SkGlyphID  glyphs[],
int  count,
SkScalar  widths[] 
) const
inline

Retrieves the advance and bounds for each glyph in glyphs.

Both widths and bounds may be nullptr. If widths is not nullptr, widths must be an array of count entries. if bounds is not nullptr, bounds must be an array of count entries.

Parameters
glyphsarray of glyph indices to be measured
countnumber of glyphs
widthsreturns text advances for each glyph

◆ getWidthsBounds()

void SkFont::getWidthsBounds ( const SkGlyphID  glyphs[],
int  count,
SkScalar  widths[],
SkRect  bounds[],
const SkPaint paint 
) const

Retrieves the advance and bounds for each glyph in glyphs.

Both widths and bounds may be nullptr. If widths is not nullptr, widths must be an array of count entries. if bounds is not nullptr, bounds must be an array of count entries.

Parameters
glyphsarray of glyph indices to be measured
countnumber of glyphs
widthsreturns text advances for each glyph; may be nullptr
boundsreturns bounds for each glyph relative to (0, 0); may be nullptr
paintoptional, specifies stroking, SkPathEffect and SkMaskFilter

◆ getXPos()

void SkFont::getXPos ( const SkGlyphID  glyphs[],
int  count,
SkScalar  xpos[],
SkScalar  origin = 0 
) const

Retrieves the x-positions for each glyph, beginning at the specified origin.

The caller must allocated at least count number of elements in the xpos[] array.

Parameters
glyphsarray of glyph indices to be positioned
countnumber of glyphs
xposreturns glyphs x-positions
originx-position of the first glyph. Defaults to 0.

◆ isBaselineSnap()

bool SkFont::isBaselineSnap ( ) const
inline

Returns true if baselines will be snapped to pixel positions when the current transformation matrix is axis aligned.

Returns
baselines may be snapped to pixels

◆ isEmbeddedBitmaps()

bool SkFont::isEmbeddedBitmaps ( ) const
inline

Returns true if font engine may return glyphs from font bitmaps instead of from outlines.

Returns
true if glyphs may be font bitmaps

◆ isEmbolden()

bool SkFont::isEmbolden ( ) const
inline

Returns true if bold is approximated by increasing the stroke width when creating glyph bitmaps from outlines.

Returns
bold is approximated through stroke width

◆ isForceAutoHinting()

bool SkFont::isForceAutoHinting ( ) const
inline

If true, instructs the font manager to always hint glyphs.

Returned value is only meaningful if platform uses FreeType as the font manager.

Returns
true if all glyphs are hinted

◆ isLinearMetrics()

bool SkFont::isLinearMetrics ( ) const
inline

Returns true if font and glyph metrics are requested to be linearly scalable.

Returns
true if font and glyph metrics are requested to be linearly scalable.

◆ isSubpixel()

bool SkFont::isSubpixel ( ) const
inline

Returns true if glyphs may be drawn at sub-pixel offsets.

Returns
true if glyphs may be drawn at sub-pixel offsets.

◆ makeWithSize()

SkFont 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
sizetypographic height of text
Returns
initialized SkFont

◆ measureText() [1/2]

SkScalar SkFont::measureText ( const void *  text,
size_t  byteLength,
SkTextEncoding  encoding,
SkRect bounds = nullptr 
) const
inline

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
textcharacter storage encoded with SkTextEncoding
byteLengthlength of character storage in bytes
boundsreturns bounding box relative to (0, 0) if not nullptr
Returns
number of glyphs represented by text of length byteLength

◆ measureText() [2/2]

SkScalar SkFont::measureText ( const void *  text,
size_t  byteLength,
SkTextEncoding  encoding,
SkRect bounds,
const SkPaint paint 
) 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. paint stroke width or SkPathEffect may modify the advance with.

Parameters
textcharacter storage encoded with SkTextEncoding
byteLengthlength of character storage in bytes
boundsreturns bounding box relative to (0, 0) if not nullptr
paintoptional; may be nullptr
Returns
number of glyphs represented by text of length byteLength

◆ operator!=()

bool SkFont::operator!= ( const SkFont font) const
inline

Compares SkFont and font, and returns true if they are not equivalent.

May return true if SkTypeface has identical contents but different pointers.

Parameters
fontfont to compare
Returns
true if SkFont pair are not equivalent

◆ operator==()

bool SkFont::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
fontfont to compare
Returns
true if SkFont pair are equivalent

◆ refTypeface()

sk_sp<SkTypeface> SkFont::refTypeface ( ) const
inline

Increases SkTypeface SkRefCnt by one.

Returns
SkTypeface if previously set, nullptr otherwise

◆ refTypefaceOrDefault()

sk_sp<SkTypeface> SkFont::refTypefaceOrDefault ( ) const

Increases SkTypeface SkRefCnt by one.

Returns
SkTypeface if previously set or, a pointer to the default typeface if not previously set.

◆ setBaselineSnap()

void SkFont::setBaselineSnap ( bool  baselineSnap)

Requests that baselines be snapped to pixels when the current transformation matrix is axis aligned.

Parameters
baselineSnapsetting for baseline snapping to pixels

◆ setEdging()

void SkFont::setEdging ( Edging  edging)

Requests, but does not require, that edge pixels draw opaque or with partial transparency.

◆ setEmbeddedBitmaps()

void SkFont::setEmbeddedBitmaps ( bool  embeddedBitmaps)

Requests, but does not require, to use bitmaps in fonts instead of outlines.

Parameters
embeddedBitmapssetting to use bitmaps in fonts

◆ setEmbolden()

void SkFont::setEmbolden ( bool  embolden)

Increases stroke width when creating glyph bitmaps to approximate a bold typeface.

Parameters
emboldensetting for bold approximation

◆ setForceAutoHinting()

void SkFont::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
forceAutoHintingsetting to always hint glyphs

◆ setHinting()

void SkFont::setHinting ( SkFontHinting  hintingLevel)

Sets level of glyph outline adjustment.

Does not check for valid values of hintingLevel.

◆ setLinearMetrics()

void SkFont::setLinearMetrics ( bool  linearMetrics)

Requests, but does not require, linearly scalable font and glyph metrics.

For outline fonts 'true' means font and glyph metrics should ignore hinting and rounding. Note that some bitmap formats may not be able to scale linearly and will ignore this flag.

Parameters
linearMetricssetting for linearly scalable font and glyph metrics.

◆ setScaleX()

void SkFont::setScaleX ( SkScalar  scaleX)

Sets text scale on x-axis.

Default value is 1.

Parameters
scaleXtext horizontal scale

◆ setSize()

void SkFont::setSize ( SkScalar  textSize)

Sets text size in points.

Has no effect if textSize is not greater than or equal to zero.

Parameters
textSizetypographic height of text

◆ setSkewX()

void SkFont::setSkewX ( SkScalar  skewX)

Sets text skew on x-axis.

Default value is zero.

Parameters
skewXadditional shear on x-axis relative to y-axis

◆ setSubpixel()

void SkFont::setSubpixel ( bool  subpixel)

Requests, but does not require, that glyphs respect sub-pixel positioning.

Parameters
subpixelsetting for sub-pixel positioning

◆ setTypeface()

void SkFont::setTypeface ( sk_sp< SkTypeface tf)
inline

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
tffont and style used to draw text

◆ textToGlyphs()

int SkFont::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.

When encoding is SkTextEncoding::kUTF8, SkTextEncoding::kUTF16, or SkTextEncoding::kUTF32; then each Unicode codepoint is mapped to a single glyph. This function uses the default character-to-glyph mapping from the SkTypeface and maps characters not found in the SkTypeface to zero.

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
textcharacter storage encoded with SkTextEncoding
byteLengthlength of character storage in bytes
glyphsstorage for glyph indices; may be nullptr
maxGlyphCountstorage capacity
Returns
number of glyphs represented by text of length byteLength

◆ unicharsToGlyphs()

void SkFont::unicharsToGlyphs ( const SkUnichar  uni[],
int  count,
SkGlyphID  glyphs[] 
) const

◆ unicharToGlyph()

SkGlyphID SkFont::unicharToGlyph ( SkUnichar  uni) const

Returns glyph index for Unicode character.

If the character is not supported by the SkTypeface, returns 0.

Parameters
uniUnicode character
Returns
glyph index

Friends And Related Function Documentation

◆ GrAtlasSubRun

friend class GrAtlasSubRun
friend

◆ GrTextBlob

friend class GrTextBlob
friend

◆ SkFontPriv

friend class SkFontPriv
friend

◆ SkGlyphRunListPainter

friend class SkGlyphRunListPainter
friend

◆ SkStrikeSpec

friend class SkStrikeSpec
friend

◆ SkTextBlobCacheDiffCanvas

friend class SkTextBlobCacheDiffCanvas
friend

The documentation for this class was generated from the following file: