Abstract font backend for text rendering operations. More...

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

Inheritance diagram for donner::svg::TextBackend:

Classes
struct	BitmapGlyph
	Bitmap glyph data from color fonts (CBDT/CBLC). More...
struct	BitmapGlyphMetrics
	Validated bitmap cost and placement metadata; not an authentication or cache identity token. More...
struct	ShapedGlyph
	A single shaped glyph with advance and cluster info. More...
struct	ShapedRun
	Result of shaping a text range. More...
struct	ShapingContext
	A byte range of the span text that surrounds a shaped range. More...

Public Member Functions
virtual bool	requiresTrustedFontData () const
	Whether this backend may consume only fonts whose byte provenance is trusted.
virtual FontVMetrics	fontVMetrics (FontHandle font) const =0
	Vertical metrics (ascent, descent, lineGap) in font design units.
virtual float	scaleForPixelHeight (FontHandle font, float pixelHeight) const =0
	Scale factor: font design units → pixels, normalized to ascent−descent height. This is stbtt_ScaleForPixelHeight semantics.
virtual float	scaleForEmToPixels (FontHandle font, float pixelHeight) const =0
	Scale factor: em units → pixels. Differs from scaleForPixelHeight when ascent−descent != unitsPerEm. This is the correct scale for CSS font-size.
virtual std::optional< UnderlineMetrics >	underlineMetrics (FontHandle font) const =0
	Underline position/thickness from the 'post' table, in font design units. Returns std::nullopt if the table is missing.
virtual std::optional< UnderlineMetrics >	strikeoutMetrics (FontHandle font) const =0
	Strikeout position/thickness from the OS/2 table, in font design units. Returns std::nullopt if the table is missing.
virtual std::optional< SubSuperMetrics >	subSuperMetrics (FontHandle font) const =0
	Sub/superscript Y offsets from the OS/2 table, in font design units. Returns std::nullopt if the table is missing.
virtual Path	glyphOutline (FontHandle font, int glyphIndex, float scale) const =0
	Extract a glyph outline as a Path. Coordinates are in font units scaled by `scale`, with Y flipped for SVG's y-down convention.
virtual Path	glyphOutline (FontHandle font, int glyphIndex, float scale, bool allowSyntheticOblique) const
	Extract an outline with per-glyph synthetic-oblique permission.
virtual bool	isBitmapOnly (FontHandle font) const =0
	Returns true if the font is bitmap-only (no vector outlines).
virtual bool	isCursive (uint32_t codepoint) const =0
	Returns true if letter-spacing should be suppressed for this codepoint (cursive/connected scripts like Arabic). Simple backends return false.
virtual bool	hasSmallCapsFeature (FontHandle font) const =0
	Returns true if the font has a native OpenType small-caps feature (smcp). If false, the engine synthesizes small-caps via uppercase + reduced size.
virtual std::optional< BitmapGlyphMetrics >	bitmapGlyphMetrics (FontHandle font, int glyphIndex, float scale) const
	Query bounded bitmap metadata without materializing bitmap pixels.
virtual std::optional< BitmapGlyph >	bitmapGlyph (FontHandle font, int glyphIndex, float scale, const BitmapGlyphMetrics &admitted, std::size_t maximumRgbaBytes) const
	Decode only after independently revalidating admitted metrics and the RGBA byte limit. This bounds converted RGBA storage, not every internal decoder allocation.
virtual std::optional< BitmapGlyph >	bitmapGlyph (FontHandle font, int glyphIndex, float scale) const =0
	Extract a bitmap glyph (CBDT/CBLC color emoji). Returns std::nullopt if the glyph is not a bitmap. Simple backends always return std::nullopt.
virtual ShapedRun	shapeRun (FontHandle font, float fontSizePx, std::string_view spanText, size_t byteOffset, size_t byteLength, bool isVertical, FontVariant fontVariant, bool forceLogicalOrder) const =0
	Shape a range of text, producing glyph IDs with advances and kerning.
virtual ShapedRun	shapeRun (FontHandle font, float fontSizePx, std::string_view spanText, size_t byteOffset, size_t byteLength, bool isVertical, TextOrientation textOrientation, FontVariant fontVariant, bool forceLogicalOrder) const
	Shape a range with the resolved vertical text orientation.
virtual ShapedRun	shapeRunNoKerning (FontHandle font, float fontSizePx, std::string_view spanText, size_t byteOffset, size_t byteLength, bool isVertical, FontVariant fontVariant, bool forceLogicalOrder) const
	Shape text with kerning disabled. Backends that cannot selectively disable kerning retain their normal shaping behavior.
virtual ShapedRun	shapeRunNoKerning (FontHandle font, float fontSizePx, std::string_view spanText, size_t byteOffset, size_t byteLength, bool isVertical, TextOrientation textOrientation, FontVariant fontVariant, bool forceLogicalOrder) const
	Shape orientation-aware text with kerning disabled.
virtual ShapedRun	shapeRunInContext (FontHandle font, float fontSizePx, std::string_view spanText, const ShapingContext &context, size_t byteOffset, size_t byteLength, bool isVertical, TextOrientation textOrientation, FontVariant fontVariant, bool kerning) const
	Shape [`byteOffset`, `byteOffset` + `byteLength`) as one part of `context`, such as one face's share of a chunk drawn with several faces.
virtual double	crossSpanKern (FontHandle prevFont, float prevSizePx, FontHandle curFont, float curSizePx, uint32_t prevCodepoint, uint32_t curCodepoint, bool isVertical) const =0
	Compute cross-span kerning between the last codepoint of the previous span and the first codepoint of the current span.
virtual double	crossSpanKern (FontHandle prevFont, float prevSizePx, FontHandle curFont, float curSizePx, uint32_t prevCodepoint, uint32_t curCodepoint, bool isVertical, TextOrientation textOrientation) const
	Compute cross-span kerning with the resolved vertical orientation.
virtual double	crossSpanKern (FontHandle previousFont, float previousSize, FontHandle currentFont, float currentSize, uint32_t previousCodepoint, uint32_t currentCodepoint, bool vertical, TextOrientation orientation, const ShapingContext &context) const
	Resolve a visual neighboring pair inside one shared directional shaping context.
virtual double	crossSpanKernNoKerning (FontHandle, float, FontHandle, float, uint32_t, uint32_t, bool) const
	Compute cross-span kerning with kerning disabled.

Detailed Description

Abstract font backend for text rendering operations.

Abstracts all font-engine-specific calls (stb_truetype, HarfBuzz+FreeType) behind a uniform interface. Used by TextEngine for layout and by renderers for glyph outlines and font metrics.

Implementations:

TextBackendSimple: stb_truetype (no GSUB/GPOS, no bitmap glyphs)
TextBackendFull: HarfBuzz + FreeType (full OpenType shaping)

Class Documentation

◆ donner::svg::TextBackend::BitmapGlyph

struct donner::svg::TextBackend::BitmapGlyph

Bitmap glyph data from color fonts (CBDT/CBLC).

Class Members
double	bearingX = 0	Horizontal offset from glyph origin.
double	bearingY = 0	Vertical offset from baseline (positive = up).
int	height = 0	Bitmap height in pixels.
vector< uint8_t >	rgbaPixels	RGBA pixel data (premultiplied alpha).
double	scale = 1.0	Scale factor to apply.
int	width = 0	Bitmap width in pixels.

◆ donner::svg::TextBackend::ShapedRun

struct donner::svg::TextBackend::ShapedRun

Result of shaping a text range.

Class Members
optional< bool >	backward	Known source-group progression; absent when a backend leaves it implicit in its clusters.
vector< ShapedGlyph >	glyphs

◆ donner::svg::TextBackend::ShapingContext

struct donner::svg::TextBackend::ShapingContext

A byte range of the span text that surrounds a shaped range.

Class Members
size_t	byteLength = 0	Length of the context. Backend-defined shaping properties detected for the whole context.
size_t	byteOffset = 0	Start of the context within the span text.
Detected	detected	Filled on first use, so the ranges of one context detect its properties once.
optional< bool >	rightToLeft	Resolved horizontal embedding parity; overrides every guessed shaping direction.
bool	suppressOptionalSubstitutions = false	Analysis-only shaping suppresses optional substitutions to propose emergency boundaries.
bool	suppressRligForAnalysis = false	Analysis-only rlig comparison for font-dependent lam-alef candidate groups.
WorkBudget *	work = nullptr	Aliases a planner-owned budget alive through all synchronous fragment shaping calls.

Member Function Documentation

◆ bitmapGlyph() [1/2]

virtual std::optional< BitmapGlyph > donner::svg::TextBackend::bitmapGlyph	(	FontHandle	font,
		int	glyphIndex,
		float	scale ) const

pure virtual

Extract a bitmap glyph (CBDT/CBLC color emoji). Returns std::nullopt if the glyph is not a bitmap. Simple backends always return std::nullopt.

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ bitmapGlyph() [2/2]

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

inlinevirtual

Decode only after independently revalidating admitted metrics and the RGBA byte limit. This bounds converted RGBA storage, not every internal decoder allocation.

Parameters

font	Font to decode.
glyphIndex	Glyph within the font.
scale	Requested scale.
admitted	Previously queried cost and placement metadata.
maximumRgbaBytes	Maximum allowed converted RGBA storage bytes.

Reimplemented in donner::svg::TextBackendFull.

◆ bitmapGlyphMetrics()

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

inlinevirtual

Query bounded bitmap metadata without materializing bitmap pixels.

Parameters

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

Reimplemented in donner::svg::TextBackendFull.

◆ crossSpanKern() [1/3]

virtual double donner::svg::TextBackend::crossSpanKern	(	FontHandle	prevFont,
		float	prevSizePx,
		FontHandle	curFont,
		float	curSizePx,
		uint32_t	prevCodepoint,
		uint32_t	curCodepoint,
		bool	isVertical ) const

pure virtual

Compute cross-span kerning between the last codepoint of the previous span and the first codepoint of the current span.

Returns: Kern adjustment in pixels (added to pen position).

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ crossSpanKern() [2/3]

virtual double donner::svg::TextBackend::crossSpanKern	(	FontHandle	prevFont,
		float	prevSizePx,
		FontHandle	curFont,
		float	curSizePx,
		uint32_t	prevCodepoint,
		uint32_t	curCodepoint,
		bool	isVertical,
		TextOrientation	textOrientation ) const

inlinevirtual

Compute cross-span kerning with the resolved vertical orientation.

Reimplemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ crossSpanKern() [3/3]

virtual double donner::svg::TextBackend::crossSpanKern	(	FontHandle	previousFont,
		float	previousSize,
		FontHandle	currentFont,
		float	currentSize,
		uint32_t	previousCodepoint,
		uint32_t	currentCodepoint,
		bool	vertical,
		TextOrientation	orientation,
		const ShapingContext &	context ) const

inlinevirtual

Resolve a visual neighboring pair inside one shared directional shaping context.

Reimplemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ fontVMetrics()

virtual FontVMetrics donner::svg::TextBackend::fontVMetrics ( FontHandle font ) const

pure virtual

Vertical metrics (ascent, descent, lineGap) in font design units.

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ glyphOutline() [1/2]

virtual Path donner::svg::TextBackend::glyphOutline	(	FontHandle	font,
		int	glyphIndex,
		float	scale ) const

pure virtual

Extract a glyph outline as a Path. Coordinates are in font units scaled by scale, with Y flipped for SVG's y-down convention.

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ glyphOutline() [2/2]

virtual Path donner::svg::TextBackend::glyphOutline	(	FontHandle	font,
		int	glyphIndex,
		float	scale,
		bool	allowSyntheticOblique ) const

inlinevirtual

Extract an outline with per-glyph synthetic-oblique permission.

Parameters

font	Face whose glyph is extracted.
glyphIndex	Glyph index in the face.
scale	Font-unit to pixel scale.
allowSyntheticOblique	Whether a synthesized oblique transform may be applied.

Returns: The glyph outline; native styles and variable axes are always preserved.

Reimplemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ hasSmallCapsFeature()

virtual bool donner::svg::TextBackend::hasSmallCapsFeature ( FontHandle font ) const

pure virtual

Returns true if the font has a native OpenType small-caps feature (smcp). If false, the engine synthesizes small-caps via uppercase + reduced size.

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ isBitmapOnly()

virtual bool donner::svg::TextBackend::isBitmapOnly ( FontHandle font ) const

pure virtual

Returns true if the font is bitmap-only (no vector outlines).

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ isCursive()

virtual bool donner::svg::TextBackend::isCursive ( uint32_t codepoint ) const

pure virtual

Returns true if letter-spacing should be suppressed for this codepoint (cursive/connected scripts like Arabic). Simple backends return false.

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ requiresTrustedFontData()

virtual bool donner::svg::TextBackend::requiresTrustedFontData ( ) const

inlinevirtual

Whether this backend may consume only fonts whose byte provenance is trusted.

Reimplemented in donner::svg::TextBackendSimple.

◆ scaleForEmToPixels()

virtual float donner::svg::TextBackend::scaleForEmToPixels	(	FontHandle	font,
		float	pixelHeight ) const

pure virtual

Scale factor: em units → pixels. Differs from scaleForPixelHeight when ascent−descent != unitsPerEm. This is the correct scale for CSS font-size.

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ scaleForPixelHeight()

virtual float donner::svg::TextBackend::scaleForPixelHeight	(	FontHandle	font,
		float	pixelHeight ) const

pure virtual

Scale factor: font design units → pixels, normalized to ascent−descent height. This is stbtt_ScaleForPixelHeight semantics.

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ shapeRun() [1/2]

virtual ShapedRun donner::svg::TextBackend::shapeRun	(	FontHandle	font,
		float	fontSizePx,
		std::string_view	spanText,
		size_t	byteOffset,
		size_t	byteLength,
		bool	isVertical,
		FontVariant	fontVariant,
		bool	forceLogicalOrder ) const

pure virtual

Shape a range of text, producing glyph IDs with advances and kerning.

The full span text and a byte range within it are provided so context-aware backends (HarfBuzz) can use surrounding context for GSUB/GPOS.

Parameters

font	Font to shape with.
fontSizePx	Font size in pixels.
spanText	Full span text (UTF-8).
byteOffset	Start of the range to shape within `spanText`.
byteLength	Length of the range to shape.
isVertical	True for vertical writing mode.
fontVariant	Font variant (Normal or SmallCaps).
forceLogicalOrder	If true, return glyphs sorted by cluster (DOM order) rather than visual order. Used for per-character positioned RTL text.

Returns: Shaped glyphs with advances, kerning, and cluster mapping.

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ shapeRun() [2/2]

virtual ShapedRun donner::svg::TextBackend::shapeRun	(	FontHandle	font,
		float	fontSizePx,
		std::string_view	spanText,
		size_t	byteOffset,
		size_t	byteLength,
		bool	isVertical,
		TextOrientation	textOrientation,
		FontVariant	fontVariant,
		bool	forceLogicalOrder ) const

inlinevirtual

Shape a range with the resolved vertical text orientation.

Reimplemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ shapeRunInContext()

virtual ShapedRun donner::svg::TextBackend::shapeRunInContext	(	FontHandle	font,
		float	fontSizePx,
		std::string_view	spanText,
		const ShapingContext &	context,
		size_t	byteOffset,
		size_t	byteLength,
		bool	isVertical,
		TextOrientation	textOrientation,
		FontVariant	fontVariant,
		bool	kerning ) const

inlinevirtual

Shape [byteOffset, byteOffset + byteLength) as one part of context, such as one face's share of a chunk drawn with several faces.

A context-aware backend shapes the range with the surrounding characters as pre- and post-context and picks its direction, script and language as follows:

A range with no script of its own (punctuation, spaces, symbols) takes the context's direction, script and language, so neutrals mirror and order like their neighbors. When such a range contains decimal digits in a horizontal context, it keeps the context's script and language but runs left to right, as numbers do in right-to-left text.
A strong left-to-right range inside a vertically shaped context is shaped vertically.
A strong right-to-left range keeps its own horizontal direction.

A context no longer than the range adds nothing, and the range is shaped as by shapeRun. Other backends shape the range alone. Glyph clusters are byte offsets into spanText, as for shapeRun.

Parameters

font	Font to shape with.
fontSizePx	Font size in pixels.
spanText	Full span text (UTF-8).
context	Range of `spanText` that contains the shaped range.
byteOffset	Start of the range to shape within `spanText`.
byteLength	Length of the range to shape.
isVertical	True for vertical writing mode.
textOrientation	Resolved vertical text orientation.
fontVariant	Font variant (Normal or SmallCaps).
kerning	False to shape with kerning disabled.

Reimplemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ shapeRunNoKerning() [1/2]

virtual ShapedRun donner::svg::TextBackend::shapeRunNoKerning	(	FontHandle	font,
		float	fontSizePx,
		std::string_view	spanText,
		size_t	byteOffset,
		size_t	byteLength,
		bool	isVertical,
		FontVariant	fontVariant,
		bool	forceLogicalOrder ) const

inlinevirtual

Shape text with kerning disabled. Backends that cannot selectively disable kerning retain their normal shaping behavior.

Reimplemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ shapeRunNoKerning() [2/2]

virtual ShapedRun donner::svg::TextBackend::shapeRunNoKerning	(	FontHandle	font,
		float	fontSizePx,
		std::string_view	spanText,
		size_t	byteOffset,
		size_t	byteLength,
		bool	isVertical,
		TextOrientation	textOrientation,
		FontVariant	fontVariant,
		bool	forceLogicalOrder ) const

inlinevirtual

Shape orientation-aware text with kerning disabled.

Reimplemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ strikeoutMetrics()

virtual std::optional< UnderlineMetrics > donner::svg::TextBackend::strikeoutMetrics ( FontHandle font ) const

pure virtual

Strikeout position/thickness from the OS/2 table, in font design units. Returns std::nullopt if the table is missing.

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ subSuperMetrics()

virtual std::optional< SubSuperMetrics > donner::svg::TextBackend::subSuperMetrics ( FontHandle font ) const

pure virtual

Sub/superscript Y offsets from the OS/2 table, in font design units. Returns std::nullopt if the table is missing.

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

◆ underlineMetrics()

virtual std::optional< UnderlineMetrics > donner::svg::TextBackend::underlineMetrics ( FontHandle font ) const

pure virtual

Underline position/thickness from the 'post' table, in font design units. Returns std::nullopt if the table is missing.

Implemented in donner::svg::TextBackendFull, and donner::svg::TextBackendSimple.

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

donner/svg/text/TextBackend.h

Classes

Public Member Functions

Detailed Description

Class Documentation

◆ donner::svg::TextBackend::BitmapGlyph

◆ donner::svg::TextBackend::ShapedRun

◆ donner::svg::TextBackend::ShapingContext

Member Function Documentation

◆ bitmapGlyph() [1/2]

◆ bitmapGlyph() [2/2]

◆ bitmapGlyphMetrics()

◆ crossSpanKern() [1/3]

◆ crossSpanKern() [2/3]

◆ crossSpanKern() [3/3]

◆ fontVMetrics()

◆ glyphOutline() [1/2]

◆ glyphOutline() [2/2]

◆ hasSmallCapsFeature()

◆ isBitmapOnly()

◆ isCursive()

◆ requiresTrustedFontData()

◆ scaleForEmToPixels()

◆ scaleForPixelHeight()

◆ shapeRun() [1/2]

◆ shapeRun() [2/2]

◆ shapeRunInContext()

◆ shapeRunNoKerning() [1/2]

◆ shapeRunNoKerning() [2/2]

◆ strikeoutMetrics()

◆ subSuperMetrics()

◆ underlineMetrics()