simvx.graphics.app

Graphics application layer — engine wrapper with node tree support.

Module Contents

Classes

App

Graphics application wrapper. Supports both raw callbacks and node tree scenes.

Data

log

__all__

API

simvx.graphics.app.log[source]

‘getLogger(…)’

simvx.graphics.app.__all__

[‘App’, ‘AVAILABLE_BACKENDS’]

class simvx.graphics.app.App(title: str = 'SimVX', width: int = 1280, height: int = 720, backend: str | None = None, physics_fps: int = 60, visible: bool = True, vsync: bool = True, bg_colour: tuple[float, float, float, float] | str | None = None, **_kwargs)[source]

Graphics application wrapper. Supports both raw callbacks and node tree scenes.

Args: title: Window title string. width: Window width in pixels (must be >= 1). height: Window height in pixels (must be >= 1). backend: Windowing backend name. One of "glfw" (desktop), "sdl3" (touch/mobile), "qt" (embedding). None auto-detects. physics_fps: Physics simulation rate. visible: Open a visible window. Set False for headless tests. vsync: Enable vertical sync at present time. bg_colour: Background clear colour. "transparent", an RGBA tuple, or None to use the theme background.

Usage with node tree (recommended)::

app = App(title="My Game", width=1280, height=720)
app.run(MyGameScene())  # Node subclass with ready()/process()

Usage with raw callbacks::

app = App(title="My Game")
app.run(update=my_update, render=my_render)

After run() has created the window, window_title, window_size, and active_backend reflect the live state.

Initialization

toggle_fullscreen() → None[source]

Toggle fullscreen mode.

property is_fullscreen: bool
property engine: simvx.graphics.engine.Engine | None

Access the graphics engine (available after run() starts).

property active_backend: str | None

Return the resolved backend name (e.g. "glfw"), or None if the engine has not yet initialised a window.

property window_title: str

Current window title. Writable once the window exists.

property window_size: tuple[int, int]

Current window (width, height). Writable once the window exists.

run(root_or_update: Any = None, *, update: collections.abc.Callable[[], None] | None = None, render: collections.abc.Callable[[object, tuple[int, int]], None] | None = None) → None[source]

Run the graphics engine.

Args: root_or_update: Either a Node (scene root) or a legacy update callback. When a Node is passed, SceneTree and input are set up automatically. update: Legacy per-frame callback (alternative to positional arg). render: Custom render callback (cmd, extent). Only used in callback mode.

run_headless(root_node: Any, *, frames: int = 1, on_frame: collections.abc.Callable[[int, float], bool | None] | None = None, capture_frames: list[int] | None = None, capture_fn: collections.abc.Callable[[int], bool] | None = None) → list[source]

Run the engine headlessly for frames frames and return captured pixels.

Args: root_node: Scene root node. frames: Total number of frames to simulate. on_frame: Optional callback invoked with (frame_index, time) before each frame. Return False to stop early. capture_frames: Which frame indices to capture (None = capture all). capture_fn: Dynamic capture predicate — called with frame index, captures if True. Takes precedence over capture_frames when provided.

Returns: List of (H, W, 4) uint8 RGBA numpy arrays.

run_streaming(root_node: Any, server: Any) → None[source]

Run the engine headlessly and stream frames to browsers via WebRTC.

Args: root_node: Scene root node. server: A StreamingServer instance (from simvx.graphics.streaming).