`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¶

`resolve_font`	Path of the font a project’s text is drawn with, or None if there is none.
`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’, ‘_find_system_font’, ‘get_shared_text_renderer’, ‘…

simvx.graphics.text_renderer.log¶: ‘getLogger(…)’

class simvx.graphics.text_renderer.TextRenderer¶

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

This class does not lay out or batch glyph geometry: the one glyph layout lives in :mod:draw2d_text, which draws through Draw2D. What lives here is what every text path needs – atlas generation (:meth:get_atlas), glyph ensuring with the fallback chain (:meth:_ensure_with_fallback), and the fallback auto-detection – since Draw2D._font is one of these atlases.

Supports a font fallback chain: when the primary font is missing a glyph (the scripts and symbol blocks the bundled floor carries, CJK characters, or the private-use icon glyphs only nerd fonts carry), 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.

font_size sizes the faces the chain keeps for glyph lookup only: a glyph borrowed from one of them is always rasterised at the size of the atlas it is packed into, whatever that size is.

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.resolve_font(project_dir: str | pathlib.Path | None = None) → str | None¶

Path of the font a project’s text is drawn with, or None if there is none.

In order: the face the project named in [rendering] font, then the machine’s own fonts if it asked for those with prefer_system_fonts, then the font the engine ships with. The bundled face winning by default is what makes every machine render text in the same typeface and an export bake that typeface whoever builds it; every step after a failed one falls through to the next, so no configuration can leave text unrendered.

project_dir is where the search for simvx.toml starts. A running game stands in its own project, so :func:_find_font leaves it None and gets the working directory; a tool that works on a project it is not standing in, the web exporter above all, names that project’s directory, or it bakes a different typeface from the one the game runs in.

Not cached: the caller names which project it is asking about, and two callers may not mean the same one.

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.

simvx.graphics.text_renderer¶