The TrackBall class implements a trackball (a camera combined with model transformation). More...

#include <vclib/render/viewer/trackball.h>

Classes
struct	TransformArgs

Public Types
using	AtomicMotionArg = std::variant< TransformArgs, Scalar, Point3< Scalar >, std::monostate >

enum	MotionType { ARC , PAN , ZMOVE , ROLL , SCALE , FOV , FOCUS , DIR_LIGHT_ARC , MOTION_NUMBER }

Public Member Functions
void	adaptCurrentViewToCenter (const Point3< Scalar > &center)
	Adapt the current view to a given center. The function adapts the trackball transformation in order to manipulate the scene with a pivot point close to the given center. This is done without affecting the current view.

void	applyArc (const Point3< Scalar > &axis, Scalar angle)

void	applyAtomicMotion (MotionType motion, AtomicMotionArg step=std::monostate())
	Applies an atomic motion to the trackball. Atomic motions are motions that are applied atomically to the camera. The step parameter is a std::variant that can store different values depending on the motion type.

void	applyPan (const Point3< Scalar > &translation)

void	applyRoll (Scalar angleRad)

void	applyScale (Scalar value)

void	beginDragMotion (MotionType motion)
	Starts a drag motion.

Camera< Scalar >	camera () const
	return the camera containing the current view point of the trackball.

Point3< Scalar >	center () const

void	changeScale (Scalar factor)

MotionType	currentMotion () const

void	endDragMotion (MotionType motion)
	Ends a drag motion.

Scalar	fovDeg () const
	Get the vertical field of view.

Matrix44< Scalar >	gizmoMatrix () const

bool	isDragging () const

DirectionalLight< Scalar >	light () const

Matrix44< Scalar >	lightGizmoMatrix () const

Matrix44< Scalar >	projectionMatrix () const

Camera< Scalar >::ProjectionMode	projectionMode () const

void	reset ()

void	reset (const Point3< Scalar > &center, Scalar scale)
	Reset the manipulator to a given center and scale.

void	resetDirectionalLight ()

Scalar	scale () const

void	setCamera (const Camera< Scalar > &cam)
	Set the camera of the trackball.

void	setCenter (const Point3< Scalar > &center)

void	setFovDeg (Scalar fov)
	Set the vertical field of view adapting the eye distance.

void	setLightDirection (const Point3< Scalar > &direction)

void	setMousePosition (const Point2< Scalar > &point)

void	setMousePosition (Scalar x, Scalar y)

void	setProjectionMode (Camera< Scalar >::ProjectionMode mode)

void	setRotation (const Point3< Scalar > &axis, Scalar angle)

void	setRotation (const Quaternion< Scalar > &rotation)

void	setScale (Scalar scale)

void	setScreenSize (const Point2< Scalar > &sz)

void	setScreenSize (Scalar width, Scalar height)

void	update ()
	Updates the state of the trackball during a drag motion.

Matrix44< Scalar >	viewMatrix () const

Private Member Functions
void	drag (MotionType motion)

void	dragArc ()

void	dragDirLightArc ()

void	dragPan ()

void	dragRoll ()

void	dragScale ()

void	dragZmove ()

void	performFov (Scalar pixelDelta)

void	performPan (const Point2< Scalar > &pixelDelta)
	perform a pan operation

void	performScale (Scalar pixelDelta)

void	performZmove (const Scalar &pixelDelta)
	translate in the camera z direction

Point3< Scalar >	pointOnArcball (Point2< Scalar > screenCoord) const

Point3< Scalar >	pointOnTrackballPlane (Point2< Scalar > screenCoord) const

void	roll (Scalar delta)

void	rotate (const Quaternion< Scalar > &q)

void	rotate (Point3< Scalar > axis, Scalar angleRad)

void	rotateDirLight (const Quaternion< Scalar > &rotation)

void	rotateDirLight (Point3< Scalar > axis, Scalar angle)

void	setDragMotionValue (MotionType motion, bool value)

Scalar	trackballToPixelRatio () const

void	translate (Point3< Scalar > t)
	Translate in the camera space.

Private Attributes
Camera< Scalar >	mCamera

MotionType	mCurrDragMotion = MOTION_NUMBER

Point2< Scalar >	mCurrMousePosition

Quaternion< Scalar >	mDirectionalLightTransform

bool	mDragging = false

Quaternion< Scalar >	mInitialDirRotation = Quaternion<Scalar>::Identity()

Point3< Scalar >	mInitialPoint

Affine3< Scalar >	mInitialTransform = Affine3<Scalar>::Identity()

Point2< Scalar >	mPrevMousePosition

Scalar	mRadius = ARC_BALL_RADIUS_RATIO

Point2< Scalar >	mScreenSize = {-1, -1}

Affine3< Scalar >	mTransform = Affine3<Scalar>::Identity()

Static Private Attributes
static constexpr Scalar	ARC_BALL_RADIUS_RATIO = 1.0 / 1.61803398875

static constexpr Scalar	DEFAULT_FOV_DEG = 54.0

static constexpr Scalar	FOCUS_SCALE_FACTOR = 1.15

Detailed Description

template<typename Scalar>
class vcl::TrackBall< Scalar >

The TrackBall class implements a trackball (a camera combined with model transformation).

The trackball class stores a view and provides a set motions that allow the user to manipulate it.

There are two main types of motions:

atomic motions: these motions have no state and they are applied atomicly to the camera. They are not affected by the mouse position. An example of an atomic motion is a zoom.
drag motions: these motions have a state, that may change with the mouse position. They begin and end with the begin/end member functions, and they update their state trough the change of the mouse position. An example of a drag motion is an arcball rotation.

Member Function Documentation

◆ adaptCurrentViewToCenter()

template<typename Scalar >

void vcl::TrackBall< Scalar >::adaptCurrentViewToCenter ( const Point3< Scalar > & center )

inline

Adapt the current view to a given center. The function adapts the trackball transformation in order to manipulate the scene with a pivot point close to the given center. This is done without affecting the current view.

Parameters

[in] center The center of the scene.

Note: This function does nothing if the provided center is behind the camera.

◆ applyAtomicMotion()

template<typename Scalar >

void vcl::TrackBall< Scalar >::applyAtomicMotion	(	MotionType	motion,
		AtomicMotionArg	step = `std::monostate()`
	)

inline

Applies an atomic motion to the trackball. Atomic motions are motions that are applied atomically to the camera. The step parameter is a std::variant that can store different values depending on the motion type.

Possible motion types and supported step values are:

ROLL:
- Scalar (positive counter-clockwise roll, negative otherwise)
SCALE:
- Scalar (positive zoom in, negative zoom out)
ARC:
- TransformArgs (axis, angle) rotation along axis by angle
PAN:
- Point3 translation in trackball camera space
ZMOVE:
- Scalar z translation in trackball camera space
FOCUS:
- Point3 set center in world space
  Parameters
  
  motion
  
  step

◆ beginDragMotion()

template<typename Scalar >

void vcl::TrackBall< Scalar >::beginDragMotion ( MotionType motion )

inline

Starts a drag motion.

Parameters

[in] motion the motion type

Note: this function should be called when the drag motion begins (e.g., the mouse is pressed) or the motion type changes.

◆ camera()

template<typename Scalar >

Camera< Scalar > vcl::TrackBall< Scalar >::camera ( ) const

inline

return the camera containing the current view point of the trackball.

Returns: the camera matching the current view of the trackball

◆ dragArc()

template<typename Scalar >

void vcl::TrackBall< Scalar >::dragArc ( )

inlineprivate

— User interaction functions — -----------— Arc -----------—

◆ dragDirLightArc()

template<typename Scalar >

void vcl::TrackBall< Scalar >::dragDirLightArc ( )

inlineprivate

--— Directional Light Arc --—

◆ endDragMotion()

template<typename Scalar >

void vcl::TrackBall< Scalar >::endDragMotion ( MotionType motion )

inline

Ends a drag motion.

Parameters

[in] motion the motion type

Note: this function should be called when the drag motion ends (e.g., the mouse is released)

◆ performFov()

template<typename Scalar >

void vcl::TrackBall< Scalar >::performFov ( Scalar pixelDelta )

inlineprivate

--— Fov --—

◆ performPan()

template<typename Scalar >

void vcl::TrackBall< Scalar >::performPan ( const Point2< Scalar > & pixelDelta )

inlineprivate

perform a pan operation

-----------— Pan -----------—

Parameters

pixelDelta the pan movement in pixels

◆ performScale()

template<typename Scalar >

void vcl::TrackBall< Scalar >::performScale ( Scalar pixelDelta )

inlineprivate

-----------— Scaling -----------—

◆ performZmove()

template<typename Scalar >

void vcl::TrackBall< Scalar >::performZmove ( const Scalar & pixelDelta )

inlineprivate

translate in the camera z direction

-----------— Z-Move -----------—

Parameters

pixelDelta the delta movement in pixels

◆ reset()

template<typename Scalar >

void vcl::TrackBall< Scalar >::reset	(	const Point3< Scalar > &	center,
		Scalar	scale
	)

inline

Reset the manipulator to a given center and scale.

Parameters

center
scale

◆ roll()

template<typename Scalar >

void vcl::TrackBall< Scalar >::roll ( Scalar delta )

inlineprivate

-----------— Roll -----------—

◆ rotate()

template<typename Scalar >

void vcl::TrackBall< Scalar >::rotate ( const Quaternion< Scalar > & q )

inlineprivate

------— Base functions ------—

◆ setCamera()

template<typename Scalar >

void vcl::TrackBall< Scalar >::setCamera ( const Camera< Scalar > & cam )

inline

Set the camera of the trackball.

The function sets the trackball to match the provided camera. The function does not change the aspect ratio of the trackball camera, as it may be different from the provided camera.

Parameters

[in] cam The camera to set.

◆ setDragMotionValue()

template<typename Scalar >

void vcl::TrackBall< Scalar >::setDragMotionValue	(	MotionType	motion,
		bool	value
	)

inlineprivate

-----------— Generic Functions -----------—

◆ setFovDeg()

template<typename Scalar >

void vcl::TrackBall< Scalar >::setFovDeg ( Scalar fov )

inline

Set the vertical field of view adapting the eye distance.

Parameters

[in] fov the field of view in degrees.

◆ translate()

template<typename Scalar >

void vcl::TrackBall< Scalar >::translate ( Point3< Scalar > t )

inlineprivate

Translate in the camera space.

Note: from the trackball center Y range is [-1, 1] and X is [-aspectRatio, aspectRatio]

◆ update()

template<typename Scalar >

void vcl::TrackBall< Scalar >::update ( )

inline

Updates the state of the trackball during a drag motion.

Note: : this member function must be called only when a drag motion is in progress (e.g., when the mouse is dragging);

The documentation for this class was generated from the following file:

vclib/render/include/vclib/render/viewer/trackball.h

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Function Documentation

◆ adaptCurrentViewToCenter()

◆ applyAtomicMotion()

◆ beginDragMotion()

◆ camera()

◆ dragArc()

◆ dragDirLightArc()

◆ endDragMotion()

◆ performFov()

◆ performPan()

◆ performScale()

◆ performZmove()

◆ reset()

◆ roll()

◆ rotate()

◆ setCamera()

◆ setDragMotionValue()

◆ setFovDeg()

◆ translate()

◆ update()