donut::graphics::Text Class Reference

Facility for shaping text, according to a Font, into renderable glyphs. More...

#include <donut/graphics/Text.hpp>

Classes
struct	ShapedGlyph
	Data required to render a single shaped glyph relative to at any given starting position. More...
struct	ShapedGlyphInfo
	Additional information about a single shaped glyph, including some data that is not strictly required for simple rendering. More...
struct	ShapedLineInfo
	Information about a line of shaped glyphs, including some data that is not strictly required for simple rendering. More...
struct	ShapeResult
	Result of the shape() function. More...

Public Member Functions
	Text () noexcept=default
	Construct an empty text. More...
	Text (Font &font, u32 characterSize, std::u8string_view string, vec2 offset={0.0f, 0.0f}, vec2 scale={1.0f, 1.0f})
	Construct a shaped text from a UTF-8 string. More...
	Text (Font &font, u32 characterSize, std::string_view string, vec2 offset={0.0f, 0.0f}, vec2 scale={1.0f, 1.0f})
	Helper overload of Text() that takes an arbitrary byte string and interprets it as UTF-8. More...
void	clear () noexcept
	Erase all shaped glyphs and reset the text to an empty state. More...
ShapeResult	shape (Font &font, u32 characterSize, std::u8string_view string, vec2 offset={0.0f, 0.0f}, vec2 scale={1.0f, 1.0f})
	Use a font to shape a string of UTF-8 encoded text into a sequence of glyphs that are ready to be drawn at a given offset, relative to any starting position. More...
ShapeResult	shape (Font &font, u32 characterSize, std::string_view string, vec2 offset={0.0f, 0.0f}, vec2 scale={1.0f, 1.0f})
	Helper overload of shape() that takes an arbitrary byte string and interprets it as UTF-8. More...
ShapeResult	reshape (Font &font, u32 characterSize, std::string_view string, vec2 offset={0.0f, 0.0f}, vec2 scale={1.0f, 1.0f})
	Helper function that is equivalent to clear() followed by shape(). More...
ShapeResult	reshape (Font &font, u32 characterSize, std::u8string_view string, vec2 offset={0.0f, 0.0f}, vec2 scale={1.0f, 1.0f})
	Helper function that is equivalent to clear() followed by shape(). More...
std::span< const ShapedGlyph >	getShapedGlyphs () const noexcept
	Get the list of ShapedGlyph data for all shaped glyphs. More...
std::span< const ShapedGlyphInfo >	getShapedGlyphsInfo () const noexcept
	Get the list of ShapedGlyphInfo data for all shaped glyphs. More...
std::span< const ShapedLineInfo >	getShapedLinesInfo () const noexcept
	Get the list of ShapedLineInfo data for all shaped lines. More...
vec2	getMinExtent () const noexcept
	Get the minimum extent of the shaped text. More...
vec2	getMaxExtent () const noexcept
	Get the maximum extent of the shaped text. More...

Detailed Description

Facility for shaping text, according to a Font, into renderable glyphs.

Examples

example_game.cpp.

Constructor & Destructor Documentation

Text() [1/3]

donut::graphics::Text::Text ( )

defaultnoexcept

Construct an empty text.

Text() [2/3]

donut::graphics::Text::Text ( Font &  font, u32  characterSize, std::u8string_view  string, vec2  offset = {0.0f, 0.0f}, vec2  scale = {1.0f, 1.0f}  )

inline

Construct a shaped text from a UTF-8 string.

Parameters

font	font to shape the glyphs with.
characterSize	character size to shape the glyphs at.
string	UTF-8 encoded text string to shape.
offset	relative offset from the starting position to begin shaping at.
scale	scaling to apply to the size of the shaped glyphs. The result is affected by FontOptions::useLinearFiltering.

Exceptions

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

Note

Right-to-left text shaping is currently not supported.

Grapheme clusters are currently not supported, and may be shaped incorrectly. Only one Unicode code point is shaped at a time.

Warning

If the string contains invalid UTF-8, the invalid code points will generate unspecified glyphs that may have any appearance.

Remarks

The best visual results are usually achieved when the text is shaped at an appropriate character size to begin with, rather than relying on the scaling of this function. As such, the scale parameter should generally be kept at (1, 1) unless many different character sizes are used with this font and there is a strict requirement on the maximum size of the texture atlas.

See also

shape()

Text() [3/3]

donut::graphics::Text::Text ( Font &  font, u32  characterSize, std::string_view  string, vec2  offset = {0.0f, 0.0f}, vec2  scale = {1.0f, 1.0f}  )

inline

Helper overload of Text() that takes an arbitrary byte string and interprets it as UTF-8.

See also

Text(const Font&, u32, std::u8string_view, vec2, vec2)

Member Function Documentation

clear()

void donut::graphics::Text::clear ( )

inlinenoexcept

Erase all shaped glyphs and reset the text to an empty state.

shape() [1/2]

ShapeResult donut::graphics::Text::shape	(	Font &	font,
		u32	characterSize,
		std::u8string_view	string,
		vec2	offset = {0.0f, 0.0f},
		vec2	scale = {1.0f, 1.0f}
	)

Use a font to shape a string of UTF-8 encoded text into a sequence of glyphs that are ready to be drawn at a given offset, relative to any starting position.

Parameters

font	font to shape the glyphs with.
characterSize	character size to shape the glyphs at.
string	UTF-8 encoded text string to shape.
offset	relative offset from the starting position to begin shaping at.
scale	scaling to apply to the size of the shaped glyphs. The result is affected by FontOptions::useLinearFiltering.

Returns

see ShapeResult.

Exceptions

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

Note

Right-to-left text shaping is currently not supported.

Grapheme clusters are currently not supported, and may be shaped incorrectly. Only one Unicode code point is shaped at a time.

Warning

If the string contains invalid UTF-8, the invalid code points will generate unspecified glyphs that may have any appearance.

Remarks

The best visual results are usually achieved when the text is shaped at an appropriate character size to begin with, rather than relying on the scaling of this function. As such, the scale parameter should generally be kept at (1, 1) unless many different character sizes are used with this font and there is a strict requirement on the maximum size of the texture atlas.

See also

getShapedGlyphs()

getShapedGlyphsInfo()

getShapedLinesInfo()

getMinExtent()

getMaxExtent()

shape() [2/2]

ShapeResult donut::graphics::Text::shape ( Font &  font, u32  characterSize, std::string_view  string, vec2  offset = {0.0f, 0.0f}, vec2  scale = {1.0f, 1.0f}  )

inline

Helper overload of shape() that takes an arbitrary byte string and interprets it as UTF-8.

See also

shape(Font&, u32, std::u8string_view, vec2, vec2)

reshape() [1/2]

ShapeResult donut::graphics::Text::reshape ( Font &  font, u32  characterSize, std::string_view  string, vec2  offset = {0.0f, 0.0f}, vec2  scale = {1.0f, 1.0f}  )

inline

Helper function that is equivalent to clear() followed by shape().

See also

clear()

shape()

reshape() [2/2]

ShapeResult donut::graphics::Text::reshape ( Font &  font, u32  characterSize, std::u8string_view  string, vec2  offset = {0.0f, 0.0f}, vec2  scale = {1.0f, 1.0f}  )

inline

Helper function that is equivalent to clear() followed by shape().

See also

clear()

shape()

getShapedGlyphs()

std::span<const ShapedGlyph> donut::graphics::Text::getShapedGlyphs ( ) const

inlinenoexcept

Get the list of ShapedGlyph data for all shaped glyphs.

Returns

a non-owning read-only random-access view over the ShapedGlyph data.

See also

shape()

getShapedGlyphsInfo()

getShapedLinesInfo()

getShapedGlyphsInfo()

std::span<const ShapedGlyphInfo> donut::graphics::Text::getShapedGlyphsInfo ( ) const

inlinenoexcept

Get the list of ShapedGlyphInfo data for all shaped glyphs.

Returns

a non-owning read-only random-access view over the ShapedGlyphInfo data.

See also

shape()

getShapedGlyphs()

getShapedLinesInfo()

getShapedLinesInfo()

std::span<const ShapedLineInfo> donut::graphics::Text::getShapedLinesInfo ( ) const

inlinenoexcept

Get the list of ShapedLineInfo data for all shaped lines.

Returns

a non-owning read-only random-access view over the ShapedLineInfo data.

See also

shape()

getShapedGlyphs()

getShapedGlyphsInfo()

getMinExtent()

vec2 donut::graphics::Text::getMinExtent ( ) const

inlinenoexcept

Get the minimum extent of the shaped text.

Returns

the offset of the bottom left corner of the smallest rectangular area that spans all glyph rectangles of this text.

getMaxExtent()

vec2 donut::graphics::Text::getMaxExtent ( ) const

inlinenoexcept

Get the maximum extent of the shaped text.

Returns

the offset of the top right corner of the smallest rectangular area that spans all glyph rectangles of this text.

---

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

• include/donut/graphics/Text.hpp