A TrueType font, loaded at a fixed pixel size, with a glyph cache. More...

#include <font.h>

Classes
struct	Impl
	Shared font state: the font bytes, the parsed font and the glyph cache. More...

Public Member Functions
	Font ()=default
	Construct an empty (invalid) font. See valid().

bool	valid () const
	Whether this handle refers to a loaded font.

float	pixel_size () const
	Em size of this font in pixels (0 for an invalid font).

std::string	source_path () const
	Path this font was loaded from, or an empty string for from_memory() fonts.

FontMetrics	metrics () const
	Vertical metrics (ascent, descent, line gap) in pixels.

float	measure (const std::string &text) const
	Width of a single line of text in pixels, including kerning.

float	advance (uint32_t codepoint) const
	Pen advance of one code point in pixels.

float	kerning (uint32_t first, uint32_t second) const
	Kerning adjustment between two code points, in pixels.

const GlyphBitmap *	glyph (uint32_t codepoint) const
	The rasterized glyph for a code point, rasterizing it on first use.

std::string	family_name () const
	Family name of the font, e.g. `"Inter"` (empty if unavailable).

Font	with_pixel_size (float new_pixel_size) const
	A font handle for the same typeface at a different pixel size.

Static Public Member Functions
static Font	from_file (const std::string &path, float pixel_size)
	Load a TrueType font from a file.

static Font	from_memory (std::vector< uint8_t > data, float pixel_size)
	Create a font from TTF data already in memory.

static std::vector< uint32_t >	decode_utf8 (const std::string &text)
	Decode a UTF-8 string into Unicode code points.

static size_t	line_count (const std::string &text)
	Number of lines in a string (newline-separated, at least 1).

Detailed Description

A TrueType font, loaded at a fixed pixel size, with a glyph cache.

A Font is a cheap handle: copying it shares the underlying font data and the rasterized glyph cache (reference counting), so passing fonts around by value is fine. Glyphs are rasterized lazily on first use and then cached, which makes repeated renders of the same labels cheap.

Fonts are immutable once loaded; to render at a different size use with_pixel_size(), which re-uses the already loaded font bytes.

Example: scimesh::Font font = scimesh::cached_font("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 14.0f);

scimesh::FontMetrics m = font.metrics();

float width = font.measure("posterior");

scimesh::Font
A TrueType font, loaded at a fixed pixel size, with a glyph cache.
Definition font.h:143

scimesh::cached_font
Font cached_font(const std::string &path, float pixel_size)
Load a font, re-using an already loaded one when possible.
Definition font.cpp:405

width
float width
Definition renderer.cpp:36

scimesh::FontMetrics
Vertical metrics of a font at a given pixel size.
Definition font.h:59

x
int x
Left edge of the bitmap, in image pixels.
Definition text.cpp:223

See also: cached_font(), draw_text(), TextLayer

Since: 0.4.0

Definition at line 143 of file font.h.

Constructor & Destructor Documentation

◆ Font()

scimesh::Font::Font ( )

default

Construct an empty (invalid) font. See valid().

Member Function Documentation

◆ advance()

float scimesh::Font::advance ( uint32_t codepoint ) const

Pen advance of one code point in pixels.

Definition at line 207 of file font.cpp.

◆ decode_utf8()

std::vector< uint32_t > scimesh::Font::decode_utf8 ( const std::string & text )

static

Decode a UTF-8 string into Unicode code points.

Invalid byte sequences are decoded as U+FFFD (replacement character) instead of throwing, so arbitrary user input is safe to pass in.

Parameters

text	A UTF-8 encoded string.

Definition at line 311 of file font.cpp.

◆ family_name()

std::string scimesh::Font::family_name ( ) const

Family name of the font, e.g. "Inter" (empty if unavailable).

Definition at line 283 of file font.cpp.

◆ from_file()

Font scimesh::Font::from_file	(	const std::string &	path,
		float	pixel_size
	)

static

Load a TrueType font from a file.

Parameters

path	Path to a `.ttf` (or `.otf` with TrueType outlines) file.
pixel_size	Em size in output pixels, must be > 0.

Returns: The loaded font.

Exceptions

std::runtime_error If the file cannot be read or is not a supported font.

Definition at line 170 of file font.cpp.

◆ from_memory()

Font scimesh::Font::from_memory	(	std::vector< uint8_t >	data,
		float	pixel_size
	)

static

Create a font from TTF data already in memory.

Parameters

data	Raw contents of a `.ttf` file (moved into the font).
pixel_size	Em size in output pixels, must be > 0.

Returns: The loaded font.

Exceptions

std::runtime_error If the data is not a supported font.

Definition at line 178 of file font.cpp.

◆ glyph()

const GlyphBitmap * scimesh::Font::glyph ( uint32_t codepoint ) const

The rasterized glyph for a code point, rasterizing it on first use.

The returned pointer stays valid as long as any copy of this font lives (the glyphs are cached in the shared font data). Returns an empty glyph with a space-like advance when the font has no glyph for the code point, and nullptr only for an invalid font.

Parameters

codepoint Unicode code point (not a UTF-8 byte).

Definition at line 246 of file font.cpp.

◆ kerning()

float scimesh::Font::kerning	(	uint32_t	first,
		uint32_t	second
	)		const

Kerning adjustment between two code points, in pixels.

Only the legacy TrueType kern table is consulted (that is all stb_truetype supports). Fonts that carry their kerning in the modern GPOS table — many recent fonts, including the bundled Inter — return 0.0 here, which simply means "no kerning information available".

Definition at line 217 of file font.cpp.

◆ line_count()

size_t scimesh::Font::line_count ( const std::string & text )

static

Number of lines in a string (newline-separated, at least 1).

Definition at line 357 of file font.cpp.

◆ measure()

float scimesh::Font::measure ( const std::string & text ) const

Width of a single line of text in pixels, including kerning.

Newline characters are not handled specially here: callers that support multi-line text split the string first (see TextLayer).

Parameters

text	A UTF-8 encoded string.

Definition at line 227 of file font.cpp.

◆ metrics()

FontMetrics scimesh::Font::metrics ( ) const

Vertical metrics (ascent, descent, line gap) in pixels.

Returns all zeros for an invalid font.

Definition at line 205 of file font.cpp.

◆ pixel_size()

float scimesh::Font::pixel_size ( ) const

Em size of this font in pixels (0 for an invalid font).

Definition at line 201 of file font.cpp.

◆ source_path()

std::string scimesh::Font::source_path ( ) const

Path this font was loaded from, or an empty string for from_memory() fonts.

Definition at line 203 of file font.cpp.

◆ valid()

bool scimesh::Font::valid ( ) const

inline

Whether this handle refers to a loaded font.

Definition at line 166 of file font.h.

◆ with_pixel_size()

Font scimesh::Font::with_pixel_size ( float new_pixel_size ) const

A font handle for the same typeface at a different pixel size.

The already loaded font bytes are shared, so this does not touch the file system again. Used by the renderer to rasterize at the supersampled resolution, see RenderOptions::aa_samples.

Parameters

new_pixel_size New em size in pixels, must be > 0.

Definition at line 186 of file font.cpp.

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

src/core/scimesh/font.h
src/core/font.cpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Font()

Member Function Documentation

◆ advance()

◆ decode_utf8()

◆ family_name()

◆ from_file()

◆ from_memory()

◆ glyph()

◆ kerning()

◆ line_count()

◆ measure()

◆ metrics()

◆ pixel_size()

◆ source_path()

◆ valid()

◆ with_pixel_size()