Render text using the FreeType font library. More...

#include <modules/fontrendering/textrenderer.h>

Classes
struct	FontCache
struct	GlyphEntry

Public Member Functions
void	clear (std::shared_ptr< Texture2D > texture, vec4 color)
TextBoundingBox	computeBoundingBox (std::string_view str)
	computes the bounding boxes of both text and all glyphs for a given string in pixels (screen space).
size2_t	computeTextSize (std::string_view str)
	computes the glyph bounding box of a given string in pixels (screen space). The vertical height of the bounding box will be about (ascend + descend) + (number of lines - 1) times line height.
vec2	computeTextSize (std::string_view str, const vec2 &scale)
	computes the glyph bounding box of a given string in normalized device coordinates using the scaling factor. The vertical height of the bounding box will be about (ascend + descend) + (number of lines - 1) times line height.
void	configure (const FontSettings &settings)
int	getBaseLineDescender () const
	returns the size of the font part below the baseline, which corresponds to descent
int	getBaseLineOffset () const
	returns the offset of the baseline, which corresponds to ascent
int	getFontSize () const
int	getLineHeight () const
double	getLineSpacing () const
TextRenderer &	operator= (const TextRenderer &rhs)=delete
TextRenderer &	operator= (TextRenderer &&rhs) noexcept
void	render (const TextBoundingBox &textBoundingBox, const ivec2 &origin, std::string_view str, const vec4 &color)
	renders the given string with the specified color into a subregion of the current destination
void	render (std::string_view str, const vec2 &posf, const vec2 &scale, const vec4 &color)
void	render (std::string_view str, float x, float y, const vec2 &scale, const vec4 &color)
	renders the given string with the specified color at position x, y in normalized device coordinates [-1,1] using the scaling factor.
void	renderToTexture (const TextTextureObject &texObject, const size2_t &origin, const size2_t &size, std::string_view str, const vec4 &color, bool clearTexture=true)
	renders the given string with the specified color into a subregion of the texture.
void	renderToTexture (const TextTextureObject &texObject, std::string_view str, const vec4 &color, bool clearTexture=true)
void	renderToTexture (std::shared_ptr< Texture2D > texture, const size2_t &origin, const size2_t &size, std::string_view str, const vec4 &color, bool clearTexture=true)
void	renderToTexture (std::shared_ptr< Texture2D > texture, const std::vector< size2_t > &origin, const std::vector< size2_t > &size, const std::vector< std::string > &str, const vec4 &color, bool clearTexture=true)
void	renderToTexture (std::shared_ptr< Texture2D > texture, const std::vector< TexAtlasEntry > &entries, bool clearTexture=true)
void	renderToTexture (std::shared_ptr< Texture2D > texture, std::string_view str, const vec4 &color, bool clearTexture=true)
	renders the given string with the specified color into a texture.
void	setFont (const std::filesystem::path &fontPath)
	replace the currently loaded font face with a new one
void	setFontSize (int val)
void	setLineHeight (int lineHeight)
void	setLineSpacing (double lineSpacing)
	sets the line spacing relative to the font size (default 0.2 = 20%)
std::tuple< utilgl::DepthMaskState, utilgl::GlBoolState, utilgl::BlendModeState, utilgl::ActivateFBO >	setupRenderState (std::shared_ptr< Texture2D > texture, std::optional< vec4 > clearColor=std::nullopt)
	TextRenderer (const std::filesystem::path &fontPath=font::getFont(font::FontType::Default, font::FullPath::Yes))
	TextRenderer (const TextRenderer &rhs)=delete
	TextRenderer (TextRenderer &&rhs) noexcept

Protected Types
using	FontFamilyStyle
using	GlyphMap = std::map<unsigned int, GlyphEntry>

Protected Member Functions
std::pair< bool, GlyphEntry >	addGlyph (FontCache &fc, unsigned int glyph)
std::shared_ptr< Texture2D >	createAtlasTexture (FontCache &fc)
void	createDefaultGlyphAtlas ()
double	getFontAscender () const
FontCache &	getFontCache ()
double	getFontDescender () const
FontFamilyStyle	getFontTuple () const
std::pair< bool, GlyphEntry >	requestGlyph (FontCache &fc, unsigned int glyph)
	request glyph information from the texture atlas. The glyph will be added to the atlas if it isn't registered yet and there is space left in the atlas.
void	uploadGlyph (FontCache &fc, unsigned int glyph)
std::string_view::const_iterator	validateString (std::string_view str) const

Static Protected Member Functions
static std::shared_ptr< Shader >	getShader ()

Protected Attributes
std::shared_ptr< Texture2D >	currTexture_
FrameBufferObject	fbo_
FT_Face	fontface_
FT_Library	fontlib_
int	fontSize_
std::unordered_map< FontFamilyStyle, FontCache >	glyphAtlas_
double	lineSpacing_
	spacing between two lines in percent (default = 0.2)
std::shared_ptr< Shader >	shader_

Static Protected Attributes
static constexpr int	glyphMargin_ = 2
static constexpr char	lf = '\n'
static constexpr char	tab = '\t'

Detailed Description

Render text using the FreeType font library.

The origin is at the top-left corner. The first line starts at origin - ascender (getBaseLineOffset()). The distance between two lines is governed by either setting the line height or the line spacing. The line height defines the distance between two consecutive baselines. In contrast, the line spacing (or line gap) is given by line height minus ascend minus descend. Typically, a line spacing of 20% of the font size is used, which corresponds to a line height of 1.2 * font size.

* Origin
* +───────────────────────────ffffffffffffffff──────────────────── Top line
*                            f::::::::::::::::f    ▲          ▲
*                           f::::::::::::::::::f   │          │
*                           f::::::fffffff:::::f   │          │
*        ggggggggg   ggggg  f:::::f       ffffff   │          │
*       g:::::::::ggg::::g  f:::::f                │          │
*      g:::::::::::::::::g f:::::::ffffff          │          │
*     g::::::ggggg::::::gg f::::::::::::f          │        Ascender
*     g:::::g     g:::::g  f::::::::::::f          │          │
*     g:::::g     g:::::g  f:::::::ffffff          │          │
*     g:::::g     g:::::g   f:::::f                │          │
*     g::::::g    g:::::g   f:::::f                │          │
*     g:::::::ggggg:::::g  f:::::::f               │          │
*      g::::::::::::::::g  f:::::::f          Line height     │
*       gg::::::::::::::g  f:::::::f               │          ▼
* ────────gggggggg::::::g──fffffffff───────────────│────────────── Base line
*                 g:::::g                          │          ▲
*     gggggg      g:::::g                          │          │
*     g:::::gg   gg:::::g                          │       Descender
*      g::::::ggg:::::::g                          │          │
*       gg:::::::::::::g                           │          │
*         ggg::::::ggg                             │          ▼
* ───────────gggggg────────────────────────────────│────────────── Bottom line
*                                                  │          ▲
*                                                  │          │
*                                                  │     Line spacing
*                                                  │          │
*                                                  ▼          ▼
* ──────────────────────────────────────────────────────────────── Top line (of subsequent line)
*

Member Typedef Documentation

◆ FontFamilyStyle

using inviwo::TextRenderer::FontFamilyStyle

protected

Initial value:

std::tuple<std::string, std::string, int>

Member Function Documentation

◆ clear()

void inviwo::TextRenderer::clear	(	std::shared_ptr< Texture2D >	texture,
		vec4	color )

Clear the texture using the fbo of the text renderer. Useful when rendering many times into the texture.

◆ computeBoundingBox()

TextBoundingBox inviwo::TextRenderer::computeBoundingBox ( std::string_view str )

computes the bounding boxes of both text and all glyphs for a given string in pixels (screen space).

The vertical height of the textual bounding box is equal to (ascend + descend) + (number of lines - 1) times line height. The width corresponds to the maximum sum of all glyph advances per row, which are given by the respective font. Note: glyphs might extend beyond the text bounding box.

Parameters

str	input string

Returns: bounding box of the given string

◆ computeTextSize() [1/2]

size2_t inviwo::TextRenderer::computeTextSize ( std::string_view str )

computes the glyph bounding box of a given string in pixels (screen space). The vertical height of the bounding box will be about (ascend + descend) + (number of lines - 1) times line height.

Parameters

str	input string

Returns: size of the bounding box enclosing all glyphs of the input string in pixel

See also: computeBoundingBox

◆ computeTextSize() [2/2]

vec2 inviwo::TextRenderer::computeTextSize	(	std::string_view	str,
		const vec2 &	scale )

computes the glyph bounding box of a given string in normalized device coordinates using the scaling factor. The vertical height of the bounding box will be about (ascend + descend) + (number of lines - 1) times line height.

Parameters

str	input string
scale	scaling factor from screen space (pixel) to normalized device coordinates ([-1,1])

Returns: size of the bounding box enclosing all glyphs of the input string in normalized device coordinates

See also: computeBoundingBox

◆ getBaseLineDescender()

int inviwo::TextRenderer::getBaseLineDescender ( ) const

returns the size of the font part below the baseline, which corresponds to descent

Returns: baseline offset

◆ getBaseLineOffset()

int inviwo::TextRenderer::getBaseLineOffset ( ) const

returns the offset of the baseline, which corresponds to ascent

Returns: baseline offset

◆ render() [1/2]

void inviwo::TextRenderer::render	(	const TextBoundingBox &	textBoundingBox,
		const ivec2 &	origin,
		std::string_view	str,
		const vec4 &	color )

renders the given string with the specified color into a subregion of the current destination

Parameters

textBoundingBox	the text bounding box of the given str
origin	origin of sub region within the destination (lower left corner, in pixel)
str	input string
color	color of rendered text

◆ render() [2/2]

void inviwo::TextRenderer::render	(	std::string_view	str,
		float	x,
		float	y,
		const vec2 &	scale,
		const vec4 &	color )

renders the given string with the specified color at position x, y in normalized device coordinates [-1,1] using the scaling factor.

Parameters

str	input string
x	x component of position in normalized device coords
y	y component of position in normalized device coords
scale	scaling factor from screen space (pixel) to normalized device coords
color	color of rendered text

◆ renderToTexture() [1/2]

void inviwo::TextRenderer::renderToTexture	(	const TextTextureObject &	texObject,
		const size2_t &	origin,
		const size2_t &	size,
		std::string_view	str,
		const vec4 &	color,
		bool	clearTexture = true )

renders the given string with the specified color into a subregion of the texture.

Parameters

texObject	the text will be rendered into this texture
origin	origin of sub region within the texture (lower left corner, in pixel)
size	extent of sub region (in pixel)
str	input string
color	color of rendered text
clearTexture	if true, the texture is cleared before rendering the text

◆ renderToTexture() [2/2]

void inviwo::TextRenderer::renderToTexture	(	std::shared_ptr< Texture2D >	texture,
		std::string_view	str,
		const vec4 &	color,
		bool	clearTexture = true )

renders the given string with the specified color into a texture.

Parameters

texture	the text will be rendered into this texture
str	input string
color	color of rendered text
clearTexture	if true, the texture is cleared before rendering the text

◆ requestGlyph()

std::pair< bool, GlyphEntry > inviwo::TextRenderer::requestGlyph	(	FontCache &	fc,
		unsigned int	glyph )

protected

request glyph information from the texture atlas. The glyph will be added to the atlas if it isn't registered yet and there is space left in the atlas.

Parameters

fc	font cache for the currently selected font, style, and size
glyph	character code of the glyph

Returns: std::pair<bool, GlyphEntry> where pair.first is true if the glyph exists and GlyphEntry refers to the respective glyph

◆ setFont()

void inviwo::TextRenderer::setFont ( const std::filesystem::path & fontPath )

replace the currently loaded font face with a new one

Parameters

fontPath full path to the new font face

Exceptions

Exception	if the font file could not be opened
FileException	if the font format is unsupported

◆ setLineSpacing()

void inviwo::TextRenderer::setLineSpacing ( double lineSpacing )

sets the line spacing relative to the font size (default 0.2 = 20%)

Parameters

lineSpacing factor for line spacing

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

modules/fontrendering/include/modules/fontrendering/textrenderer.h

Classes

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Typedef Documentation

◆ FontFamilyStyle

Member Function Documentation

◆ clear()

◆ computeBoundingBox()

◆ computeTextSize() [1/2]

◆ computeTextSize() [2/2]

◆ getBaseLineDescender()

◆ getBaseLineOffset()

◆ render() [1/2]

◆ render() [2/2]

◆ renderToTexture() [1/2]

◆ renderToTexture() [2/2]

◆ requestGlyph()

◆ setFont()

◆ setLineSpacing()