CUGL 2.0
Cornell University Game Library
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
cugl::Font Class Reference

#include <CUFont.h>

Classes

class  Metrics
 

Public Types

enum  Style : int {
  Style::NORMAL = TTF_STYLE_NORMAL, Style::BOLD = TTF_STYLE_BOLD, Style::ITALIC = TTF_STYLE_ITALIC, Style::UNDERLINE = TTF_STYLE_UNDERLINE,
  Style::STRIKE = TTF_STYLE_STRIKETHROUGH
}
 
enum  Hinting : int { Hinting::NORMAL = TTF_HINTING_NORMAL, Hinting::LIGHT = TTF_HINTING_LIGHT, Hinting::MONO = TTF_HINTING_MONO, Hinting::NONE = TTF_HINTING_NONE }
 
enum  Resolution : int { Resolution::SOLID = 0, Resolution::SHADED = 1, Resolution::BLENDED = 2 }
 

Public Member Functions

 Font ()
 
 ~Font ()
 
virtual void dispose ()
 
bool init (const std::string file, int size)
 
const std::string & getName () const
 
const std::string & getStyleName () const
 
int getHeight () const
 
int getDescent () const
 
int getAscent () const
 
int getLineSkip () const
 
bool isFixedWidth () const
 
bool usesKerning () const
 
void setKerning (bool kerning)
 
bool hasGlyph (char a) const
 
bool hasGlyph (Uint32 a) const
 
bool hasString (const std::string text) const
 
Style getStyle () const
 
void setStyle (Style style)
 
Hinting getHinting () const
 
void setHinting (Hinting hinting)
 
Resolution getResolution () const
 
void setResolution (Resolution resolution)
 
const Metrics getMetrics (char thechar) const
 
const Metrics getMetrics (Uint32 thechar) const
 
unsigned int getKerning (char a, char b) const
 
unsigned int getKerning (Uint32 a, Uint32 b) const
 
Size getSize (const std::string text, bool utf8=true) const
 
Rect getInternalBounds (const std::string text, bool utf8=true) const
 
void clearAtlas ()
 
bool buildAtlas ()
 
bool buildAtlas (const std::string charset)
 
bool buildAtlasAsync ()
 
bool buildAtlasAsync (const std::string charset)
 
const std::shared_ptr< Texture > & getAtlas ()
 
bool hasAtlas () const
 
std::shared_ptr< TexturegetMesh (const std::string text, const Vec2 origin, Mesh< SpriteVertex2 > &mesh, bool utf8=true)
 
std::shared_ptr< TexturegetMesh (const std::string text, const Vec2 origin, const Rect rect, Mesh< SpriteVertex2 > &mesh, bool utf8=true)
 
std::shared_ptr< TexturegetQuad (Uint32 thechar, Vec2 &offset, Mesh< SpriteVertex2 > &mesh)
 
std::shared_ptr< TexturegetQuad (Uint32 thechar, Vec2 &offset, const Rect rect, Mesh< SpriteVertex2 > &mesh)
 
std::shared_ptr< TexturegetMesh (const std::string text, const Vec2 origin, Mesh< SpriteVertex3 > &mesh, float z=0, bool utf8=true)
 
std::shared_ptr< TexturegetMesh (const std::string text, const Vec2 origin, const Rect rect, Mesh< SpriteVertex3 > &mesh, float z=0, bool utf8=true)
 
std::shared_ptr< TexturegetQuad (Uint32 thechar, Vec2 &offset, Mesh< SpriteVertex3 > &mesh, float z=0)
 
std::shared_ptr< TexturegetQuad (Uint32 thechar, Vec2 &offset, const Rect rect, Mesh< SpriteVertex3 > &mesh, float z=0)
 

Static Public Member Functions

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

Protected Member Functions

void getAtlasMesh (const std::string text, const Vec2 origin, const Rect rect, Mesh< SpriteVertex2 > &mesh, bool utf8)
 
std::shared_ptr< TexturegetRenderedMesh (const std::string text, const Vec2 origin, const Rect rect, Mesh< SpriteVertex2 > &mesh, bool utf8)
 
bool getAtlasQuad (Uint32 thechar, Vec2 &offset, const Rect rect, Mesh< SpriteVertex2 > &mesh)
 
std::shared_ptr< TexturegetRenderedQuad (Uint32 thechar, Vec2 &offset, const Rect rect, Mesh< SpriteVertex2 > &mesh)
 
void getAtlasMesh (const std::string text, const Vec2 origin, const Rect rect, Mesh< SpriteVertex3 > &mesh, float z, bool utf8)
 
std::shared_ptr< TexturegetRenderedMesh (const std::string text, const Vec2 origin, const Rect rect, Mesh< SpriteVertex3 > &mesh, float z, bool utf8)
 
bool getAtlasQuad (Uint32 thechar, Vec2 &offset, const Rect rect, Mesh< SpriteVertex3 > &mesh, float z)
 
std::shared_ptr< TexturegetRenderedQuad (Uint32 thechar, Vec2 &offset, const Rect rect, Mesh< SpriteVertex3 > &mesh, float z)
 
Size getSizeASCII (const std::string text) const
 
Size getSizeUTF8 (const std::string text) const
 
Rect getInternalBoundsASCII (const std::string text) const
 
Rect getInternalBoundsUTF8 (const std::string text) const
 
int prepareAtlas ()
 
int prepareAtlas (std::string charset)
 
void prepareAtlasKerning ()
 
Metrics computeMetrics (Uint32 thechar) const
 
int computeKerning (Uint32 a, Uint32 b) const
 
void computeAtlasSize (int *width, int *height)
 
std::vector< std::vector< Uint32 > > planAtlas (int width, int height)
 
void layoutAtlas (const std::vector< std::vector< Uint32 > > &rectangle)
 
bool generateSurface (int width, int height)
 
SDL_Surface * allocSurface (int width, int height)
 

Protected Attributes

std::string _name
 
std::string _stylename
 
int _size
 
TTF_Font * _data
 
unsigned int _fontHeight
 
unsigned int _fontDescent
 
unsigned int _fontAscent
 
unsigned int _fontLineSkip
 
bool _fixedWidth
 
bool _useKerning
 
Style _style
 
Hinting _hints
 
Resolution _render
 
bool _hasAtlas
 
std::vector< Uint32 > _glyphset
 
std::unordered_map< Uint32, Rect_glyphmap
 
std::unordered_map< Uint32, Metrics_glyphsize
 
std::unordered_map< Uint32, std::unordered_map< Uint32, Uint32 > > _kernmap
 
std::shared_ptr< Texture_texture
 
SDL_Surface * _surface
 

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 textures and quads for rendering text to the screen. This is typically done via the scene2::Label class, though the methods are available for any rendering pipeline.

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 an atlas. This is a texture with all of the avaliable characters prerendered. This single texture is then used to render the font on screen. This is a potentially fast way of rendering fonts, because it uses only one call to the graphics card.

However, there are disadvantages to a font atlas, and so you should be aware of how to use them properly. First of all, you are trading one texture with many vertices, while rendering the font directly only needs four vertices. If you have a static label that never changes, it may be faster to pay the initial rendering cost of a font with no atlas.

More importantly, font 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.

For this reason, the method buildAtlas() and its variants require that you explicitly specify a character set for the atlas. Indeed, a character set is the only way to get unicode support; the basic atlas only includes ASCII characters.

Member Enumeration Documentation

◆ Hinting

enum 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 usedm so the font may become very blurry or messy at smaller sizes.

◆ Resolution

enum cugl::Font::Resolution : int
strong

This enum represents the font resolution for rendering.

The option SOLID is only useful for the case where there is no atlas. The preferred value for atlases and high quality fonts is BLENDED.
However, when you need a font to "pop" out from a background, you may want SHADED instead.

Enumerator
SOLID 

The text is renderized with no antialiasing.

When rendering with this option, the font will have a very hard edge. Rendering is faster than the other options, but this only matters when the font has no atlas.

SHADED 

The text is renderized smoothly with a hard edge

When rendering with this option, the font will have smooth edges, but there will be a dark border around the font (regardless of the font color). This acts as a form of outlining and guarantees the font will always pop out from its background.

Rendering fonts this way is much slower than SOLID, but has no serious effects when using an atlas.

BLENDED 

The text is renderized with a 32-bit RGBA surface.

When rendering with this option, the font will have an antialiased edge that blends in with its background. This is the preferred option for rendering high quality fonts.

Rendering fonts this way is much slower than SOLID, but has no serious effects when using an atlas.

◆ Style

enum 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,
int  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.

◆ allocSurface()

SDL_Surface* cugl::Font::allocSurface ( int  width,
int  height 
)
protected

Allocates a blank surface of the given size.

This method is necessary because SDL surface allocation is quite involved when you want proper alpha support.

Returns
a blank surface of the given size.

◆ buildAtlas() [1/2]

bool cugl::Font::buildAtlas ( )
inline

Creates an atlas for the ASCII characters in this font.

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

The character atlas texture is generated immediately, so the method getAtlas() may be called with no delay.

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

Returns
true if the atlas was successfully created.

◆ buildAtlas() [2/2]

bool cugl::Font::buildAtlas ( const std::string  charset)
inline

Creates an atlas 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.

The character atlas texture is generated immediately, so the method getAtlas() may be called with no delay.

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

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

◆ buildAtlasAsync() [1/2]

bool cugl::Font::buildAtlasAsync ( )

Creates an atlas for the ASCII characters in this font.

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

This method does not generate the OpenGL texture, but does all other work in creates the atlas. In particular it creates the image buffer so that texture creation is just one OpenGL call. This creation will happen the first time that getAtlas() 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 atlas was successfully created.

◆ buildAtlasAsync() [2/2]

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

Creates an 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.

This method does not generate the OpenGL texture, but does all other work in creates the atlas. In particular it creates the image buffer so that texture creation is just one OpenGL call. This creation will happen the first time that getAtlas() 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 atlas was successfully created.

◆ clearAtlas()

void cugl::Font::clearAtlas ( )

Deletes the current atlas

The font will use direct rendering until a new atlas is created.

◆ computeAtlasSize()

void cugl::Font::computeAtlasSize ( int *  width,
int *  height 
)
protected

Computes the size of the atlas texture

This method computes the minimum bounding box that will contain all of the glyphs in this atlas. The bounding box is guaranteed to have dimensions that are a power of 2, so that the texture is compatible with all graphics cards.

The dimensions are store in the provided pointers. The width should be a value > 1. For best results, the width should be the size of the maximum character width.

Parameters
widthInteger to store the width in
heightInteger to store the height in

◆ computeKerning()

int cugl::Font::computeKerning ( Uint32  a,
Uint32  b 
) const
protected

Returns the kerning between the two characters if available.

The method will return -1 if there either of the two characters are not supported by this font.

Returns
the kerning between the two characters if available.

◆ computeMetrics()

Metrics cugl::Font::computeMetrics ( Uint32  thechar) const
protected

Returns the metrics for the given character if available.

This method returns a metric with all zeroes if no data is fount.

Returns
the metrics for the given character if available.

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

◆ generateSurface()

bool cugl::Font::generateSurface ( int  width,
int  height 
)
protected

Generates an SDL surface for the font atlas.

The data from this surface can be used to generate the OpenGL texture.

Parameters
widthThe width of the bounding box
heightThe height of the bounding box
Returns
true if the surface was successfully generated.

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

◆ getAtlas()

const std::shared_ptr<Texture>& cugl::Font::getAtlas ( )

Returns the OpenGL texture for the associated atlas.

When combined with a quad sequence generated by this font, this texture can be used to draw a font in a SpriteBatch. If there is no atlas, this method returns nullptr.

Returns
the OpenGL texture for the associated atlas.

◆ getAtlasMesh() [1/2]

void cugl::Font::getAtlasMesh ( const std::string  text,
const Vec2  origin,
const Rect  rect,
Mesh< SpriteVertex2 > &  mesh,
bool  utf8 
)
protected

Creates quads to render this string and stores them in the mesh

This method will append the vertices to the provided mesh and update the indices to include these new vertices. This method does not return anything because the quads use the atlas.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. However, by setting the optional value 'utf8' to false, you can speed up the method by skipping the text conversion.

The origin value determines the position of the bottom of the glyph, including the descent. It is not the position of the baseline.

Parameters
textThe string to convert to render data.
originThe position of the first character
rectThe bounding box for the quads
meshThe mesh to store the vertices
utf8Whether the string is a UTF8 that must be decoded.

◆ getAtlasMesh() [2/2]

void cugl::Font::getAtlasMesh ( const std::string  text,
const Vec2  origin,
const Rect  rect,
Mesh< SpriteVertex3 > &  mesh,
float  z,
bool  utf8 
)
protected

Creates quads to render this string and stores them in the mesh

This method will append the vertices to the provided mesh and update the indices to include these new vertices. This method does not return anything because the quads use the atlas.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. However, by setting the optional value 'utf8' to false, you can speed up the method by skipping the text conversion.

The origin value determines the position of the bottom of the glyph, including the descent. It is not the position of the baseline.

Parameters
textThe string to convert to render data.
originThe position of the first character
rectThe bounding box for the quads
meshThe mesh to store the vertices
zThe uniform z-offset in 3-d space
utf8Whether the string is a UTF8 that must be decoded.

◆ getAtlasQuad() [1/2]

bool cugl::Font::getAtlasQuad ( Uint32  thechar,
Vec2 offset,
const Rect  rect,
Mesh< SpriteVertex2 > &  mesh 
)
protected

Creates a single quad to render this character and stores it in the mesh

This method will append the vertices to the given mesh and update the indices to include these new vertices. 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.

This method will return false if the right edge of the glyph is not rendered. This lets us know if a character has exceeded the bounding rectangle. Without this, kerning may move the next character back into range.

Parameters
thecharThe character to convert to render data
offsetThe (unkerned) starting position of the quad
rectThe bounding box for the quad
meshThe mesh to store the vertices
Returns
true if the right edge of the glyph was generated

◆ getAtlasQuad() [2/2]

bool cugl::Font::getAtlasQuad ( Uint32  thechar,
Vec2 offset,
const Rect  rect,
Mesh< SpriteVertex3 > &  mesh,
float  z 
)
protected

Creates a single quad to render this character and stores it in the mesh

This method will append the vertices to the given mesh and update the indices to include these new vertices. 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.

This method will return false if the right edge of the glyph is not rendered. This lets us know if a character has exceeded the bounding rectangle. Without this, kerning may move the next character back into range.

Parameters
thecharThe character to convert to render data
offsetThe (unkerned) starting position of the quad
rectThe bounding box for the quad
meshThe mesh to store the vertices
zThe uniform z-offset in 3-d space
Returns
true if the right edge of the glyph was generated

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

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

Rect cugl::Font::getInternalBounds ( const std::string  text,
bool  utf8 = true 
) 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, indicating that it is safe to start rendering there.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. However, by setting the optional value 'utf8' to false, you can speed up the method by skipping the text conversion.

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

Parameters
textThe string to measure.
utf8Whether the string is a UTF8 that must be decoded.
Returns
the size of the quad sequence generated for this string.

◆ getInternalBoundsASCII()

Rect cugl::Font::getInternalBoundsASCII ( const std::string  text) const
protected

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, indicating that it is safe to start rendering there.

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

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

◆ getInternalBoundsUTF8()

Rect cugl::Font::getInternalBoundsUTF8 ( const std::string  text) const
protected

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, indicating that it is safe to start rendering there.

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

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

◆ getKerning() [1/2]

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

Returns the kerning adjustment between the two (ASCII) 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.

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

◆ getKerning() [2/2]

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.

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.

◆ getMesh() [1/4]

std::shared_ptr<Texture> cugl::Font::getMesh ( const std::string  text,
const Vec2  origin,
const Rect  rect,
Mesh< SpriteVertex2 > &  mesh,
bool  utf8 = true 
)

Creates the mesh to render this string

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. If this is an atlas, the texture will be that atlas.

The quad sequence is adjusted so that all of the vertices fit in the provided rectangle. This may mean that some of the glyphs are truncated or even omitted.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. However, by setting the optional value 'utf8' to false, you can speed up the method by skipping the text conversion.

The origin value determines the position of the bottom of the glyph, including the descent. It is not the position of the baseline.

If this font has an atlas, it will return the atlas texture. Otherwise, it is returning a unique texture specifically generated for this string.

Parameters
textThe string to convert to render data.
originThe position of the first character
rectThe bounding box for the quads
meshThe mesh to store the vertices
utf8Whether the string is a UTF8 that must be decoded.
Returns
the texture associated with the mesh

◆ getMesh() [2/4]

std::shared_ptr<Texture> cugl::Font::getMesh ( const std::string  text,
const Vec2  origin,
const Rect  rect,
Mesh< SpriteVertex3 > &  mesh,
float  z = 0,
bool  utf8 = true 
)

Creates the mesh to render this string

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. If this is an atlas, the texture will be that atlas.

The quad sequence is adjusted so that all of the vertices fit in the provided rectangle. This may mean that some of the glyphs are truncated or even omitted.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. However, by setting the optional value 'utf8' to false, you can speed up the method by skipping the text conversion.

The origin value determines the position of the bottom of the glyph, including the descent. It is not the position of the baseline.

If this font has an atlas, it will return the atlas texture. Otherwise, it is returning a unique texture specifically generated for this string.

Parameters
textThe string to convert to render data.
originThe position of the first character
rectThe bounding box for the quads
meshThe mesh to store the vertices
zThe uniform z-offset in 3-d space
utf8Whether the string is a UTF8 that must be decoded.
Returns
the texture associated with the mesh

◆ getMesh() [3/4]

std::shared_ptr<Texture> cugl::Font::getMesh ( const std::string  text,
const Vec2  origin,
Mesh< SpriteVertex2 > &  mesh,
bool  utf8 = true 
)

Creates the mesh to render this string

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. If this is an atlas, the texture will be that atlas.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. However, by setting the optional value 'utf8' to false, you can speed up the method by skipping the text conversion.

The origin value determines the position of the bottom of the glyph, including the descent. It is not the position of the baseline.

If this font has an atlas, it will return the atlas texture. Otherwise, it is returning a unique texture specifically generated for this string.

This method will fail if the string is not supported by this font.

Parameters
textThe string to convert to render data.
originThe position of the first character
meshThe mesh to store the vertices
utf8Whether the string is a UTF8 that must be decoded.
Returns
the texture associated with the mesh

◆ getMesh() [4/4]

std::shared_ptr<Texture> cugl::Font::getMesh ( const std::string  text,
const Vec2  origin,
Mesh< SpriteVertex3 > &  mesh,
float  z = 0,
bool  utf8 = true 
)

Creates the mesh to render this string

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. If this is an atlas, the texture will be that atlas.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. However, by setting the optional value 'utf8' to false, you can speed up the method by skipping the text conversion.

The origin value determines the position of the bottom of the glyph, including the descent. It is not the position of the baseline.

If this font has an atlas, it will return the atlas texture. Otherwise, it is returning a unique texture specifically generated for this string.

This method will fail if the string is not supported by this font.

Parameters
textThe string to convert to render data.
originThe position of the first character
meshThe mesh to store the vertices
zThe uniform z-offset in 3-d space
utf8Whether the string is a UTF8 that must be decoded.
Returns
the texture associated with the mesh

◆ getMetrics() [1/2]

const Metrics cugl::Font::getMetrics ( char  thechar) const
inline

Returns the glyph metrics for the given (ASCII) 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.

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

◆ getMetrics() [2/2]

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.

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

◆ getQuad() [1/4]

std::shared_ptr<Texture> cugl::Font::getQuad ( Uint32  thechar,
Vec2 offset,
const Rect  rect,
Mesh< SpriteVertex2 > &  mesh 
)

Creates a single quad to render this character and stores it in the mesh

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. If this is an atlas, the texture will be that atlas.

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.

Once the font is generated, offset will be adjusted to contain the next place to render a character. This method will not generate anything if the character is not supported by this font.

If this font has an atlas, it will return the atlas texture. Otherwise, it is returning a unique texture specifically generated for this string.

Parameters
thecharThe character to convert to render data
offsetThe (unkerned) starting position of the quad
rectThe bounding box for the quad
meshThe mesh to store the vertices
Returns
the texture associated with the quad

◆ getQuad() [2/4]

std::shared_ptr<Texture> cugl::Font::getQuad ( Uint32  thechar,
Vec2 offset,
const Rect  rect,
Mesh< SpriteVertex3 > &  mesh,
float  z = 0 
)

Creates a single quad to render this character and stores it in the mesh

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. If this is an atlas, the texture will be that atlas.

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.

Once the font is generated, offset will be adjusted to contain the next place to render a character. This method will not generate anything if the character is not supported by this font.

If this font has an atlas, it will return the atlas texture. Otherwise, it is returning a unique texture specifically generated for this string.

Parameters
thecharThe character to convert to render data
offsetThe (unkerned) starting position of the quad
rectThe bounding box for the quad
zThe uniform z-offset in 3-d space
meshThe mesh to store the vertices
Returns
the texture associated with the quad

◆ getQuad() [3/4]

std::shared_ptr<Texture> cugl::Font::getQuad ( Uint32  thechar,
Vec2 offset,
Mesh< SpriteVertex2 > &  mesh 
)

Creates a single quad to render this character and stores it in the mesh

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. If this is an atlas, the texture will be that atlas.

Once the font is generated, offset will be adjusted to contain the next place to render a character. This method will not generate anything if the character is not supported by this font.

Parameters
thecharThe character to convert to render data
offsetThe (unkerned) starting position of the quad
meshThe mesh to store the vertices

If this font has an atlas, it will return the atlas texture. Otherwise, it is returning a unique texture specifically generated for this string.

Returns
the texture associated with the mesh

◆ getQuad() [4/4]

std::shared_ptr<Texture> cugl::Font::getQuad ( Uint32  thechar,
Vec2 offset,
Mesh< SpriteVertex3 > &  mesh,
float  z = 0 
)

Creates a single quad to render this character and stores it in the mesh

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. If this is an atlas, the texture will be that atlas.

Once the font is generated, offset will be adjusted to contain the next place to render a character. This method will not generate anything if the character is not supported by this font.

Parameters
thecharThe character to convert to render data
offsetThe (unkerned) starting position of the quad
meshThe mesh to store the vertices
zThe uniform z-offset in 3-d space

If this font has an atlas, it will return the atlas texture. Otherwise, it is returning a unique texture specifically generated for this string.

Returns
the texture associated with the mesh

◆ getRenderedMesh() [1/2]

std::shared_ptr<Texture> cugl::Font::getRenderedMesh ( const std::string  text,
const Vec2  origin,
const Rect  rect,
Mesh< SpriteVertex2 > &  mesh,
bool  utf8 
)
protected

Creates quads to render this string and stores them in the mesh

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. If this is an atlas, the texture will be that atlas.

The quad sequence is adjusted so that all of the vertices fit in the provided rectangle. This may mean that some of the glyphs are truncated or even omitted.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. However, by setting the optional value 'utf8' to false, you can speed up the method by skipping the text conversion.

The origin value determines the position of the bottom of the glyph, including the descent. It is not the position of the baseline.

Parameters
textThe string to convert to render data.
originThe position of the first character
rectThe bounding box for the quads.
meshThe mesh to store the vertices
utf8Whether the string is a UTF8 that must be decoded.
Returns
the texture associated with the quads

◆ getRenderedMesh() [2/2]

std::shared_ptr<Texture> cugl::Font::getRenderedMesh ( const std::string  text,
const Vec2  origin,
const Rect  rect,
Mesh< SpriteVertex3 > &  mesh,
float  z,
bool  utf8 
)
protected

Creates quads to render this string and stores them in the mesh

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. If this is an atlas, the texture will be that atlas.

The quad sequence is adjusted so that all of the vertices fit in the provided rectangle. This may mean that some of the glyphs are truncated or even omitted.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. However, by setting the optional value 'utf8' to false, you can speed up the method by skipping the text conversion.

The origin value determines the position of the bottom of the glyph, including the descent. It is not the position of the baseline.

Parameters
textThe string to convert to render data.
originThe position of the first character
rectThe bounding box for the quads.
meshThe mesh to store the vertices
zThe uniform z-offset in 3-d space
utf8Whether the string is a UTF8 that must be decoded.
Returns
the texture associated with the quads

◆ getRenderedQuad() [1/2]

std::shared_ptr<Texture> cugl::Font::getRenderedQuad ( Uint32  thechar,
Vec2 offset,
const Rect  rect,
Mesh< SpriteVertex2 > &  mesh 
)
protected

Creates a single quad to render this character and stores it in the mesh

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. If this is an atlas, the texture will be that atlas.

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.

Once the font is generated, offset will be adjusted to contain the next place to render a character. This method will not generate anything if the character is not supported by this font.

Parameters
thecharThe character to convert to render data
offsetThe (unkerned) starting position of the quad
rectThe bounding box for the quad
meshThe mesh to store the vertices
Returns
the texture associated with the quads

◆ getRenderedQuad() [2/2]

std::shared_ptr<Texture> cugl::Font::getRenderedQuad ( Uint32  thechar,
Vec2 offset,
const Rect  rect,
Mesh< SpriteVertex3 > &  mesh,
float  z 
)
protected

Creates a single quad to render this character and stores it in the mesh

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. If this is an atlas, the texture will be that atlas.

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.

Once the font is generated, offset will be adjusted to contain the next place to render a character. This method will not generate anything if the character is not supported by this font.

Parameters
thecharThe character to convert to render data
offsetThe (unkerned) starting position of the quad
rectThe bounding box for the quad
meshThe mesh to store the vertices
zThe uniform z-offset in 3-d space
Returns
the texture associated with the quads

◆ getResolution()

Resolution cugl::Font::getResolution ( ) const
inline

Returns the rendering resolution for this font.

The option SOLID is only useful for the case where there is no atlas. The preferred value for atlases and high quality fonts is BLENDED. However, when you need a font to "pop" out from a background, you may want SHADED instead.

Returns
the rendering resolution for this font.

◆ getSize()

Size cugl::Font::getSize ( const std::string  text,
bool  utf8 = true 
) const

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

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. However, by setting the optional value 'utf8' to false, you can speed up the method by skipping the text conversion.

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.

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

Parameters
textThe string to measure.
utf8Whether the string is a UTF8 that must be decoded.
Returns
the size (in pixels) necessary to render this string.

◆ getSizeASCII()

Size cugl::Font::getSizeASCII ( const std::string  text) const
protected

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.

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

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

◆ getSizeUTF8()

Size cugl::Font::getSizeUTF8 ( const std::string  text) const
protected

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.

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

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

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

◆ hasAtlas()

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

Returns true if this font has an active atlas.

If this method is true, then getAtlas() can be used to draw a font in a SpriteBatch.

Returns
true if this font has an active atlas.

◆ hasGlyph() [1/2]

bool cugl::Font::hasGlyph ( char  a) const
inline

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

If the font has an associated atlas, this will return true only if the character is in the atlas. You will need to clear the atlas to get the full range of characters.

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

◆ hasGlyph() [2/2]

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.

If the font has an associated atlas, this will return true only if the character is in the atlas. You will need to clear the atlas to get the full range of characters.

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

◆ hasString()

bool cugl::Font::hasString ( const std::string  text) const

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

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

If the font has an associated atlas, this will return true only if the string characters are in the atlas. You will need to clear the atlas to get the full range of characters.

Parameters
textThe string to check.
Returns
true if this font can successfuly render the given string.

◆ init()

bool cugl::Font::init ( const std::string  file,
int  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.

◆ layoutAtlas()

void cugl::Font::layoutAtlas ( const std::vector< std::vector< Uint32 > > &  rectangle)
protected

Takes the rectangular plan and arranges the glyphs in the SDL surface.

Parameters
rectangleA plan for the atlas as a rectangular array of characters.

◆ planAtlas()

std::vector< std::vector<Uint32> > cugl::Font::planAtlas ( int  width,
int  height 
)
protected

Returns a plan for the atlas as a rectangular array of characters.

These characters are organized to fit in the size predicted by computeSize.

Parameters
widthThe width of the bounding box
heightThe height of the bounding box
Returns
a plan for the atlas as a rectangular array of characters.

◆ prepareAtlas() [1/2]

int cugl::Font::prepareAtlas ( )
protected

Prepares an atlas of all of the ASCII glyphs in this font

This method records what glyphs are available in the atlas. It also stores the metrics and initializes the bounding rectangles.

Returns
the maximum width of this font atlas

◆ prepareAtlas() [2/2]

int cugl::Font::prepareAtlas ( std::string  charset)
protected

Prepares an atlas of the font glyphs from the given charset.

This method records what glyphs are available in the atlas. It also stores the metrics and initializes the bounding rectangles.

Parameters
charsetThe set of characters to support
Returns
the maximum width of this font atlas

◆ prepareAtlasKerning()

void cugl::Font::prepareAtlasKerning ( )
protected

Gathers the kerning information for the atlas.

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

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 enitre advance when rendered. This may make spacing look awkard. This value is true by default.

Parameters
kerningWhether this font atlas uses kerning when rendering.

◆ setResolution()

void cugl::Font::setResolution ( Resolution  resolution)
inline

Sets the rendering resolution for this font.

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

The option SOLID is only useful for the case where there is no atlas. The preferred value for atlases and high quality fonts is BLENDED. However, when you need a font to "pop" out from a background, you may want SHADED instead.

Parameters
resolutionThe rendering resolution for this font.

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

Parameters
styleThe style for this font.

◆ 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 enitre advance when rendered. This may make spacing look awkard. This value is true by default.

Returns
true if this font atlas uses kerning when rendering.

Member Data Documentation

◆ _data

TTF_Font* cugl::Font::_data
protected

The underlying SDL data

◆ _fixedWidth

bool cugl::Font::_fixedWidth
protected

Whether this is a fixed width font

◆ _fontAscent

unsigned int cugl::Font::_fontAscent
protected

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

◆ _fontDescent

unsigned int cugl::Font::_fontDescent
protected

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

◆ _fontHeight

unsigned int cugl::Font::_fontHeight
protected

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

◆ _fontLineSkip

unsigned int cugl::Font::_fontLineSkip
protected

The recommended line skip for this font

◆ _glyphmap

std::unordered_map<Uint32, Rect> cugl::Font::_glyphmap
protected

The location of each glyph in the atlas texture

◆ _glyphset

std::vector<Uint32> cugl::Font::_glyphset
protected

The set of (unicode) glyphs supported by this atlas

◆ _glyphsize

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

The cached metrics for each font glyph

◆ _hasAtlas

bool cugl::Font::_hasAtlas
protected

Whether this font has an active atlas

◆ _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)

◆ _render

Resolution cugl::Font::_render
protected

The rendering resolution (when there is no atlas)

◆ _size

int cugl::Font::_size
protected

The font size in points

◆ _style

Style cugl::Font::_style
protected

The font face style

◆ _stylename

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

The name of this font style

◆ _surface

SDL_Surface* cugl::Font::_surface
protected

A (temporary) SDL surface for computing the atlas texture

◆ _texture

std::shared_ptr<Texture> cugl::Font::_texture
protected

The OpenGL texture representing this atlas

◆ _useKerning

bool cugl::Font::_useKerning
protected

Whether to use kerning when rendering


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