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< GlyphRun >	getGlyph (Uint32 thechar, Vec2 &offset)
std::shared_ptr< GlyphRun >	getGlyph (Uint32 thechar, Vec2 &offset, const Rect rect)
Mesh< SpriteVertex2 >	getGlyphBoxes (const std::string text, const Vec2 origin)
Mesh< SpriteVertex2 >	getGlyphBoxes (const char *substr, const char *end, const Vec2 origin)
Mesh< SpriteVertex2 >	getGlyphBoxes (const std::string text, const Vec2 origin, const Rect rect, float track=0)
Mesh< SpriteVertex2 >	getGlyphBoxes (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< Font >	alloc (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

file	The file with the font asset
size	The 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

charset

The 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

charset

The 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

charset

The 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

charset

The 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

thechar	The character to convert to render data
offset	The (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

thechar	The character to convert to render data
offset	The (unkerned) starting position of the quad
rect	The 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

substr	The start of the string for glyph generation
end	The end of the string for glyph generation
origin	The 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

substr	The start of the string for glyph generation
end	The end of the string for glyph generation
origin	The position of the first character
rect	The bounding box for the mesh
track	The 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

text	The string for glyph generation
origin	The 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

text	The string to convert to render data.
origin	The position of the first character
rect	The bounding box for the mesh
track	The 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

mesh	The mesh to store the new quads
substr	The start of the string for glyph generation
end	The end of the string for glyph generation
origin	The 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

mesh	The mesh to store the new quads
substr	The start of the string for glyph generation
end	The end of the string for glyph generation
origin	The position of the first character
rect	The bounding box for the mesh
track	The 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

mesh	The mesh to store the new quads
text	The string for glyph generation
origin	The 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

mesh	The mesh to store the new quads
text	The string to convert to render data.
origin	The position of the first character
rect	The bounding box for the mesh
track	The 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

substr	The start of the string for glyph generation
end	The end of the string for glyph generation
origin	The 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

substr	The start of the string for glyph generation
end	The end of the string for glyph generation
origin	The position of the first character
rect	The bounding box for the quads
track	The 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

text	The string for glyph generation
origin	The 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

text	The string for glyph generation
origin	The position of the first character
rect	The bounding box for the quads
track	The 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

runs	The map to store the glyph runs
substr	The start of the string for glyph generation
end	The end of the string for glyph generation
origin	The 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

runs	The map to store the glyph runs
substr	The start of the string for glyph generation
end	The end of the string for glyph generation
origin	The position of the first character
rect	The bounding box for the quads
track	The 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

runs	The map to store the glyph runs
text	The string for glyph generation
origin	The 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

runs	The map to store the glyph runs
text	The string for glyph generation
origin	The position of the first character
rect	The bounding box for the quads
track	The 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

substr	The start of the string to measure
end	The 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

text	The 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

a	The first Unicode character in the pair
b	The 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

thechar

The 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

substr	The start of the string to measure
end	The 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

text	The 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

substr	The start of the string to measure
end	The end of the string to measure
width	The 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

text	The text to measure
width	The 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

thechar

The 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

charset

The 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

charset

The 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

a	The 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

glyphs

The 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

glyphs

The 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

file	The file with the font asset
size	The 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

fallback

Whether 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

hinting

The 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

kerning

Whether 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

padding

The 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

limit

The 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

limit

The 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

style

The 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:

• cugl/include/cugl/render/CUFont.h