CUGL 2.0
Cornell University Game Library
|
#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< Texture > | getMesh (const std::string text, const Vec2 origin, Mesh< SpriteVertex2 > &mesh, bool utf8=true) |
std::shared_ptr< Texture > | getMesh (const std::string text, const Vec2 origin, const Rect rect, Mesh< SpriteVertex2 > &mesh, bool utf8=true) |
std::shared_ptr< Texture > | getQuad (Uint32 thechar, Vec2 &offset, Mesh< SpriteVertex2 > &mesh) |
std::shared_ptr< Texture > | getQuad (Uint32 thechar, Vec2 &offset, const Rect rect, Mesh< SpriteVertex2 > &mesh) |
std::shared_ptr< Texture > | getMesh (const std::string text, const Vec2 origin, Mesh< SpriteVertex3 > &mesh, float z=0, bool utf8=true) |
std::shared_ptr< Texture > | getMesh (const std::string text, const Vec2 origin, const Rect rect, Mesh< SpriteVertex3 > &mesh, float z=0, bool utf8=true) |
std::shared_ptr< Texture > | getQuad (Uint32 thechar, Vec2 &offset, Mesh< SpriteVertex3 > &mesh, float z=0) |
std::shared_ptr< Texture > | getQuad (Uint32 thechar, Vec2 &offset, const Rect rect, Mesh< SpriteVertex3 > &mesh, float z=0) |
Static Public Member Functions | |
static std::shared_ptr< Font > | alloc (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< Texture > | getRenderedMesh (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< Texture > | getRenderedQuad (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< Texture > | getRenderedMesh (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< Texture > | getRenderedQuad (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 |
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.
|
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).
|
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.
|
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.
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.
|
inline |
Deletes this font, disposing of all resources.
|
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.
file | The file with the font asset |
size | The font size in points |
|
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.
|
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.
|
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.
charset | The set of characters in the atlas |
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.
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.
void cugl::Font::clearAtlas | ( | ) |
Deletes the current atlas
The font will use direct rendering until a new atlas is created.
|
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.
width | Integer to store the width in |
height | Integer to store the height in |
|
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.
|
protected |
Returns the metrics for the given character if available.
This method returns a metric with all zeroes if no data is fount.
|
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.
|
protected |
Generates an SDL surface for the font atlas.
The data from this surface can be used to generate the OpenGL texture.
width | The width of the bounding box |
height | The height of the bounding box |
|
inline |
Returns the maximum distance from the baseline to the top of a glyph.
This value will always be positive.
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.
|
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.
text | The string to convert to render data. |
origin | The position of the first character |
rect | The bounding box for the quads |
mesh | The mesh to store the vertices |
utf8 | Whether the string is a UTF8 that must be decoded. |
|
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.
text | The string to convert to render data. |
origin | The position of the first character |
rect | The bounding box for the quads |
mesh | The mesh to store the vertices |
z | The uniform z-offset in 3-d space |
utf8 | Whether the string is a UTF8 that must be decoded. |
|
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.
thechar | The character to convert to render data |
offset | The (unkerned) starting position of the quad |
rect | The bounding box for the quad |
mesh | The mesh to store the vertices |
|
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.
thechar | The character to convert to render data |
offset | The (unkerned) starting position of the quad |
rect | The bounding box for the quad |
mesh | The mesh to store the vertices |
z | The uniform z-offset in 3-d space |
|
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.
|
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.
|
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).
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.
text | The string to measure. |
utf8 | Whether the string is a UTF8 that must be decoded. |
|
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.
text | The ASCII string to measure. |
|
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.
text | The UTF8 string to measure. |
|
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.
a | The first ASCII character in the pair |
b | The second ASCII character in the pair |
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.
a | The first Unicode character in the pair |
b | The second Unicode character in the pair |
|
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.
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.
text | The string to convert to render data. |
origin | The position of the first character |
rect | The bounding box for the quads |
mesh | The mesh to store the vertices |
utf8 | Whether the string is a UTF8 that must be decoded. |
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.
text | The string to convert to render data. |
origin | The position of the first character |
rect | The bounding box for the quads |
mesh | The mesh to store the vertices |
z | The uniform z-offset in 3-d space |
utf8 | Whether the string is a UTF8 that must be decoded. |
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.
text | The string to convert to render data. |
origin | The position of the first character |
mesh | The mesh to store the vertices |
utf8 | Whether the string is a UTF8 that must be decoded. |
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.
text | The string to convert to render data. |
origin | The position of the first character |
mesh | The mesh to store the vertices |
z | The uniform z-offset in 3-d space |
utf8 | Whether the string is a UTF8 that must be decoded. |
|
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.
thechar | The ASCII character to measure. |
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.
thechar | The Unicode character to measure. |
|
inline |
Returns the family name of this font.
This method may return an empty string, meaning the information is not available.
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.
thechar | The character to convert to render data |
offset | The (unkerned) starting position of the quad |
rect | The bounding box for the quad |
mesh | The mesh to store the vertices |
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.
thechar | The character to convert to render data |
offset | The (unkerned) starting position of the quad |
rect | The bounding box for the quad |
z | The uniform z-offset in 3-d space |
mesh | The mesh to store the vertices |
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.
thechar | The character to convert to render data |
offset | The (unkerned) starting position of the quad |
mesh | The 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.
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.
thechar | The character to convert to render data |
offset | The (unkerned) starting position of the quad |
mesh | The mesh to store the vertices |
z | The 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.
|
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.
text | The string to convert to render data. |
origin | The position of the first character |
rect | The bounding box for the quads. |
mesh | The mesh to store the vertices |
utf8 | Whether the string is a UTF8 that must be decoded. |
|
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.
text | The string to convert to render data. |
origin | The position of the first character |
rect | The bounding box for the quads. |
mesh | The mesh to store the vertices |
z | The uniform z-offset in 3-d space |
utf8 | Whether the string is a UTF8 that must be decoded. |
|
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.
thechar | The character to convert to render data |
offset | The (unkerned) starting position of the quad |
rect | The bounding box for the quad |
mesh | The mesh to store the vertices |
|
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.
thechar | The character to convert to render data |
offset | The (unkerned) starting position of the quad |
rect | The bounding box for the quad |
mesh | The mesh to store the vertices |
z | The uniform z-offset in 3-d space |
|
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.
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.
text | The string to measure. |
utf8 | Whether the string is a UTF8 that must be decoded. |
|
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.
text | The ASCII string to measure. |
|
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.
text | The UTF8 string to measure. |
|
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.
|
inline |
Returns the style name of this font.
This method may return an empty string, meaning the information is not available.
|
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.
|
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.
a | The ASCII character to check. |
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.
a | The Unicode character to check. |
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.
text | The string to check. |
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.
file | The file with the font asset |
size | The font size in points |
|
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
|
protected |
Takes the rectangular plan and arranges the glyphs in the SDL surface.
rectangle | A plan for the atlas as a rectangular array of characters. |
|
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.
width | The width of the bounding box |
height | The height of the bounding box |
|
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.
|
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.
charset | The set of characters to support |
|
protected |
Gathers the kerning information for the atlas.
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).
hinting | The rasterization hints |
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.
kerning | Whether this font atlas uses kerning when rendering. |
|
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.
resolution | The rendering resolution for this font. |
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.
style | The style for this font. |
|
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.
|
protected |
The underlying SDL data
|
protected |
Whether this is a fixed width font
|
protected |
The maximum distance from the baseline to the glyph top (always positive)
|
protected |
The maximum distance from the baseline to the glyph bottom (always negative)
|
protected |
The (maximum) height of this font. It is the sum of ascent and descent.
|
protected |
The recommended line skip for this font
|
protected |
The location of each glyph in the atlas texture
|
protected |
The set of (unicode) glyphs supported by this atlas
|
protected |
The cached metrics for each font glyph
|
protected |
Whether this font has an active atlas
|
protected |
The rasterization hints
|
protected |
The kerning for each pair of characters
|
protected |
The name of this font (typically the family name if known)
|
protected |
The rendering resolution (when there is no atlas)
|
protected |
The font size in points
|
protected |
The font face style
|
protected |
The name of this font style
|
protected |
A (temporary) SDL surface for computing the atlas texture
|
protected |
The OpenGL texture representing this atlas
|
protected |
Whether to use kerning when rendering