Skip to main content

OrbitCameraController

Struct OrbitCameraController 

Source
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§

§navigation_mode: NavigationMode

How drag input is interpreted by apply_to_camera.

Defaults to NavigationMode::Arcball.

§fly_speed: f32

Movement 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: f32

Multiplier on fly_speed while Action::FlySpeedBoost is held (Shift in the default bindings). Defaults to 3.0.

§orbit_sensitivity: f32

Sensitivity for drag-based orbit (radians per pixel).

§zoom_sensitivity: f32

Sensitivity for scroll-based zoom (scale factor per pixel).

§gesture_sensitivity: f32

Sensitivity 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

Source

pub const DEFAULT_ORBIT_SENSITIVITY: f32 = 0.005

Default drag orbit sensitivity: 0.005 radians per pixel.

Source

pub const DEFAULT_ZOOM_SENSITIVITY: f32 = 0.001

Default scroll zoom sensitivity: 0.001 scale per pixel.

Source

pub const DEFAULT_GESTURE_SENSITIVITY: f32 = 1.0

Default gesture sensitivity: 1.0 (gesture radians applied 1:1 to camera yaw).

Source

pub const DEFAULT_FLY_SPEED: f32 = 6.0

Default fly speed: 6 world units per second.

Source

pub const DEFAULT_FLY_BOOST: f32 = 3.0

Default fly speed multiplier while boosting.

Source

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.

Source

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.

Source

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.

Source

pub fn viewport_primitives() -> Self

👎Deprecated:

renamed: use OrbitCameraController::viewer, or new_stateless if the host owns the resolver

Former name for viewer.

Source

pub 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

Former name for new(BindingPreset::Default), from when that preset was called ViewportAll.

Source

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.

Source

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.

Source

pub fn push_event(&mut self, event: ViewportEvent)

👎Deprecated:

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.

Source

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.

Source

pub fn apply_to_camera(&mut self, camera: &mut Camera) -> ActionFrame

👎Deprecated:

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:

Takes no frame time, so fly movement assumes 60 frames per second.

Source

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.

Source

pub fn target(&self) -> Option<CameraTarget>

The orbit centre, distance and orientation the controller last wrote, or None before it has moved a camera.

Source

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.

Source

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

Source§

fn apply(&mut self, camera: &mut Camera, frame: &ActionFrame, dt: f32)

Apply one frame of resolved input to the camera. 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)

The size the scene draws at, in logical pixels, and its device pixels per point. A runner calls this before each 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.
Source§

fn as_any_mut(&mut self) -> Option<&mut dyn Any>

The controller as Any, so a host that handed it to a runner as a trait object can reach its concrete type again. The default returns None; return Some(self) to allow it.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.