gpui-python-runtime

Retained scene specifications for the GPUI Python wrapper.

Python declares UI and scene3d objects. Rust validates the scene, tracks stable ids, classifies dirty resources, and adapts supported nodes to gpui-d3rs 3D elements. Raw wgpu devices, queues, buffers, pipelines, and shaders remain private to the renderer.

V1 Scene3D Scope

• Surfaces: row-major z grids with optional x/y axes, log axes, z range, labels, colormaps, wireframe mode, orbit cameras, and interactions.
• Lines: retained orbit camera state and CPU-projected Lines3DElement segments/line strips.
• Meshes, materials, perspective cameras, and lights: validated spec objects for the lower-level scene API. Mesh rendering is intentionally not bound to a GPUI element yet.

JSON Schema Contract

Python-authored payloads are versioned at the JSON boundary:

• app IR uses schema_version: 1, exposed as PYTHON_APP_IR_SCHEMA_VERSION.
• Scene3D specs use schema_version: 1, exposed as SCENE3D_SPEC_SCHEMA_VERSION.

New Python emitters write the current schema version. Rust treats omitted schema_version fields as v1 so early examples and local scripts keep loading, but validation rejects unsupported future versions before rendering or reusing a cached spec.

Compatibility policy:

1. Additive optional fields may stay on v1 when Rust gives them safe defaults.
2. Renaming fields, removing fields, changing data-shape semantics, or changing renderer meaning requires a schema-version bump.
3. A schema-version bump must include compatibility tests for previous v1 payloads and a migration path before Python emitters start writing it.
4. Consumers should parse JSON, validate PythonAppIr, then parse and validate Scene3D specs through TypedSpecCache or validate_scene3d_spec_schema_version.

Resource Model

RetainedSceneCache fingerprints geometry, material, and camera state separately:

• unchanged scenes do no renderer work,
• camera-only changes update uniforms/state,
• color/material changes update small renderer state,
• data/mesh changes reupload affected geometry.

Gpui3DCache is available behind the gpui feature and keeps Surface3DElement / line camera state keyed by stable ids.

Python Examples

The examples build JSON-serializable scene specs that the Rust runtime can validate and adapt to GPUI elements:

PYTHONPATH=python python examples/surface_dispersion.py
PYTHONPATH=python python examples/lines_orbit.py
PYTHONPATH=python python examples/mesh_scene.py

• surface_dispersion.py shows a log-frequency surface with orbit controls.
• lines_orbit.py shows line strips, axis references, and a shared orbit camera.
• mesh_scene.py shows the future lower-level scene shape with mesh, path, and light nodes.

The larger app-authored demos mirror the Rust showcase programs:

# Dump the native app IR without requiring a GPUI host.
GPUI_TOOLKIT_DUMP_IR=1 PYTHONPATH=python python examples/spinorama_demo.py
GPUI_TOOLKIT_DUMP_IR=1 PYTHONPATH=python python examples/surface3d_demo.py
GPUI_TOOLKIT_DUMP_IR=1 PYTHONPATH=python python examples/chart_gallery.py

# Without a host-related environment variable, each script prints JSON too.
PYTHONPATH=python python examples/spinorama_demo.py > /tmp/spinorama-python.json

• spinorama_demo.py contains CEA2034, horizontal SPL, vertical SPL, contour, and retained 3D surface sections using deterministic local data.
• surface3d_demo.py contains the sinc, spinorama-style, and saddle surface modes from the Rust surface3d_demo.
• chart_gallery.py covers scatter, line, area, heatmap, contour, isoline, bar, pie, donut, box-plot, and treemap declarations.

Replace the local data-builder functions with measurement or application data when adapting a demo; the chart and Scene3D declarations remain unchanged.

Python Package

The Python declarations are packaged as gpui-toolkit with the import package gpui_toolkit. The package is pure Python and intentionally has no runtime dependencies; Rust/GPUI remains the rendering host.

python -m pip install gpui-toolkit
python -c "import gpui_toolkit; print(gpui_toolkit.__version__)"

The package version matches the Rust crate version. Update both pyproject.toml and Cargo.toml together when releasing a new Python-facing runtime.

Showcase Application

Run the Python-authored native GPUI showcase with retained 3D scenes and embedded gpui-px charts:

cargo run -p gpui-python-runtime --features showcase --bin gpui-python-showcase -- crates/gpui-toolkit/gpui-python-runtime/python/showcase.py
PYTHONPATH=crates/gpui-toolkit/gpui-python-runtime/python ./venv/bin/python crates/gpui-toolkit/gpui-python-runtime/python/showcase.py

The showcase app, sections, UI kit demos, chart data, and scene3d specs live in Python. Rust loads the JSON UI IR, then owns GPUI, retained 3D renderer state, chart widgets, and theme integration.

Platform Notes

The renderer path is inherited from wgpu via gpui-d3rs:

• macOS/iOS: Metal,
• Linux: Vulkan where available,
• Windows: DirectX 12 or Vulkan depending adapter support,
• Android: Vulkan once a GPUI Android backend exists.

The Python API is intended to stay the same across platforms; only GPUI backend initialization should differ.