simvx.graphics.text_renderer

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

Module Contents

Classes

TextRenderer

Manages font atlases and batches text geometry for GPU submission.

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(max_chars: int = 4096)

Manages font atlases and batches text geometry for GPU submission.

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.

begin_frame() → None

Reset vertex batch for new frame.

draw_text(text: str, x: float, y: float, font_path: str | None = None, size: float = 24.0, colour: tuple[float, ...] = (1.0, 1.0, 1.0, 1.0), font_size: int = 48) → None

Append text quads to the per-frame vertex batch.

Args: text: String to render. x, y: Top-left position in pixel coordinates. font_path: Path to .ttf file (auto-detected if None). size: Display size in pixels. colour: RGBA colour tuple. font_size: Atlas generation size (higher = sharper base quality).

property vertices: numpy.ndarray

Vertex array for the current frame (trimmed to actual size).

property indices: numpy.ndarray

Index array for the current frame (trimmed to actual size).

property char_count: int

property has_text: bool

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.