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

#include <textrenderer.h>

Classes
struct	FontCache

struct	GlyphEntry

Public Member Functions
	TextRenderer (const std::string &fontPath=util::getDefaultFontPath()+"/arial.ttf")

void	setFont (const std::string &fontPath)
	replace the currently loaded font face with a new one More...

void	render (const std::string &str, const vec2 &posf, const vec2 &scale, const vec4 &color)

void	render (const std::string &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. More...

void	renderToTexture (std::shared_ptr< Texture2D > texture, const std::string &str, const vec4 &color, bool clearTexture=true)
	renders the given string with the specified color into a texture. More...

void	renderToTexture (const TextTextureObject &texObject, const std::string &str, const vec4 &color, bool clearTexture=true)

void	renderToTexture (const TextTextureObject &texObject, const size2_t &origin, const size2_t &size, const std::string &str, const vec4 &color, bool clearTexture=true)
	renders the given string with the specified color into a subregion of the texture. More...

void	renderToTexture (std::shared_ptr< Texture2D > texture, const size2_t &origin, const size2_t &size, const std::string &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)

vec2	computeTextSize (const std::string &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. More...

size2_t	computeTextSize (const std::string &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. More...

TextBoundingBox	computeBoundingBox (const std::string &str)
	computes the bounding boxes of both text and all glyphs for a given string in pixels (screen space). More...

void	setFontSize (int val)

int	getFontSize () const

void	setLineSpacing (double lineSpacing)
	sets the line spacing relative to the font size (default 0.2 = 20%) More...

double	getLineSpacing () const

void	setLineHeight (int lineHeight)

int	getLineHeight () const

int	getBaseLineOffset () const
	returns the offset of the baseline, which corresponds to ascent More...

int	getBaseLineDescender () const
	returns the size of the font part below the baseline, which corresponds to descent More...

void	configure (const FontSettings &settings)

Protected Types
using	FontFamilyStyle = std::tuple< std::string, std::string, int >

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

Protected Member Functions
double	getFontAscender () const

double	getFontDescender () 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. More...

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

void	uploadGlyph (FontCache &fc, unsigned int glyph)

FontCache &	getFontCache ()

void	createDefaultGlyphAtlas ()

std::shared_ptr< Texture2D >	createAtlasTexture (FontCache &fc)

FontFamilyStyle	getFontTuple () const

std::tuple< utilgl::DepthMaskState, utilgl::GlBoolState, utilgl::BlendModeState, utilgl::Activate< FrameBufferObject > >	setupRenderState (std::shared_ptr< Texture2D > texture, bool clearTexture)

std::string::const_iterator	validateString (const std::string &str) const

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

Protected Attributes
std::unordered_map< FontFamilyStyle, FontCache >	glyphAtlas_

FT_Library	fontlib_

FT_Face	fontface_

int	fontSize_

double	lineSpacing_
	spacing between two lines in percent (default = 0.2)

const int	glyphMargin_

std::shared_ptr< Shader >	shader_

FrameBufferObject	fbo_

std::shared_ptr< Texture2D >	prevTexture_

Static Protected Attributes
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 Function Documentation

◆ computeBoundingBox()

TextBoundingBox inviwo::TextRenderer::computeBoundingBox ( const std::string & 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]

vec2 inviwo::TextRenderer::computeTextSize	(	const std::string &	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

◆ computeTextSize() [2/2]

size2_t inviwo::TextRenderer::computeTextSize ( const std::string & 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

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

void inviwo::TextRenderer::render	(	const std::string &	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	(	std::shared_ptr< Texture2D >	texture,
		const std::string &	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

◆ renderToTexture() [2/2]

void inviwo::TextRenderer::renderToTexture	(	const TextTextureObject &	texObject,
		const size2_t &	origin,
		const size2_t &	size,
		const std::string &	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

◆ requestGlyph()

std::pair< bool, TextRenderer::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::string & 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 files:

textrenderer.h
textrenderer.cpp

Classes

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ computeBoundingBox()

◆ computeTextSize() [1/2]

◆ computeTextSize() [2/2]

◆ getBaseLineDescender()

◆ getBaseLineOffset()

◆ render()

◆ renderToTexture() [1/2]

◆ renderToTexture() [2/2]

◆ requestGlyph()

◆ setFont()

◆ setLineSpacing()