Rendering text¶

2D overlays, 3D billboards, text baked onto surfaces, and CJK fallback.

Tags: 3d

Shows the three ways to put text on screen and how non-Latin scripts are handled:

Text2D nodes draw a screen-space overlay on top of the 3D scene. Set text and font_scale; position with the usual Node2D transform.
Text3D floats a depth-tested MSDF billboard at a 3D world position, so it is occluded by geometry in front of it instead of being pasted over the frame.
Text painted onto a cube face is a normal texture: engine.create_text_texture() rasterises a string to an image that a Material samples like any other texture.
Japanese (hiragana, katakana, kanji) renders with no extra setup, by two different routes. On the desktop, glyphs the primary font lacks are borrowed from a CJK face found on the machine and packed into the same atlas. A web export bakes only the glyphs the bundled font itself can draw, so those characters are rasterised on demand by the browser’s own text engine instead.

Controls: ESC: Quit

Usage: uv run python examples/features/3d/text.py

Source¶

#!/usr/bin/env python3
"""Rendering text: 2D overlays, 3D billboards, text baked onto surfaces, and CJK fallback.

Shows the three ways to put text on screen and how non-Latin scripts are handled:

  - Text2D nodes draw a screen-space overlay on top of the 3D scene. Set ``text``
    and ``font_scale``; position with the usual Node2D transform.
  - Text3D floats a depth-tested MSDF billboard at a 3D world position, so it is
    occluded by geometry in front of it instead of being pasted over the frame.
  - Text painted onto a cube face is a normal texture: ``engine.create_text_texture()``
    rasterises a string to an image that a Material samples like any other texture.
  - Japanese (hiragana, katakana, kanji) renders with no extra setup, by two
    different routes. On the desktop, glyphs the primary font lacks are borrowed
    from a CJK face found on the machine and packed into the same atlas. A web
    export bakes only the glyphs the bundled font itself can draw, so those
    characters are rasterised on demand by the browser's own text engine instead.

Controls:
    ESC: Quit

Usage:
    uv run python examples/features/3d/text.py
"""

import math

from simvx.core import (
    Camera3D,
    DirectionalLight3D,
    Input,
    InputMap,
    Key,
    Material,
    Mesh,
    MeshInstance3D,
    Node,
    Text2D,
    Text3D,
    Vec3,
)
from simvx.graphics import App


class RotatingCube(MeshInstance3D):
    """A cube that rotates around its Y axis."""

    def __init__(self, speed: float = 45.0, **kwargs):
        super().__init__(**kwargs)
        self.speed = speed

    def on_update(self, dt: float):
        self.rotate_y(math.radians(self.speed) * dt)


class TextDemoScene(Node):
    """Main demo scene with labeled cubes and text overlays."""

    def on_ready(self):
        InputMap.add_action("escape", [Key.ESCAPE])

        engine = self.app.engine

        # Camera: positioned to see cubes at origin
        camera = self.add_child(
            Camera3D(
                name="Camera",
                position=Vec3(0, 3, 8),
            )
        )
        camera.look_at(Vec3(0, 0, 0))
        camera.fov = 50.0

        light = self.add_child(DirectionalLight3D(name="Sun"))
        light.look_at(Vec3(-1, -2, -1))

        # Create text textures for each cube label
        labels = [
            ("RED", (1.0, 0.3, 0.3, 1.0)),
            ("GREEN", (0.3, 1.0, 0.4, 1.0)),
            ("BLUE", (0.4, 0.5, 1.0, 1.0)),
        ]
        text_textures = []
        for label, colour in labels:
            tt = engine.create_text_texture(size=48, width=256, height=64)
            tt.colour = colour
            tt.text = label
            text_textures.append(tt)

        # Red cube: left, rotating slowly
        red = self.add_child(
            RotatingCube(
                name="RedCube",
                position=Vec3(-2.5, 0, 0),
                speed=30.0,
            )
        )
        red.mesh = Mesh.cube(size=1.5)
        red.material = Material(colour=(0.9, 0.2, 0.2, 1.0))
        red.material.albedo_tex_index = text_textures[0].texture_index

        # Green cube: center, rotating faster
        green = self.add_child(
            RotatingCube(
                name="GreenCube",
                position=Vec3(0, 0, 0),
                speed=60.0,
            )
        )
        green.mesh = Mesh.cube(size=1.5)
        green.material = Material(colour=(0.2, 0.8, 0.3, 1.0))
        green.material.albedo_tex_index = text_textures[1].texture_index

        # Blue cube: right, counter-rotating
        blue = self.add_child(
            RotatingCube(
                name="BlueCube",
                position=Vec3(2.5, 0, 0),
                speed=-45.0,
            )
        )
        blue.mesh = Mesh.cube(size=1.5)
        blue.material = Material(colour=(0.2, 0.4, 0.9, 1.0))
        blue.material.albedo_tex_index = text_textures[2].texture_index

        # --- 3D text billboard ---
        # A world-space label above the centre cube. It faces the camera but is
        # depth-tested against the scene, so a cube passing in front hides it.
        self.add_child(
            Text3D(
                name="CubeLabel",
                text="Text3D billboard",
                position=Vec3(0, 1.6, 0),
                font_scale=3.0,
                colour=(1.0, 0.85, 0.4, 1.0),
            )
        )

        # --- 2D text overlays ---
        self.add_child(
            Text2D(
                name="Title",
                text="Text Rendering",
                position=(10.0, 10.0),
                font_scale=2.0,
                colour=(1.0, 1.0, 1.0, 1.0),
            )
        )

        self.add_child(
            Text2D(
                name="Subtitle",
                text="Baked text textures on the cubes, a Text3D billboard, and these Text2D overlays",
                position=(10.0, 50.0),
                font_scale=1.2,
                colour=(0.71, 0.71, 0.71, 1.0),
            )
        )

        self.add_child(
            Text2D(
                name="Hiragana",
                text="ひらがな: あいうえお かきくけこ",
                position=(10.0, 90.0),
                font_scale=1.2,
                colour=(1.0, 0.59, 0.78, 1.0),
            )
        )
        self.add_child(
            Text2D(
                name="Katakana",
                text="カタカナ: アイウエオ カキクケコ",
                position=(10.0, 120.0),
                font_scale=1.2,
                colour=(0.59, 0.78, 1.0, 1.0),
            )
        )
        self.add_child(
            Text2D(
                name="Kanji",
                text="漢字: 東京都 日本語テスト",
                position=(10.0, 150.0),
                font_scale=1.2,
                colour=(1.0, 0.9, 0.39, 1.0),
            )
        )

        # Dynamic frame counter
        self.frame_text = self.add_child(
            Text2D(
                name="FrameCounter",
                text="Frame: 0",
                position=(10.0, 190.0),
                font_scale=1.0,
                colour=(0.39, 1.0, 0.39, 1.0),
            )
        )

        self.frame = 0

    def on_update(self, dt: float):
        self.frame += 1
        self.frame_text.text = f"Frame: {self.frame}  dt: {dt*1000:.1f}ms"

        if Input.is_action_just_pressed("escape"):
            self.app.quit()


def main():
    app = App(
        title="Text Rendering",
        width=1280,
        height=720,
    )
    app.run(TextDemoScene())


if __name__ == "__main__":
    main()