donner::svg::TextEngine Class Reference

Shared SVG text engine. More...

#include "donner/svg/text/TextEngine.h"

Classes
struct	GlyphOutline
	A placed glyph outline paired with the source element that produced it. More...

Public Member Functions
	TextEngine (FontManager &fontManager, Registry &registry)
	Construct a text engine using the provided font manager and ECS registry.
	TextEngine (FontManager &fontManager, Registry &registry, std::unique_ptr< TextBackend > backend)
	Test-only constructor that injects a custom TextBackend.
	TextEngine (const TextEngine &)=delete
TextEngine &	operator= (const TextEngine &)=delete
void	addFontFace (const css::FontFace &face)
	Register a single face with the engine's font manager.
void	addFontFaces (std::span< const css::FontFace > faces)
	Register a batch of faces with the engine's font manager.
void	prepareForElement (EntityHandle handle, ParseWarningSink &warningSink)
	Prepare text dependencies for the text root containing handle.
std::vector< Entity >	refreshFontResources ()
	Adopt pending face resolutions under serialized document access and invalidate only the text roots whose cached runs used a changed face. Call before the renderer's dirty snapshot.
bool	needsFontResourceRefresh () const
	Whether changed or pending font resources require another text preparation pass.
std::vector< TextRun >	layout (const components::ComputedTextComponent &text, const TextLayoutParams &params)
	Lay out all spans, returning positioned glyph runs.
std::size_t	layoutCallCountForTesting () const
	Number of full text layouts performed by this engine, for CPU-work regression tests.
std::size_t	objectBoundingBoxSpanVisitsForTesting () const
	Span bounding-box entries examined while building or answering object-box queries.
ResolvedTextFont	resolveUsedFont (EntityHandle styleOwner, const Box2d &viewBox, const FontMetrics &fontMetrics) const
	Resolve a style owner's face and adjusted used size for declaring-element font metrics.
FontVMetrics	fontVMetrics (FontHandle font) const
	Return vertical font metrics for font.
float	scaleForPixelHeight (FontHandle font, float pixelHeight) const
	Return the scale factor mapping design units to pixelHeight pixels for font.
float	scaleForEmToPixels (FontHandle font, float pixelHeight) const
	Return the scale factor mapping one em to pixelHeight pixels for font.
std::optional< UnderlineMetrics >	underlineMetrics (FontHandle font) const
	Return underline position/thickness for font, if available.
std::optional< UnderlineMetrics >	strikeoutMetrics (FontHandle font) const
	Return strikeout position/thickness for font, if available.
std::optional< SubSuperMetrics >	subSuperMetrics (FontHandle font) const
	Return subscript/superscript offset metrics for font, if available.
Path	glyphOutline (FontHandle font, int glyphIndex, float scale) const
	Return the vector outline for glyphIndex in font at the given scale.
bool	isBitmapOnly (FontHandle font) const
	Return true if font only contains bitmap glyphs (e.g. color emoji).
std::optional< TextBackend::BitmapGlyph >	bitmapGlyph (FontHandle font, int glyphIndex, float scale) const
	Return a rasterized bitmap glyph for glyphIndex in font at the given scale.
std::optional< TextBackend::BitmapGlyphMetrics >	bitmapGlyphMetrics (FontHandle font, int glyphIndex, float scale) const
	Query bitmap cost and placement without decoding pixels.
std::optional< TextBackend::BitmapGlyph >	bitmapGlyph (FontHandle font, int glyphIndex, float scale, const TextBackend::BitmapGlyphMetrics &admitted, std::size_t maximumRgbaBytes) const
	Decode an admitted bitmap only after revalidating its metadata and RGBA byte cap.
std::optional< double >	measureChUnitInEm (std::span< const RcString > fontFamilies, Entity geometryOwner=entt::null)
	Measure the ch unit in ems for the given font-family cascade.
void	resolvePerSpanLayoutStyles (EntityHandle textRootHandle, components::ComputedTextComponent &text, const TextStyleContext *styleContext=nullptr) const
	Resolve per-span layout-affecting style state on a computed text tree.
const components::ComputedTextGeometryComponent &	ensureComputedTextGeometryComponent (EntityHandle handle) const
	Ensure cached text geometry exists for the text root containing handle.
std::vector< Path >	computedGlyphPaths (EntityHandle handle) const
	Return glyph outlines for the text subtree rooted at handle.
std::vector< GlyphOutline >	computedGlyphOutlines (EntityHandle handle) const
	Return glyph outlines paired with their source entities for the subtree rooted at handle. The paint that colored each glyph lives on its source entity's computed style; callers that must preserve per-span paint (e.g. text-to-outlines) resolve style from sourceEntity.
Box2d	computedInkBounds (EntityHandle handle) const
	Return the ink bounds for the text subtree rooted at handle.
Box2d	computedObjectBoundingBox (EntityHandle handle) const
	Return the object bounding box for the text subtree rooted at handle.
Entity	textRootEntity (EntityHandle handle) const
	The root <text> element that handle takes part in, if any.
long	getNumberOfChars (EntityHandle handle) const
	Return the number of addressable characters for the text subtree rooted at handle.
double	getComputedTextLength (EntityHandle handle) const
	Return the computed text length for the text subtree rooted at handle.
double	getSubStringLength (EntityHandle handle, std::size_t charnum, std::size_t nchars) const
	Return the substring length for the text subtree rooted at handle.
Vector2d	getStartPositionOfChar (EntityHandle handle, std::size_t charnum) const
	Return the start position of a character for the text subtree rooted at handle.
Vector2d	getEndPositionOfChar (EntityHandle handle, std::size_t charnum) const
	Return the end position of a character for the text subtree rooted at handle.
Box2d	getExtentOfChar (EntityHandle handle, std::size_t charnum) const
	Return the extent of a character for the text subtree rooted at handle.
double	getRotationOfChar (EntityHandle handle, std::size_t charnum) const
	Return the rotation of a character for the text subtree rooted at handle.
long	getCharNumAtPosition (EntityHandle handle, const Vector2d &point) const
	Return the character index at the given point for the text subtree rooted at handle.

Detailed Description

Shared SVG text engine.

Owns the selected text backend and provides layout plus font-related operations while hiding backend selection from callers.

Usage:

Registry registry;
auto& fontManager = registry.ctx().emplace<FontManager>(registry);
auto& engine = registry.ctx().emplace<TextEngine>(fontManager, registry);
std::vector<TextRun> runs = engine.layout(text, params);

---

Class Documentation

donner::svg::TextEngine::GlyphOutline

struct donner::svg::TextEngine::GlyphOutline

A placed glyph outline paired with the source element that produced it.

Class Members
Path	path	Glyph outline in text-element local coordinates.
Entity	sourceEntity = entt::null	Span source entity (text/tspan) that owns this glyph.

Member Function Documentation

bitmapGlyph()

std::optional< TextBackend::BitmapGlyph > donner::svg::TextEngine::bitmapGlyph	(	FontHandle	font,
		int	glyphIndex,
		float	scale,
		const TextBackend::BitmapGlyphMetrics &	admitted,
		std::size_t	maximumRgbaBytes ) const

Decode an admitted bitmap only after revalidating its metadata and RGBA byte cap.

Parameters

font	Font to decode.
glyphIndex	Glyph within the font.
scale	Requested scale.
admitted	Metadata whose cost the caller has reserved.
maximumRgbaBytes	Maximum converted RGBA storage allowed by that reservation.

bitmapGlyphMetrics()

std::optional< TextBackend::BitmapGlyphMetrics > donner::svg::TextEngine::bitmapGlyphMetrics	(	FontHandle	font,
		int	glyphIndex,
		float	scale ) const

Query bitmap cost and placement without decoding pixels.

Parameters

font	Font to query.
glyphIndex	Glyph within the font.
scale	Requested scale.

textRootEntity()

Entity donner::svg::TextEngine::textRootEntity

(

EntityHandle

handle

)

const

The root <text> element that handle takes part in, if any.

Every geometry query here resolves through the text root and requires one to exist. Element types that carry text components without always being text content, notably <a>, reach those queries from outside any text element, so callers test this first.

Parameters

handle

The element to resolve.

Returns

The root text entity, or entt::null when handle is not inside a text element.

---

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

• donner/svg/text/TextEngine.h