Struct ViewportRuntime 

pub struct ViewportRuntime { /* private fields */ }

Per-frame scene orchestration layer.

Owns plugins, an optional fixed timestep accumulator, and a transform snapshot table. Does not own the scene, selection, GPU resources, or window.

Priority execution order

Each call to step executes plugins in ascending priority order:

1. [i32::MIN, SELECT) – Prepare (100), Pick (200): once, at wall dt
2. [SELECT, MANIPULATE) – Select (300): once (built-in SelectionSystem runs first)
3. [MANIPULATE, SIMULATE) – Manipulate (400), Animate (500): once
4. [SIMULATE, POST_SIM) – Simulate (600): once per fixed step or once at wall dt
5. [POST_SIM, i32::MAX] – PostSim (700), Writeback (800): once at wall dt

Implementations

impl ViewportRuntime

pub fn new() -> Self

Create a runtime with default settings and no plugins.

pub fn with_selection_system(self) -> Self

Enable the built-in click-to-select system.

The SelectionSystem runs before the Select phase each frame. It reads RuntimeFrameContext::clicked, pick_hit, and shift_held to produce SelectionOp entries in RuntimeOutput.

pub fn with_manipulation_system(self) -> Self

Enable the built-in manipulation system.

The ManipulationSystem runs before the Manipulate phase each frame. It drives G/R/S sessions and gizmo drag from RuntimeFrameContext inputs, writing transform changes via TransformWriteback.

pub fn is_manipulating(&self) -> bool

True while the built-in manipulation system has an active G/R/S session or gizmo drag.

Use this to suppress orbit camera movement while manipulating objects.

pub fn manipulation_system(&self) -> Option<&ManipulationSystem>

Access the built-in manipulation system, if enabled.

pub fn with_mode(self, mode: SceneRuntimeMode) -> Self

Set the runtime mode.

pub fn with_plugin(self, plugin: impl RuntimePlugin) -> Self

Register a plugin. Plugins run in ascending priority order each frame. Plugins with equal priority run in registration order (stable sort).

pub fn add_plugin(&mut self, plugin: impl RuntimePlugin)

Register a plugin on an existing runtime.

Same semantics as with_plugin but takes &mut self, for hosts that need to add plugins after the runtime has been constructed and possibly already run frames.

pub fn with_gpu_plugin(self, plugin: impl GpuPlugin) -> Self

Register a GPU plugin. GPU plugins encode wgpu command buffers from ViewportRuntime::pre_prepare, which the host calls each frame after step and before renderer.prepare(). Plugins run in ascending priority order; equal priorities preserve registration order.

Registering a plugin after the runtime has already run a frame re-runs every GPU plugin’s init_gpu on the next pre_prepare. Implementations should be idempotent or guard their own one-time setup.

pub fn add_gpu_plugin(&mut self, plugin: impl GpuPlugin)

Register a GPU plugin on an existing runtime.

Same semantics as with_gpu_plugin but takes &mut self.

pub fn with_gpu_plugin_for_viewport( self, viewport: ViewportId, plugin: impl GpuPlugin, ) -> Self

Register a GPU plugin scoped to a single viewport.

The plugin’s pre_prepare and post_paint only execute when the host’s GpuFrameContext::viewport_id equals viewport. init_gpu and on_device_recreated still run unconditionally.

Use this in multi-viewport hosts (CAD quad-view, split-screen) that call pre_prepare / post_paint once per viewport with a populated viewport_id. Single-viewport hosts that never set viewport_id effectively disable scoped plugins; use with_gpu_plugin instead.

pub fn notify_device_recreated(&mut self, device: &Device, queue: &Queue)

Notify every registered GPU plugin that the wgpu device has been recreated (device loss, surface re-init, host-driven reset).

Calls GpuPlugin::on_device_recreated on each plugin, then clears the init flag so init_gpu runs again with the new device on the next pre_prepare. The runtime does not detect device loss on its own; the host is responsible for invoking this when it recreates the device.

pub fn pre_prepare( &mut self, device: &Device, queue: &Queue, ctx: &GpuFrameContext<'_>, ) -> Vec<CommandBuffer>

Run every registered GPU plugin’s pre_prepare in ascending priority order and return the concatenated command buffers.

Call after step and before renderer.prepare(). The returned buffers should be submitted ahead of the renderer’s own:

let plugin_bufs  = runtime.pre_prepare(device, queue, &gpu_ctx);
let prepare_bufs = renderer.pass().prepare(device, queue, &frame);
queue.submit(plugin_bufs.into_iter().chain(prepare_bufs));

wgpu submit ordering guarantees plugin work completes before prepare()’s, so any storage buffer written by a plugin is observable by the standard render passes in the same frame.

On the first call (or after a new plugin is registered), every plugin’s init_gpu is invoked once before any pre_prepare.

pub fn post_paint( &mut self, device: &Device, queue: &Queue, targets: &PostPaintTargets<'_>, ctx: &GpuFrameContext<'_>, ) -> Vec<CommandBuffer>

Run every registered GPU plugin’s post_paint in ascending priority order and return the concatenated command buffers.

Call after renderer.paint_to() has run for the frame. The host supplies views of the just-rendered color and depth targets (and optionally a pick-id view), and is responsible for compositing any plugin overlay output into the final image: the lib does not loop plugin output back into the rendered color.

Plugins registered after the first frame still go through init_gpu on the next pre_prepare; this method does not trigger init on its own to keep the post-paint path deterministic.

pub fn with_fixed_timestep(self, ts: FixedTimestep) -> Self

Enable fixed-timestep accumulation for physics plugins.

When set, plugins in the [SIMULATE, POST_SIM) range run once per accumulated fixed step rather than once per frame at wall dt. All other priority ranges always run once per frame.

pub fn set_fixed_timestep(&mut self, ts: FixedTimestep)

Replace the fixed timestep at runtime. Resets the accumulator.

Use this to change the simulation rate after construction without rebuilding the runtime or its plugins.

pub fn clear_fixed_timestep(&mut self)

Remove the fixed timestep, reverting to one simulate call per frame at wall dt.

pub fn mode(&self) -> SceneRuntimeMode

The current runtime mode.

pub fn snapshots(&self) -> &TransformSnapshotTable

The transform snapshot table for interpolated rendering.

Updated each frame during writeback. Pass alpha as the blend factor to TransformSnapshotTable::interpolated.

pub fn resources(&self) -> &RuntimeResources

Read access to the shared resource registry.

Use this after step to inspect resources without running the frame loop. During the frame loop, access resources through RuntimeStepContext::resources.

pub fn resources_mut(&mut self) -> &mut RuntimeResources

Write access to the shared resource registry.

Use this to pre-populate resources before the first step, or to inject resources from outside the plugin system (e.g. from the application).

pub fn alpha(&self) -> f32

Blend factor for rendering interpolation between fixed steps.

Returns 1.0 if no fixed timestep is configured (render directly from current scene transforms without interpolation).

pub fn step_index(&self) -> u64

Monotonically increasing simulation step counter.

Incremented once per simulate execution. With a fixed timestep this means it may increment multiple times per rendered frame. Wraps on overflow.

pub fn with_camera_follow(self, follow: CameraFollow) -> Self

Set a camera follow binding (builder style).

Each call to step will compute a suggested camera center from the followed node and emit it as a CameraFollowTarget event on RuntimeOutput::events.

pub fn set_camera_follow(&mut self, follow: CameraFollow)

Update the camera follow binding at runtime.

pub fn clear_camera_follow(&mut self)

Remove the camera follow binding. No CameraFollowTarget event will be emitted after this call.

pub fn camera_follow(&self) -> Option<&CameraFollow>

The current camera follow binding.

pub fn step( &mut self, scene: &mut Scene, selection: &mut Selection, frame: &RuntimeFrameContext, ) -> RuntimeOutput

Run one frame of the runtime.

Plugins run in ascending priority order. The simulate range [SIMULATE, POST_SIM) runs once per accumulated fixed step (or once at frame.dt when no fixed timestep is configured). All other ranges run once per frame. Transform ops are flushed to scene and the snapshot table is updated after the writeback range.

Selection ops produced by plugins are applied to selection before returning. Contact events and the applied transform ops are returned in RuntimeOutput.

Trait Implementations

impl Default for ViewportRuntime

fn default() -> Self

Returns the “default value” for a type.