Support Forum       Library Source       SourceForge Page       G3D Web Page     
Classes | Public Types | Public Member Functions

G3D::GCamera Class Reference

Abstraction of a lens or pinhole camera. More...

List of all members.

Classes

class  Frustum

Public Types

enum  FOVDirection {
  HORIZONTAL,
  VERTICAL
}
 

Stores the direction of the field of view.

More...

Public Member Functions

 GCamera (const Any &any)
 Must be of the format produced by the Any cast, e.g.,.
 GCamera (const Matrix4 &proj, const CFrame &frame)
 GCamera ()
virtual ~GCamera ()
float circleOfConfusionRadius (float z, const class Rect2D &viewport) const
 Circle of confusion radius, in pixels, for a point at negative position z from the center of projection along the camera-space z axis.
Point3 convertFromUnitToNormal (const Point3 &in, const Rect2D &viewport) const
 Converts projected points from OpenGL standards (-1, 1) to normal 3D coordinate standards (0, 1)
const CoordinateFramecoordinateFrame () const
 Returns the current coordinate frame.
void deserialize (class BinaryInput &bi)
float exposureTime () const
 Time from "shutter open" to "shutter close".
float farPlaneZ () const
 Returns a negative z-value.
float focusPlaneZ () const
void frustum (const Rect2D &viewport, GCamera::Frustum &f) const
 Returns the world space view frustum, which is a truncated pyramid describing the volume of space seen by this camera.
GCamera::Frustum frustum (const Rect2D &viewport) const
void getClipPlanes (const Rect2D &viewport, Array< Plane > &outClip) const
 Returns the clipping planes of the frustum, in world space.
void getCoordinateFrame (CoordinateFrame &c) const
 Sets c to the camera's coordinate frame.
void getFarViewportCorners (const class Rect2D &viewport, Point3 &outUR, Point3 &outUL, Point3 &outLL, Point3 &outLR) const
 Returns the world space 3D viewport corners under pinhole projection.
void getFieldOfView (float &angle, FOVDirection &direction) const
 Returns the current full field of view angle (from the left side of the viewport to the right side) and direction.
void getNearViewportCorners (const class Rect2D &viewport, Point3 &outUR, Point3 &outUL, Point3 &outLL, Point3 &outLR) const
 Returns the world space 3D viewport corners under pinhole projection.
void getProjectPixelMatrix (const Rect2D &viewport, Matrix4 &P) const
 Sets P equal to the matrix that transforms points to pixel coordinates on the given viewport.
void getProjectUnitMatrix (const Rect2D &viewport, Matrix4 &P) const
 Sets P equal to the camera's projection matrix.
float imagePlanePixelsPerMeter (const class Rect2D &viewport) const
 The number of pixels per meter at z=-1 for the given viewport.
float lensRadius () const
void lookAt (const Point3 &position, const Vector3 &up=Vector3::unitY())
 Rotate the camera in place to look at the target.
float nearPlaneViewportHeight (const class Rect2D &viewport) const
 Returns the camera space height of the viewport in meters at the near plane.
float nearPlaneViewportWidth (const class Rect2D &viewport) const
 Returns the camera space width in meters of the viewport at the near plane.
float nearPlaneZ () const
 Returns a negative z-value.
const Vector2pixelOffset () const
Point3 project (const Point3 &point, const class Rect2D &viewport) const
 Pinhole projects a world space point onto a width x height screen.
Point3 projectUnit (const Point3 &point, const class Rect2D &viewport) const
 Pinhole projects a world space point onto a unit cube.
void serialize (class BinaryOutput &bo) const
 Read and Write camera parameters.
void setCoordinateFrame (const CoordinateFrame &c)
 Sets a new coordinate frame for the camera.
void setExposureTime (float t)
void setFarPlaneZ (float z)
 Sets a new value for the far clipping plane Expects a negative value.
void setFieldOfView (float edgeToEdgeAngleRadians, FOVDirection direction)
 Sets the field of view, in radians.
void setFocusPlaneZ (float z)
 Plane that is in focus under a lens camera.
void setLensRadius (float r)
void setNearPlaneZ (float z)
 Sets a new value for the near clipping plane Expects a negative value.
void setPixelOffset (const Vector2 &p)
 Displacement from the upper left added in pixels in screen space to the projection matrix.
void setPosition (const Point3 &t)
Any toAny () const
Point3 unproject (const Point3 &v, const Rect2D &viewport) const
 Gives the world-space coordinates of screen space point v, where v.x is in pixels from the left, v.y is in pixels from the top, and v.z is on the range 0 (near plane) to 1 (far plane).
Point3 unprojectUnit (const Point3 &v, const Rect2D &viewport) const
 Gives the world-space coordinates of unit cube point v, where v varies from -1 to 1 on all axes.
Ray worldRay (float x, float y, float u, float v, const class Rect2D &viewport) const
 World space ray from a lens camera.
Ray worldRay (float x, float y, const class Rect2D &viewport) const
 Returns the world space ray passing through the center of pixel (x, y) on the image plane under pinhole projection.
float worldToScreenSpaceArea (float area, float z, const class Rect2D &viewport) const
 Returns the pixel area covered by a shape of the given world space area at the given z value (z must be negative) under pinhole projection.

Detailed Description

Abstraction of a lens or pinhole camera.

The area a camera sees is called a frustum. It is bounded by the near plane, the far plane, and the sides of the view frame projected into the scene. It has the shape of a pyramid with the top cut off.

Cameras can project points from 3D to 2D. The "unit" projection matches OpenGL. It maps the entire view frustum to a cube of unit radius (i.e., edges of length 2) centered at the origin. The non-unit projection then maps that cube to the specified pixel viewport in X and Y and the range [0, 1] in Z. The projection is reversable as long as the projected Z value is known.

All viewport arguments are the pixel bounds of the viewport-- e.g., RenderDevice::viewport().

See http://bittermanandy.wordpress.com/2009/04/10/a-view-to-a-thrill-part-one-camera-concepts/ for a nice introduction to camera transformations.


Member Enumeration Documentation

Stores the direction of the field of view.

Enumerator:
HORIZONTAL 
VERTICAL 

Constructor & Destructor Documentation

G3D::GCamera::GCamera ( const Any any )

Must be of the format produced by the Any cast, e.g.,.

        GCamera {
            coordinateFrame = CFrame::fromXYZYPRDegrees(-13.3f, 8.0f, -1.9f, 246.6f, -3),
            nearPlaneZ = -0.5,
            farPlaneZ = -50,
            fovDirection = "HORIZONTAL",
            fovAngleDegrees = 90
        }

Missing fields are filled from the default GCamera constructor.

G3D::GCamera::GCamera (  )
G3D::GCamera::GCamera ( const Matrix4 proj,
const CFrame frame 
)
virtual G3D::GCamera::~GCamera (  ) [virtual]

Member Function Documentation

float G3D::GCamera::circleOfConfusionRadius ( float  z,
const class Rect2D viewport 
) const

Circle of confusion radius, in pixels, for a point at negative position z from the center of projection along the camera-space z axis.

Point3 G3D::GCamera::convertFromUnitToNormal ( const Point3 in,
const Rect2D viewport 
) const

Converts projected points from OpenGL standards (-1, 1) to normal 3D coordinate standards (0, 1)

Deprecated:
const CoordinateFrame& G3D::GCamera::coordinateFrame (  ) const [inline]

Returns the current coordinate frame.

void G3D::GCamera::deserialize ( class BinaryInput bi )
float G3D::GCamera::exposureTime (  ) const [inline]

Time from "shutter open" to "shutter close".

This is often 0 for traditional real-time rendering. Larger numbers are useful for capturing motion blur in more sophisticated rendering systems.

In a real camera, a longer exposure also makes the image brighter. In rendering, it is useful to control the global image intensity separately from the amount of motion blur, so this interval may not affect image intensity under your renderer.

float G3D::GCamera::farPlaneZ (  ) const [inline]

Returns a negative z-value.

float G3D::GCamera::focusPlaneZ (  ) const [inline]
void G3D::GCamera::frustum ( const Rect2D viewport,
GCamera::Frustum f 
) const

Returns the world space view frustum, which is a truncated pyramid describing the volume of space seen by this camera.

GCamera::Frustum G3D::GCamera::frustum ( const Rect2D viewport ) const
void G3D::GCamera::getClipPlanes ( const Rect2D viewport,
Array< Plane > &  outClip 
) const

Returns the clipping planes of the frustum, in world space.

The planes have normals facing into the view frustum.

The plane order is guaranteed to be: Near, Right, Left, Top, Bottom, [Far]

If the far plane is at infinity, the resulting array will have 5 planes, otherwise there will be 6.

The viewport is used only to determine the aspect ratio of the screen; the absolute dimensions and xy values don't matter.

void G3D::GCamera::getCoordinateFrame ( CoordinateFrame c ) const

Sets c to the camera's coordinate frame.

void G3D::GCamera::getFarViewportCorners ( const class Rect2D viewport,
Point3 outUR,
Point3 outUL,
Point3 outLL,
Point3 outLR 
) const

Returns the world space 3D viewport corners under pinhole projection.

These are at the Far clipping plane. The corners are constructed from the nearPlaneZ, farPlaneZ, viewportWidth, and viewportHeight. "left" and "right" are from the GCamera's perspective.

void G3D::GCamera::getFieldOfView ( float &  angle,
FOVDirection direction 
) const [inline]

Returns the current full field of view angle (from the left side of the viewport to the right side) and direction.

void G3D::GCamera::getNearViewportCorners ( const class Rect2D viewport,
Point3 outUR,
Point3 outUL,
Point3 outLL,
Point3 outLR 
) const

Returns the world space 3D viewport corners under pinhole projection.

These are at the near clipping plane. The corners are constructed from the nearPlaneZ, viewportWidth, and viewportHeight. "left" and "right" are from the GCamera's perspective.

void G3D::GCamera::getProjectPixelMatrix ( const Rect2D viewport,
Matrix4 P 
) const

Sets P equal to the matrix that transforms points to pixel coordinates on the given viewport.

A point correspoinding to the top-left corner of the viewport in camera space will transform to viewport.x0y0() and the bottom-right to viewport.x1y1().

void G3D::GCamera::getProjectUnitMatrix ( const Rect2D viewport,
Matrix4 P 
) const

Sets P equal to the camera's projection matrix.

This is the matrix that maps points to the homogeneous clip cube that varies from -1 to 1 on all axes. The projection matrix does not include the camera transform.

For rendering direct to an OSWindow (vs. rendering to Texture/Framebuffer), multiply this matrix by Matrix4::scale(1, -1, 1).

This is the matrix that a RenderDevice (or OpenGL) uses as the projection matrix.

See also:
RenderDevice::setProjectionAndCameraMatrix, RenderDevice::setProjectionMatrix, Matrix4::perspectiveProjection, gluPerspective
float G3D::GCamera::imagePlanePixelsPerMeter ( const class Rect2D viewport ) const

The number of pixels per meter at z=-1 for the given viewport.

This is useful for performing explicit projections and for transforming world-space values like circle of confusion into screen space.

float G3D::GCamera::lensRadius (  ) const [inline]
void G3D::GCamera::lookAt ( const Point3 position,
const Vector3 up = Vector3::unitY() 
)

Rotate the camera in place to look at the target.

Does not persistently look at that location when the camera moves; i.e., if you move the camera and still want it to look at the old target, you must call lookAt again after moving the camera.)

float G3D::GCamera::nearPlaneViewportHeight ( const class Rect2D viewport ) const

Returns the camera space height of the viewport in meters at the near plane.

float G3D::GCamera::nearPlaneViewportWidth ( const class Rect2D viewport ) const

Returns the camera space width in meters of the viewport at the near plane.

float G3D::GCamera::nearPlaneZ (  ) const [inline]

Returns a negative z-value.

const Vector2& G3D::GCamera::pixelOffset (  ) const [inline]
Point3 G3D::GCamera::project ( const Point3 point,
const class Rect2D viewport 
) const

Pinhole projects a world space point onto a width x height screen.

The returned coordinate uses pixmap addressing: x = right and y = down. The resulting z value is 0 at the near plane, 1 at the far plane, and is a linear compression of unit cube projection.

If the point is behind the camera, Point3::inf() is returned.

See also:
RenderDevice::invertY
Point3 G3D::GCamera::projectUnit ( const Point3 point,
const class Rect2D viewport 
) const

Pinhole projects a world space point onto a unit cube.

The resulting x,y,z values range between -1 and 1, where z is -1 at the near plane and 1 at the far plane and varies hyperbolically in between.

If the point is behind the camera, Point3::inf() is returned.

void G3D::GCamera::serialize ( class BinaryOutput bo ) const

Read and Write camera parameters.

void G3D::GCamera::setCoordinateFrame ( const CoordinateFrame c )

Sets a new coordinate frame for the camera.

void G3D::GCamera::setExposureTime ( float  t ) [inline]
void G3D::GCamera::setFarPlaneZ ( float  z ) [inline]

Sets a new value for the far clipping plane Expects a negative value.

void G3D::GCamera::setFieldOfView ( float  edgeToEdgeAngleRadians,
FOVDirection  direction 
)

Sets the field of view, in radians.

The initial angle is toRadians(55). Must specify the direction of the angle.

This is the full angle, i.e., from the left side of the viewport to the right side.

The field of view is specified for the pinhole version of the camera.

void G3D::GCamera::setFocusPlaneZ ( float  z ) [inline]

Plane that is in focus under a lens camera.

This is a negative number.

void G3D::GCamera::setLensRadius ( float  r ) [inline]
void G3D::GCamera::setNearPlaneZ ( float  z ) [inline]

Sets a new value for the near clipping plane Expects a negative value.

void G3D::GCamera::setPixelOffset ( const Vector2 p ) [inline]

Displacement from the upper left added in pixels in screen space to the projection matrix.

This is useful for shifting the sampled location from the pixel center (OpenGL convention) to other locations, such as the upper-left.

void G3D::GCamera::setPosition ( const Point3 t )
Any G3D::GCamera::toAny (  ) const
Point3 G3D::GCamera::unproject ( const Point3 v,
const Rect2D viewport 
) const

Gives the world-space coordinates of screen space point v, where v.x is in pixels from the left, v.y is in pixels from the top, and v.z is on the range 0 (near plane) to 1 (far plane).

Point3 G3D::GCamera::unprojectUnit ( const Point3 v,
const Rect2D viewport 
) const

Gives the world-space coordinates of unit cube point v, where v varies from -1 to 1 on all axes.

The unproject first transforms the point into a pixel location for the viewport, then calls unproject

Ray G3D::GCamera::worldRay ( float  x,
float  y,
const class Rect2D viewport 
) const

Returns the world space ray passing through the center of pixel (x, y) on the image plane under pinhole projection.

The pixel x and y axes are opposite the 3D object space axes: (0,0) is the upper left corner of the screen. They are in viewport coordinates, not screen coordinates.

The ray origin is at the camera-space origin, that is, in world space it is at GCamera::coordinateFrame().translation. To start it at the image plane, move it forward by imagePlaneDepth/ray.direction.z along the camera's look vector.

Integer (x, y) values correspond to the upper left corners of pixels. If you want to cast rays through pixel centers, add 0.5 to x and y.

Ray G3D::GCamera::worldRay ( float  x,
float  y,
float  u,
float  v,
const class Rect2D viewport 
) const

World space ray from a lens camera.

(u, v) are signed (-1, 1) that should lie within a unit-radius disc.

float G3D::GCamera::worldToScreenSpaceArea ( float  area,
float  z,
const class Rect2D viewport 
) const

Returns the pixel area covered by a shape of the given world space area at the given z value (z must be negative) under pinhole projection.

 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

documentation generated on Mon Nov 14 2011 10:39:17 using doxygen 1.7.2