class HT_Camera

class HT_Camera

Objects of this class specify the camera, which defines the way the 3D scene is projected to an image plane and framed in a field of view. The HT_Rendition class contains an HT_Camera member. For more information and an overview of the 3D transformation pipeline, see the sections, "Transformation Pipeline" and "Camera classes," in chapter 2, "Heidi Architecture."

Classes derived from HT_Camera are able to specify the camera parameters by various independent subsets.

Note: All angles are specified in radians unless otherwise stated.

See Also

HT_Camera_Obliquity, HT_Camera_Field,

Read-Only Access Methods

See HT_Camera parameters for synopses of these methods:

aspect_ratio

Returns a float giving the height-to-width ratio of the field of view.

distance

Returns a float that is the distance between the camera target and camera position.

eye_direction

Returns an HT_Vector indicating the vector from the camera position to the camera target.

field

Returns a structure, HT_Camera_Field, containing a pair of floats that specify the rectangle, in the view plane and centered on the origin, defining the view frustum¾ used to define the screen mapping.

horizontal_axis

Returns an HT_Vector representing one of the three basis vectors that form the camera coordinate system. The other two are viewing_axis and vertical_axis.

obliquity

Returns an HT_Camera_Obliquity containing the two
shear coefficients.

ortho_range, set_ortho_range

Returns a float giving the orthographic range. See the Details following this section.

position

Returns an HT_Point, where the camera is located.

projection

Returns an HT_Camera_Data::Projection¾either parallel or perspective.

projection_matrix

Returns the transformation matrix from viewing coordinates to normalized projection coordinates.

set_field

Sets the field of view for the camera.

set_obliquity

Sets the rotation of the viewing axis (Z axis) from the perpendicular to the image plane.

set_position

Sets the camera position.

set_projection

Sets the projection style, one of the enumerated values for parallel or perspective.

set_stretched

Controls whether the mapping between the field rectangle and the screen viewport is isotropic or anisotropic.

set_target

Sets the camera target.

set_up_vector

Defines the view-up direction.

set_wlimit

Sets the wlimit for perspective transformation. A wlimit of 0, corresponds to the camera position; a value of 1 corresponds to the view target. For more information, see the Details following this section.

stretched

Returns the value of the stretched flag, which indicates whether isotropic or anisotropic scaling is used to map the field rectangle into the viewport.

target

Returns the camera target, that is, the origin of the camera coordinate system.

up_vector

Returns the camera view-up direction vector.

viewing_axis

Returns one of the three basis vectors that form the camera coordinate system. The other two are up_vector and horizontal_axis.

viewing_matrix

Returns the transformation matrix from World Coordinates to viewing coordinates.

wlimit

Returns a float defining the w limit for perspective transformation. For more information, see the section Details¾Mapping into the Z Buffer following this section. Camera Control

dolly

Moves the camera left and right, up and down, or in and out. Basically both target and position are translated by the given vector.

orbit

Orbits the camera position around the object being looked at. The first parameter, x, is the angle, in radians, that the camera should sweep around the target to the right; the second parameter, y, to the top. These numbers can be negative.

pan

Rotates the camera across its current scene giving the effect of turning in place. The first parameter, x, is the angle, in radians, that the camera should rotate to the right; the second parameter, y, is the angle that the camera should tilt upwards. These numbers can be negative.

roll

Rotates the camera about the viewing axis.

zoom

Narrows or enlarges the viewing field of the camera. Constructor/Destructor

HT_Camera

Constructs an HT_Camera and initializes its defaults.

~HT_Camera

Destroys an HT_Camera object. Details ¾ Mapping into the Z Buffer The parameters wlimit and ortho_range control the mapping of the scene into the Z buffer. Perspective projections use wlimit and orthographic projections use ortho_range. Both parameters are specified with respect to a normalized coordinate system in which the view target has Z=0 and the camera position has Z=-1.

Orthographic projections linearly map the scene from ± ortho_range into the Z buffer. For example, ortho_range=4 will map the normalized range of Z values=(-4,4) to the Z buffer.

Perspective projections non linearly map the scene from normalized Z=(-1+wlimit) to Z=infinity. The mapping is given by Z`=Z/w. Since w=Z+1, this becomes Z`=Z/Z+1.

In figure 1, four intersecting values of Z are noted: Z=-1 (the camera position), Z=-1+wlimit (the fore clipping plane), Z=0 (the view target), and Z=infinity.

Figure 1. Four intersecting Z values
The mapping of Z to Z` is show in table 1. Table 1. Mapping of Z to Z`

Z	Z`
-1	-infinity
-1+wlimit	(-1+wlimit)/wlimit
0	0
infinity	1

For the default wlimit=0.05, Z`=-19. This maps the scene in normalized Z=(-0.95,infinity) to the Z buffer. Note that 95% of the Z Buffer is allocated to the range (-0.95,0). Increasing wlimit moves the fore clipping plane toward the view target, but allows more resolution in Z.

HT_Camera::(parameter)

Purpose

Query and set camera parameters. Synopsis

virtual float aspect_ratio (void) const

double aspect_ratio_d (void) const

virtual float distance (void) const

double distance_d (void) const

HT_Vector const & eye_direction (void) const

HT_Vector_D eye_direction_d (void) const

HT_Camera_Field const & field (void) const

HT_Camera_Field_D field_d (void) const

virtual HT_Vector const horizontal_axis (void) const

HT_Vector_D horizontal_axis_d (void) const

HT_Camera_Obliquity const & obliquity (void) const

HT_Camera_Obliquity_D obliquity_d (void)

float ortho_range(void) const

HT_Point const & position (void) const

HT_Point_D position_d (void) const

HT_Camera_Projection const & projection (void) const

HT_Matrix HT_Camera::projection_matrix (void) const

HT_Boolean stretched (void) const

HT_Point const & target (void) const

HT_Point_D target_d (void) const

HT_Vector const & up_vector (void) const

HT_Vector_D up_vector_d (void)

HT_Vector const & viewing_axis (void) const

HT_Vector_D viewing_axis_d (void) const

HT_Matrix HT_Camera::viewing_matrix (void) const

float wlimit (void) const

void set_field (HT_Camera_Field const & fld)

void  set_field (HT_Camera_Field_D const & fld)

void set_obliquity (HT_Camera_Obliquity const & obl)

void  set_obliquity (HT_Camera_Obliquity_D const & obl)

void set_ortho_range (float range) alter;

void set_position (HT_Point const & pos)

void  set_position (HT_Point_D const & pos)

void  set_projection (HT_Camera_Projection proj)

void set_stretched (HT_Boolean str)

void set_target (HT_Point const & tar)

void  set_target (HT_Point_D const & tar)

void set_up_vector (HT_Vector const & up)

void  set_up_vector (HT_Vector_D const & up)

void set_wlimit (float w)

Parameter Details aspect_ratio gives the ratio of height-to-width of the field of view.

distance gives the distance between camera target and camera position in World space units.

field.x and field.y give the dimensions of the view rectangle in World space units. The view rectangle is centered on target in the XY plane.

obliquity measures the amount that the Z axis is rotated from the perpendicular to the image plane. obliquity.x gives the rotation angle about the Y axis and obliquity.y the angle of rotation about the X axis.

position is the projection center in the case of perspective projection; the line joining position with target gives the projection direction in the case of parallel projection.

projection is one of the enumerated values perspective, parallel.

stretched indicates whether the mapping between the field rectangle and the screen viewport is isotropic (stretched == HK_False) or anisotropic (stretched == HK_True).

target is the center of the camera coordinate system, expressed with respect to World Coordinates. It lies on the image plane at the center of the view rectangle.

up is a vector whose projection on the image plane defines the view-up direction. The view-right direction is defined by the projection of a vector perpendicular to up and the view axis.

Note: Methods followed by an _d are double precision and are similar in functionality to the 32 bit versions¾for example aspect_ratio_d or obliquity_d.

For more information about cameras and viewing parameters, see the section "Camera Classes," in chapter 2, "Heidi Architecture."

HT_Camera::dolly

Purpose

One of a set of routines to manipulate the point of view, Dolly moves the camera left and right, up and down, or in and out. Synopsis

void dolly (HT_Vector const & d)

void  dolly (double x, double y, double z)

void dolly (float x, float y, float z)

void  dolly (HT_Vector_D const & d)

Details dolly moves the camera to the right, up, or in. The scene on the screen appears to move left, down, or in. The distances moved can be negative. The camera's target and position are moved a matching distance, and the field of view remains unchanged.

In the first form, the distance is specified as a vector. In the second form, each component is specified separately. Positive values move the camera right, up, and in.

For information about "walking around" an object that you are continuously looking at, see camera control, orbit. For information about looking in a different direction, without changing the camera position, see pan (in the same location). For information about "focusing in" on an object without changing the camera position, see zoom (also in the same location).

HT_Camera::HT_Camera

Purpose

Initialize a new camera object Synopsis

HT_Camera ()

HT_Camera (HT_Camera const & cam)

Details The first form HT_Camera() initializes the new camera object to the following default parameter set:

projection = perspective
stretched = false
target = (0, 0, 0)
position = (0,0,-5)
ortho_range = 4
wlimit = 0.05
horizontal = (1, 0, 0)
up_vector = (0, 1, 0)
eye = (0, 0, 1)
distance = 5
field = (2, 2)
obliquity = (0, 0)

The second form, HT_Camera (HT_Camera const & cam) ,makes the new camera object¾ initially a copy of cam.

HT_Camera::~HT_Camera

Purpose

Destroys a camera object Synopsis

~HT_Camera ()

Details The camera is deleted.

HT_Camera::orbit

Purpose

One of a set of routines that manipulate the point of view, orbit walks the camera position around the object being looked at. Synopsis

void orbit (float x, float y)

void orbit (double x, double y)

Details orbit creates the effect of circling around the camera target. The target does not move.

The x parameter specifies the angle, in radians, that the camera should "walk around" the target to the right. This value can be negative. The y parameter specifies the angle, in radians, that the camera should float up and over the target. This value can also be negative.

The second form is for double precision.

For information about moving the camera position and camera target by equal distances, see camera control, dolly. For information about looking in a different direction, but not changing the camera position,, see pan (in this class). For information about "focusing in" on an object without changing the camera position, see zoom (also in this class).

HT_Camera::pan

Purpose

One of a set of routines that manipulate the point of view, pan sweeps the camera across its current scene. Synopsis

void pan (float x, float y)

void  pan (double x, double y)

Details pan gives the effect of turning in place, that is with your view apparently moving from one side to the other across the scene in front of you. The target is moved, but the position is static.

The x parameter specifies the angle, in radians, that the camera should sweep to the right. This value can be negative (sweep to the left). The y parameter specifies the angle, in radians, that the camera tilts upward. This value can also be negative (downward).

The second form is for double precision.

For information about moving the camera position and camera target by equal angles, see camera control, dolly. For information about "walking around" an object that you are continuously looking at, see orbit (in this class). For information about "focusing in" on an object without changing the camera position, see zoom (also in this class)).

HT_Camera::roll

Purpose

One of a set of routines that manipulates the point of view, roll pinwheels (spins vertically) the user's point of view around the viewing axis. Synopsis

void roll (float angle)

void  roll (double angle)

Details roll twirls the camera about its position. This gives the effect of spinning the screen around its center point. Neither the position nor the target are moved. The vertical viewing axis and possibly the other two viewing axis are modified.

The angle specifies the amount of roll. A positive angle rolls the camera counter-clockwise; the scene appears to roll by clockwise. To roll in the opposite direction, specify a negative angle.

The second form is for double precision.

HT_Camera::zoom

Purpose

One of a set of routines that manipulate the point of view, zoom narrows or enlarges the viewing field of the camera. Synopsis

void zoom (float factor)

void zoom (double factor)

Details zoom changes the viewing field (the focal length) of the camera to give the effect of dynamically moving in or out of a scene. The camera position and target are not changed.

The factor parameter specifies the relative change in width of the field of view. A factor of 2 zooms in until the viewing field is half its previous size.

The second form is for double precision.

For information about moving the camera position and camera target by equal distances, see camera control, dolly. For information about "walking around" an object that you are continuously looking at, see orbit (in this class). For information about looking in a different direction, but not changing the camera position, see pan (also in this class).