pub struct OrbitCameraController {
pub navigation_mode: NavigationMode,
pub fly_speed: f32,
pub fly_boost: f32,
pub orbit_sensitivity: f32,
pub zoom_sensitivity: f32,
pub gesture_sensitivity: f32,
/* private fields */
}Expand description
High-level orbit / pan / zoom camera controller.
Wraps the lower-level ViewportInput resolver and applies semantic
camera actions to a Camera in a single apply_to_camera call.
The controller keeps the orbit centre and distance as its own state and writes the camera’s pose, with the focus distance set to the orbit distance. When something else moves the camera (a fly-to, a preset, a host writing the pose), the next call reads the pivot back from the camera’s focus point, so the orbit continues from the new view.
§Integration pattern (winit / single window)
// --- AppState construction ---
controller.begin_frame(ViewportContext::new(InputOwnership::full_window(), viewport_size));
// --- window_event ---
controller.push_event(translated_event);
// --- RedrawRequested ---
controller.apply_to_camera(&mut state.camera);
controller.begin_frame(ViewportContext::new(InputOwnership::full_window(), viewport_size));
// ... render ...§Integration pattern (eframe / egui)
// --- update() ---
use viewport_lib_input::input::adapters::{AdapterCtx, egui};
let ownership = egui::ownership(&response, ui.ctx(), rect, session_active);
controller.begin_frame(ViewportContext::new(ownership, [rect.width(), rect.height()]));
let actx = AdapterCtx::new(1.0, glam::Vec2::new(rect.left(), rect.top()));
let mut events = Vec::new();
ui.input(|i| {
egui::begin_frame(i, &actx, &mut events);
for ev in &i.events {
egui::translate(ev, &actx, &mut events);
}
});
for ev in events {
controller.push_event(ev);
}
controller.apply_to_camera(&mut self.camera);Fields§
How drag input is interpreted by apply_to_camera.
Defaults to NavigationMode::Arcball.
fly_speed: f32Movement speed for NavigationMode::Fly, in world units per second.
Moving diagonally is as fast as moving straight.
Defaults to 6.0. Scale this to match your scene : 6.0 suits a scene
with objects a few units across.
fly_boost: f32Multiplier on fly_speed while
Action::FlySpeedBoost is held
(Shift in the default bindings). Defaults to 3.0.
orbit_sensitivity: f32Sensitivity for drag-based orbit (radians per pixel).
zoom_sensitivity: f32Sensitivity for scroll-based zoom (scale factor per pixel).
gesture_sensitivity: f32Sensitivity applied to two-finger trackpad rotation gesture (radians per radian).
Default: 1.0 (gesture angle applied directly to camera yaw).
Set to 0.0 to suppress the gesture entirely.
Implementations§
Source§impl OrbitCameraController
impl OrbitCameraController
Sourcepub const DEFAULT_ORBIT_SENSITIVITY: f32 = 0.005
pub const DEFAULT_ORBIT_SENSITIVITY: f32 = 0.005
Default drag orbit sensitivity: 0.005 radians per pixel.
Sourcepub const DEFAULT_ZOOM_SENSITIVITY: f32 = 0.001
pub const DEFAULT_ZOOM_SENSITIVITY: f32 = 0.001
Default scroll zoom sensitivity: 0.001 scale per pixel.
Sourcepub const DEFAULT_GESTURE_SENSITIVITY: f32 = 1.0
pub const DEFAULT_GESTURE_SENSITIVITY: f32 = 1.0
Default gesture sensitivity: 1.0 (gesture radians applied 1:1 to camera yaw).
Sourcepub const DEFAULT_FLY_SPEED: f32 = 6.0
pub const DEFAULT_FLY_SPEED: f32 = 6.0
Default fly speed: 6 world units per second.
Sourcepub const DEFAULT_FLY_BOOST: f32 = 3.0
pub const DEFAULT_FLY_BOOST: f32 = 3.0
Default fly speed multiplier while boosting.
Sourcepub fn new_stateless() -> Self
pub fn new_stateless() -> Self
Create a controller that holds no bindings of its own.
This is the one to use. The host (or a ViewportInstance) owns the
ViewportInput that holds the bindings and resolves the frame; the
controller just applies the resulting ActionFrame to a camera through
apply. Sensitivities stay on the controller.
Sourcepub fn new(preset: BindingPreset) -> Self
pub fn new(preset: BindingPreset) -> Self
Create a controller from the given binding preset.
The preset seeds an internal resolver used only by the deprecated
event-driven methods (push_event and
apply_to_camera). A session ignores it:
ViewportInstance resolves with its own bindings and calls
apply, so the preset chosen here has no effect there. Set the
scheme on the session instead, with ViewportInstance::with_bindings.
Sourcepub fn viewer() -> Self
pub fn viewer() -> Self
Create a controller seeded with the BindingPreset::Viewer scheme.
The scheme has changed: left drag still orbits, but right drag no longer pans.
See new for why a session ignores this.
Sourcepub fn viewport_primitives() -> Self
👎Deprecated: renamed: use OrbitCameraController::viewer, or new_stateless if the host owns the resolver
pub fn viewport_primitives() -> Self
renamed: use OrbitCameraController::viewer, or new_stateless if the host owns the resolver
Former name for viewer.
Sourcepub fn viewport_all() -> Self
👎Deprecated: renamed: use OrbitCameraController::new_stateless if a session or host owns the resolver, or new(BindingPreset::Default) for the standalone path
pub fn viewport_all() -> Self
renamed: use OrbitCameraController::new_stateless if a session or host owns the resolver, or new(BindingPreset::Default) for the standalone path
Former name for new(BindingPreset::Default), from when that preset was
called ViewportAll.
Sourcepub fn begin_frame(&mut self, ctx: ViewportContext)
pub fn begin_frame(&mut self, ctx: ViewportContext)
Begin a new frame.
Resets per-frame accumulators and records viewport context (hover/focus
state and size). Call this at the end of each rendered frame : after
apply_to_camera : so the accumulator is ready for the next batch of
events.
Also call once immediately after construction to prime the accumulator.
Sourcepub fn set_viewport_size(&mut self, viewport_size: [f32; 2])
pub fn set_viewport_size(&mut self, viewport_size: [f32; 2])
Record the viewport size used for pan when applying a frame through
apply without going through
begin_frame.
Sourcepub fn push_event(&mut self, event: ViewportEvent)
👎Deprecated: own a ViewportInput and use OrbitCameraController::apply(&mut camera, &frame, dt)
pub fn push_event(&mut self, event: ViewportEvent)
own a ViewportInput and use OrbitCameraController::apply(&mut camera, &frame, dt)
Push a single viewport-scoped event into the controller’s own accumulator.
Superseded: own a ViewportInput (or a ViewportInstance), push events
into that, and drive the camera with apply. Bindings belong
to the resolver, and a controller holding a second one is how a session and a
controller end up disagreeing about the control scheme.
Sourcepub fn resolve(&self) -> ActionFrame
pub fn resolve(&self) -> ActionFrame
Resolve accumulated events into an ActionFrame without applying any
camera navigation.
Use this when the caller needs to inspect actions but camera movement should be suppressed : for example during gizmo manipulation or fly mode where the camera is driven by other logic.
Sourcepub fn apply_to_camera(&mut self, camera: &mut Camera) -> ActionFrame
👎Deprecated: own a ViewportInput and use OrbitCameraController::apply(&mut camera, &frame, dt)
pub fn apply_to_camera(&mut self, camera: &mut Camera) -> ActionFrame
own a ViewportInput and use OrbitCameraController::apply(&mut camera, &frame, dt)
Resolve accumulated events, apply camera navigation, and return the
ActionFrame for this frame.
Call this in the render / update step, before begin_frame for the
next frame.
The behavior of orbit drag depends on Self::navigation_mode:
NavigationMode::Arcball: unconstrained arcball (default).NavigationMode::Turntable: yaw around world Z, pitch clamped to +/-89 deg.NavigationMode::Planar: pan only, orbit input is ignored.NavigationMode::Fly: mouselook + WASD translation. Requires theDefaultbinding preset so that movement keys are resolved.
Takes no frame time, so fly movement assumes 60 frames per second.
Sourcepub fn orbit_by(&mut self, camera: &mut Camera, delta: Vec2)
pub fn orbit_by(&mut self, camera: &mut Camera, delta: Vec2)
Orbit camera by a pointer delta in pixels, as a drag in the viewport
would: scaled by orbit_sensitivity and
applied in navigation_mode. Planar mode
ignores it.
Use this for a drag the viewport did not see itself, such as a drag on an orientation widget, so it moves the camera the same way a drag in the scene does.
Sourcepub fn target(&self) -> Option<CameraTarget>
pub fn target(&self) -> Option<CameraTarget>
The orbit centre, distance and orientation the controller last wrote,
or None before it has moved a camera.
Sourcepub fn sync_from_camera(&mut self, camera: &Camera)
pub fn sync_from_camera(&mut self, camera: &Camera)
Read the pivot from camera’s focus point now rather than on the next
call that sees the camera has moved.
Sourcepub fn apply(&mut self, camera: &mut Camera, frame: &ActionFrame, dt: f32)
pub fn apply(&mut self, camera: &mut Camera, frame: &ActionFrame, dt: f32)
Apply an already-resolved ActionFrame to the camera without draining
the event queue.
Use this when the host owns a single ViewportInput resolver shared
across several controllers (orbit, first-person, third-person) and feeds
the same frame to whichever one is active.
apply_to_camera is the convenience wrapper
that resolves and applies in one call.
Pan needs the viewport height, read from the size recorded by the last
begin_frame or
set_viewport_size.
dt is the frame time in seconds. Only held input reads it: fly movement
in NavigationMode::Fly. Drags, the wheel and touch arrive as deltas
and move the camera the same at any frame rate.
Trait Implementations§
Source§impl CameraController for OrbitCameraController
impl CameraController for OrbitCameraController
Source§fn apply(&mut self, camera: &mut Camera, frame: &ActionFrame, dt: f32)
fn apply(&mut self, camera: &mut Camera, frame: &ActionFrame, dt: f32)
dt is the frame time
in seconds, for input that is held rather than moved (a key held to fly,
a stick held over): such input moves the camera at a rate, and needs the
time to turn that rate into a distance. Drags and the wheel arrive in the
frame as deltas already.Source§fn set_viewport(&mut self, viewport_size: [f32; 2], _pixels_per_point: f32)
fn set_viewport(&mut self, viewport_size: [f32; 2], _pixels_per_point: f32)
apply, for
controllers whose motion depends on the viewport (dragging by pixels,
zooming about the cursor). For a viewport presented at a reference
size it is the reference size with one pixel per point. The default
ignores it.