Windowing backends¶

The windowing backend gives the Vulkan renderer its surface. With no choice made, App tries SDL3, then GLFW, then Qt and uses the first that imports. Pin one with backend=:

from simvx.graphics import App

app = App(title="Game", backend="glfw")

GLFW always installs with SimVX. SDL3 and Qt are extras: pip install --pre "simvx-graphics[sdl3]" or "simvx-graphics[qt]". Rendering is identical on all three; they differ in input and lifecycle features.

Feature matrix¶

Legend: ✓ supported · partial · ✗ not supported.

Capability	SDL3	GLFW	Qt (PySide6)
Keyboard input	✓	✓	✓
Mouse buttons + cursor pos	✓	✓	✓
Mouse scroll wheel	✓	✓	✓ (mouse_button)
Cursor shape	✓	✓	✓
Controller (buttons + axes)	✓	✓	✗
Touch events	✓ (`set_touch_callback`)	✗	✗
Pen pressure and tilt	✓	✗	✗
Pointer lock	✓ (relative mouse mode)	✓	✗ (grab is not a lock)
Platform event timestamps	✓	✗	✓
IME / text input (Unicode)	✓ (always-on)	✓ (always-on)	✓
Clipboard read/write	✗ (use OS shim)	✗ (use OS shim)	✗ (use OS shim)
Drag-and-drop (file paths)	✗	✗	✗
Native file dialogs	✗ (use SimVX UI `FileBrowser`)	✗ (use SimVX UI `FileBrowser`)	✗ (use SimVX UI `FileBrowser`)
Multi-window	✗ (single window)	✗ (single window)	✗ (single window)
Headless / hidden window	✓ (`visible=False`)	✓ (`visible=False`)	partial (Qt creates a real window)
Fullscreen toggle	✗	✓ (`set_fullscreen`)	✗
App lifecycle hooks	✓ (`set_lifecycle_callback`, mobile)	✗	✗
Pause-when-backgrounded	✓ (`paused`)	✗	✗
HiDPI content scale	✓	✓	✓
Vulkan surface creation	✓	✓	✓

A game reads what the active backend can do from Input.capabilities. A backend declares each fact when it creates its window, and only a backend that knows a fact turns it on.

For anyone writing a backend, two obligations to the input layer:

Keys are physical positions. A backend whose native codes are layout keysyms converts first (Qt does, through its native scan code), so a rebind file made under one backend binds the same four positions under another.
Pads are polled before the frame’s ticks, not between physics and logic, or a pad edge reaches a tick a frame later than a key edge.

When to pick each backend¶

SDL3 for touch screens, pens, and mobile-style app lifecycle (pause when backgrounded). It is the only backend with multi-touch.
GLFW for a plain desktop game: the smallest dependency, and the only built-in fullscreen toggle. It installs by default.
Qt (PySide6) only to put the Vulkan surface inside an existing Qt application. It has no touch, controller or fullscreen toggle, and App(visible=False) still opens a window.

Headless rendering¶

App(visible=False) and App.run_headless(scene, frames=N) work on all three, but only SDL3 and GLFW really hide the window: PySide6 cannot create a Vulkan surface without a real one, so Qt positions it off screen. Use SDL3 or GLFW for CI and test captures.

Known limitations¶

SDL3 text input is always on rather than following focus, which can make a mobile IME flicker.
No backend delivers dropped file paths.
Each backend opens a single window.