CUGL 2.3
Cornell University Game Library
Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
cugl::Font Class Reference

#include <CUFont.h>

Classes

class  Atlas
 
class  Metrics
 

Public Types

enum class  Style : int {
  NORMAL = TTF_STYLE_NORMAL , BOLD = TTF_STYLE_BOLD , ITALIC = TTF_STYLE_ITALIC , UNDERLINE = TTF_STYLE_UNDERLINE ,
  STRIKE = TTF_STYLE_STRIKETHROUGH
}
 
enum class  Hinting : int {
  NORMAL = TTF_HINTING_NORMAL , LIGHT = TTF_HINTING_LIGHT , MONO = TTF_HINTING_MONO , NONE = TTF_HINTING_NONE ,
  SUBPIXEL = TTF_HINTING_LIGHT_SUBPIXEL
}
 

Public Member Functions

 Font ()
 
 ~Font ()
 
virtual void dispose ()
 
bool init (const std::string file, Uint32 size)
 
const std::string getName () const
 
int getPointSize () const
 
const std::string getStyleName () const
 
int getHeight () const
 
int getDescent () const
 
int getAscent () const
 
int getLineSkip () const
 
bool isFixedWidth () const
 
bool hasGlyph (Uint32 a) const
 
bool hasGlyphs (const std::string glyphs) const
 
bool hasGlyphs (const std::vector< Uint32 > &glyphs) const
 
bool usesKerning () const
 
void setKerning (bool kerning)
 
Style getStyle () const
 
void setStyle (Style style)
 
Hinting getHinting () const
 
void setHinting (Hinting hinting)
 
Uint32 getPadding () const
 
void setPadding (Uint32 padding)
 
void setAtlasFallback (bool fallback)
 
bool hasAtlasFallback () const
 
void setShrinkLimit (Uint32 limit)
 
Uint32 getShrinkLimit () const
 
void setStretchLimit (Uint32 limit)
 
Uint32 getStretchLimit () const
 
const Metrics getMetrics (Uint32 thechar) const
 
unsigned int getKerning (Uint32 a, Uint32 b) const
 
Size getSize (const std::string text) const
 
Size getSize (const char *substr, const char *end) const
 
Rect getInternalBounds (const std::string text) const
 
Rect getInternalBounds (const char *substr, const char *end) const
 
std::vector< int > getTracking (const std::string text, float width)
 
std::vector< int > getTracking (const char *substr, const char *end, float width)
 
void clearAtlases ()
 
bool buildAtlases ()
 
bool buildAtlases (const std::string charset)
 
bool buildAtlases (const std::vector< Uint32 > &charset)
 
bool buildAtlasesAsync ()
 
bool buildAtlasesAsync (const std::string charset)
 
bool buildAtlasesAsync (const std::vector< Uint32 > &charset)
 
bool storeAtlases ()
 
const std::vector< std::shared_ptr< Texture > > getAtlases ()
 
bool hasAtlas (Uint32 thechar) const
 
bool hasAtlases (const std::string charset) const
 
bool hasAtlases (const std::vector< Uint32 > &charset) const
 
std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > getGlyphs (const std::string text, const Vec2 origin)
 
std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > getGlyphs (const char *substr, const char *end, const Vec2 origin)
 
std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > getGlyphs (const std::string text, const Vec2 origin, const Rect rect, float track=0)
 
std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > getGlyphs (const char *substr, const char *end, const Vec2 origin, const Rect rect, float track=0)
 
size_t getGlyphs (std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > &runs, const std::string text, const Vec2 origin)
 
size_t getGlyphs (std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > &runs, const char *substr, const char *end, const Vec2 origin)
 
size_t getGlyphs (std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > &runs, const char *substr, const char *end, const Vec2 origin, const Rect rect, float track=0)
 
size_t getGlyphs (std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > &runs, const std::string text, const Vec2 origin, const Rect rect, float track=0)
 
std::shared_ptr< GlyphRungetGlyph (Uint32 thechar, Vec2 &offset)
 
std::shared_ptr< GlyphRungetGlyph (Uint32 thechar, Vec2 &offset, const Rect rect)
 
Mesh< SpriteVertex2getGlyphBoxes (const std::string text, const Vec2 origin)
 
Mesh< SpriteVertex2getGlyphBoxes (const char *substr, const char *end, const Vec2 origin)
 
Mesh< SpriteVertex2getGlyphBoxes (const std::string text, const Vec2 origin, const Rect rect, float track=0)
 
Mesh< SpriteVertex2getGlyphBoxes (const char *substr, const char *end, const Vec2 origin, const Rect rect, float track=0)
 
size_t getGlyphBoxes (Mesh< SpriteVertex2 > &mesh, const std::string text, const Vec2 origin)
 
size_t getGlyphBoxes (Mesh< SpriteVertex2 > &mesh, const char *substr, const char *end, const Vec2 origin)
 
size_t getGlyphBoxes (Mesh< SpriteVertex2 > &mesh, const std::string text, const Vec2 origin, const Rect rect, float track=0)
 
size_t getGlyphBoxes (Mesh< SpriteVertex2 > &mesh, const char *substr, const char *end, const Vec2 origin, const Rect rect, float track=0)
 

Static Public Member Functions

static std::shared_ptr< Fontalloc (const std::string file, Uint32 size)
 

Protected Attributes

std::string _name
 
std::string _stylename
 
TTF_Font * _data
 
int _fontSize
 
int _fontHeight
 
int _fontDescent
 
int _fontAscent
 
int _fontLineSkip
 
bool _fixedWidth
 
bool _useKerning
 
Style _style
 
Hinting _hints
 
std::unordered_map< Uint32, Metrics_glyphsize
 
std::unordered_map< Uint32, std::unordered_map< Uint32, Uint32 > > _kernmap
 
std::vector< std::shared_ptr< Atlas > > _atlases
 
Uint32 _atlasPadding
 
std::unordered_map< Uint32, size_t > _atlasmap
 
bool _fallback
 
int _shrinkLimit
 
int _stretchLimit
 

Detailed Description

This class represents a true type font at a fixed size.

It is possible to change many of the font settings after loading. However, the size is fixed and cannot be changed. If you want a different size of the same font, you must load it as a new asset.

This font can be used to generate GlyphRun sequences for rendering text to the screen. This is typically done via the scene2::Label class, though the a glyph run contains enough information to be rendered directly with a SpriteBatch.

Rendering ASCII text is easy. For unicode support however, you need to encode you text properly. the only unicode encoding that we support is UTF8.
For the reason why, see

 http://utf8everywhere.org/#how

This font can also support atlases. This is a texture with all of the selected characters prerendered. This texture is then used to render the font on screen. This is a potentially fast way of rendering fonts, as you can simply represent the text as a quad mesh with a single texture.

However, afont atlas textures can be huge if all glyphs are included. For example, if we include all the unicode characters in Times New Roman at 48 point font, the resulting atlas texture is 2048x4096, which is too much for mobile devices. As a result, fonts may spread their glyphs across multiple altases to keep the texture size small.

In addition, only ASCII characters are included in a font atlas by default. To get unicode characters outside of the ASCII range, you must specify them when you build the atlas.

Member Enumeration Documentation

◆ Hinting

enum class cugl::Font::Hinting : int
strong

This enum represents the hints for rasterization.

Hinting is used to align the font to a rasterized grid. At low screen resolutions, hinting is critical for producing clear, legible text (particularly if you are not supporting antialiasing).

Enumerator
NORMAL 

This corresponds to the default hinting algorithm, optimized for standard gray-level rendering

LIGHT 

This is a lighter hinting algorithm for non-monochrome modes. Many generated glyphs are more fuzzy but better resemble its original shape. This is a bit like rendering on Mac OS X.

MONO 

This is a strong hinting algorithm that should only be used for monochrome output. The result is probably unpleasant if the glyph is rendered in non-monochrome modes.

NONE 

In this case, no hinting is used so the font may become very blurry or messy at smaller sizes.

SUBPIXEL 

This is a new hinting to leverage Freetypes subpixel support

◆ Style

enum class cugl::Font::Style : int
strong

This enum represents the possible font styles.

Generally, these styles would be encoded in the font face, but they are provided to allow the user some flexibility with any font.

With the exception of normal style (which is an absent of any style), all of the styles may be combined. So it is possible to have a bold, italic, underline font with strikethrough. To combine styles, simply treat the Style value as a bitmask, and combine them with bitwise operations.

Enumerator
NORMAL 

The default style provided by this face

BOLD 

An adhoc created bold style

ITALIC 

An adhoc created italics style

UNDERLINE 

An adhoc created underline style

STRIKE 

An adhoc created strike-through style

Constructor & Destructor Documentation

◆ Font()

cugl::Font::Font ( )

Creates a degenerate font with no data.

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate an object on the heap, use one of the static constructors instead.

◆ ~Font()

cugl::Font::~Font ( )
inline

Deletes this font, disposing of all resources.

Member Function Documentation

◆ alloc()

static std::shared_ptr< Font > cugl::Font::alloc ( const std::string  file,
Uint32  size 
)
inlinestatic

Returns a newly allocated font of the given size from the file.

The font size is fixed on creation. It cannot be changed without creating a new font asset. However, all other attributes may be changed.

Parameters
fileThe file with the font asset
sizeThe font size in points
Returns
a newly allocated font of the given size from the file.

◆ buildAtlases() [1/3]

bool cugl::Font::buildAtlases ( )

Creates an atlas collection for the ASCII characters in this font.

Only the ASCII characters are added to the atlases, even if the font has support for more characters. You should use a character set method if you want Unicode characters supported.

If there is already an active atlas collection, this method will preserve those atlas textures. Instead, it will only generate atlases for the characters that are not currently supported.

The character atlas textures are generated immediately, so the method getAtlases() may be called with no delay.

WARNING: This method is not thread safe. It generates OpenGL textures, which means that it may only be called in the main thread.

Returns
true if the atlases were successfully created.

◆ buildAtlases() [2/3]

bool cugl::Font::buildAtlases ( const std::string  charset)

Creates an atlas collection for the given character set.

The atlases generated contains characters in the provided character set, and will omit all other chacters. This includes ASCII characters that may be missing from the character set. The character set string must either be in ASCII or UTF8 encoding. It will handle both automatically, but no other encoding (e.g. Latin1) is accepted.

If there is already an active atlas collection, this method will preserve those atlas textures. Instead, it will only generate atlases for the characters that are not currently supported.

The character atlas textures are generated immediately, so the method getAtlases() may be called with no delay.

WARNING: This method is not thread safe. It generates OpenGL textures, which means that it may only be called in the main thread.

Parameters
charsetThe set of characters in the atlas
Returns
true if the atlases were successfully created.

◆ buildAtlases() [3/3]

bool cugl::Font::buildAtlases ( const std::vector< Uint32 > &  charset)

Creates an atlas collection for the given character set.

The atlases generated contains characters in the provided character set, and will omit all other chacters. This includes ASCII characters that may be missing from the character set. The character set provided must be a collection of UNICODE encodings. The Unicode representation uses the endianness native to the platform. Therefore, this value should not be serialized. Use UTF8 to represent unicode in a platform-independent manner.

If there is already an active atlas collection, this method will preserve those atlas textures. Instead, it will only generate atlases for the characters that are not currently supported.

The character atlas textures are generated immediately, so the method getAtlases() may be called with no delay.

WARNING: This method is not thread safe. It generates OpenGL textures, which means that it may only be called in the main thread.

Parameters
charsetThe set of characters in the atlas
Returns
true if the atlases were successfully created.

◆ buildAtlasesAsync() [1/3]

bool cugl::Font::buildAtlasesAsync ( )

Creates an atlas collection for the ASCII characters in this font.

Only the ASCII characters are added to the atlases, even if the font has support for more characters. You should use a character set method if you want Unicode characters supported.

If there is already an active atlas collection, this method will preserve those atlas textures. Instead, it will only generate atlases for the characters that are not currently supported.

This method does not generate any OpenGL textures, but does all other work in creates the atlases. In particular it creates the image buffers so that texture creation is just one OpenGL call. This creation will happen the first time that storeAtlases() is called.

As a result, this method is thread safe. It may be called in any thread, including threads other than the main one.

Returns
true if the atlases were successfully created.

◆ buildAtlasesAsync() [2/3]

bool cugl::Font::buildAtlasesAsync ( const std::string  charset)

Creates an atlas collection for the given character set.

The atlas only contains characters in the provided character set, and will omit all other chacters. This includes ASCII characters that may be missing from the character set. The character set string must either be in ASCII or UTF8 encoding. It will handle both automatically, but no other encoding (e.g. Latin1) is accepted.

If there is already an active atlas collection, this method will preserve those atlas textures. Instead, it will only generate atlases for the characters that are not currently supported.

This method does not generate any OpenGL textures, but does all other work in creates the atlases. In particular it creates the image buffers so that texture creation is just one OpenGL call. This creation will happen the first time that storeAtlases() is called.

As a result, this method is thread safe. It may be called in any thread, including threads other than the main one.

Parameters
charsetThe set of characters in the atlas
Returns
true if the atlases were successfully created.

◆ buildAtlasesAsync() [3/3]

bool cugl::Font::buildAtlasesAsync ( const std::vector< Uint32 > &  charset)

Creates an atlas collection for the given character set.

The atlases generated contains characters in the provided character set, and will omit all other chacters. This includes ASCII characters that may be missing from the character set. The character set provided must be a collection of UNICODE encodings. The Unicode representation uses the endianness native to the platform. Therefore, this value should not be serialized. Use UTF8 to represent unicode in a platform-independent manner.

If there is already an active atlas collection, this method will preserve those atlas textures. Instead, it will only generate atlases for the characters that are not currently supported.

This method does not generate any OpenGL textures, but does all other work in creates the atlases. In particular it creates the image buffers so that texture creation is just one OpenGL call. This creation will happen the first time that storeAtlases() is called.

As a result, this method is thread safe. It may be called in any thread, including threads other than the main one.

Parameters
charsetThe set of characters in the atlas
Returns
true if the atlases were successfully created.

◆ clearAtlases()

void cugl::Font::clearAtlases ( )

Deletes the current collections of atlases

Until a new font atlas is created, any attempt to use this font will result in adhoc atlases (e.g. one-off atlases associated with a single glyph run).

◆ dispose()

virtual void cugl::Font::dispose ( )
virtual

Deletes the font resources and resets all attributes.

This will delete the original font information in addition to any generating atlases. You must reinitialize the font to use it.

◆ getAscent()

int cugl::Font::getAscent ( ) const
inline

Returns the maximum distance from the baseline to the top of a glyph.

This value will always be positive.

Returns
the maximum distance from the baseline to the top of a glyph.

◆ getAtlases()

const std::vector< std::shared_ptr< Texture > > cugl::Font::getAtlases ( )

Returns the OpenGL textures for the associated atlas collection.

When combined with a quad sequence generated by the associate atlas, each texture can be used to draw a font in a SpriteBatch. If there is no atlas collection, this method returns an empty vector.

Returns
the OpenGL textures for the associated atlas collection.

◆ getDescent()

int cugl::Font::getDescent ( ) const
inline

Returns the maximum distance from the baseline to the bottom of a glyph.

This value will always be negative. You should add this value to the y position to shift the baseline down to the rendering origin.

Returns
the maximum distance from the baseline to the bottom of a glyph.

◆ getGlyph() [1/2]

std::shared_ptr< GlyphRun > cugl::Font::getGlyph ( Uint32  thechar,
Vec2 offset 
)

Returns a single glyph run quad to render this character.

The glyph run will consist of a single quad and the texture to render a quad. If the character is not represented by a glyph in the atlas collection, the glyph run will be empty unless setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for this character and return its texture as part of the glyph run. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

This method will append the vertices to the provided mesh and update the indices to include these new vertices. In addition, it will return the texture that should be used with these vertices. Finally, once the glyph is generated, the offset will be adjusted to contain the next place to render a character.

The offset determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The character should be represented by a UNICODE value. For ASCII characters, this agrees with the ASCII code.

Parameters
thecharThe character to convert to render data
offsetThe (unkerned) starting position of the quad
Returns
a single glyph run quad to render this character.

◆ getGlyph() [2/2]

std::shared_ptr< GlyphRun > cugl::Font::getGlyph ( Uint32  thechar,
Vec2 offset,
const Rect  rect 
)

Returns a single glyph run quad to render this character.

The glyph run will consist of a single quad and the texture to render a quad. If the character is not represented by a glyph in the atlas collection, the glyph run will be empty unless setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for this character and return its texture as part of the glyph run. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

This method will append the vertices to the provided mesh and update the indices to include these new vertices. In addition, it will return the texture that should be used with these vertices. Finally, once the glyph is generated, the offset will be adjusted to contain the next place to render a character.

The offset determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The quad is adjusted so that all of the vertices fit in the provided rectangle. This may mean that no quad is generated at all.

The character should be represented by a UNICODE value. For ASCII characters, this agrees with the ASCII code.

Parameters
thecharThe character to convert to render data
offsetThe (unkerned) starting position of the quad
rectThe bounding box for the quad
Returns
a single glyph run quad to render this character.

◆ getGlyphBoxes() [1/8]

Mesh< SpriteVertex2 > cugl::Font::getGlyphBoxes ( const char *  substr,
const char *  end,
const Vec2  origin 
)

Returns a (line) mesh of the quad outlines for the text glyphs.

This method is useful for debugging. When this mesh is drawn together with a glyph run sequence, it shows the bounding box for each glyph. However, these bounding boxes are determined by the glyph metrics, and do not take into account atlas padding. So they do not represent potential overlaps when the padding is non-zero.

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing. The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
substrThe start of the string for glyph generation
endThe end of the string for glyph generation
originThe position of the first character
Returns
a (line) mesh of the quad outlines for the text glyphs

◆ getGlyphBoxes() [2/8]

Mesh< SpriteVertex2 > cugl::Font::getGlyphBoxes ( const char *  substr,
const char *  end,
const Vec2  origin,
const Rect  rect,
float  track = 0 
)

Returns a (line) mesh of the quad outlines for the text glyphs.

This method is useful for debugging. When this mesh is drawn together with a glyph run sequence, it shows the bounding box for each glyph. However, these bounding boxes are determined by the glyph metrics, and do not take into account atlas padding. So they do not represent potential overlaps when the padding is non-zero.

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The mesh sequence is adjusted so that all of the vertices fit in the provided rectangle. The primary use-case for this is to guarantee that glyph boxes do no spill outside of a window. This may mean that some of the boxes will be truncrated or even omitted.

The tracking width is used to justify text in multi-line formats. If track is positive, the spacing between the boxes will be adjusted to fit that width exactly. Once again, this may result in boxes being truncated if either the track width is greater then the rectangle width, or if the font shrink limit is insufficent.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing. The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
substrThe start of the string for glyph generation
endThe end of the string for glyph generation
originThe position of the first character
rectThe bounding box for the mesh
trackThe tracking width (if positive)
Returns
a (line) mesh of the quad outlines for the text glyphs

◆ getGlyphBoxes() [3/8]

Mesh< SpriteVertex2 > cugl::Font::getGlyphBoxes ( const std::string  text,
const Vec2  origin 
)

Returns a (line) mesh of the quad outlines for the text glyphs.

This method is useful for debugging. When this mesh is drawn together with a glyph run sequence, it shows the bounding box for each glyph. However, these bounding boxes are determined by the glyph metrics, and do not take into account atlas padding. So they do not represent potential overlaps when the padding is non-zero.

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
textThe string for glyph generation
originThe position of the first character
Returns
a (line) mesh of the quad outlines for the text glyphs

◆ getGlyphBoxes() [4/8]

Mesh< SpriteVertex2 > cugl::Font::getGlyphBoxes ( const std::string  text,
const Vec2  origin,
const Rect  rect,
float  track = 0 
)

Returns a (line) mesh of the quad outlines for the text glyphs.

This method is useful for debugging. When this mesh is drawn together with a glyph run sequence, it shows the bounding box for each glyph. However, these bounding boxes are determined by the glyph metrics, and do not take into account atlas padding. So they do not represent potential overlaps when the padding is non-zero.

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The mesh sequence is adjusted so that all of the vertices fit in the provided rectangle. The primary use-case for this is to guarantee that glyph boxes do no spill outside of a window. This may mean that some of the boxes will be truncrated or even omitted.

The tracking width is used to justify text in multi-line formats. If track is positive, the spacing between the boxes will be adjusted to fit that width exactly. Once again, this may result in boxes being truncated if either the track width is greater then the rectangle width, or if the font shrink limit is insufficent.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
textThe string to convert to render data.
originThe position of the first character
rectThe bounding box for the mesh
trackThe tracking width (if positive)
Returns
a (line) mesh of the quad outlines for the text glyphs

◆ getGlyphBoxes() [5/8]

size_t cugl::Font::getGlyphBoxes ( Mesh< SpriteVertex2 > &  mesh,
const char *  substr,
const char *  end,
const Vec2  origin 
)

Stores the quad outlines for the text glyphs in the given mesh.

This method is useful for debugging. When this mesh is drawn together with a glyph run sequence, it shows the bounding box for each glyph. However, these bounding boxes are determined by the glyph metrics, and do not take into account atlas padding. So they do not represent potential overlaps when the padding is non-zero.

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing. The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
meshThe mesh to store the new quads
substrThe start of the string for glyph generation
endThe end of the string for glyph generation
originThe position of the first character
Returns
the number of quads generated

◆ getGlyphBoxes() [6/8]

size_t cugl::Font::getGlyphBoxes ( Mesh< SpriteVertex2 > &  mesh,
const char *  substr,
const char *  end,
const Vec2  origin,
const Rect  rect,
float  track = 0 
)

Stores the quad outlines for the text glyphs in the given mesh.

This method is useful for debugging. When this mesh is drawn together with a glyph run sequence, it shows the bounding box for each glyph. However, these bounding boxes are determined by the glyph metrics, and do not take into account atlas padding. So they do not represent potential overlaps when the padding is non-zero.

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The mesh sequence is adjusted so that all of the vertices fit in the provided rectangle. The primary use-case for this is to guarantee that glyph boxes do no spill outside of a window. This may mean that some of the boxes will be truncrated or even omitted.

The tracking width is used to justify text in multi-line formats. If track is positive, the spacing between the boxes will be adjusted to fit that width exactly. Once again, this may result in boxes being truncated if either the track width is greater then the rectangle width, or if the font shrink limit is insufficent.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing. The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
meshThe mesh to store the new quads
substrThe start of the string for glyph generation
endThe end of the string for glyph generation
originThe position of the first character
rectThe bounding box for the mesh
trackThe tracking width (if positive)
Returns
the number of quads generated

◆ getGlyphBoxes() [7/8]

size_t cugl::Font::getGlyphBoxes ( Mesh< SpriteVertex2 > &  mesh,
const std::string  text,
const Vec2  origin 
)

Stores the quad outlines for the text glyphs in the given mesh.

This method is useful for debugging. When this mesh is drawn together with a glyph run sequence, it shows the bounding box for each glyph. However, these bounding boxes are determined by the glyph metrics, and do not take into account atlas padding. So they do not represent potential overlaps when the padding is non-zero.

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
meshThe mesh to store the new quads
textThe string for glyph generation
originThe position of the first character
Returns
the number of quads generated

◆ getGlyphBoxes() [8/8]

size_t cugl::Font::getGlyphBoxes ( Mesh< SpriteVertex2 > &  mesh,
const std::string  text,
const Vec2  origin,
const Rect  rect,
float  track = 0 
)

Stores the quad outlines for the text glyphs in the given mesh.

This method is useful for debugging. When this mesh is drawn together with a glyph run sequence, it shows the bounding box for each glyph. However, these bounding boxes are determined by the glyph metrics, and do not take into account atlas padding. So they do not represent potential overlaps when the padding is non-zero.

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The mesh sequence is adjusted so that all of the vertices fit in the provided rectangle. The primary use-case for this is to guarantee that glyph boxes do no spill outside of a window. This may mean that some of the boxes will be truncrated or even omitted.

The tracking width is used to justify text in multi-line formats. If track is positive, the spacing between the boxes will be adjusted to fit that width exactly. Once again, this may result in boxes being truncated if either the track width is greater then the rectangle width, or if the font shrink limit is insufficent.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
meshThe mesh to store the new quads
textThe string to convert to render data.
originThe position of the first character
rectThe bounding box for the mesh
trackThe tracking width (if positive)
Returns
the number of quads generated

◆ getGlyphs() [1/8]

std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > cugl::Font::getGlyphs ( const char *  substr,
const char *  end,
const Vec2  origin 
)

Returns a set of glyph runs to render the given (sub)string

Each glyph run will consist of a quad mesh and a texture to render those quads. Rendering all of the glyph runs together will render the entire string. Generally the quads are non-overlapping, so any blending mode is supported. However, if the atlas padding is non-zero (to support font blur), the quads will overlap at the padding intervals. Therefore, we recommend alpha blending when you render a string.

The keys for the glyph runs are the Texture#getBuffer values for the appropriate atlas texture. This, combined with the method getAtlases allows you to identify the atlas for each run.

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing. The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
substrThe start of the string for glyph generation
endThe end of the string for glyph generation
originThe position of the first character
Returns
a set of glyph runs to render the given string

◆ getGlyphs() [2/8]

std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > cugl::Font::getGlyphs ( const char *  substr,
const char *  end,
const Vec2  origin,
const Rect  rect,
float  track = 0 
)

Returns a set of glyph runs to render the given string

Each glyph run will consist of a quad mesh and a texture to render those quads. Rendering all of the glyph runs together will render the entire string. Generally the quads are non-overlapping, so any blending mode is supported. However, if the atlas padding is non-zero (to support font blur), the quads will overlap at the padding intervals. Therefore, we recommend alpha blending when you render a string.

The keys for the glyph runs are the Texture#getBuffer values for the appropriate atlas texture. This, combined with the method getAtlases allows you to identify the atlas for each run.

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The quad sequence is adjusted so that all of the vertices fit in the provided rectangle. The primary use-case for this is to guarantee that glyphs do no spill outside of a window. This may mean that some of the glyphs will be truncrated or even omitted.

The tracking width is used to justify text in multi-line formats. If track is positive, the spacing between the glyphs will be adjusted to fit that width exactly. Once again, this may result in glyphs being truncated if either the track width is greater then the rectangle width, or if the font shrink limit is insufficent.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing. The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
substrThe start of the string for glyph generation
endThe end of the string for glyph generation
originThe position of the first character
rectThe bounding box for the quads
trackThe tracking width (if positive)
Returns
a set of glyph runs to render the given string

◆ getGlyphs() [3/8]

std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > cugl::Font::getGlyphs ( const std::string  text,
const Vec2  origin 
)

Returns a set of glyph runs to render the given string

Each glyph run will consist of a quad mesh and a texture to render those quads. Rendering all of the glyph runs together will render the entire string. Generally the quads are non-overlapping, so any blending mode is supported. However, if the atlas padding is non-zero (to support font blur), the quads will overlap at the padding intervals. Therefore, we recommend alpha blending when you render a string.

The keys for the glyph runs are the Texture#getBuffer values for the appropriate atlas texture. This, combined with the method getAtlases allows you to identify the atlas for each run.

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
textThe string for glyph generation
originThe position of the first character
Returns
a set of glyph runs to render the given string

◆ getGlyphs() [4/8]

std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > cugl::Font::getGlyphs ( const std::string  text,
const Vec2  origin,
const Rect  rect,
float  track = 0 
)

Returns a set of glyph runs to render the given string

Each glyph run will consist of a quad mesh and a texture to render those quads. Rendering all of the glyph runs together will render the entire string. Generally the quads are non-overlapping, so any blending mode is supported. However, if the atlas padding is non-zero (to support font blur), the quads will overlap at the padding intervals. Therefore, we recommend alpha blending when you render a string.

The keys for the glyph runs are the Texture#getBuffer values for the appropriate atlas texture. This, combined with the method getAtlases allows you to identify the atlas for each run.

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The quad sequence is adjusted so that all of the vertices fit in the provided rectangle. The primary use-case for this is to guarantee that glyphs do no spill outside of a window. This may mean that some of the glyphs will be truncrated or even omitted.

The tracking width is used to justify text in multi-line formats. If track is positive, the spacing between the glyphs will be adjusted to fit that width exactly. Once again, this may result in glyphs being truncated if either the track width is greater then the rectangle width, or if the font shrink limit is insufficent.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
textThe string for glyph generation
originThe position of the first character
rectThe bounding box for the quads
trackThe tracking width (if positive)
Returns
a set of glyph runs to render the given string

◆ getGlyphs() [5/8]

size_t cugl::Font::getGlyphs ( std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > &  runs,
const char *  substr,
const char *  end,
const Vec2  origin 
)

Stores the glyph runs to render the given string in the given map

Each glyph run will consist of a quad mesh and a texture to render those quads. Rendering all of the glyph runs together will render the entire string. Generally the quads are non-overlapping, so any blending mode is supported. However, if the atlas padding is non-zero (to support font blur), the quads will overlap at the padding intervals. Therefore, we recommend alpha blending when you render a string.

The keys for the glyph runs are the Texture#getBuffer values for the appropriate atlas texture. This, combined with the method getAtlases allows you to identify the atlas for each run. If the map is non-empty, the glyph run data will be appended to the relevant existing glyph run (if possible).

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
runsThe map to store the glyph runs
substrThe start of the string for glyph generation
endThe end of the string for glyph generation
originThe position of the first character
Returns
the number of glyphs successfully processed

◆ getGlyphs() [6/8]

size_t cugl::Font::getGlyphs ( std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > &  runs,
const char *  substr,
const char *  end,
const Vec2  origin,
const Rect  rect,
float  track = 0 
)

Stores the glyph runs to render the given string in the given map

Each glyph run will consist of a quad mesh and a texture to render those quads. Rendering all of the glyph runs together will render the entire string. Generally the quads are non-overlapping, so any blending mode is supported. However, if the atlas padding is non-zero (to support font blur), the quads will overlap at the padding intervals. Therefore, we recommend alpha blending when you render a string.

The keys for the glyph runs are the Texture#getBuffer values for the appropriate atlas texture. This, combined with the method getAtlases allows you to identify the atlas for each run. If the map is non-empty, the glyph run data will be appended to the relevant existing glyph run (if possible).

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The quad sequence is adjusted so that all of the vertices fit in the provided rectangle. The primary use-case for this is to guarantee that glyphs do no spill outside of a window. This may mean that some of the glyphs will be truncrated or even omitted.

The tracking width is used to justify text in multi-line formats. If track is positive, the spacing between the glyphs will be adjusted to fit that width exactly. Once again, this may result in glyphs being truncated if either the track width is greater then the rectangle width, or if the font shrink limit is insufficent.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
runsThe map to store the glyph runs
substrThe start of the string for glyph generation
endThe end of the string for glyph generation
originThe position of the first character
rectThe bounding box for the quads
trackThe tracking width (if positive)
Returns
the number of glyphs successfully processed

◆ getGlyphs() [7/8]

size_t cugl::Font::getGlyphs ( std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > &  runs,
const std::string  text,
const Vec2  origin 
)

Stores the glyph runs to render the given string in the given map

Each glyph run will consist of a quad mesh and a texture to render those quads. Rendering all of the glyph runs together will render the entire string. Generally the quads are non-overlapping, so any blending mode is supported. However, if the atlas padding is non-zero (to support font blur), the quads will overlap at the padding intervals. Therefore, we recommend alpha blending when you render a string.

The keys for the glyph runs are the Texture#getBuffer values for the appropriate atlas texture. This, combined with the method getAtlases allows you to identify the atlas for each run. If the map is non-empty, the glyph run data will be appended to the relevant existing glyph run (if possible).

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing. The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
runsThe map to store the glyph runs
textThe string for glyph generation
originThe position of the first character
Returns
the number of glyphs successfully processed

◆ getGlyphs() [8/8]

size_t cugl::Font::getGlyphs ( std::unordered_map< GLuint, std::shared_ptr< GlyphRun > > &  runs,
const std::string  text,
const Vec2  origin,
const Rect  rect,
float  track = 0 
)

Stores the glyph runs to render the given string in the given map

Each glyph run will consist of a quad mesh and a texture to render those quads. Rendering all of the glyph runs together will render the entire string. Generally the quads are non-overlapping, so any blending mode is supported. However, if the atlas padding is non-zero (to support font blur), the quads will overlap at the padding intervals. Therefore, we recommend alpha blending when you render a string.

The keys for the glyph runs are the Texture#getBuffer values for the appropriate atlas texture. This, combined with the method getAtlases allows you to identify the atlas for each run. If the map is non-empty, the glyph run data will be appended to the relevant existing glyph run (if possible).

If a character in the string is not represented by a glyph in the atlas collection, then it will be skipped unless the value setAtlasFallback is set to true. In that case, this method will generate a one-time atlas for these characters and return its texture as part of the set. However, this atlas will not be stored for future use. In addition, forcing this creation of a fallback atlas makes this method no longer safe to be used outside of the main thread (this is not an issue if hasAtlasFallback is false). Note that control characters (e.g. newlines) have no glyphs.

The origin value determines the position of the bottom of the text baseline. You should use the methods getDescent and getAscent to place either the bottom or top of the text, respectively.

The quad sequence is adjusted so that all of the vertices fit in the provided rectangle. The primary use-case for this is to guarantee that glyphs do no spill outside of a window. This may mean that some of the glyphs will be truncrated or even omitted.

The tracking width is used to justify text in multi-line formats. If track is positive, the spacing between the glyphs will be adjusted to fit that width exactly. Once again, this may result in glyphs being truncated if either the track width is greater then the rectangle width, or if the font shrink limit is insufficent.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing. The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
runsThe map to store the glyph runs
textThe string for glyph generation
originThe position of the first character
rectThe bounding box for the quads
trackThe tracking width (if positive)
Returns
the number of glyphs successfully processed

◆ getHeight()

int cugl::Font::getHeight ( ) const
inline

Returns the maximum height of this font.

This is the sum of the ascent and the negative descent. Any box that is this many characters high can sucessfully hold a glyph from this font.

Returns
the maximum height of this font.

◆ getHinting()

Hinting cugl::Font::getHinting ( ) const
inline

Returns the rasterization hints

Hinting is used to align the font to a rasterized grid. At low screen resolutions, hinting is critical for producing clear, legible text (particularly if you are not supporting antialiasing).

Returns
the rasterization hints

◆ getInternalBounds() [1/2]

Rect cugl::Font::getInternalBounds ( const char *  substr,
const char *  end 
) const

Returns the pixel offset of the glyphs inside a rendered string.

The result of getSize() is very conservative. Even if no character uses the maximum height, it provides the full height of the font. Furthermore, if the last character does not use the full advance, there will be padding after that character.

The rectangle returned by this method provide the internal bounds of the rendered text. The value is in "text space". If a string is rendered at position (0,0), this is the bounding box for all of the glyphs that are actually rendered. It is the tightest bounding box that can fit all of the generated glyph. You can use this rectangle to eliminate any font-specific spacing that may have been placed around the glyphs.

For example, suppose the string is "ah". In many fonts, these two glyphs would not dip below the baseline. Therefore, the y value of the returned rectangle would be at the font baseline (which is always 0), indicating that it is safe to start rendering there.

This measurement does not actually render the string. This method will not fail if it includes glyphs that are not present in the font, but it will drop them when measuring the size.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing. The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
substrThe start of the string to measure
endThe end of the string to measure
Returns
the size of the quad sequence generated for this string.

◆ getInternalBounds() [2/2]

Rect cugl::Font::getInternalBounds ( const std::string  text) const

Returns the pixel offset of the glyphs inside a rendered string.

The result of getSize() is very conservative. Even if no character uses the maximum height, it provides the full height of the font. Furthermore, if the last character does not use the full advance, there will be padding after that character.

The rectangle returned by this method provide the internal bounds of the rendered text. The value is in "text space". If a string is rendered at position (0,0), this is the bounding box for all of the glyphs that are actually rendered. It is the tightest bounding box that can fit all of the generated glyph. You can use this rectangle to eliminate any font-specific spacing that may have been placed around the glyphs.

For example, suppose the string is "ah". In many fonts, these two glyphs would not dip below the baseline. Therefore, the y value of the returned rectangle would be at the font baseline (which is always 0), indicating that it is safe to start rendering there.

This measurement does not actually render the string. This method will not fail if it includes glyphs that are not present in the font, but it will drop them when measuring the size.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
textThe string to measure
Returns
the size of the quad sequence generated for this string.

◆ getKerning()

unsigned int cugl::Font::getKerning ( Uint32  a,
Uint32  b 
) const

Returns the kerning adjustment between the two (Unicode) characters.

This value is the amount of overlap (in pixels) between any two adjacent character glyphs rendered by this font. If the value is 0, there is no kerning for this pair.

The Unicode representation uses the endianness native to the platform. Therefore, this value should not be serialized. Use UTF8 to represent unicode in a platform-independent manner. See the function strtool::getCodePoints for how to get a unicode codepoint from a UTF8 string.

Parameters
aThe first Unicode character in the pair
bThe second Unicode character in the pair
Returns
the kerning adjustment between the two (Unicode) characters.

◆ getLineSkip()

int cugl::Font::getLineSkip ( ) const
inline

Returns the recommended lineskip of this font.

The line skip is the recommended height of a line of text. It is often larger than the font height.

Returns
the recommended lineskip of this font.

◆ getMetrics()

const Metrics cugl::Font::getMetrics ( Uint32  thechar) const

Returns the glyph metrics for the given (Unicode) character.

See Metrics for an explanation of the data provided by this method. This method will fail if the glyph is not in this font. In particular, control characters (e.g. newlines) will fail while spaces will not.

The Unicode representation uses the endianness native to the platform. Therefore, this value should not be serialized. Use UTF8 to represent unicode in a platform-independent manner. See the function strtool::getCodePoints for how to get a unicode codepoint from a UTF8 string.

Parameters
thecharThe Unicode character to measure.
Returns
the glyph metrics for the given (Unicode) character.

◆ getName()

const std::string cugl::Font::getName ( ) const
inline

Returns the family name of this font.

This method may return an empty string, meaning the information is not available.

Returns
the family name of this font.

◆ getPadding()

Uint32 cugl::Font::getPadding ( ) const
inline

Returns the atlas padding

The atlas padding the guaranteed padding between glyphs in the textures for the atlas collection. By default, glyphs are no more than a pixel apart from each other, to minimize texture size. This value represents the individual pixels to add along all four borders of the glyph.

However, this prevents font blur effects, as the individual glyphs will blur into each other. If you plan to render a font with a non-zero value to SpriteBatch#setBlur, then you must add padding equal to or exceeding the radius.

Returns
the atlas padding

◆ getPointSize()

int cugl::Font::getPointSize ( ) const
inline

Returns the point size of this font.

The point size does not convey any metric information about this font. However, it is important for scaling the font to other sizes.

Returns
the point size of this font.

◆ getShrinkLimit()

Uint32 cugl::Font::getShrinkLimit ( ) const
inline

Returns the limit for shrinking the advance during tracking

A font can provided limited tracking support to shrink or grow the space between characters (in order to fit a glyph run to a given width). This value is the maximum number of units that tracking will ever reduce the advance between two characters. This limit is applied uniformly to all characters, including spaces.

By default this value is 0, disabling all (negative) tracking.

Returns
the limit for shrinking the advance during tracking

◆ getSize() [1/2]

Size cugl::Font::getSize ( const char *  substr,
const char *  end 
) const

Returns the size (in pixels) necessary to render this string.

This size is a conservative estimate to render the string. The height is guaranteed to be the maximum height of the font, regardless of the text measured. In addition, the measurement will include the full advance of the both the first and last characters. This means that there may be some font-specific padding around these characters.

The y-origin of this rectangle is guaranteed to be getDescent. That is because glyphs will use the baseline as the origin when rendering the text.

This measurement does not actually render the string. This method will not fail if it includes glyphs that are not present in the font, but it will drop them when measuring the size.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing. The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
substrThe start of the string to measure
endThe end of the string to measure
Returns
the size (in pixels) necessary to render this string.

◆ getSize() [2/2]

Size cugl::Font::getSize ( const std::string  text) const

Returns the size (in pixels) necessary to render this string.

This size is a conservative estimate to render the string. The height is guaranteed to be the maximum height of the font, regardless of the text measured. In addition, the measurement will include the full advance of the both the first and last characters. This means that there may be some font-specific padding around these characters.

The y-origin of this rectangle is guaranteed to be getDescent. That is because glyphs will use the baseline as the origin when rendering the text.

This measurement does not actually render the string. This method will not fail if it includes glyphs that are not present in the font, but it will drop them when measuring the size.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
textThe string to measure
Returns
the size (in pixels) necessary to render this string.

◆ getStretchLimit()

Uint32 cugl::Font::getStretchLimit ( ) const
inline

Returns the limit for stretching the advance during tracking

A font can provided limited tracking support to shrink or grow the space between characters (in order to fit a glyph run to a given width). This value is the maximum number of units that tracking will ever grow the advance between two (non-space) characters.

By default this value is 0. That means that any positive tracking will be applied to spaces only. In that case, the result would be equivalent to old-school justification, which stretches a line by only resizing whitespace.

Returns
the limit for stretching the advance during tracking

◆ getStyle()

Style cugl::Font::getStyle ( ) const
inline

Returns the style for this font.

With the exception of normal style (which is an absent of any style), all of the styles may be combined. So it is possible to have a bold, italic, underline font with strikethrough. To combine styles, simply treat the Style value as a bitmask, and combine them with bitwise operations.

Returns
the style for this font.

◆ getStyleName()

const std::string cugl::Font::getStyleName ( ) const
inline

Returns the style name of this font.

This method may return an empty string, meaning the information is not available.

Returns
the style name of this font.

◆ getTracking() [1/2]

std::vector< int > cugl::Font::getTracking ( const char *  substr,
const char *  end,
float  width 
)

Returns the tracking adjustments to fit the text in the given width

Unlike kerning, tracking is used to dynamically adjust the spaces between characters. The purpose is to fix the text to the given width exactly (or as close as possible). Usually this means shrinking the space when the text is larger than the width. But in the case of justification, it may also be used to increase the space. The number of tracking measurements is one less than the number of characters.

All tracking is measured in integer offsets. That is because text looks more uniform when glyph positions are at integral values (otherwise the texture may shimmer on movement). Whenever possible, the algorithm will try to track the text to within 1 unit of the width (under, not over). In the case of shrinking, this may not be possible if the shrink limit is too low.

Tracking adjustments will be uniform between non-space characters. If any non-uniform adjustments need to be made, they will be made around white-space.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing. The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
substrThe start of the string to measure
endThe end of the string to measure
widthThe line width
Returns
the tracking adjustments to fit the text in the given width

◆ getTracking() [2/2]

std::vector< int > cugl::Font::getTracking ( const std::string  text,
float  width 
)

Returns the tracking adjustments to fit the text in the given width

Unlike kerning, tracking is used to dynamically adjust the spaces between characters. The purpose is to fix the text to the given width exactly (or as close as possible). Usually this means shrinking the space when the text is larger than the width. But in the case of justification, it may also be used to increase the space. The number of tracking measurements is one less than the number of characters.

All tracking is measured in integer offsets. That is because text looks more uniform when glyph positions are at integral values (otherwise the texture may shimmer on movement). Whenever possible, the algorithm will try to track the text to within 1 unit of the width (under, not over). In the case of shrinking, this may not be possible if the shrink limit is too low.

Tracking adjustments will be uniform between non-space characters. If any non-uniform adjustments need to be made, they will be made around white-space.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
textThe text to measure
widthThe line width
Returns
the tracking adjustments to fit the text in the given width

◆ hasAtlas()

bool cugl::Font::hasAtlas ( Uint32  thechar) const
inline

Returns true if the given unicode character has atlas support.

If this method is true, then getGlyphs() is guaranteed to succeed and be thread safe, whenever the text is consists of the provide character.

The characters provided should be represented by a UNICODE value. The Unicode representation uses the endianness native to the platform. Therefore, this value should not be serialized. Use UTF8 to represent unicode in a platform-independent manner.

Parameters
thecharThe character to test (as UNICODE)
Returns
true if the given characters have atlas support.

◆ hasAtlases() [1/2]

bool cugl::Font::hasAtlases ( const std::string  charset) const

Returns true if the given characters have atlas support.

If this method is true, then getGlyphs() is guaranteed to succeed and be thread safe, whenever the text is consists of provided characters.

The characters provided should be in UTF8 or ASCII format.

Parameters
charsetThe characters to test (as UTF8 or ASCII)
Returns
true if the given characters have atlas support.

◆ hasAtlases() [2/2]

bool cugl::Font::hasAtlases ( const std::vector< Uint32 > &  charset) const

Returns true if the given characters have atlas support.

If this method is true, then getGlyphs() is guaranteed to succeed and be thread safe, whenever the text is consists of provided characters.

The characters provided should be represented by UNICODE values. The Unicode representation uses the endianness native to the platform. Therefore, this value should not be serialized. Use UTF8 to represent unicode in a platform-independent manner.

Parameters
charsetThe characters to test (as UNICODE)
Returns
true if the given characters have atlas support.

◆ hasAtlasFallback()

bool cugl::Font::hasAtlasFallback ( ) const
inline

Returns true if this font generates a fallback atlas for glyph runs.

When creating a set of glyphs run it is possible for some of the glyphs to be supported by the font, but missing from the all of the atlases. This is particularly true for unicode characters beyond the ascii range. By default, the glyph run set will simply omit this glyphs.

However, if this value is set to true, the glyph run methods like getGlyphs will generate a one-time atlas for the missing characters. This atlas will not be stored for future use. In addition, forcing this creation means that the glyph generation methods are no longer safe to be used outside of the main thread (this is not an issue if this attribute is false).

Returns
true if this font generates a fallback atlas for glyph runs.

◆ hasGlyph()

bool cugl::Font::hasGlyph ( Uint32  a) const

Returns true if this font has a glyph for the given (UNICODE) character.

The Unicode representation uses the endianness native to the platform. Therefore, this value should not be serialized. Use UTF8 to represent unicode in a platform-independent manner.

This method is not an indication of whether or not there is a font atlas for this font. It is simply an indication whether or not this glyphs are present in the font source. Note that control characters (like newline) never have glyphs. However, spaces do.

Parameters
aThe Unicode character to check.
Returns
true if this font has a glyph for the given (UNICODE) character.

◆ hasGlyphs() [1/2]

bool cugl::Font::hasGlyphs ( const std::string  glyphs) const

Returns true if this font can successfuly render the given glyphs.

This method is not an indication of whether or not there is a font atlas for this font. It is simply an indication whether or not these glyphs are present in the font source. Note that control characters (like newline) never have glyphs. However, spaces do.

This method will return false if just one glyph is missing. The glyph identifiers may either be in UTF8 or ASCII; the method will handle conversion automatically.

Parameters
glyphsThe glyph identifiers to check.
Returns
true if this font can successfuly render the given glyphs.

◆ hasGlyphs() [2/2]

bool cugl::Font::hasGlyphs ( const std::vector< Uint32 > &  glyphs) const
inline

Returns true if this font can successfuly render the given glyphs.

This method is not an indication of whether or not there is a font atlas for this font. It is simply an indication whether or not these glyphs are present in the font source. Note that control characters (like newline) never have glyphs. However, spaces do.

This method will return false if just one glyph is missing. The glyph identifiers should be the UNICODE values. The Unicode representation uses the endianness native to the platform. Therefore, these values should not be serialized. You should use UTF8 to represent unicode in a platform-independent manner.

Parameters
glyphsThe glyph identifiers to check.
Returns
true if this font can successfuly render the given glyphs.

◆ init()

bool cugl::Font::init ( const std::string  file,
Uint32  size 
)

Initializes a font of the given size from the file.

The font size is fixed on initialization. It cannot be changed without disposing of the entire font. However, all other attributes may be changed.

Parameters
fileThe file with the font asset
sizeThe font size in points
Returns
true if initialization is successful.

◆ isFixedWidth()

bool cugl::Font::isFixedWidth ( ) const
inline

Returns true if the font is a fixed width font.

Fixed width fonts are monospace, meaning every character that exists in the font is the same width. In this case you can assume that a rendered string's width is going to be the result of a simple calculation:

 glyph_width * string_length
Returns
true if the font is a fixed width font.

◆ setAtlasFallback()

void cugl::Font::setAtlasFallback ( bool  fallback)
inline

Sets whether to generate a fallback atlas for glyph runs.

When creating a set of glyphs run it is possible for some of the glyphs to be supported by the font, but missing from the all of the atlases. This is particularly true for unicode characters beyond the ascii range. By default, the glyph run set will simply omit this glyphs.

However, if this value is set to true, the glyph run methods like getGlyphs will generate a one-time atlas for the missing characters. This atlas will not be stored for future use. In addition, forcing this creation means that the glyph generation methods are no longer safe to be used outside of the main thread (this is not an issue if this attribute is false).

Parameters
fallbackWhether to generate a fallback atlas for glyph runs.

◆ setHinting()

void cugl::Font::setHinting ( Hinting  hinting)

Sets the rasterization hints

Changing this value will delete any atlas that is present. The atlas must be regenerated.

Hinting is used to align the font to a rasterized grid. At low screen resolutions, hinting is critical for producing clear, legible text (particularly if you are not supporting antialiasing).

Reseting this value will clear any existing atlas collection.

Parameters
hintingThe rasterization hints

◆ setKerning()

void cugl::Font::setKerning ( bool  kerning)

Sets whether this font atlas uses kerning when rendering.

Without kerning, each character is guaranteed to take up its entire advance when rendered. This may make spacing look awkard. This value is true by default.

Note that kerning is different from tracking (see getGlyphs). Tracking is u␐sed to dynamically shrink or stretch the text to fit a given region, while kerning is used at all times.

Reseting this value will clear any existing atlas collection.

Parameters
kerningWhether this font atlas uses kerning when rendering.

◆ setPadding()

void cugl::Font::setPadding ( Uint32  padding)

Sets the atlas padding

The atlas padding the guaranteed padding between glyphs in the textures for the atlas collection. By default, glyphs are no more than a pixel apart from each other, to minimize texture size. This value represents the individual pixels to add along all four borders of the glyph.

However, this prevents font blur effects, as the individual glyphs will blur into each other. If you plan to render a font with a non-zero value to SpriteBatch#setBlur, then you must add padding equal to or exceeding the radius.

Reseting this value will clear any existing atlas collection.

Parameters
paddingThe additional atlas padding

◆ setShrinkLimit()

void cugl::Font::setShrinkLimit ( Uint32  limit)
inline

Sets the limit for shrinking the advance during tracking

A font can provided limited tracking support to shrink or grow the space between characters (in order to fit a glyph run to a given width). This value is the maximum number of units that tracking will ever reduce the advance between two characters. This limit is applied uniformly to all characters, including spaces.

By default this value is 0, disabling all (negative) tracking.

Parameters
limitThe limit for shrinking the advance during tracking

◆ setStretchLimit()

void cugl::Font::setStretchLimit ( Uint32  limit)
inline

Sets the limit for stretching the advance during tracking

A font can provided limited tracking support to shrink or grow the space between characters (in order to fit a glyph run to a given width). This value is the maximum number of units that tracking will ever grow the advance between two (non-space) characters.

By default this value is 0. That means that any positive tracking will be applied to spaces only. In that case, the result would be equivalent to old-school justification, which stretches a line by only resizing whitespace.

Parameters
limitThe limit for stretching the advance during tracking

◆ setStyle()

void cugl::Font::setStyle ( Style  style)

Sets the style for this font.

Changing this value will delete any atlas that is present. The atlas must be regenerated.

With the exception of normal style (which is an absent of any style), all of the styles may be combined. So it is possible to have a bold, italic, underline font with strikethrough. To combine styles, simply treat the Style value as a bitmask, and combine them with bitwise operations.

Reseting this value will clear any existing atlas collection.

Parameters
styleThe style for this font.

◆ storeAtlases()

bool cugl::Font::storeAtlases ( )

Creates an OpenGL texture for each atlas in the collection.

This method should be called to finalize the work of buildAtlasesAsync. This method must be called on the main thread.

◆ usesKerning()

bool cugl::Font::usesKerning ( ) const
inline

Returns true if this font atlas uses kerning when rendering.

Without kerning, each character is guaranteed to take up its entire advance when rendered. This may make spacing look awkard. This value is true by default.

Note that kerning is different from tracking (see getGlyphs). Tracking is u␐sed to dynamically shrink or stretch the text to fit a given region, while kerning is used at all times.

Returns
true if this font atlas uses kerning when rendering.

Member Data Documentation

◆ _atlases

std::vector<std::shared_ptr<Atlas> > cugl::Font::_atlases
protected

The individual atlases for this font

◆ _atlasmap

std::unordered_map<Uint32, size_t> cugl::Font::_atlasmap
protected

The atlas storing any particular character

◆ _atlasPadding

Uint32 cugl::Font::_atlasPadding
protected

The number of pixels to pad around each edge of a glyph. Necessary to support font blurs.

◆ _data

TTF_Font* cugl::Font::_data
protected

The underlying SDL data

◆ _fallback

bool cugl::Font::_fallback
protected

Whether to generate an impromptu atlas for missing glyphs

◆ _fixedWidth

bool cugl::Font::_fixedWidth
protected

Whether this is a fixed width font

◆ _fontAscent

int cugl::Font::_fontAscent
protected

The maximum distance from the baseline to the glyph top (always positive)

◆ _fontDescent

int cugl::Font::_fontDescent
protected

The maximum distance from the baseline to the glyph bottom (always negative)

◆ _fontHeight

int cugl::Font::_fontHeight
protected

The (maximum) height of this font. It is the sum of ascent and descent.

◆ _fontLineSkip

int cugl::Font::_fontLineSkip
protected

The recommended line skip for this font

◆ _fontSize

int cugl::Font::_fontSize
protected

The point size of this font.

◆ _glyphsize

std::unordered_map<Uint32, Metrics> cugl::Font::_glyphsize
protected

The cached metrics for each font glyph. This does not include padding.

◆ _hints

Hinting cugl::Font::_hints
protected

The rasterization hints

◆ _kernmap

std::unordered_map<Uint32, std::unordered_map<Uint32, Uint32> > cugl::Font::_kernmap
protected

The kerning for each pair of characters

◆ _name

std::string cugl::Font::_name
protected

The name of this font (typically the family name if known)

◆ _shrinkLimit

int cugl::Font::_shrinkLimit
protected

The maximum number of pixels to reduce the advance when shrinking a line

◆ _stretchLimit

int cugl::Font::_stretchLimit
protected

The maximum number of pixels to grow the advance when stretching a line

◆ _style

Style cugl::Font::_style
protected

The font face style

◆ _stylename

std::string cugl::Font::_stylename
protected

The name of this font style

◆ _useKerning

bool cugl::Font::_useKerning
protected

Whether to use kerning when rendering


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