simvx.graphics.text_renderer

Text rendering: font caching, vertex batching, and font fallback chain.

Module Contents

Classes

TextRenderer

Manages MSDF font atlases + the font fallback chain (the shared atlas store).

Functions

get_shared_text_renderer	Return the module-level shared TextRenderer (lazy singleton).
rasterise	Bake a string into an RGBA uint8 buffer using FreeType bitmap rendering.

Data

__all__
log

API

simvx.graphics.text_renderer.__all__

[‘TextRenderer’, ‘_find_font’, ‘_find_cjk_fonts’, ‘get_shared_text_renderer’, ‘rasterise’]

simvx.graphics.text_renderer.log

‘getLogger(…)’

class simvx.graphics.text_renderer.TextRenderer

Manages MSDF font atlases + the font fallback chain (the shared atlas store).

After the P3a one-text-path unification this class no longer lays out or batches glyph geometry (the deleted desktop overlay pass did that): the ONE glyph layout lives in :mod:draw2d_text, which draws through Draw2D. What survives here is the part both paths need – atlas generation (:meth:get_atlas), glyph ensuring with the fallback chain (:meth:_ensure_with_fallback), and the CJK fallback auto-detection – since Draw2D._font is one of these atlases.

Supports a font fallback chain: when the primary font is missing a glyph (e.g. CJK characters), fallback fonts are tried in order. Fallback glyphs are packed into the primary atlas so the GPU sees a single texture.

Initialization

property fallback_fonts: list[simvx.core.text.Font]

The current fallback font chain.

set_font_fallbacks(paths: list[str], font_size: int = 64) → None

Set the font fallback chain (replaces auto-detected fallbacks).

Fonts are tried in order when the primary font is missing a glyph. Each path should be a .ttf or .ttc file.

get_atlas(font_path: str, font_size: int = 64) → simvx.core.text.MSDFAtlas

Get or create an MSDF atlas for the given font.

property atlas_version: int

simvx.graphics.text_renderer.get_shared_text_renderer() → simvx.graphics.text_renderer.TextRenderer

Return the module-level shared TextRenderer (lazy singleton).

simvx.graphics.text_renderer.rasterise(text: str, size: int = 24, font: str | pathlib.Path | simvx.core.text.Font | None = None, *, colour: tuple[float, float, float, float] = (1.0, 1.0, 1.0, 1.0), padding: int = 2) → numpy.ndarray

Bake a string into an RGBA uint8 buffer using FreeType bitmap rendering.

Every port that draws text-on-textures (cards, tiles, sprite atlases) re-invented this freetype glue: open a face, walk glyphs, lay them out along the baseline, composite into a buffer. Centralised here so ports pass a string and get pixels back.

Args: text: Single- or multi-line string to bake. \n starts a new line. size: Pixel size for the font (height of one line of text). font: A :class:Font instance, a path to a .ttf/.otf, or None to auto-detect via :func:_find_font. colour: RGBA tint applied to each glyph’s coverage value. padding: Pixels of transparent margin around the laid-out text.

Returns: (H, W, 4) uint8 array, ready for :func:save_png or :class:TextureManager.load_from_array. Empty input returns a (0, 0, 4) array.