Typeface describing an assortment of character glyphs that may be rendered on-demand into an expanding texture atlas, for use in Text rendering. More...

#include <donut/graphics/Font.hpp>

Classes
struct	Glyph
	Information about a single glyph's entry in the texture atlas. More...

struct	GlyphMetrics
	Dimensions of a single glyph in this font, for shaping text. More...

struct	LineMetrics
	Vertical dimensions for shaping lines of text with this font. More...

Public Member Functions
	Font (const Filesystem &filesystem, const char *filepath, const FontOptions &options={})
	Load a font from a virtual file. More...

	~Font ()=default
	Destructor. More...

	Font (const Font &)=delete
	Copying a font is not allowed, since the memory location of the file contents must remain stable. More...

	Font (Font &&other) noexcept=default
	Move constructor. More...

Font &	operator= (const Font &other)=delete
	Copying a font is not allowed, since the memory location of the file contents must remain stable. More...

Font &	operator= (Font &&other) noexcept=default
	Move assignment. More...

Glyph	findGlyph (u32 characterSize, char32_t codePoint) const noexcept
	Look up the information about a glyph's entry in the texture atlas for a specific code point. More...

std::pair< Glyph, bool >	renderGlyph (Renderer &renderer, u32 characterSize, char32_t codePoint)
	Render the glyph for a specific character and store it in the texture atlas, if it has not already been rendered. More...

GlyphMetrics	getGlyphMetrics (u32 characterSize, char32_t codePoint) const noexcept
	Get the dimensions of a single glyph in this font, for shaping text. More...

LineMetrics	getLineMetrics (u32 characterSize) const noexcept
	Get the vertical dimensions for shaping lines of text with this font. More...

vec2	getKerning (u32 characterSize, char32_t left, char32_t right) const noexcept
	Get the kerning offset to use between a pair of adjacent character glyphs while shaping text. More...

void	markGlyphForRendering (u32 characterSize, char32_t codePoint)
	Enqueue a glyph for rendering on the next call to renderMarkedGlyphs() if it has not already been rendered. More...

bool	renderMarkedGlyphs (Renderer &renderer)
	Render all glyphs marked using markGlyphForRendering() that have not already been rendered. More...

bool	containsGlyphsMarkedForRendering () const noexcept
	Check if any unrendered glyphs have been marked for rendering. More...

const Texture &	getAtlasTexture () const noexcept
	Get the texture atlas to use when rendering glyphs from this font. More...

Detailed Description

Typeface describing an assortment of character glyphs that may be rendered on-demand into an expanding texture atlas, for use in Text rendering.

Examples: example_game.cpp.

Constructor & Destructor Documentation

◆ Font() [1/3]

donut::graphics::Font::Font	(	const Filesystem &	filesystem,
		const char *	filepath,
		const FontOptions &	options = `{}`
	)

Load a font from a virtual file.

The supported file formats are:

TrueType (.ttf)
OpenType (.otf)

Parameters

filesystem	virtual filesystem to load the file from.
filepath	virtual filepath of the font file to load.
options	font options, see FontOptions.

Exceptions

File::Error	on failure to open the file.
graphics::Error	on failure to load a font from the file.
std::bad_alloc	on allocation failure.

Note: The only supported text encoding is Unicode.; Only TrueType fonts are fully supported. OpenType extensions that are not a part of TrueType may not work.

◆ ~Font()

donut::graphics::Font::~Font ( )

default

Destructor.

◆ Font() [2/3]

donut::graphics::Font::Font ( const Font & )

delete

Copying a font is not allowed, since the memory location of the file contents must remain stable.

◆ Font() [3/3]

donut::graphics::Font::Font ( Font && other )

defaultnoexcept

Move constructor.

Member Function Documentation

◆ operator=() [1/2]

Font& donut::graphics::Font::operator= ( const Font & other )

delete

Copying a font is not allowed, since the memory location of the file contents must remain stable.

◆ operator=() [2/2]

Font& donut::graphics::Font::operator= ( Font && other )

defaultnoexcept

Move assignment.

◆ findGlyph()

Glyph donut::graphics::Font::findGlyph	(	u32	characterSize,
		char32_t	codePoint
	)		const

noexcept

Look up the information about a glyph's entry in the texture atlas for a specific code point.

Parameters

characterSize	character size of the glyph to search for.
codePoint	Unicode code point of the glyph to search for.

Returns: the glyph information, see Glyph.

See also: renderGlyph(); getAtlasTexture()

◆ renderGlyph()

std::pair<Glyph, bool> donut::graphics::Font::renderGlyph	(	Renderer &	renderer,
		u32	characterSize,
		char32_t	codePoint
	)

Render the glyph for a specific character and store it in the texture atlas, if it has not already been rendered.

Parameters

renderer	renderer to use for rendering the glyph.
characterSize	character size to render the glyph at.
codePoint	Unicode code point of the glyph to render.

Returns

a pair where:

the first element contains information about the rendered glyph, and
the second element contains a bool that is true if the glyph was actually rendered, or false if the glyph had already been rendered previously.

Exceptions

graphics::Error	on failure to render the glyph.
std::bad_alloc	on allocation failure.

Note: If the specified glyph has already been rendered previously, no modification is made, and the already rendered glyph is returned. In this case, the function is guaranteed to not throw any exceptions.

See also: findGlyph(); getGlyphMetrics(); getAtlasTexture()

◆ getGlyphMetrics()

GlyphMetrics donut::graphics::Font::getGlyphMetrics	(	u32	characterSize,
		char32_t	codePoint
	)		const

noexcept

Get the dimensions of a single glyph in this font, for shaping text.

Parameters

characterSize	character size to get the glyph metrics of.
codePoint	Unicode code point to get the glyph metrics of.

Returns: the glyph metrics of the given code point at the given character size, see GlyphMetrics.

See also: findGlyph(); renderGlyph()

◆ getLineMetrics()

LineMetrics donut::graphics::Font::getLineMetrics ( u32 characterSize ) const

noexcept

Get the vertical dimensions for shaping lines of text with this font.

Parameters

characterSize character size to get the line metrics of.

Returns: the line metrics at the given character size, see LineMetrics.

◆ getKerning()

vec2 donut::graphics::Font::getKerning	(	u32	characterSize,
		char32_t	left,
		char32_t	right
	)		const

noexcept

Get the kerning offset to use between a pair of adjacent character glyphs while shaping text.

Parameters

characterSize	character size of the glyphs to get the kerning of.
left	Unicode code point of the left glyph in the adjacent pair.
right	Unicode code point of the right glyph in the adjacent pair.

Returns: if the font contains a valid glyph for both the left and the right characters, returns the additional offset to advance the position by when going from the left glyph to the right glyph. Otherwise, returns (0, 0).

◆ markGlyphForRendering()

void donut::graphics::Font::markGlyphForRendering	(	u32	characterSize,
		char32_t	codePoint
	)

Enqueue a glyph for rendering on the next call to renderMarkedGlyphs() if it has not already been rendered.

Parameters

characterSize	character size to render the glyph at.
codePoint	Unicode code point of the glyph to render.

Exceptions

graphics::Error	on failure to mark the glyph.
std::bad_alloc	on allocation failure.

See also: renderMarkedGlyphs()

◆ renderMarkedGlyphs()

bool donut::graphics::Font::renderMarkedGlyphs ( Renderer & renderer )

Render all glyphs marked using markGlyphForRendering() that have not already been rendered.

Parameters

renderer renderer to use for rendering the glyphs.

Returns: true if at least one marked glyph needed to be rendered, false if no rendering took place because all marked glyphs were already rendered.

Exceptions

graphics::Error	on failure to render a glyph.
std::bad_alloc	on allocation failure.

See also: markGlyphForRendering(); containsGlyphsMarkedForRendering()

◆ containsGlyphsMarkedForRendering()

bool donut::graphics::Font::containsGlyphsMarkedForRendering ( ) const

noexcept

Check if any unrendered glyphs have been marked for rendering.

Returns: true if some marked glyph might need to be rendered, false if certainly no unrendered glyphs have been marked.

◆ getAtlasTexture()

const Texture& donut::graphics::Font::getAtlasTexture ( ) const

inlinenoexcept

Get the texture atlas to use when rendering glyphs from this font.

Returns: a read-only reference to a square texture containing all loaded glyphs.

See also: findGlyph(); loadGlyph()

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

include/donut/graphics/Font.hpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Font() [1/3]

◆ ~Font()

◆ Font() [2/3]

◆ Font() [3/3]

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ findGlyph()

◆ renderGlyph()

◆ getGlyphMetrics()

◆ getLineMetrics()

◆ getKerning()

◆ markGlyphForRendering()

◆ renderMarkedGlyphs()

◆ containsGlyphsMarkedForRendering()

◆ getAtlasTexture()