CUGL 2.3
Cornell University Game Library
Loading...
Searching...
No Matches
Public Member Functions | Protected Attributes | List of all members
cugl::Camera Class Referenceabstract

#include <CUCamera.h>

Inheritance diagram for cugl::Camera:
cugl::OrthographicCamera cugl::PerspectiveCamera

Public Member Functions

 Camera ()
 
 ~Camera ()
 
virtual void dispose ()
 
const Vec3 getPosition () const
 
void setPosition (const Vec3 pos)
 
const Vec3 getDirection () const
 
void setDirection (const Vec3 vec)
 
const Vec3 getUp () const
 
void setUp (const Vec3 vec)
 
float getNear () const
 
void setNear (float value)
 
float getFar () const
 
void setFar (float value)
 
const Rect getViewport () const
 
const Mat4getProjection () const
 
const Mat4getView () const
 
const Mat4getCombined () const
 
const Mat4getInverseProjectView () const
 
virtual void update ()=0
 
void lookAt (const Vec3 target)
 
void lookAt (const Vec3 target, const Vec3 up)
 
void lookAt (float x, float y, float z)
 
void normalizeUp ()
 
void rotate (const Quaternion &quat)
 
void rotate (const Vec3 axis, float angle)
 
void rotateX (float angle)
 
void rotateY (float angle)
 
void rotateZ (float angle)
 
void rotate (float angle)
 
void rotate (const Mat4 &transform)
 
void rotateAround (const Vec3 point, const Vec3 axis, float angle)
 
void translate (const Vec3 vec)
 
void translate (const Vec2 vec)
 
void translate (float tx, float ty, float tz)
 
void translate (float tx, float ty)
 
void transform (const Mat4 &transform)
 
Vec3 unproject (const Vec3 windowCoords) const
 
Vec3 unproject (const Vec3 windowCoords, const Rect viewport) const
 
Vec3 screenToWorldCoords (const Vec2 screenCoords) const
 
Vec3 project (const Vec3 worldCoords) const
 
Vec3 project (const Vec3 worldCoords, const Rect viewport) const
 
Vec2 worldToScreenCoords (const Vec3 worldCoords) const
 
Ray getPickRay (const Vec3 windowCoords) const
 
Ray getPickRay (const Vec3 windowCoords, const Rect viewport) const
 
Ray getPickRayFromScreen (const Vec2 screenCoords) const
 
Vec2 windowToScreenCoords (const Vec3 windowCoords) const
 
Vec2 windowToScreenCoords (const Vec3 windowCoords, const Rect viewport) const
 
Vec3 screenToWindowCoords (const Vec2 screenCoords) const
 
Vec3 screenToWindowCoords (const Vec2 screenCoords, const Rect viewport) const
 

Protected Attributes

Vec3 _position
 
Vec3 _direction
 
Vec3 _upwards
 
Mat4 _projection
 
Mat4 _modelview
 
Mat4 _combined
 
Mat4 _inverse
 
float _near
 
float _far
 
Rect _viewport
 

Detailed Description

This is a base class for a camera.

The actual cameras are OrthographicCamera and PerspectiveCamera.This class hash the shared functionality for transforms and queries in 3d space. In particular, it has several methods that help you to select a 3d object with the mouse.

The design of this class ensures that the direction vector and the up vector of the camera are orthonormal at all times.

Constructor & Destructor Documentation

◆ Camera()

cugl::Camera::Camera ( )

Creates a degenerate camera.

All of the matrices are the identity and the viewport is empty.

◆ ~Camera()

cugl::Camera::~Camera ( )
inline

Deletes this camera, disposing all resources.

Member Function Documentation

◆ dispose()

virtual void cugl::Camera::dispose ( )
virtual

Returns this camera to the denegerate one.

All of the matrices will be the identity and the viewport will be empty.

Reimplemented in cugl::OrthographicCamera, and cugl::PerspectiveCamera.

◆ getCombined()

const Mat4 & cugl::Camera::getCombined ( ) const
inline

Returns the combined projection and view matrix

Returns
the combined projection and view matrix

◆ getDirection()

const Vec3 cugl::Camera::getDirection ( ) const
inline

Returns the unit length direction vector of the camera

Returns
the unit length direction vector of the camera

◆ getFar()

float cugl::Camera::getFar ( ) const
inline

Returns the far clipping plane distance (has to be positive)

Returns
the far clipping plane distance (has to be positive)

◆ getInverseProjectView()

const Mat4 & cugl::Camera::getInverseProjectView ( ) const
inline

Returns the combined projection and view matrix

Returns
the combined projection and view matrix

◆ getNear()

float cugl::Camera::getNear ( ) const
inline

Returns the near clipping plane distance (has to be positive)

Returns
the near clipping plane distance (has to be positive)

◆ getPickRay() [1/2]

Ray cugl::Camera::getPickRay ( const Vec3  windowCoords) const

Returns a picking Ray from the coordinates given in window coordinates.

A picking ray is used to select an object in 3d space. It creates a ray into the screen based on a selection in the viewport. You can then use this ray to select an object.

Window coords are the location of the point in the viewport. Ideally, the viewport should be the same size as the screen, but these are not screen coordinates. The screen has the origin in the top left, while window coordinates still have the origin in the bottom left.

While the viewport is a flat 2d plane, this method still takes a 3d point. The z-coordinate corresponds to the position of the point in the z-buffer.

Parameters
windowCoordsThe point in window coordinates

Returns a picking Ray from the coordinates given in window coordinates.

◆ getPickRay() [2/2]

Ray cugl::Camera::getPickRay ( const Vec3  windowCoords,
const Rect  viewport 
) const

Returns a picking Ray from the coordinates given in window coordinates.

A picking ray is used to select an object in 3d space. It creates a ray into the screen based on a selection in the viewport. You can then use this ray to select an object.

Window coords are the location of the point in the viewport. Ideally, the viewport should be the same size as the screen, but these are not screen coordinates. The screen has the origin in the top left, while window coordinates still have the origin in the bottom left.

While the viewport is a flat 2d plane, this method still takes a 3d point. The z-coordinate corresponds to the position of the point in the z-buffer.

Parameters
windowCoordsThe point in window coordinates
viewportThe screen viewport

Returns a picking Ray from the coordinates given in window coordinates.

◆ getPickRayFromScreen()

Ray cugl::Camera::getPickRayFromScreen ( const Vec2  screenCoords) const
inline

Returns a picking Ray from the coordinates given in screen coordinates.

A picking ray is used to select an object in 3d space. It creates a ray into the screen based on a selection in the viewport. You can then use this ray to select an object.

Screen coords differ from window coordinates, as the the origin is in the top left instad of the bottom left. The SDL event system uses screen space for input events, which is why this method is necessary.

Parameters
screenCoordsThe point in screen coordinates

Returns a picking Ray from the coordinates given in screen coordinates.

◆ getPosition()

const Vec3 cugl::Camera::getPosition ( ) const
inline

Returns the position of the camera

Returns
the position of the camera

◆ getProjection()

const Mat4 & cugl::Camera::getProjection ( ) const
inline

Returns the projection matrix

Returns
the projection matrix

◆ getUp()

const Vec3 cugl::Camera::getUp ( ) const
inline

Returns the unit length up vector of the camera

Returns
the unit length up vector of the camera

◆ getView()

const Mat4 & cugl::Camera::getView ( ) const
inline

Returns the view matrix

Returns
the view matrix

◆ getViewport()

const Rect cugl::Camera::getViewport ( ) const
inline

Returns the viewport

The viewport represents the "screen space". However, it is not actually screen space because the origin is still in the bottom left corner. So we call ir Window space instead.

Returns
the viewport size

◆ lookAt() [1/3]

void cugl::Camera::lookAt ( const Vec3  target)

Sets the direction of the camera to look at the given point.

This function assumes the up vector is normalized. This method will fail if the direction vector is 0

Parameters
targetThe point to look at

◆ lookAt() [2/3]

void cugl::Camera::lookAt ( const Vec3  target,
const Vec3  up 
)

Sets the direction of the camera to look at the given point.

This given up vector will be adjusted to guarantee that direction and up will be orthonormal. This method will fail if the direction vector is 0, or if up and the direction vector are colinear.

Parameters
targetThe point to look at
upThe up direction

◆ lookAt() [3/3]

void cugl::Camera::lookAt ( float  x,
float  y,
float  z 
)
inline

Sets the direction of the camera to look at the given point.

This function assumes the up vector is normalized.

Parameters
xThe x-coordinate of the point to look at
yThe y-coordinate of the point to look at
zThe z-coordinate of the point to look at

◆ normalizeUp()

void cugl::Camera::normalizeUp ( )
inline

Normalizes the up vector to be orthogonal to direction.

This method first calculats the right vector via a cross product between direction and up. Then it recalculates the up vector via a cross product between right and direction.

◆ project() [1/2]

Vec3 cugl::Camera::project ( const Vec3  worldCoords) const

Returns the window space equivalent of a point in world coordinates.

This is the same as GLU gluProject. Window coords are the location of the point in the viewport. Ideally, the viewport should be the same size as the screen, but these are not screen coordinates. The screen has the origin in the top left, while

While the viewport is a flat 2d plane, this method still returns a 3d point. The z-coordinate corresponds to the position of the point in the z-buffer.

Parameters
worldCoordsThe point in wprld coordinates
Returns
the window space equivalent of a point in world coordinates.

◆ project() [2/2]

Vec3 cugl::Camera::project ( const Vec3  worldCoords,
const Rect  viewport 
) const

Returns the window space equivalent of a point in world coordinates.

This is the same as GLU gluProject. Window coords are the location of the point in the viewport. Ideally, the viewport should be the same size as the screen, but these are not screen coordinates. The screen has the origin in the top left, while

While the viewport is a flat 2d plane, this method still returns a 3d point. The z-coordinate corresponds to the position of the point in the z-buffer.

Parameters
worldCoordsThe point in world coordinates
viewportThe screen viewport
Returns
the window space equivalent of a point in world coordinates.

◆ rotate() [1/4]

void cugl::Camera::rotate ( const Mat4 transform)
inline

Rotates the direction and up vector of this camera by the given matrix.

You must call update() for the view matrix to be updated. The direction and up vector will not be orthogonalized until you call update().

The translational and scaling components of the matrix will be ignored.

Parameters
transformThe rotation matrix

◆ rotate() [2/4]

void cugl::Camera::rotate ( const Quaternion quat)
inline

Rotates the direction and up vector by the given Quaternion

You must call update() for the view matrix to be updated. The direction and up vector will not be orthogonalized until you call update().

Parameters
quatThe rotation quaternion.

◆ rotate() [3/4]

void cugl::Camera::rotate ( const Vec3  axis,
float  angle 
)
inline

Rotates the direction and up vector by the given angle around the given axis.

You must call update() for the view matrix to be updated. The direction and up vector will not be orthogonalized until you call update().

Parameters
axisThe axis to rotate about.
angleThe angle (in radians).

◆ rotate() [4/4]

void cugl::Camera::rotate ( float  angle)
inline

Rotates the camera by the given angle around the direction vector.

You must call update() for the view matrix to be updated. The direction and up vector will not be orthogonalized until you call update().

Parameters
angleThe angle (in radians).

◆ rotateAround()

void cugl::Camera::rotateAround ( const Vec3  point,
const Vec3  axis,
float  angle 
)

Rotates the direction and up vector by the given angle around the given axis.

This version of the method assumes the axis is attached to the given point.

You must call update() for the view matrix to be updated. The direction and up vector will not be orthogonalized until you call update().

Parameters
pointThe point to attach the axis to
axisThe axis to rotate about.
angleThe angle (in radians).

◆ rotateX()

void cugl::Camera::rotateX ( float  angle)
inline

Rotates the direction and up vectod by the given angle around the x-axis.

You must call update() for the view matrix to be updated. The direction and up vector will not be orthogonalized until you call update().

Parameters
angleThe angle (in radians).

◆ rotateY()

void cugl::Camera::rotateY ( float  angle)
inline

Rotates the direction and up vectod by the given angle around the z-axis.

You must call update() for the view matrix to be updated. The direction and up vector will not be orthogonalized until you call update().

Parameters
angleThe angle (in radians).

◆ rotateZ()

void cugl::Camera::rotateZ ( float  angle)
inline

Rotates the direction and up vectod by the given angle around the z-axis.

You must call update() for the view matrix to be updated. The direction and up vector will not be orthogonalized until you call update().

Parameters
angleThe angle (in radians).

◆ screenToWindowCoords() [1/2]

Vec3 cugl::Camera::screenToWindowCoords ( const Vec2  screenCoords) const

Returns the screen space equivalent of a point in window coordinates.

Ideally, window space and screen space would be the same space. They are both defined by the viewport and have the same offset and dimension. However, screen coordinates have the origin in the top left while window coordinates have the origin in the bottom left.

We need this conversion because events (such as mouse clicks) register in screen space, while drawing happens in window space.

While the viewport is a flat 2d plane, this method still takes a 3d point. The z-coordinate corresponds to the near position, closest to the screen.

Parameters
screenCoordsThe point in screen coordinates

◆ screenToWindowCoords() [2/2]

Vec3 cugl::Camera::screenToWindowCoords ( const Vec2  screenCoords,
const Rect  viewport 
) const

Returns the screen space equivalent of a point in window coordinates.

Ideally, window space and screen space would be the same space. They are both defined by the viewport and have the same offset and dimension. However, screen coordinates have the origin in the top left while window coordinates have the origin in the bottom left.

We need this conversion because events (such as mouse clicks) register in screen space, while drawing happens in window space.

While the viewport is a flat 2d plane, this method still takes a 3d point. The z-coordinate corresponds to the near position, closest to the screen.

Parameters
screenCoordsThe point in screen coordinates
viewportThe screen viewport

◆ screenToWorldCoords()

Vec3 cugl::Camera::screenToWorldCoords ( const Vec2  screenCoords) const
inline

Returns the world space equivalent of a point in screen coordinates.

Ideally, window space and screen space would be the same space. They are both defined by the viewport and have the same offset and dimension. However, screen coordinates have the origin in the top left while window coordinates have the origin in the bottom left.

In computing the world space coordinates, this method assumes that the z-value of the original vector is the same as near, which is the closest it can be the screen.

This method is important for converting event coordinates (such as a mouse click) to world coordinates.

Parameters
screenCoordsThe point in screen coordinates
Returns
the world space equivalent of a point in screen coordinates.

◆ setDirection()

void cugl::Camera::setDirection ( const Vec3  vec)

Sets the direction vector of the camera

This method always guarantees that the up vector and directional vector are orthonormal. The up vector may be recomputed to adjust.

This function assumes the up vector is normalized.

Parameters
vecthe direction vector of the camera

◆ setFar()

void cugl::Camera::setFar ( float  value)
inline

Sets the far clipping plane distance (has to be positive)

Changing this value will have no effect on the underlying matrices until you call the update() method.

Parameters
valueThe far clipping plane distance (has to be positive)

◆ setNear()

void cugl::Camera::setNear ( float  value)
inline

Sets the near clipping plane distance (has to be positive)

Changing this value will have no effect on the underlying matrices until you call the update() method.

Parameters
valueThe near clipping plane distance (has to be positive)

◆ setPosition()

void cugl::Camera::setPosition ( const Vec3  pos)
inline

Sets the position of the camera

Parameters
posthe position of the camera

◆ setUp()

void cugl::Camera::setUp ( const Vec3  vec)

Sets the up vector of the camera

This method always guarantees that the up vector and directional vector are orthonormal.The final value of the up vector may be adjusted to for this reason.

Parameters
vecthe up vector of the camera

◆ transform()

void cugl::Camera::transform ( const Mat4 transform)
inline

Transforms the position, direction and up vector by the given matrix

You must call update() for the view matrix to be updated. The direction and up vector will not be orthogonalized until you call update().

Parameters
transformThe transform matrix

◆ translate() [1/4]

void cugl::Camera::translate ( const Vec2  vec)
inline

Moves the camera by the given vector.

You must call update() for the view matrix to be updated. The direction and up vector will not be orthogonalized until you call update().

Parameters
vecThe displacement vector

◆ translate() [2/4]

void cugl::Camera::translate ( const Vec3  vec)
inline

Moves the camera by the given vector.

Parameters
vecThe displacement vector

◆ translate() [3/4]

void cugl::Camera::translate ( float  tx,
float  ty 
)
inline

Moves the camera by the given vector.

You must call update() for the view matrix to be updated. The direction and up vector will not be orthogonalized until you call update().

Parameters
txThe displacement on the x-axis
tyThe displacement on the y-axis

◆ translate() [4/4]

void cugl::Camera::translate ( float  tx,
float  ty,
float  tz 
)
inline

Moves the camera by the given vector.

You must call update() for the view matrix to be updated. The direction and up vector will not be orthogonalized until you call update().

Parameters
txThe displacement on the x-axis
tyThe displacement on the y-axis
tzThe displacement on the z-axis

◆ unproject() [1/2]

Vec3 cugl::Camera::unproject ( const Vec3  windowCoords) const

Returns the world space equivalent of a point in window coordinates.

This is the same as GLU gluUnProject, but does not rely on OpenGL. Window coords are the location of the point in the viewport. Ideally, the viewport should be the same size as the screen, but these are not screen coordinates. The screen has the origin in the top left, while Window coordinates still have the origin in the bottom left.

While the viewport is a flat 2d plane, this method still requires a 3d point. The z-coordinate corresponds to the position of the point in the z-buffer.

Parameters
windowCoordsThe point in window coordinates
Returns
the world space equivalent of a point in window coordinates.

◆ unproject() [2/2]

Vec3 cugl::Camera::unproject ( const Vec3  windowCoords,
const Rect  viewport 
) const

Returns the world space equivalent of a point in window coordinates.

This is the same as GLU gluUnProject, but does not rely on OpenGL. Window coords are the location of the point in the viewport. Ideally, the viewport should be the same size as the screen, but these are not screen coordinates. The screen has the origin in the top left, while Window coordinates still have the origin in the bottom left.

While the viewport is a flat 2d plane, this method still requires a 3d point. The z-coordinate corresponds to the position of the point in the z-buffer.

Parameters
windowCoordsThe point in window coordinates
viewportThe screen viewport
Returns
the world space equivalent of a point in window coordinates.

◆ update()

virtual void cugl::Camera::update ( )
pure virtual

Recalculates the projection and view matrix of this camera.

Use this after you've manipulated any of the attributes of the camera.

Implemented in cugl::OrthographicCamera, and cugl::PerspectiveCamera.

◆ windowToScreenCoords() [1/2]

Vec2 cugl::Camera::windowToScreenCoords ( const Vec3  windowCoords) const

Returns the window space equivalent of a point in screen coordinates.

Ideally, window space and screen space would be the same space. They are both defined by the viewport and have the same offset and dimension. However, screen coordinates have the origin in the top left while window coordinates have the origin in the bottom left.

We need this conversion because events (such as mouse clicks) register in screen space, while drawing happens in window space.

Parameters
windowCoordsThe point in window coordinates

◆ windowToScreenCoords() [2/2]

Vec2 cugl::Camera::windowToScreenCoords ( const Vec3  windowCoords,
const Rect  viewport 
) const

Returns the window space equivalent of a point in screen coordinates.

Ideally, window space and screen space would be the same space. They are both defined by the viewport and have the same offset and dimension. However, screen coordinates have the origin in the top left while window coordinates have the origin in the bottom left.

We need this conversion because events (such as mouse clicks) register in screen space, while drawing happens in window space.

Parameters
windowCoordsThe point in window coordinates
viewportThe screen viewport

◆ worldToScreenCoords()

Vec2 cugl::Camera::worldToScreenCoords ( const Vec3  worldCoords) const
inline

Returns the screen space equivalent of a point in world coordinates.

Ideally, window space and screen space would be the same space. They are both defined by the viewport and have the same offset and dimension. However, screen coordinates have the origin in the top left while window coordinates have the origin in the bottom left.

This method is important for converting world coordinates to event coordinates (such as a mouse click).

Parameters
worldCoordsThe point in wprld coordinates
Returns
the screen space equivalent of a point in world coordinates.

Member Data Documentation

◆ _combined

Mat4 cugl::Camera::_combined
protected

The combined projection and view matrix

◆ _direction

Vec3 cugl::Camera::_direction
protected

The unit length direction vector of the camera

◆ _far

float cugl::Camera::_far
protected

The far clipping plane distance, has to be positive

◆ _inverse

Mat4 cugl::Camera::_inverse
protected

The inverse of the combined projection and view matrix

◆ _modelview

Mat4 cugl::Camera::_modelview
protected

The view matrix

◆ _near

float cugl::Camera::_near
protected

The near clipping plane distance, has to be positive

◆ _position

Vec3 cugl::Camera::_position
protected

The position of the camera

◆ _projection

Mat4 cugl::Camera::_projection
protected

The projection matrix

◆ _upwards

Vec3 cugl::Camera::_upwards
protected

The unit length up vector of the camera

◆ _viewport

Rect cugl::Camera::_viewport
protected

The Window viewport


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