cugl::scene3::Gimbal Class Reference

#include <CUGimbal.h>

Public Member Functions
	Gimbal ()
	~Gimbal ()
void	dispose ()
bool	init ()
bool	initWithCamera (const std::shared_ptr< PerspectiveCamera > &camera)
std::shared_ptr< PerspectiveCamera >	getCamera () const
void	setCamera (const std::shared_ptr< PerspectiveCamera > &camera)
Vec3	getEye () const
Vec3	getTarget () const
Vec3	getUp () const
float	getZoom () const
float	getMinimumZoom () const
void	setMinimumZoom (float min)
float	getMaximumZoom () const
void	setMaximumZoom (float max)
void	rotateY (float angle)
void	rotateX (float angle)
void	rotateZ (float angle)
void	adjustZoom (float dt)
void	pan (Vec3 delta)
void	pan (float dx, float dy, float dz)
void	reset ()
void	update ()

Static Public Member Functions
static std::shared_ptr< Gimbal >	alloc ()
static std::shared_ptr< Gimbal >	allocWithCamera (const std::shared_ptr< PerspectiveCamera > &camera)

Detailed Description

This class represents a camera gimbal.

A camera gimbal is a harness for moving a persepective (3d) camera about the screen. Controls are with respect to screen space, not camera space. In this space, the screen is the x-y plane with the origin in the bottom left corner of the display. The z-axis is perpendicular to the screen with postive z going into the screen.

The gimbal has both an eye position and a target. The eye position is the location of the camera. All rotation happens about the target. Zooming adjusts the distance between the eye and the target, while panning moves the eye and target together.

Constructor & Destructor Documentation

Gimbal()

cugl::scene3::Gimbal::Gimbal ( )

inline

Creates a new degenerate batch on the stack.

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate an object on the heap, use one of the static constructors instead.

~Gimbal()

cugl::scene3::Gimbal::~Gimbal ( )

inline

Deletes this gimbal, disposing all resources

Member Function Documentation

adjustZoom()

void cugl::scene3::Gimbal::adjustZoom

(

float

dt

)

Adjusts the zoom by the given amount.

The zoom is the distance between the eye and the target. It defines the radius of rotation about the target. It can be any value between getMinimumZoom and getMaximumZoom. Values outside this range are clamped to the range.

This method will have no effect until update is called. This will allow you to make other changes to the camera before updating it.

Parameters

dt	The amount to adjust the zoom.

alloc()

static std::shared_ptr< Gimbal > cugl::scene3::Gimbal::alloc ( )

inlinestatic

Returns a newly allocated gimbal with no camera.

You should call setCamera before using the gimbal.

Returns

a newly allocated gimbal with no camera.

allocWithCamera()

static std::shared_ptr< Gimbal > cugl::scene3::Gimbal::allocWithCamera ( const std::shared_ptr< PerspectiveCamera > &  camera )

inlinestatic

Returns a newly allocated gimbal for the specified camera

Parameters

camera

The camera to control

Returns

a newly allocated gimbal for the specified camera

dispose()

void cugl::scene3::Gimbal::dispose

(

)

Disposes all of the resources used by this gimbal.

A disposed batch can be safely reinitialized.

getCamera()

std::shared_ptr< PerspectiveCamera > cugl::scene3::Gimbal::getCamera ( ) const

inline

Returns the current camera

This value can be null.

Returns

the current camera

getEye()

Vec3 cugl::scene3::Gimbal::getEye ( ) const

inline

Returns the eye position of this gimbal.

This vector corresponds to the position of the camera. The value returned is not intended to be modified. Modifying this value can have unintended side effects on the next call to update.

Returns

the eye position of this gimbal.

getMaximumZoom()

float cugl::scene3::Gimbal::getMaximumZoom ( ) const

inline

Returns the maximum zoom factor allowed.

The zoom is the distance between the eye and the target. It defines the radius of rotation about the target. It can be any value between getMinimumZoom and getMaximumZoom.

This value should be > 0 and greater than getMinimumZoom. Other values will result in undefined behavior.

Returns

the maximum zoom factor allowed..

getMinimumZoom()

float cugl::scene3::Gimbal::getMinimumZoom ( ) const

inline

Returns the minimum zoom factor allowed.

The zoom is the distance between the eye and the target. It defines the radius of rotation about the target. It can be any value between getMinimumZoom and getMaximumZoom.

This value should be > 0 and less than getMaximumZoom. Other values will result in undefined behavior.

Returns

the minimum zoom factor allowed..

getTarget()

Vec3 cugl::scene3::Gimbal::getTarget ( ) const

inline

Returns the target position of this gimbal.

This vector corresponds to the look-at position of the camera. The value returned is not intended to be modified. Modifying this value can have unintended side effects on the next call to update.

Returns

the target position of this gimbal.

getUp()

Vec3 cugl::scene3::Gimbal::getUp ( ) const

inline

Returns the up direction of this gimbal.

This vector corresponds to the upwards direction of the camera. The value returned is not intended to be modified. Modifying this value can have unintended side effects on the next call to update.

Returns

the up direction of this gimbal.

getZoom()

float cugl::scene3::Gimbal::getZoom ( ) const

inline

Returns the zoom factor of this gimbal.

The zoom is the distance between the eye and the target. It defines the radius of rotation about the target. It can be any value between getMinimumZoom and getMaximumZoom.

Returns

the zoom factor of this gimbal.

init()

bool cugl::scene3::Gimbal::init

(

)

Initializes a gimbal with no camera.

You should call setCamera before using the gimbal.

Returns

true if initialization was successful.

initWithCamera()

bool cugl::scene3::Gimbal::initWithCamera

(

const std::shared_ptr< PerspectiveCamera > &

camera

)

Initializes a gimbal for the specified camera

Parameters

camera

The camera to control

Returns

true if initialization was successful.

pan() [1/2]

void cugl::scene3::Gimbal::pan	(	float	dx,
		float	dy,
		float	dz
	)

Pans the camera by the given amount.

Panning takes place in screen space. So panning the x-coordinate by a positive amount will move the camera to the right, and panning the the y-coordinate by a positive amount will move the camera upwards. Panning the z-coordinate will superficially look the same as zooming. However, panning modifies both the eye and the target position, meaning that the zoom length is unchanged.

Parameters

dx	The x-coordinate pan
dy	The y-coordinate pan
dz	The z-coordinate pan

pan() [2/2]

void cugl::scene3::Gimbal::pan

(

Vec3

delta

)

Pans the camera by the given vector.

Panning takes place in screen space. So panning the x-coordinate by a positive amount will move the camera to the right, and panning the the y-coordinate by a positive amount will move the camera upwards. Panning the z-coordinate will superficially look the same as zooming. However, panning modifies both the eye and the target position, meaning that the zoom length is unchanged.

Parameters

delta

The direction to pan

reset()

void cugl::scene3::Gimbal::reset

(

)

Resets the gimbal to its initial configuration.

The initial configuration is the state of the camera at the time that this object was constructed or setCamera was called.

rotateX()

void cugl::scene3::Gimbal::rotateX

(

float

angle

)

Rotates the scene about the screen x-axis.

This has the effect of rotating the image vertically. A positive value will rotate the camera counter-clockwise (so to camera goes to down while the image goes up). A negative value will rotate clockwise.

This method will have no effect until update is called. This will allow you to make other changes to the camera before updating it.

Parameters

angle

The rotation angle in radians

rotateY()

void cugl::scene3::Gimbal::rotateY

(

float

angle

)

Rotates the scene about the screen y-axis.

This has the effect of rotating the image horizontally. A positive value will rotate the camera counter-clockwise (so to camera goes to the right while the image goes left). A negative value will rotate clockwise.

This method will have no effect until update is called. This will allow you to make other changes to the camera before updating it.

Parameters

angle

The rotation angle in radians

rotateZ()

void cugl::scene3::Gimbal::rotateZ

(

float

angle

)

Rotates the scene about the screen z-axis.

This has the effect of rotating the with the the plane of the screen, with the rotation origin in the center of the display. A positive value will rotate the camera counter-clockwise along the z-axis. As the z-axis going into the screen, this has the effect of rotating the image in a counter-clockwise direction as well. A negative value will rotate clockwise.

This method will have no effect until update is called. This will allow you to make other changes to the camera before updating it.

Parameters

angle

The rotation angle in radians

setCamera()

void cugl::scene3::Gimbal::setCamera

(

const std::shared_ptr< PerspectiveCamera > &

camera

)

Sets the current camera

This value can be null.

Parameters

camera

the current camera

setMaximumZoom()

void cugl::scene3::Gimbal::setMaximumZoom

(

float

max

)

Sets the maximum zoom factor allowed.

The zoom is the distance between the eye and the target. It defines the radius of rotation about the target. It can be any value between getMinimumZoom and getMaximumZoom.

This value should be > 0 and less than getMaximumZoom. Other values will result in undefined behavior.

Parameters

max	the maximum zoom factor allowed..

setMinimumZoom()

void cugl::scene3::Gimbal::setMinimumZoom

(

float

min

)

Sets the minimum zoom factor allowed.

The zoom is the distance between the eye and the target. It defines the radius of rotation about the target. It can be any value between getMinimumZoom and getMaximumZoom.

This value should be > 0 and less than getMaximumZoom. Other values will result in undefined behavior.

Parameters

min	the minimum zoom factor allowed..

update()

void cugl::scene3::Gimbal::update

(

)

Updates the camera to match the gimbal state.

If the gimbal has been moved (rotating, zooming, or panning), this method must be called for this movement to have an effect.

---

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

• /Users/wmwhite/Developer/CUGL/include/cugl/scene3/CUGimbal.h