libQGLViewer Version 2.6.4

Public Types | Public Member Functions | List of all members
Camera Class Reference

A perspective or orthographic camera. More...

## Public Types
enum | Type { PERSPECTIVE, ORTHOGRAPHIC }

## Public Member Functions
| Camera ()
virtual | ~Camera ()
| Camera (const Camera &camera)
Camera & | operator= (const Camera &camera)

## Position and orientation
Vec | position () const
Vec | upVector () const
Vec | viewDirection () const
Vec | rightVector () const
Quaternion | orientation () const
void | setFromModelViewMatrix (const GLdouble *const modelViewMatrix)
void | setFromProjectionMatrix (const qreal matrix[12])
void | setPosition (const Vec &pos)
void | setOrientation (const Quaternion &q)
void | setOrientation (qreal theta, qreal phi)
void | setUpVector (const Vec &up, bool noMove=true)
void | setViewDirection (const Vec &direction)

## Positioning tools
void | lookAt (const Vec &target)
void | showEntireScene ()
void | fitSphere (const Vec &center, qreal radius)
void | fitBoundingBox (const Vec &min, const Vec &max)
void | fitScreenRegion (const QRect &rectangle)
void | centerScene ()
void | interpolateToZoomOnPixel (const QPoint &pixel)
void | interpolateToFitScene ()
void | interpolateTo (const Frame &fr, qreal duration)

## Frustum
Type | type () const
qreal | fieldOfView () const
qreal | horizontalFieldOfView () const
qreal | aspectRatio () const
int | screenWidth () const
int | screenHeight () const
void | getViewport (GLint viewport[4]) const
qreal | pixelGLRatio (const Vec &position) const
qreal | zNearCoefficient () const
qreal | zClippingCoefficient () const
virtual qreal | zNear () const
virtual qreal | zFar () const
virtual void | getOrthoWidthHeight (GLdouble &halfWidth, GLdouble &halfHeight) const
void | getFrustumPlanesCoefficients (GLdouble coef[6][4]) const
void | setType (Type type)
void | setFieldOfView (qreal fov)
void | setHorizontalFieldOfView (qreal hfov)
void | setFOVToFitScene ()
void | setAspectRatio (qreal aspect)
void | setScreenWidthAndHeight (int width, int height)
void | setZNearCoefficient (qreal coef)
void | setZClippingCoefficient (qreal coef)

## Scene radius and center
qreal | sceneRadius () const
Vec | sceneCenter () const
qreal | distanceToSceneCenter () const
void | setSceneRadius (qreal radius)
void | setSceneCenter (const Vec &center)
bool | setSceneCenterFromPixel (const QPoint &pixel)
void | setSceneBoundingBox (const Vec &min, const Vec &max)

## Pivot Point
Vec | pivotPoint () const
void | setPivotPoint (const Vec &point)
bool | setPivotPointFromPixel (const QPoint &pixel)

## Associated frame
ManipulatedCameraFrame * | frame () const
void | setFrame (ManipulatedCameraFrame *const mcf)

## KeyFramed paths
KeyFrameInterpolator * | keyFrameInterpolator (unsigned int i) const
void | setKeyFrameInterpolator (unsigned int i, KeyFrameInterpolator *const kfi)
virtual void | addKeyFrameToPath (unsigned int i)
virtual void | playPath (unsigned int i)
virtual void | deletePath (unsigned int i)
virtual void | resetPath (unsigned int i)
virtual void | drawAllPaths ()

## OpenGL matrices
virtual void | loadProjectionMatrix (bool reset=true) const
virtual void | loadModelViewMatrix (bool reset=true) const
void | computeProjectionMatrix () const
void | computeModelViewMatrix () const
virtual void | loadProjectionMatrixStereo (bool leftBuffer=true) const
virtual void | loadModelViewMatrixStereo (bool leftBuffer=true) const
void | getProjectionMatrix (GLfloat m[16]) const
void | getProjectionMatrix (GLdouble m[16]) const
void | getModelViewMatrix (GLfloat m[16]) const
void | getModelViewMatrix (GLdouble m[16]) const
void | getModelViewProjectionMatrix (GLfloat m[16]) const
void | getModelViewProjectionMatrix (GLdouble m[16]) const

## Drawing
virtual void | draw (bool drawFarPlane=true, qreal scale=1.0) const

## World to Camera coordinate systems conversions
Vec | cameraCoordinatesOf (const Vec &src) const
Vec | worldCoordinatesOf (const Vec &src) const
void | getCameraCoordinatesOf (const qreal src[3], qreal res[3]) const
void | getWorldCoordinatesOf (const qreal src[3], qreal res[3]) const

## 2D screen to 3D world coordinate systems conversions
Vec | projectedCoordinatesOf (const Vec &src, const Frame *frame=NULL) const
Vec | unprojectedCoordinatesOf (const Vec &src, const Frame *frame=NULL) const
void | getProjectedCoordinatesOf (const qreal src[3], qreal res[3], const Frame *frame=NULL) const
void | getUnprojectedCoordinatesOf (const qreal src[3], qreal res[3], const Frame *frame=NULL) const
void | convertClickToLine (const QPoint &pixel, Vec &orig, Vec &dir) const
Vec | pointUnderPixel (const QPoint &pixel, bool &found) const

## Fly speed
qreal | flySpeed () const
void | setFlySpeed (qreal speed)

## Stereo parameters
qreal | IODistance () const
qreal | physicalDistanceToScreen () const
qreal | physicalScreenWidth () const
qreal | focusDistance () const
void | setIODistance (qreal distance)
void | setPhysicalScreenWidth (qreal width)
void | setFocusDistance (qreal distance)

## XML representation
virtual QDomElement | domElement (const QString &name, QDomDocument &document) const
virtual void | initFromDOMElement (const QDomElement &element)

## Detailed Description

A perspective or orthographic camera.

A Camera defines some intrinsic parameters (fieldOfView(), position(), viewDirection(), upVector()...) and useful positioning tools that ease its placement (showEntireScene(), fitSphere(), lookAt()...). It exports its associated OpenGL projection and modelview matrices and can interactively be modified using the mouse.

### Mouse manipulation

The position() and orientation() of the Camera are defined by a ManipulatedCameraFrame (retrieved using frame()). These methods are just convenient wrappers to the equivalent Frame methods. This also means that the Camera frame() can be attached to a Frame::referenceFrame() which enables complex Camera setups.

Different displacements can be performed using the mouse. The list of possible actions is defined by the QGLViewer::MouseAction enum. Use QGLViewer::setMouseBinding() to attach a specific action to an arbitrary mouse button-state key binding. These actions are detailed in the mouse page.

The default button binding are: ROTATE (left), ZOOM (middle) and TRANSLATE (right). With this configuration, the Camera observes a scene and rotates around its pivotPoint(). You can switch between this mode and a fly mode using the CAMERA_MODE (see QGLViewer::toggleCameraMode()) keyboard shortcut (default is 'Space').

### Other functionalities

The type() of the Camera can be Camera::ORTHOGRAPHIC or Camera::PERSPECTIVE (see Type()). fieldOfView() is meaningless with Camera::ORTHOGRAPHIC.

The near and far planes of the Camera are fitted to the scene and determined from QGLViewer::sceneRadius(), QGLViewer::sceneCenter() and zClippingCoefficient() by the zNear() and zFar() methods. Reasonable values on the scene extends hence have to be provided to the QGLViewer in order for the Camera to correctly display the scene. High level positioning methods also use this information (showEntireScene(), centerScene()...).

A Camera holds KeyFrameInterpolator that can be used to save Camera positions and paths. You can interactively addKeyFrameToPath() to a given path using the default `Alt+F`[1-12] shortcuts. Use playPath() to make the Camera follow the path (default shortcut is F[1-12]). See the keyboard page for details on key customization.

Use cameraCoordinatesOf() and worldCoordinatesOf() to convert to and from the Camera frame() coordinate system. projectedCoordinatesOf() and unprojectedCoordinatesOf() will convert from screen to 3D coordinates. convertClickToLine() is very useful for analytical object selection.

Stereo display is possible on machines with quad buffer capabilities (with Camera::PERSPECTIVE type() only). Test the stereoViewer example to check.

A Camera can also be used outside of a QGLViewer or even without OpenGL for its coordinate system conversion capabilities. Note however that some of them explicitly rely on the presence of a Z-buffer.

## Member Enumeration Documentation

## § Type

enum Type

Enumerates the two possible types of Camera.

See type() and setType(). This type mainly defines different Camera projection matrix (see loadProjectionMatrix()). Many other methods (pointUnderPixel(), convertClickToLine(), projectedCoordinatesOf(), pixelGLRatio()...) are affected by this Type.

Enumerator
PERSPECTIVE |
ORTHOGRAPHIC |

## Constructor & Destructor Documentation

## § Camera() [1/2]

Camera | ( |  | ) |

Default constructor.

sceneCenter() is set to (0,0,0) and sceneRadius() is set to 1.0. type() is Camera::PERSPECTIVE, with a `M_PI/4` fieldOfView().

See IODistance(), physicalDistanceToScreen(), physicalScreenWidth() and focusDistance() documentations for default stereo parameter values.

## § ~Camera()

~Camera | ( |  | ) |
| virtual

Virtual destructor.

The frame() is deleted, but the different keyFrameInterpolator() are not deleted (in case they are shared).

## § Camera() [2/2]

Camera | ( | const Camera & | camera | ) |

Copy constructor. Performs a deep copy using operator=().

## Member Function Documentation

## § addKeyFrameToPath

void addKeyFrameToPath | ( | unsigned int | i | ) |
| virtual slot

Adds the current Camera position() and orientation() as a keyFrame to the path number `i`.

This method can also be used if you simply want to save a Camera point of view (a path made of a single keyFrame). Use playPath() to make the Camera play the keyFrame path (resp. restore the point of view). Use deletePath() to clear the path.

The default keyboard shortcut for this method is Alt+F[1-12]. Set QGLViewer::pathKey() and QGLViewer::addKeyFrameKeyboardModifiers().

If you use directly this method and the keyFrameInterpolator(i) does not exist, a new one is created. Its KeyFrameInterpolator::interpolated() signal should then be connected to the QGLViewer::update() slot (see setKeyFrameInterpolator()).

## § aspectRatio()

qreal aspectRatio | ( |  | ) | const

Returns the Camera aspect ratio defined by screenWidth() / screenHeight().

When the Camera is attached to a QGLViewer, these values and hence the aspectRatio() are automatically fitted to the viewer's window aspect ratio using setScreenWidthAndHeight().

## § cameraCoordinatesOf()

Vec cameraCoordinatesOf | ( | const Vec & | src | ) | const

Returns the Camera frame coordinates of a point `src` defined in world coordinates.

worldCoordinatesOf() performs the inverse transformation.

Note that the point coordinates are simply converted in a different coordinate system. They are not projected on screen. Use projectedCoordinatesOf() for that.

## § centerScene

void centerScene | ( |  | ) |
| slot

Moves the Camera so that its sceneCenter() is projected on the center of the window. The orientation() and fieldOfView() are unchanged.

Simply projects the current position on a line passing through sceneCenter(). See also showEntireScene().

## § computeModelViewMatrix()

void computeModelViewMatrix | ( |  | ) | const

Computes the modelView matrix associated with the Camera's position() and orientation().

This matrix converts from the world coordinates system to the Camera coordinates system, so that coordinates can then be projected on screen using the projection matrix (see computeProjectionMatrix()).

Use getModelViewMatrix() to retrieve this matrix.

Note
  You must call this method if your Camera is not associated with a QGLViewer and is used for offscreen computations (using (un)projectedCoordinatesOf() for instance). loadModelViewMatrix() does it otherwise.

## § computeProjectionMatrix()

void computeProjectionMatrix | ( |  | ) | const

Computes the projection matrix associated with the Camera.

If type() is Camera::PERSPECTIVE, defines a `GL_PROJECTION` matrix similar to what would `gluPerspective()` do using the fieldOfView(), window aspectRatio(), zNear() and zFar() parameters.

If type() is Camera::ORTHOGRAPHIC, the projection matrix is as what `glOrtho()` would do. Frustum's width and height are set using getOrthoWidthHeight().

Both types use zNear() and zFar() to place clipping planes. These values are determined from sceneRadius() and sceneCenter() so that they best fit the scene size.

Use getProjectionMatrix() to retrieve this matrix. Overload loadProjectionMatrix() if you want your Camera to use an exotic projection matrix.

Note
  You must call this method if your Camera is not associated with a QGLViewer and is used for offscreen computations (using (un)projectedCoordinatesOf() for instance). loadProjectionMatrix() does it otherwise.

## § convertClickToLine()

void convertClickToLine | ( | const QPoint & | pixel,
|  | Vec & | orig,
|  | Vec & | dir
| ) |  | const

Gives the coefficients of a 3D half-line passing through the Camera eye and pixel (x,y).

The origin of the half line (eye position) is stored in `orig`, while `dir` contains the properly oriented and normalized direction of the half line.

`x` and `y` are expressed in Qt format (origin in the upper left corner). Use screenHeight() - y to convert to OpenGL units.

This method is useful for analytical intersection in a selection method.

See the select example for an illustration.

## § deletePath

void deletePath | ( | unsigned int | i | ) |
| virtual slot

Deletes the keyFrameInterpolator() of index `i`.

Disconnect the keyFrameInterpolator() KeyFrameInterpolator::interpolated() signal before deleting the keyFrameInterpolator() if needed:

disconnect(camera()->keyFrameInterpolator(i), SIGNAL(interpolated()), this, SLOT(update()));
camera()->deletePath(i);

## § distanceToSceneCenter()

qreal distanceToSceneCenter | ( |  | ) | const

Returns the distance from the Camera center to sceneCenter(), projected along the Camera Z axis. Used by zNear() and zFar() to optimize the Z range.

## § domElement()

QDomElement domElement | ( | const QString & | name,
|  | QDomDocument & | document
| ) |  | const
| virtual

Returns an XML `QDomElement` that represents the Camera.

`name` is the name of the QDomElement tag. `doc` is the `QDomDocument` factory used to create QDomElement.

Concatenates the Camera parameters, the ManipulatedCameraFrame::domElement() and the paths' KeyFrameInterpolator::domElement().

Use initFromDOMElement() to restore the Camera state from the resulting `QDomElement`.

If you want to save the Camera state in a file, use:

QDomDocument document("myCamera");
doc.appendChild( myCamera->domElement("Camera", document) );
QFile f("myCamera.xml");
if (f.open(IO_WriteOnly))
{
QTextStream out(&f);
document.save(out, 2);
}

Note that the QGLViewer::camera() is automatically saved by QGLViewer::saveStateToFile() when a QGLViewer is closed. Use QGLViewer::restoreStateFromFile() to restore it back.

## § draw()

void draw | ( | bool | drawFarPlane = `true`,
|  | qreal | scale = `1.0`
| ) |  | const
| virtual

Draws a representation of the Camera in the 3D world.

The near and far planes are drawn as quads, the frustum is drawn using lines and the camera up vector is represented by an arrow to disambiguate the drawing. See the standardCamera example for an illustration.

Note that the current `glColor` and `glPolygonMode` are used to draw the near and far planes. See the frustumCulling example for an example of semi-transparent plane drawing. Similarly, the current `glLineWidth` and `glColor` is used to draw the frustum outline.

When `drawFarPlane` is `false`, only the near plane is drawn. `scale` can be used to scale the drawing: a value of 1.0 (default) will draw the Camera's frustum at its actual size.

This method assumes that the `glMatrixMode` is `GL_MODELVIEW` and that the current ModelView matrix corresponds to the world coordinate system (as it is at the beginning of QGLViewer::draw()). The Camera is then correctly positioned and orientated.

Note
  The drawing of a QGLViewer's own QGLViewer::camera() should not be visible, but may create artefacts due to numerical imprecisions.

## § drawAllPaths

void drawAllPaths | ( |  | ) |
| virtual slot

Draws all the Camera paths defined by the keyFrameInterpolator().

Simply calls KeyFrameInterpolator::drawPath() for all the defined paths. The path color is the current `glColor()`.

Attention
  The OpenGL state is modified by this method: see KeyFrameInterpolator::drawPath().

## § fieldOfView()

qreal fieldOfView | ( |  | ) | const

Returns the vertical field of view of the Camera (in radians).

Value is set using setFieldOfView(). Default value is pi/4 radians. This value is meaningless if the Camera type() is Camera::ORTHOGRAPHIC.

The field of view corresponds the one used in `gluPerspective` (see manual). It sets the Y (vertical) aperture of the Camera. The X (horizontal) angle is inferred from the window aspect ratio (see aspectRatio() and horizontalFieldOfView()).

Use setFOVToFitScene() to adapt the fieldOfView() to a given scene.

## § fitBoundingBox

void fitBoundingBox | ( | const Vec & | min,
|  | const Vec & | max
| ) |  |
| slot

Moves the Camera so that the (world axis aligned) bounding box (`min`, `max`) is entirely visible, using fitSphere().

## § fitScreenRegion

void fitScreenRegion | ( | const QRect & | rectangle | ) |
| slot

Moves the Camera so that the rectangular screen region defined by `rectangle` (pixel units, with origin in the upper left corner) fits the screen.

The Camera is translated (its orientation() is unchanged) so that `rectangle` is entirely visible. Since the pixel coordinates only define a frustum in 3D, it's the intersection of this frustum with a plane (orthogonal to the viewDirection() and passing through the sceneCenter()) that is used to define the 3D rectangle that is eventually fitted.

## § fitSphere

void fitSphere | ( | const Vec & | center,
|  | qreal | radius
| ) |  |
| slot

Moves the Camera so that the sphere defined by (`center`, `radius`) is visible and fits in the frustum.

The Camera is simply translated to center the sphere in the screen and make it fit the frustum. Its orientation() and its fieldOfView() are unchanged.

You should therefore orientate the Camera before you call this method. See lookAt(), setOrientation() and setUpVector().

## § flySpeed()

qreal flySpeed | ( |  | ) | const

Returns the fly speed of the Camera.

Simply returns frame()->flySpeed(). See the ManipulatedCameraFrame::flySpeed() documentation. This value is only meaningful when the MouseAction bindings is MOVE_FORWARD or MOVE_BACKWARD.

Set to 1% of the sceneRadius() by setSceneRadius(). See also setFlySpeed().

## § focusDistance()

qreal focusDistance | ( |  | ) | const

Returns the focus distance used by stereo display, expressed in OpenGL units.

This is the distance in the virtual world between the Camera and the plane where the horizontal stereo parallax is null (the stereo left and right cameras' lines of sigth cross at this distance).

This distance is the virtual world equivalent of the real-world physicalDistanceToScreen().

Attention
  This value is modified by QGLViewer::setSceneRadius(), setSceneRadius() and setFieldOfView(). When one of these values is modified, focusDistance() is set to sceneRadius() / tan(fieldOfView()/2), which provides good results.

## § frame()

ManipulatedCameraFrame* frame | ( |  | ) | const

Returns the ManipulatedCameraFrame attached to the Camera.

This ManipulatedCameraFrame defines its position() and orientation() and can translate mouse events into Camera displacement. Set using setFrame().

## § getCameraCoordinatesOf()

void getCameraCoordinatesOf | ( | const qreal | src[3],
|  | qreal | res[3]
| ) |  | const

Same as cameraCoordinatesOf(), but with `qreal`[3] parameters (`src` and `res` may be identical pointers).

## § getFrustumPlanesCoefficients()

void getFrustumPlanesCoefficients | ( | GLdouble | coef[6][4] | ) | const

Returns the 6 plane equations of the Camera frustum.

The six 4-component vectors of `coef` respectively correspond to the left, right, near, far, top and bottom Camera frustum planes. Each vector holds a plane equation of the form:

a*x + b*y + c*z + d = 0

where `a`, `b`, `c` and `d` are the 4 components of each vector, in that order.

See the frustumCulling example for an application.

This format is compatible with the `glClipPlane()` function. One camera frustum plane can hence be applied in an other viewer to visualize the culling results:

// Retrieve plane equations
GLdouble coef[6][4];
mainViewer->camera()->getFrustumPlanesCoefficients(coef);
// These two additional clipping planes (which must have been enabled)
// will reproduce the mainViewer's near and far clipping.
glClipPlane(GL_CLIP_PLANE0, coef[2]);
glClipPlane(GL_CLIP_PLANE1, coef[3]);

## § getModelViewMatrix() [1/2]

void getModelViewMatrix | ( | GLfloat | m[16] | ) | const

Overloaded getModelViewMatrix(GLdouble m[16]) method using a `GLfloat` array instead.

## § getModelViewMatrix() [2/2]

void getModelViewMatrix | ( | GLdouble | m[16] | ) | const

Fills `m` with the Camera modelView matrix values.

First calls computeModelViewMatrix() to define the Camera modelView matrix.

Note that this matrix may not be the one you would get from a `glGetDoublev(GL_MODELVIEW_MATRIX, m)`. It actually represents the state of the `GL_MODELVIEW` after QGLViewer::preDraw(), at the beginning of QGLViewer::draw(). It converts from the world to the Camera coordinate system. As soon as you modify the `GL_MODELVIEW` in your QGLViewer::draw() method (using glTranslate, glRotate... or similar methods), the two matrices differ.

The result is an OpenGL 4x4 matrix, which is given in column-major order (see `glMultMatrix` man page for details).

See also getProjectionMatrix() and setFromModelViewMatrix().

## § getModelViewProjectionMatrix() [1/2]

void getModelViewProjectionMatrix | ( | GLfloat | m[16] | ) | const

Overloaded getModelViewProjectionMatrix(GLdouble m[16]) method using a `GLfloat` array instead.

## § getModelViewProjectionMatrix() [2/2]

void getModelViewProjectionMatrix | ( | GLdouble | m[16] | ) | const

Fills `m` with the product of the ModelView and Projection matrices.

Calls getModelViewMatrix() and getProjectionMatrix() and then fills `m` with the product of these two matrices.

## § getOrthoWidthHeight()

void getOrthoWidthHeight | ( | GLdouble & | halfWidth,
|  | GLdouble & | halfHeight
| ) |  | const
| virtual

Returns the `halfWidth` and `halfHeight` of the Camera orthographic frustum.

These values are only valid and used when the Camera is of type() Camera::ORTHOGRAPHIC. They are expressed in OpenGL units and are used by loadProjectionMatrix() to define the projection matrix using:

glOrtho( -halfWidth, halfWidth, -halfHeight, halfHeight, zNear(), zFar() )

These values are proportional to the Camera (z projected) distance to the pivotPoint(). When zooming on the object, the Camera is translated forward and its frustum is narrowed, making the object appear bigger on screen, as intuitively expected.

Overload this method to change this behavior if desired, as is done in the standardCamera example.

## § getProjectedCoordinatesOf()

void getProjectedCoordinatesOf | ( | const qreal | src[3],
|  | qreal | res[3],
|  | const Frame * | frame = `NULL`
| ) |  | const

Same as projectedCoordinatesOf(), but with `qreal` parameters (`src` and `res` can be identical pointers).

## § getProjectionMatrix() [1/2]

void getProjectionMatrix | ( | GLfloat | m[16] | ) | const

Overloaded getProjectionMatrix(GLdouble m[16]) method using a `GLfloat` array instead.

## § getProjectionMatrix() [2/2]

void getProjectionMatrix | ( | GLdouble | m[16] | ) | const

Fills `m` with the Camera projection matrix values.

Based on computeProjectionMatrix() to make sure the Camera projection matrix is up to date.

This matrix only reflects the Camera's internal parameters and it may differ from the `GL_PROJECTION` matrix retrieved using `glGetDoublev(GL_PROJECTION_MATRIX, m)`. It actually represents the state of the `GL_PROJECTION` after QGLViewer::preDraw(), at the beginning of QGLViewer::draw(). If you modified the `GL_PROJECTION` matrix (for instance using QGLViewer::startScreenCoordinatesSystem()), the two results differ.

The result is an OpenGL 4x4 matrix, which is given in column-major order (see `glMultMatrix` man page for details).

See also getModelViewMatrix() and setFromProjectionMatrix().

## § getUnprojectedCoordinatesOf()

void getUnprojectedCoordinatesOf | ( | const qreal | src[3],
|  | qreal | res[3],
|  | const Frame * | frame = `NULL`
| ) |  | const

Same as unprojectedCoordinatesOf(), but with `qreal` parameters (`src` and `res` can be identical pointers).

## § getViewport()

void getViewport | ( | GLint | viewport[4] | ) | const

Fills `viewport` with the Camera OpenGL viewport.

This method is mainly used in conjunction with `gluProject`, which requires such a viewport. Returned values are (0, screenHeight(), screenWidth(), - screenHeight()), so that the origin is located in the upper left corner of the window (Qt style coordinate system).

## § getWorldCoordinatesOf()

void getWorldCoordinatesOf | ( | const qreal | src[3],
|  | qreal | res[3]
| ) |  | const

Same as worldCoordinatesOf(), but with `qreal`[3] parameters (`src` and `res` may be identical pointers).

## § horizontalFieldOfView()

qreal horizontalFieldOfView | ( |  | ) | const

Returns the horizontal field of view of the Camera (in radians).

Value is set using setHorizontalFieldOfView() or setFieldOfView(). These values are always linked by:

horizontalFieldOfView() = 2.0 * atan ( tan(fieldOfView()/2.0) * aspectRatio() ).

## § initFromDOMElement

void initFromDOMElement | ( | const QDomElement & | element | ) |
| virtual slot

Restores the Camera state from a `QDomElement` created by domElement().

Use the following code to retrieve a Camera state from a file created using domElement():

// Load DOM from file
QDomDocument document;
QFile f("myCamera.xml");
if (f.open(IO_ReadOnly))
{
document.setContent(&f);
f.close();
}
// Parse the DOM tree
QDomElement main = document.documentElement();
myCamera->initFromDOMElement(main);

The frame() pointer is not modified by this method. The frame() state is however modified.

Attention
  The original keyFrameInterpolator() are deleted and should be copied first if they are shared.

## § interpolateTo

void interpolateTo | ( | const Frame & | fr,
|  | qreal | duration
| ) |  |
| slot

Smoothly interpolates the Camera on a KeyFrameInterpolator path so that it goes to `fr`.

`fr` is expressed in world coordinates. `duration` tunes the interpolation speed (default is 1 second).

See also interpolateToFitScene() and interpolateToZoomOnPixel().

## § interpolateToFitScene

void interpolateToFitScene | ( |  | ) |
| slot

Interpolates the Camera on a one second KeyFrameInterpolator path so that the entire scene fits the screen at the end.

The scene is defined by its sceneCenter() and its sceneRadius(). See showEntireScene().

The orientation() of the Camera is not modified. See also interpolateToZoomOnPixel().

## § interpolateToZoomOnPixel

void interpolateToZoomOnPixel | ( | const QPoint & | pixel | ) |
| slot

Makes the Camera smoothly zoom on the pointUnderPixel() `pixel`.

Nothing happens if no pointUnderPixel() is found. Otherwise a KeyFrameInterpolator is created that animates the Camera on a one second path that brings the Camera closer to the point under `pixel`.

See also interpolateToFitScene().

## § IODistance()

qreal IODistance | ( |  | ) | const

Returns the user's inter-ocular distance (in meters). Default value is 0.062m, which fits most people.

loadProjectionMatrixStereo() uses this value to define the Camera offset and frustum. See setIODistance().

## § keyFrameInterpolator()

KeyFrameInterpolator * keyFrameInterpolator | ( | unsigned int | i | ) | const

Returns the KeyFrameInterpolator that defines the Camera path number `i`.

If path `i` is not defined for this index, the method returns a `NULL` pointer.

## § loadModelViewMatrix()

void loadModelViewMatrix | ( | bool | reset = `true` | ) | const
| virtual

Loads the OpenGL `GL_MODELVIEW` matrix with the modelView matrix corresponding to the Camera.

Calls computeModelViewMatrix() to compute the Camera's modelView matrix.

This method is used by QGLViewer::preDraw() (called before user's QGLViewer::draw() method) to set the `GL_MODELVIEW` matrix according to the viewer's QGLViewer::camera() position() and orientation().

As a result, the vertices used in QGLViewer::draw() can be defined in the so called world coordinate system. They are multiplied by this matrix to get converted to the Camera coordinate system, before getting projected using the `GL_PROJECTION` matrix (see loadProjectionMatrix()).

When `reset` is `true` (default), the method loads (overwrites) the `GL_MODELVIEW` matrix. Setting `reset` to `false` simply calls `glMultMatrixd` (might be useful for some applications).

Overload this method or simply call glLoadMatrixd() at the beginning of QGLViewer::draw() if you want your Camera to use an exotic modelView matrix. See also loadProjectionMatrix().

getModelViewMatrix() returns the 4x4 modelView matrix.

Attention
  glMatrixMode is set to `GL_MODELVIEW`
  If you use several OpenGL contexts and bypass the Qt main refresh loop, you should call QGLWidget::makeCurrent() before this method in order to activate the right OpenGL context.

## § loadModelViewMatrixStereo()

void loadModelViewMatrixStereo | ( | bool | leftBuffer = `true` | ) | const
| virtual

Same as loadModelViewMatrix() but for a stereo setup.

Only the Camera::PERSPECTIVE type() is supported for stereo mode. See QGLViewer::setStereoDisplay().

The modelView matrix is almost identical to the mono-vision one. It is simply translated along its horizontal axis by a value that depends on stereo parameters (see focusDistance(), IODistance(), and physicalScreenWidth()).

When `leftBuffer` is `true`, computes the modelView matrix associated to the left eye (right eye otherwise).

loadProjectionMatrixStereo() explains how to retrieve to resulting matrix.

See the stereoViewer and the anaglyph examples for an illustration.

Attention
  glMatrixMode is set to `GL_MODELVIEW`.

## § loadProjectionMatrix()

void loadProjectionMatrix | ( | bool | reset = `true` | ) | const
| virtual

Loads the OpenGL `GL_PROJECTION` matrix with the Camera projection matrix.

The Camera projection matrix is computed using computeProjectionMatrix().

When `reset` is `true` (default), the method clears the previous projection matrix by calling `glLoadIdentity` before setting the matrix. Setting `reset` to `false` is useful for `GL_SELECT` mode, to combine the pushed matrix with a picking matrix. See QGLViewer::beginSelection() for details.

This method is used by QGLViewer::preDraw() (called before user's QGLViewer::draw() method) to set the `GL_PROJECTION` matrix according to the viewer's QGLViewer::camera() settings.

Use getProjectionMatrix() to retrieve this matrix. Overload this method if you want your Camera to use an exotic projection matrix. See also loadModelViewMatrix().

Attention
  `glMatrixMode` is set to `GL_PROJECTION`.
  If you use several OpenGL contexts and bypass the Qt main refresh loop, you should call QGLWidget::makeCurrent() before this method in order to activate the right OpenGL context.

## § loadProjectionMatrixStereo()

void loadProjectionMatrixStereo | ( | bool | leftBuffer = `true` | ) | const
| virtual

Same as loadProjectionMatrix() but for a stereo setup.

Only the Camera::PERSPECTIVE type() is supported for stereo mode. See QGLViewer::setStereoDisplay().

Uses focusDistance(), IODistance(), and physicalScreenWidth() to compute cameras offset and asymmetric frustums.

When `leftBuffer` is `true`, computes the projection matrix associated to the left eye (right eye otherwise). See also loadModelViewMatrixStereo().

See the stereoViewer and the anaglyph examples for an illustration.

To retrieve this matrix, use a code like:

glMatrixMode(GL_PROJECTION);
glPushMatrix();
loadProjectionMatrixStereo(left_or_right);
glGetDoublev(GL_PROJECTION_MATRIX, m);
glPopMatrix();

Note that getProjectionMatrix() always returns the mono-vision matrix.

Attention
  glMatrixMode is set to `GL_PROJECTION`.

## § lookAt

void lookAt | ( | const Vec & | target | ) |
| slot

Sets the Camera orientation(), so that it looks at point `target` (defined in the world coordinate system).

The Camera position() is not modified. Simply setViewDirection().

See also setUpVector(), setOrientation(), showEntireScene(), fitSphere() and fitBoundingBox().

## § operator=()

Camera & operator= | ( | const Camera & | camera | ) |

Equal operator.

All the parameters of `camera` are copied. The frame() pointer is not modified, but its Frame::position() and Frame::orientation() are set to those of `camera`.

Attention
  The Camera screenWidth() and screenHeight() are set to those of `camera`. If your Camera is associated with a QGLViewer, you should update these value after the call to this method:
  *(camera()) = otherCamera;
  camera()->setScreenWidthAndHeight(width(), height());
  The same applies to sceneCenter() and sceneRadius(), if needed.

## § orientation()

Quaternion orientation | ( |  | ) | const

Returns the Camera orientation, defined in the world coordinate system.

Actually returns `frame()->orientation()`. Use setOrientation(), setUpVector() or lookAt() to set the Camera orientation.

## § physicalDistanceToScreen()

qreal physicalDistanceToScreen | ( |  | ) | const

Returns the physical distance between the user's eyes and the screen (in meters).

physicalDistanceToScreen() and focusDistance() represent the same distance. The former is expressed in physical real world units, while the latter is expressed in OpenGL virtual world units.

This is a helper function. It simply returns physicalScreenWidth() / 2.0 / tan(horizontalFieldOfView() / 2.0);

## § physicalScreenWidth()

qreal physicalScreenWidth | ( |  | ) | const

Returns the physical screen width, in meters. Default value is 0.5m (average monitor width).

Used for stereo display only (see loadModelViewMatrixStereo() and loadProjectionMatrixStereo()). Set using setPhysicalScreenWidth().

## § pivotPoint()

Vec pivotPoint | ( |  | ) | const

The point the Camera pivots around with the ROTATE mouse binding. Defined in world coordinate system.

Default value is the sceneCenter().

Attention
  setSceneCenter() changes this value.

## § pixelGLRatio()

qreal pixelGLRatio | ( | const Vec & | position | ) | const

Returns the ratio between pixel and OpenGL units at `position`.

A line of `n` * pixelGLRatio() OpenGL units, located at `position` in the world coordinates system, will be projected with a length of `n` pixels on screen.

Use this method to scale objects so that they have a constant pixel size on screen. The following code will draw a 20 pixel line, starting at sceneCenter() and always directed along the screen vertical direction:

glBegin(GL_LINES);
glVertex3fv(sceneCenter());
glVertex3fv(sceneCenter() + 20 * pixelGLRatio(sceneCenter()) * camera()->upVector());
glEnd();

## § playPath

void playPath | ( | unsigned int | i | ) |
| virtual slot

Makes the Camera follow the path of keyFrameInterpolator() number `i`.

If the interpolation is started, it stops it instead.

This method silently ignores undefined (empty) paths (see keyFrameInterpolator()).

The default keyboard shortcut for this method is F[1-12]. Set QGLViewer::pathKey() and QGLViewer::playPathKeyboardModifiers().

## § pointUnderPixel()

Vec pointUnderPixel | ( | const QPoint & | pixel,
|  | bool & | found
| ) |  | const

Returns the coordinates of the 3D point located at pixel (x,y) on screen.

Calls a `glReadPixel` to get the pixel depth and applies an unprojectedCoordinatesOf() to the result. `found` indicates whether a point was found or not (i.e. background pixel, result's depth is zFar() in that case).

`x` and `y` are expressed in pixel units with an origin in the upper left corner. Use screenHeight() - y to convert to OpenGL standard.

Attention
  This method assumes that a GL context is available, and that its content was drawn using the Camera (i.e. using its projection and modelview matrices). This method hence cannot be used for offscreen Camera computations. Use cameraCoordinatesOf() and worldCoordinatesOf() to perform similar operations in that case.

Note
  The precision of the z-Buffer highly depends on how the zNear() and zFar() values are fitted to your scene. Loose boundaries will result in imprecision along the viewing direction.

## § position()

Vec position | ( |  | ) | const

Returns the Camera position (the eye), defined in the world coordinate system.

Use setPosition() to set the Camera position. Other convenient methods are showEntireScene() or fitSphere(). Actually returns `frame()->position()`.

This position corresponds to the projection center of a Camera::PERSPECTIVE Camera. It is not located in the image plane, which is at a zNear() distance ahead.

## § projectedCoordinatesOf()

Vec projectedCoordinatesOf | ( | const Vec & | src,
|  | const Frame * | frame = `NULL`
| ) |  | const

Returns the screen projected coordinates of a point `src` defined in the `frame` coordinate system.

When `frame` in `NULL` (default), `src` is expressed in the world coordinate system.

The x and y coordinates of the returned Vec are expressed in pixel, (0,0) being the upper left corner of the window. The z coordinate ranges between 0.0 (near plane) and 1.0 (excluded, far plane). See the `gluProject` man page for details.

unprojectedCoordinatesOf() performs the inverse transformation.

See the screenCoordSystem example.

This method only uses the intrinsic Camera parameters (see getModelViewMatrix(), getProjectionMatrix() and getViewport()) and is completely independent of the OpenGL `GL_MODELVIEW`, `GL_PROJECTION` and viewport matrices. You can hence define a virtual Camera and use this method to compute projections out of a classical rendering context.

Attention
  However, if your Camera is not attached to a QGLViewer (used for offscreen computations for instance), make sure the Camera matrices are updated before calling this method. Call computeModelViewMatrix() and computeProjectionMatrix() to do so.

If you call this method several times with no change in the matrices, consider precomputing the projection times modelview matrix to save computation time if required (`P` x `M` in the `gluProject` man page).

Here is the code corresponding to what this method does (kindly submitted by Robert W. Kuhn) :

Vec project(Vec point)
{
GLint Viewport[4];
GLdouble Projection[16], Modelview[16];
GLdouble matrix[16];
// Precomputation begin
glGetIntegerv(GL_VIEWPORT , Viewport);
glGetDoublev (GL_MODELVIEW_MATRIX , Modelview);
glGetDoublev (GL_PROJECTION_MATRIX, Projection);
for (unsigned short m=0; m<4; ++m)
{
for (unsigned short l=0; l<4; ++l)
{
qreal sum = 0.0;
for (unsigned short k=0; k<4; ++k)
sum += Projection[l+4*k]*Modelview[k+4*m];
matrix[l+4*m] = sum;
}
}
// Precomputation end
GLdouble v[4], vs[4];
v[0]=point[0]; v[1]=point[1]; v[2]=point[2]; v[3]=1.0;
vs[0]=matrix[0 ]*v[0] + matrix[4 ]*v[1] + matrix[8 ]*v[2] + matrix[12 ]*v[3];
vs[1]=matrix[1 ]*v[0] + matrix[5 ]*v[1] + matrix[9 ]*v[2] + matrix[13 ]*v[3];
vs[2]=matrix[2 ]*v[0] + matrix[6 ]*v[1] + matrix[10]*v[2] + matrix[14 ]*v[3];
vs[3]=matrix[3 ]*v[0] + matrix[7 ]*v[1] + matrix[11]*v[2] + matrix[15 ]*v[3];
vs[0] /= vs[3];
vs[1] /= vs[3];
vs[2] /= vs[3];
vs[0] = vs[0] * 0.5 + 0.5;
vs[1] = vs[1] * 0.5 + 0.5;
vs[2] = vs[2] * 0.5 + 0.5;
vs[0] = vs[0] * Viewport[2] + Viewport[0];
vs[1] = vs[1] * Viewport[3] + Viewport[1];
return Vec(vs[0], Viewport[3]-vs[1], vs[2]);
}

## § resetPath

void resetPath | ( | unsigned int | i | ) |
| virtual slot

Resets the path of the keyFrameInterpolator() number `i`.

If this path is not being played (see playPath() and KeyFrameInterpolator::interpolationIsStarted()), resets it to its starting position (see KeyFrameInterpolator::resetInterpolation()). If the path is played, simply stops interpolation.

## § rightVector()

Vec rightVector | ( |  | ) | const

Returns the normalized right vector of the Camera, defined in the world coordinate system.

This vector lies in the Camera horizontal plane, directed along the X axis (orthogonal to upVector() and to viewDirection()). Set using setUpVector(), lookAt() or setOrientation().

Simply returns frame()->inverseTransformOf(Vec(1.0, 0.0, 0.0)).

## § sceneCenter()

Vec sceneCenter | ( |  | ) | const

Returns the position of the scene center, defined in the world coordinate system.

The scene observed by the Camera should be roughly centered on this position, and included in a sceneRadius() sphere. This approximate description of the scene permits a zNear() and zFar() clipping planes definition, and allows convenient positioning methods such as showEntireScene().

Default value is (0,0,0) (world origin). Use setSceneCenter() to change it. See also setSceneBoundingBox().

Note that QGLViewer::sceneCenter() (resp. QGLViewer::setSceneCenter()) simply calls this method (resp. setSceneCenter()) on its associated QGLViewer::camera().

## § sceneRadius()

qreal sceneRadius | ( |  | ) | const

Returns the radius of the scene observed by the Camera.

You need to provide such an approximation of the scene dimensions so that the Camera can adapt its zNear() and zFar() values. See the sceneCenter() documentation.

See also setSceneBoundingBox().

Note that QGLViewer::sceneRadius() (resp. QGLViewer::setSceneRadius()) simply call this method (resp. setSceneRadius()) on its associated QGLViewer::camera().

## § screenHeight()

int screenHeight | ( |  | ) | const

Returns the height (in pixels) of the Camera screen.

Set using setScreenWidthAndHeight(). This value is automatically fitted to the QGLViewer's window dimensions when the Camera is attached to a QGLViewer. See also QGLWidget::height()

## § screenWidth()

int screenWidth | ( |  | ) | const

Returns the width (in pixels) of the Camera screen.

Set using setScreenWidthAndHeight(). This value is automatically fitted to the QGLViewer's window dimensions when the Camera is attached to a QGLViewer. See also QGLWidget::width()

## § setAspectRatio

void setAspectRatio | ( | qreal | aspect | ) |
| slot

Defines the Camera aspectRatio().

This value is actually inferred from the screenWidth() / screenHeight() ratio. You should use setScreenWidthAndHeight() instead.

This method might however be convenient when the Camera is not associated with a QGLViewer. It actually sets the screenHeight() to 100 and the screenWidth() accordingly. See also setFOVToFitScene().

Note
  If you absolutely need an aspectRatio() that does not correspond to your viewer's window dimensions, overload loadProjectionMatrix() or multiply the created GL_PROJECTION matrix by a scaled diagonal matrix in your QGLViewer::draw() method.

## § setFieldOfView

void setFieldOfView | ( | qreal | fov | ) |
| slot

Sets the vertical fieldOfView() of the Camera (in radians).

Note that focusDistance() is set to sceneRadius() / tan(fieldOfView()/2) by this method.

## § setFlySpeed

void setFlySpeed | ( | qreal | speed | ) |
| slot

Sets the Camera flySpeed().

Attention
  This value is modified by setSceneRadius().

## § setFocusDistance

void setFocusDistance | ( | qreal | distance | ) |
| slot

Sets the focusDistance(), in OpenGL scene units.

## § setFOVToFitScene

void setFOVToFitScene | ( |  | ) |
| slot

Changes the Camera fieldOfView() so that the entire scene (defined by QGLViewer::sceneCenter() and QGLViewer::sceneRadius()) is visible from the Camera position().

The position() and orientation() of the Camera are not modified and you first have to orientate the Camera in order to actually see the scene (see lookAt(), showEntireScene() or fitSphere()).

This method is especially useful for shadow maps computation. Use the Camera positioning tools (setPosition(), lookAt()) to position a Camera at the light position. Then use this method to define the fieldOfView() so that the shadow map resolution is optimally used:

// The light camera needs size hints in order to optimize its fieldOfView
lightCamera->setSceneRadius(sceneRadius());
lightCamera->setSceneCenter(sceneCenter());
// Place the light camera.
lightCamera->setPosition(lightFrame->position());
lightCamera->lookAt(sceneCenter());
lightCamera->setFOVToFitScene();

See the (soon available) shadowMap contribution example for a practical implementation.

Attention
  The fieldOfView() is clamped to M_PI/2.0. This happens when the Camera is at a distance lower than sqrt(2.0) * sceneRadius() from the sceneCenter(). It optimizes the shadow map resolution, although it may miss some parts of the scene.

## § setFrame

void setFrame | ( | ManipulatedCameraFrame *const | mcf | ) |
| slot

Sets the Camera frame().

If you want to move the Camera, use setPosition() and setOrientation() or one of the Camera positioning methods (lookAt(), fitSphere(), showEntireScene()...) instead.

If you want to save the Camera position(), there's no need to call this method either. Use addKeyFrameToPath() and playPath() instead.

This method is actually mainly useful if you derive the ManipulatedCameraFrame class and want to use an instance of your new class to move the Camera.

A `NULL` `mcf` pointer will silently be ignored. The calling method is responsible for deleting the previous frame() pointer if needed in order to prevent memory leaks.

## § setFromModelViewMatrix()

void setFromModelViewMatrix | ( | const GLdouble *const | modelViewMatrix | ) |

Sets the Camera's position() and orientation() from an OpenGL ModelView matrix.

This enables a Camera initialisation from an other OpenGL application. `modelView` is a 16 GLdouble vector representing a valid OpenGL ModelView matrix, such as one can get using:

GLdouble mvm[16];
glGetDoublev(GL_MODELVIEW_MATRIX, mvm);
myCamera->setFromModelViewMatrix(mvm);

After this method has been called, getModelViewMatrix() returns a matrix equivalent to `modelView`.

Only the orientation() and position() of the Camera are modified.

Note
  If you defined your matrix as `GLdouble` `mvm`[4][4], pass `&`(mvm[0][0]) as a parameter.

## § setFromProjectionMatrix()

void setFromProjectionMatrix | ( | const qreal | matrix[12] | ) |

Defines the Camera position(), orientation() and fieldOfView() from a projection matrix.

`matrix` has to be given in the format used by vision algorithm. It has 3 lines and 4 columns. It transforms a point from the world homogeneous coordinate system (4 coordinates: `sx`, `sy`, `sz` and `s`) into a point in the screen homogeneous coordinate system (3 coordinates: `sx`, `sy`, and `s`, where `x` and `y` are the pixel coordinates on the screen).

Its three lines correspond to the homogeneous coordinates of the normals to the planes x=0, y=0 and z=0, defined in the Camera coordinate system.

The elements of the matrix are ordered in line major order: you can call `setFromProjectionMatrix(&(matrix[0][0]))` if you defined your matrix as a `qreal` `matrix`[3][4].

Attention
  Passing the result of getProjectionMatrix() or getModelViewMatrix() to this method is not possible (purposefully incompatible matrix dimensions). `matrix` is more likely to be the product of these two matrices, without the last line.

Use setFromModelViewMatrix() to set position() and orientation() from a `GL_MODELVIEW` matrix. fieldOfView() can also be retrieved from a perspective `GL_PROJECTION` matrix using 2.0 * atan(1.0/projectionMatrix[5]).

This code was written by Sylvain Paris.

## § setHorizontalFieldOfView

void setHorizontalFieldOfView | ( | qreal | hfov | ) |
| slot

Sets the horizontalFieldOfView() of the Camera (in radians).

horizontalFieldOfView() and fieldOfView() are linked by the aspectRatio(). This method actually calls setFieldOfView(( 2.0 * atan (tan(hfov / 2.0) / aspectRatio()) )) so that a call to horizontalFieldOfView() returns the expected value.

## § setIODistance

void setIODistance | ( | qreal | distance | ) |
| slot

Sets the IODistance().

## § setKeyFrameInterpolator

void setKeyFrameInterpolator | ( | unsigned int | i,
|  | KeyFrameInterpolator *const | kfi
| ) |  |
| slot

Sets the KeyFrameInterpolator that defines the Camera path of index `i`.

The previous keyFrameInterpolator() is lost and should be deleted by the calling method if needed.

The KeyFrameInterpolator::interpolated() signal of `kfi` probably needs to be connected to the Camera's associated QGLViewer::update() slot, so that when the Camera position is interpolated using `kfi`, every interpolation step updates the display:

myViewer.camera()->deletePath(3);
myViewer.camera()->setKeyFrameInterpolator(3, myKeyFrameInterpolator);
connect(myKeyFrameInterpolator, SIGNAL(interpolated()), myViewer, SLOT(update());

Note
  These connections are done automatically when a Camera is attached to a QGLViewer, or when a new KeyFrameInterpolator is defined using the QGLViewer::addKeyFrameKeyboardModifiers() and QGLViewer::pathKey() (default is Alt+F[1-12]). See the keyboard page for details.

## § setOrientation [1/2]

void setOrientation | ( | const Quaternion & | q | ) |
| slot

Sets the Camera orientation(), defined in the world coordinate system.

## § setOrientation [2/2]

void setOrientation | ( | qreal | theta,
|  | qreal | phi
| ) |  |
| slot

Sets the orientation() of the Camera using polar coordinates.

`theta` rotates the Camera around its Y axis, and then `phi` rotates it around its X axis. The polar coordinates are defined in the world coordinates system: `theta` = `phi` = 0 means that the Camera is directed towards the world Z axis. Both angles are expressed in radians.

See also setUpVector(). The position() of the Camera is unchanged, you may want to call showEntireScene() after this method to move the Camera.

This method can be useful to create Quicktime VR panoramic sequences, see the QGLViewer::saveSnapshot() documentation for details.

## § setPhysicalScreenWidth

void setPhysicalScreenWidth | ( | qreal | width | ) |
| slot

Sets the physical screen (monitor or projected wall) width (in meters).

## § setPivotPoint

void setPivotPoint | ( | const Vec & | point | ) |
| slot

Changes the pivotPoint() to `point` (defined in the world coordinate system).

## § setPivotPointFromPixel

bool setPivotPointFromPixel | ( | const QPoint & | pixel | ) |
| slot

The pivotPoint() is set to the point located under `pixel` on screen.

Returns `true` if a pointUnderPixel() was found. If no point was found under `pixel`, the pivotPoint() is left unchanged.

`pixel` is expressed in Qt format (origin in the upper left corner of the window). See pointUnderPixel().

See also setSceneCenterFromPixel().

## § setPosition

void setPosition | ( | const Vec & | pos | ) |
| slot

Sets the Camera position() (the eye), defined in the world coordinate system.

## § setSceneBoundingBox

void setSceneBoundingBox | ( | const Vec & | min,
|  | const Vec & | max
| ) |  |
| slot

Similar to setSceneRadius() and setSceneCenter(), but the scene limits are defined by a (world axis aligned) bounding box.

## § setSceneCenter

void setSceneCenter | ( | const Vec & | center | ) |
| slot

Sets the sceneCenter().

Attention
  This method also sets the pivotPoint() to sceneCenter().

## § setSceneCenterFromPixel

bool setSceneCenterFromPixel | ( | const QPoint & | pixel | ) |
| slot

setSceneCenter() to the result of pointUnderPixel(`pixel`).

Returns `true` if a pointUnderPixel() was found and sceneCenter() was actually changed.

See also setPivotPointFromPixel(). See the pointUnderPixel() documentation.

## § setSceneRadius

void setSceneRadius | ( | qreal | radius | ) |
| slot

Sets the sceneRadius() value. Negative values are ignored.

Attention
  This methods also sets focusDistance() to sceneRadius() / tan(fieldOfView()/2) and flySpeed() to 1% of sceneRadius().

## § setScreenWidthAndHeight

void setScreenWidthAndHeight | ( | int | width,
|  | int | height
| ) |  |
| slot

Sets Camera screenWidth() and screenHeight() (expressed in pixels).

You should not call this method when the Camera is associated with a QGLViewer, since the latter automatically updates these values when it is resized (hence overwritting your values).

Non-positive dimension are silently replaced by a 1 pixel value to ensure frustrum coherence.

If your Camera is used without a QGLViewer (offscreen rendering, shadow maps), use setAspectRatio() instead to define the projection matrix.

## § setType

void setType | ( | Type | type | ) |
| slot

Defines the Camera type().

Changing the camera Type alters the viewport and the objects' sizes can be changed. This method garantees that the two frustum match in a plane normal to viewDirection(), passing through the pivotPoint().

Prefix the type with `Camera` if needed, as in:

camera()->setType(Camera::ORTHOGRAPHIC);
// or even qglviewer::Camera::ORTHOGRAPHIC if you do not use namespace

## § setUpVector

void setUpVector | ( | const Vec & | up,
|  | bool | noMove = `true`
| ) |  |
| slot

Rotates the Camera so that its upVector() becomes `up` (defined in the world coordinate system).

The Camera is rotated around an axis orthogonal to `up` and to the current upVector() direction. Use this method in order to define the Camera horizontal plane.

When `noMove` is set to `false`, the orientation modification is compensated by a translation, so that the pivotPoint() stays projected at the same position on screen. This is especially useful when the Camera is used as an observer of the scene (default mouse binding).

When `noMove` is `true` (default), the Camera position() is left unchanged, which is an intuitive behavior when the Camera is in a walkthrough fly mode (see the MOVE_FORWARD and MOVE_BACKWARD QGLViewer::MouseAction).

The frame()'s ManipulatedCameraFrame::sceneUpVector() is set accordingly.

See also setViewDirection(), lookAt() and setOrientation().

## § setViewDirection

void setViewDirection | ( | const Vec & | direction | ) |
| slot

Rotates the Camera so that its viewDirection() is `direction` (defined in the world coordinate system).

The Camera position() is not modified. The Camera is rotated so that the horizon (defined by its upVector()) is preserved. See also lookAt() and setUpVector().

## § setZClippingCoefficient

void setZClippingCoefficient | ( | qreal | coef | ) |
| slot

Sets the zClippingCoefficient() value.

## § setZNearCoefficient

void setZNearCoefficient | ( | qreal | coef | ) |
| slot

Sets the zNearCoefficient() value.

## § showEntireScene

void showEntireScene | ( |  | ) |
| slot

Moves the Camera so that the entire scene is visible.

Simply calls fitSphere() on a sphere defined by sceneCenter() and sceneRadius().

You will typically use this method in QGLViewer::init() after you defined a new sceneRadius().

## § type()

Type type | ( |  | ) | const

Returns the Camera::Type of the Camera.

Set by setType(). Mainly used by loadProjectionMatrix().

A Camera::PERSPECTIVE Camera uses a classical projection mainly defined by its fieldOfView().

With a Camera::ORTHOGRAPHIC type(), the fieldOfView() is meaningless and the width and height of the Camera frustum are inferred from the distance to the pivotPoint() using getOrthoWidthHeight().

Both types use zNear() and zFar() (to define their clipping planes) and aspectRatio() (for frustum shape).

## § unprojectedCoordinatesOf()

Vec unprojectedCoordinatesOf | ( | const Vec & | src,
|  | const Frame * | frame = `NULL`
| ) |  | const

Returns the world unprojected coordinates of a point `src` defined in the screen coordinate system.

The `src.x` and `src.y` input values are expressed in pixels, (0,0) being the upper left corner of the window. `src.z` is a depth value ranging in [0..1[ (respectively corresponding to the near and far planes). Note that src.z is not a linear interpolation between zNear and zFar. /code src.z = zFar() / (zFar() - zNear()) * (1.0 - zNear() / z); /endcode Where z is the distance from the point you project to the camera, along the viewDirection(). See the `gluUnProject` man page for details.

The result is expressed in the `frame` coordinate system. When `frame` is `NULL` (default), the result is expressed in the world coordinates system. The possible `frame` Frame::referenceFrame() are taken into account.

projectedCoordinatesOf() performs the inverse transformation.

This method only uses the intrinsic Camera parameters (see getModelViewMatrix(), getProjectionMatrix() and getViewport()) and is completely independent of the OpenGL `GL_MODELVIEW`, `GL_PROJECTION` and viewport matrices. You can hence define a virtual Camera and use this method to compute un-projections out of a classical rendering context.

Attention
  However, if your Camera is not attached to a QGLViewer (used for offscreen computations for instance), make sure the Camera matrices are updated before calling this method (use computeModelViewMatrix(), computeProjectionMatrix()). See also setScreenWidthAndHeight().

This method is not computationally optimized. If you call it several times with no change in the matrices, you should buffer the entire inverse projection matrix (modelview, projection and then viewport) to speed-up the queries. See the `gluUnProject` man page for details.

## § upVector()

Vec upVector | ( |  | ) | const

Returns the normalized up vector of the Camera, defined in the world coordinate system.

Set using setUpVector() or setOrientation(). It is orthogonal to viewDirection() and to rightVector().

It corresponds to the Y axis of the associated frame() (actually returns frame()->inverseTransformOf(Vec(0.0, 1.0, 0.0)) ).

## § viewDirection()

Vec viewDirection | ( |  | ) | const

Returns the normalized view direction of the Camera, defined in the world coordinate system.

Change this value using setViewDirection(), lookAt() or setOrientation(). It is orthogonal to upVector() and to rightVector().

This corresponds to the negative Z axis of the frame() ( frame()->inverseTransformOf(Vec(0.0, 0.0, -1.0)) ).

## § worldCoordinatesOf()

Vec worldCoordinatesOf | ( | const Vec & | src | ) | const

Returns the world coordinates of the point whose position `src` is defined in the Camera coordinate system.

cameraCoordinatesOf() performs the inverse transformation.

## § zClippingCoefficient()

qreal zClippingCoefficient | ( |  | ) | const

Returns the coefficient used to position the near and far clipping planes.

The near (resp. far) clipping plane is positioned at a distance equal to zClippingCoefficient() * sceneRadius() in front of (resp. behind) the sceneCenter(). This garantees an optimal use of the z-buffer range and minimizes aliasing. See the zNear() and zFar() documentations.

Default value is square root of 3.0 (so that a cube of size sceneRadius() is not clipped).

However, since the sceneRadius() is used for other purposes (see showEntireScene(), flySpeed(), ...) and you may want to change this value to define more precisely the location of the clipping planes. See also zNearCoefficient().

For a total control on clipping planes' positions, an other option is to overload the zNear() and zFar() methods. See the standardCamera example.

Attention
  When QGLViewer::cameraPathAreEdited(), this value is set to 5.0 so that the Camera paths are not clipped. The previous zClippingCoefficient() value is restored back when you leave this mode.

## § zFar()

qreal zFar | ( |  | ) | const
| virtual

Returns the far clipping plane distance used by the Camera projection matrix.

The far clipping plane is positioned at a distance equal to zClippingCoefficient() * sceneRadius() behind the sceneCenter():

zFar = distanceToSceneCenter() + zClippingCoefficient()*sceneRadius();

See the zNear() documentation for details.

## § zNear()

qreal zNear | ( |  | ) | const
| virtual

Returns the near clipping plane distance used by the Camera projection matrix.

The clipping planes' positions depend on the sceneRadius() and sceneCenter() rather than being fixed small-enough and large-enough values. A good scene dimension approximation will hence result in an optimal precision of the z-buffer.

The near clipping plane is positioned at a distance equal to zClippingCoefficient() * sceneRadius() in front of the sceneCenter():

zNear = distanceToSceneCenter() - zClippingCoefficient()*sceneRadius();

In order to prevent negative or too small zNear() values (which would degrade the z precision), zNearCoefficient() is used when the Camera is inside the sceneRadius() sphere:

const qreal zMin = zNearCoefficient() * zClippingCoefficient() * sceneRadius();
if (zNear < zMin)
zNear = zMin;
// With an ORTHOGRAPHIC type, the value is simply clamped to 0.0

See also the zFar(), zClippingCoefficient() and zNearCoefficient() documentations.

If you need a completely different zNear computation, overload the zNear() and zFar() methods in a new class that publicly inherits from Camera and use QGLViewer::setCamera():

class myCamera :: public qglviewer::Camera
{
virtual qreal Camera::zNear() const { return 0.001; };
virtual qreal Camera::zFar() const { return 100.0; };
}

See the standardCamera example for an application.

Attention
  The value is always positive although the clipping plane is positioned at a negative z value in the Camera coordinate system. This follows the `gluPerspective` standard.

## § zNearCoefficient()

qreal zNearCoefficient | ( |  | ) | const

Returns the coefficient which is used to set zNear() when the Camera is inside the sphere defined by sceneCenter() and zClippingCoefficient() * sceneRadius().

In that case, the zNear() value is set to zNearCoefficient() * zClippingCoefficient() * sceneRadius(). See the zNear() documentation for details.

Default value is 0.005, which is appropriate for most applications. In case you need a high dynamic ZBuffer precision, you can increase this value (~0.1). A lower value will prevent clipping of very close objects at the expense of a worst Z precision.

Only meaningful when Camera type is Camera::PERSPECTIVE.