# Visualization Library

A lightweight C++ OpenGL middleware for 2D/3D graphics

[Home] [Tutorials] [All Classes] [Grouped Classes]

# vl::Camera Class Reference

Represents a virtual camera defining, among other things, the point of view from which scenes can be rendered. More...

`#include <Camera.hpp>`

Inheritance diagram for vl::Camera:

List of all members.

## Public Member Functions

virtual const char * | className ()
| Returns the name of the class.
| Camera (const std::string &name="Camera")
| Constructor.
void | activate ()
| Initializes the GL_PROJECTION and GL_MODELVIEW matrices according to the Camera's projection and view matrix and computes the frustum planes.
void | computeFrustumPlanes ()
| Computes the Camera's frustum planes in world space.
void | applyModelViewMatrix (const mat4 &model_matrix) const
| Loads the GL_MODELVIEW matrix with the Camera's view matrix multiplied by the specified model matrix.
void | applyViewMatrix () const
| Loads the GL_MODELVIEW matrix with the Camera's view matrix.
void | setActive (bool active)
bool | active () const
void | setFOV (Real fov)
Real | fov () const
Real | aspectRatio () const
| Returns the aspect ratio computed as viewport()->width()/viewport()->height().
void | setNearPlane (Real nearplane)
Real | nearPlane () const
void | setFarPlane (Real farplane)
Real | farPlane () const
void | setFrustum (const Frustum &frustum)
const Frustum & | frustum () const
void | setViewport (Viewport *viewport)
Viewport * | viewport ()
const Viewport * | viewport () const
void | followTransform (Transform *transform)
const Transform * | followedTransform () const
Transform * | followedTransform ()
void | setViewMatrix (const mat4 &mat)
| Sets the Camera's view matrix.
const mat4 & | viewMatrix () const
| The Camera's view matrix.
void | setInverseViewMatrix (const mat4 &mat)
| The camera's reference frame matrix, the inverse of the view matrix.
const mat4 & | inverseViewMatrix () const
| The camera's reference frame matrix, the inverse of the view matrix.
void | setProjectionMatrix (const mat4 &mat)
| The camera's projection matrix.
const mat4 & | projectionMatrix () const
| The camera's projection matrix.
void | setProjectionAsPerspective ()
| Builds a perspective projection matrix for the Camera based on the Camera's and Viewport's settings.
void | setProjectionAsPerspective (Real fov, Real near, Real far)
| Builds a perspective projection matrix for the Camera based on the Camera's and Viewport's settings.
void | setProjectionAsFrustum (Real left, Real right, Real bottom, Real top, Real near, Real far)
| Builds a perspective projection matrix for the Camera based on the give frustum.
void | setProjectionAsOrtho (Real offset=-0.5f)
| Builds an orthographic projection matrix for the Camera based on the Camera's near/far planes and its Viewport's settings.
void | setProjectionAsOrtho2D (Real offset=-0.5f)
| Builds an orthographic projection matrix for the Camera based on its Viewport's settings.
void | setViewMatrixAsLookAt (const vec3 &eye, const vec3 &center, const vec3 &up)
void | getViewMatrixAsLookAt (vec3 &eye, vec3 &look, vec3 &up, vec3 &right) const
bool | project (const vec4 &in, vec4 &out) const
bool | unproject (const vec3 &win, vec4 &out) const
| Unprojects a vector from window coordinates to world coordinates.
bool | unproject (std::vector< vec3 > &points) const
| Unprojects a set of points. See unproject(const vec3& win, vec4& out) for more information.
Ray | computeRay (int winx, int winy)
| Computes the ray passing through the point <winx,winy>.
Frustum | computeRayFrustum (int winx, int winy)
| Computes a frustum suitable to cull object during ray intersection detection.
void | setNearFarClippingPlanesOptimized (bool enable)
| Enables the optimization of the near and far clipping planes.
bool | nearFarClippingPlanesOptimized () const
| Set to true if the optimization of the near and far clipping planes is enabled.
void | setSceneBoundingSphere (const Sphere &sphere)
| The bounding sphere of the scene used to optimize the near and far clipping planes.
const Sphere & | sceneBoundingSphere () const
| The bounding sphere of the scene used to optimize the near and far clipping planes.
void | adjustView (const AABB &aabb, const vec3 &dir, const vec3 &up, Real bias=1.0f)
| Adjusts the camera position so that the given aabb can be properly viewed.

## Protected Attributes

mat4 | mViewMatrix
mat4 | mInverseViewMatrix
mat4 | mProjectionMatrix
ref< Viewport > | mViewport
Frustum | mFrustum
ref< Transform > | mFollowTransform
Real | mFOV
Real | mNearPlane
Real | mFarPlane
Sphere | mSceneBoundingSphere
bool | mActive
bool | mNearFarClippingPlanesOptimized

## Detailed Description

Represents a virtual camera defining, among other things, the point of view from which scenes can be rendered.

## Constructor & Destructor Documentation

Camera::Camera | ( | const std::string & | name = `"Camera"` | ) |

Constructor.

## Member Function Documentation

virtual const char* vl::Camera::className | ( |  | ) | `[inline, virtual]`

Returns the name of the class.

Reimplemented from vl::Object.

void Camera::activate | ( |  | ) |

Initializes the GL_PROJECTION and GL_MODELVIEW matrices according to the Camera's projection and view matrix and computes the frustum planes.

void Camera::computeFrustumPlanes | ( |  | ) |

Computes the Camera's frustum planes in world space.

If nearFarClippingPlanesOptimized() == true the near and far culling planes distances are respectively set to nearPlane() and farPlane()

void Camera::applyModelViewMatrix | ( | const mat4 & | model_matrix | ) | const

Loads the GL_MODELVIEW matrix with the Camera's view matrix multiplied by the specified model matrix.

void Camera::applyViewMatrix | ( |  | ) | const

Loads the GL_MODELVIEW matrix with the Camera's view matrix.

void vl::Camera::setActive | ( | bool | active | ) | `[inline]`

bool vl::Camera::active | ( |  | ) | const`[inline]`

void vl::Camera::setFOV | ( | Real | fov | ) | `[inline]`

Real vl::Camera::fov | ( |  | ) | const`[inline]`

Real vl::Camera::aspectRatio | ( |  | ) | const`[inline]`

Returns the aspect ratio computed as viewport()->width()/viewport()->height().

If viewport() == NULL the function returns 0.

void vl::Camera::setNearPlane | ( | Real | nearplane | ) | `[inline]`

Real vl::Camera::nearPlane | ( |  | ) | const`[inline]`

void vl::Camera::setFarPlane | ( | Real | farplane | ) | `[inline]`

Real vl::Camera::farPlane | ( |  | ) | const`[inline]`

void vl::Camera::setFrustum | ( | const Frustum & | frustum | ) | `[inline]`

const Frustum& vl::Camera::frustum | ( |  | ) | const`[inline]`

void vl::Camera::setViewport | ( | Viewport * | viewport | ) | `[inline]`

Viewport* vl::Camera::viewport | ( |  | ) | `[inline]`

const Viewport* vl::Camera::viewport | ( |  | ) | const`[inline]`

void vl::Camera::followTransform | ( | Transform * | transform | ) | `[inline]`

const Transform* vl::Camera::followedTransform | ( |  | ) | const`[inline]`

Transform* vl::Camera::followedTransform | ( |  | ) | `[inline]`

void vl::Camera::setViewMatrix | ( | const mat4 & | mat | ) | `[inline]`

Sets the Camera's view matrix.

const mat4& vl::Camera::viewMatrix | ( |  | ) | const`[inline]`

The Camera's view matrix.

This is what you would pass to OpenGL with "glMatrixMode(GL_MODELVIEW);glLoadMatrix(camera.viewMatrix().ptr());"

void vl::Camera::setInverseViewMatrix | ( | const mat4 & | mat | ) | `[inline]`

The camera's reference frame matrix, the inverse of the view matrix.

const mat4& vl::Camera::inverseViewMatrix | ( |  | ) | const`[inline]`

The camera's reference frame matrix, the inverse of the view matrix.

void vl::Camera::setProjectionMatrix | ( | const mat4 & | mat | ) | `[inline]`

The camera's projection matrix.

const mat4& vl::Camera::projectionMatrix | ( |  | ) | const`[inline]`

The camera's projection matrix.

void Camera::setProjectionAsPerspective | ( |  | ) |

Builds a perspective projection matrix for the Camera based on the Camera's and Viewport's settings.

See also http://www.opengl.org/sdk/docs/man/xhtml/gluPerspective.xml for more information.

void Camera::setProjectionAsPerspective | ( | Real | fov,
|  | Real | near,
|  | Real | far |
| ) |  |  |

Builds a perspective projection matrix for the Camera based on the Camera's and Viewport's settings.

See also http://www.opengl.org/sdk/docs/man/xhtml/gluPerspective.xml for more information.

void Camera::setProjectionAsFrustum | ( | Real | left,
|  | Real | right,
|  | Real | bottom,
|  | Real | top,
|  | Real | near,
|  | Real | far |
| ) |  |  |

Builds a perspective projection matrix for the Camera based on the give frustum.

See also http://www.opengl.org/sdk/docs/man/xhtml/glFrustum.xml for more information.

Note:
  This method sets fov() to -1.

void Camera::setProjectionAsOrtho | ( | Real | offset = `-0.5f` | ) |

Builds an orthographic projection matrix for the Camera based on the Camera's near/far planes and its Viewport's settings.

See also http://www.opengl.org/sdk/docs/man/xhtml/glOrtho.xml for more information. Equivalent to:

     setProjectionMatrix(
       mat4::ortho(
         offset, (Real)mViewport->width()  + offset,
         offset, (Real)mViewport->height() + offset,
         nearPlane(), farPlane())
     );

void Camera::setProjectionAsOrtho2D | ( | Real | offset = `-0.5f` | ) |

Builds an orthographic projection matrix for the Camera based on its Viewport's settings.

See also http://www.opengl.org/sdk/docs/man/xhtml/glOrtho2D.xml for more information.

Equivalent to:

     setProjectionMatrix(
       mat4::ortho(
         offset, viewport()->width()  + offset,
         offset, viewport()->height() + offset,
         -1, +1)
     );

void Camera::setViewMatrixAsLookAt | ( | const vec3 & | eye,
|  | const vec3 & | center,
|  | const vec3 & | up |
| ) |  |  |

void Camera::getViewMatrixAsLookAt | ( | vec3 & | eye,
|  | vec3 & | look,
|  | vec3 & | up,
|  | vec3 & | right |
| ) |  |  | const

bool Camera::project | ( | const vec4 & | in,
|  | vec4 & | out |
| ) |  |  | const

bool Camera::unproject | ( | const vec3 & | win,
|  | vec4 & | out |
| ) |  |  | const

Unprojects a vector from window coordinates to world coordinates.

Parameters:

  | win | The window coordinates point to be projected. Note that, in accordance to OpenGL conventions, the window coordinates have the Y axis pointing upwards and origin at the bottom left corner of the window.
  | out | The world coordinates of the projected point.

Note:
  The `w` coordinate of `win` determines the position of the projected point along the ray passing through `win`. If `w` equals 0 then `out` will lay on the near clipping plane, if equals 1 then `out` will lay on the far clipping plane.

bool Camera::unproject | ( | std::vector< vec3 > & | points | ) | const

Unprojects a set of points. See unproject(const vec3& win, vec4& out) for more information.

Ray Camera::computeRay | ( | int | winx,
|  | int | winy |
| ) |  |  |

Computes the ray passing through the point <winx,winy>.

Parameters:

  | winx | The x position of the point defining the ray
  | winy | The y position of the point defining the ray

Note:
  <winx,winy> is considered to be point in widows coordinate. In accordance to the OpenGL conventions the windows coordinates have origin on the bottom left corner of the window, with the Y axis pointing upwards. Most GUI libraries define the the orgin at the top left corner of the window and Y axis pointing downwards. You can convert such coordinates to OpenGL ones using the following simple formula: `"opengl_y = window_height - coord_y"`.

Frustum Camera::computeRayFrustum | ( | int | winx,
|  | int | winy |
| ) |  |  |

Computes a frustum suitable to cull object during ray intersection detection.

void vl::Camera::setNearFarClippingPlanesOptimized | ( | bool | enable | ) | `[inline]`

Enables the optimization of the near and far clipping planes.

If the optimization is enabled the near and far clipping planes are adjusted to fit the sphere returned by sceneBoundingSphere(). Optimizing the near and far clipping planes results in an optimized usage of the z-buffer with the consequence of minimizing possible z-fighting artifacts and enhancing the rendering quality.

See also:
  setSceneBoundingSphere()

Note:
  Optimizing the near and far clipping planes can slightly slow down the rendering performances.

  At the moment the near and far clipping planes optimization is available only when using a perspective projection matrix and not for orthographic projection matrices.

bool vl::Camera::nearFarClippingPlanesOptimized | ( |  | ) | const`[inline]`

Set to true if the optimization of the near and far clipping planes is enabled.

If the optimization is enabled the near and far clipping planes are adjusted to fit the sphere returned by sceneBoundingSphere(). Optimizing the near and far clipping planes results in an optimized usage of the z-buffer with the consequence of minimizing possible z-fighting artifacts and enhancing the rendering quality.

See also:
  setSceneBoundingSphere()

Note:
  Optimizing the near and far clipping planes might slightly slow down the rendering performances if the scene contains several thousands of objects.

  At the moment the near and far clipping planes optimization is available only when using a perspective projection matrix set up by setProjectionAsPerspective().

void vl::Camera::setSceneBoundingSphere | ( | const Sphere & | sphere | ) | `[inline]`

The bounding sphere of the scene used to optimize the near and far clipping planes.

See also:
  setNearFarClippingPlanesOptimized()

const Sphere& vl::Camera::sceneBoundingSphere | ( |  | ) | const`[inline]`

The bounding sphere of the scene used to optimize the near and far clipping planes.

See also:
  setNearFarClippingPlanesOptimized()

void Camera::adjustView | ( | const AABB & | aabb,
|  | const vec3 & | dir,
|  | const vec3 & | up,
|  | Real | bias = `1.0f` |
| ) |  |  |

Adjusts the camera position so that the given aabb can be properly viewed.

Parameters:

  | aabb | The AABB (in world coords) that should be visible from the newly computed camera position.
  | dir | The direction (in world coords) along which the camera should be displaced to view the given AABB.
  | up | The vector that defines the `up` direction (in world coords). Used to properly compute the new camera matrix.
  | bias | A bias factor used to adjust the computed camera distance from the given AABB. Values between 0 and 1 make the camera closer to the AABB center, values greater than 1 position the camera further away.

## Member Data Documentation

mat4 vl::Camera::mViewMatrix`[protected]`

mat4 vl::Camera::mInverseViewMatrix`[protected]`

mat4 vl::Camera::mProjectionMatrix`[protected]`

ref<Viewport> vl::Camera::mViewport`[protected]`

Frustum vl::Camera::mFrustum`[protected]`

ref<Transform> vl::Camera::mFollowTransform`[protected]`

Real vl::Camera::mFOV`[protected]`

Real vl::Camera::mNearPlane`[protected]`

Real vl::Camera::mFarPlane`[protected]`

Sphere vl::Camera::mSceneBoundingSphere`[protected]`

bool vl::Camera::mActive`[protected]`

bool vl::Camera::mNearFarClippingPlanesOptimized`[protected]`

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

- E:/VisualizationLibrary/BuildSystem/VL_DISTRO/Visualization_Library_SDK/src/vl/Camera.hpp
- E:/VisualizationLibrary/BuildSystem/VL_DISTRO/Visualization_Library_SDK/src/vl/Camera.cpp

Visualization Library v2009.07 Reference Documentation
Copyright 2005-2009 Michele Bosi. All rights reserved.
Updated on Mon Aug 10 21:41:34 2009.
Permission is granted to use this page to write and publish articles regarding Visualization Library.