OrbitControls

Interactive camera controller for orbit-style navigation.

OrbitControls lets the user rotate, pan, and zoom a camera around a target point using mouse input. It is added to the scene like any other node and updates the attached camera each frame. The controller maintains a spherical orbit radius and angular orientation pitch and yaw and applies smoothing when a non-zero damping factor is set.

The control scheme includes:

• Left mouse drag: orbit around the target
• Right mouse drag or Shift + left mouse drag: pan in view space
• Scroll wheel: zoom in and out

struct MyScene : public vglx::Scene {
  MyScene(vglx::Camera* camera) {
    Add(vglx::OrbitControls::Create(camera, {
      .radius = 5.0f
    }));
  }
};

INFO

Derives from Node and inherits all public properties and methods.

Construction

Constructors

OrbitControls()

Constructs orbit controls.

OrbitControls::OrbitControls(Camera* camera, const Parameters& params);

Parameter	Description
camera	Camera the controller manipulates.
params	Configuration parameters.

Factories preferred

OrbitControls::Create() std::unique_ptr<OrbitControls>

Creates an instance of OrbitControls.

static std::unique_ptr<OrbitControls> OrbitControls::Create(Camera* camera, const Parameters& params);

Parameter	Description
camera	Camera the controller manipulates.
params	Configuration parameters.

Types

OrbitControls::Parameters struct

Parameters for constructing an OrbitControls object.

Parameter	Description
radius float	Initial distance of the camera from its target.
pitch float	Initial pitch angle in radians.
yaw float	Initial yaw angle in radians.
target Vector3	Initial point the camera orbits around.
orbit_speed float	Orbit sensitivity in radians per viewport-height drag.
pan_speed float	Pan sensitivity. At 1 the target tracks the cursor exactly.
zoom_speed float	Scroll wheel zoom sensitivity multiplier.
damping_factor float	Set to 1 for instant response.
min_distance float	Minimum orbit distance from the target.
max_distance float	Maximum orbit distance from the target.
min_pitch float	Minimum pitch angle in radians.
max_pitch float	Maximum pitch angle in radians.

Properties

enabled bool

When false, all mouse input is ignored.

bool enabled {true};

Functions

OnMouseEvent() void virtual

Responds to mouse input for orbiting, panning, and zooming.

void OrbitControls::OnMouseEvent(MouseEvent* event) override;

Parameter	Description
event	Mouse event pointer.

OnUpdate() void virtual

Updates camera position each frame, applying damping if enabled.

void OrbitControls::OnUpdate(float delta) override;

Parameter	Description
delta	Time step in seconds.

SetTarget() void

Sets the point the camera orbits around.

The camera keeps its current position and re-derives its orbit distance and orientation toward the new target. Any in-flight damped motion is cancelled.

void OrbitControls::SetTarget(const Vector3& target);

Parameter	Description
target	World space position to orbit around.