The viewport is the rectangular portal through which you view a scene. The viewport can be as large as a csWindow, or it can be just a portion of a csWindow, as shown in Figure 9-1.

Figure 9-1. Viewport

You set the size of the viewport using the following csContext method:

static void setViewport(csInt x, csInt y, csInt w, csInt h);

x and y are the coordinates of the lower, left corner of the viewport (where the lower, left corner of the csWindow is (0. 0)).

w and h are the width and height of the viewport.

csCamera is an abstract base class from which all other cameras are derived. csCamera defines the viewing volume. The viewing volume is bounded by the camera's origin and orientation, the far clip plane, and an aspect ratio. The aspect ratio is defined as the image's width divided by its height, as shown in Figure 9-2.

Figure 9-2. Aspect Ratio

The distances to the near and far clip planes are in the Z dimension in camera space. The viewing frustum can be transformed into world space using the position and orientation methods in csCamera.

Normally, the aspect ratio of the image matches that of the window. If the aspect ratio does not match that of the window, the image is distorted: it is either expanded or contracted along one or both axes, as shown in Figure 9-3.

Figure 9-3. Changing the Window Without Changing the Image's Aspect

It is important, therefore, to change the aspect of the image if the window is revised. To do that, you use csWindow, as explained in Chapter 12, “User Interface Mechanisms.” The aspect ratio can be set through methods of csOrthoCamera and csPerspCamera.

The following methods set the position and orientation of a camera.

void setPosition(const csVec3f& position);
void setPosition(csFloat v0, csFloat v1, csFloat v2);
void setOrientation(const csRotation& orientation);
void setOrientation(csFloat v0, csFloat v1, csFloat v2, csFloat v3);

There is a corresponding get...() field for each set...() field.

You use the setPosition() methods to locate the camera in the scene. Initially, it is pointing along the Z axis. To rotate the camera use the setOrientation() field. You set the near and far clip planes using the setNear() and setFar() methods.

csOrthoCamera defines an orthographic projection. An orthographic projection uses a parallelepiped (box) frustum. Unlike the frustum in Figure 9-2, the size of the frustum does not change from one end to the other. For this reason, the distance from the camera to an object in the frustum does not affect the size of the object.

You use this type of camera when you do not want to view objects in perspective. For example, when you create architectural blueprints and CAD models, it is important to maintain the actual sizes of objects and angles between them when they are projected.

csOrthoCamera uses the following methods to define the viewing frustum:

void setWidth(csfloat width)
void setHeight(csfloat height)
void setCenter(const csVec2f* center)
void setCenter(csFloat v0, csFloat v1);
void setNearClip(csFloat nearClip);
void setFarClip(csFloat farClip);

There is a corresponding get...() field for each set...() field.

The width and height methods define the left, right, top, and bottom of the parallelepiped (box) frustum. The setCenter() method points the csOrthoCamera at the center of the scene you want to view.

A csPerspCamera creates a perspective view in which objects closer to the camera appear larger than the same-sized objects located further from the camera. This type of camera imitates normal vision. For example, train tracks and the distance between them appear smaller the more distant they are.

You can understand why more distant objects appear smaller by looking at Figure 9-4.

Figure 9-4. Perspective Explained

If you compare the height of an object in the near clipping plane to the height of the near clipping plane, you see that the ratio is larger than the ratio of the height of the same object in the far clipping plane to the height of the far clipping plane.

   Hobject         Hobject
  --------  > --------
   Hnear          Hfar

Consequently, when you compare the size of the object to its surroundings, it appears smaller in the distance.

Setting the Frustum

The frustum is the truncated pyramidal volume depicted in Figure 9-2. It is defined by four quantities, as shown in Figure 9-5:

• Distance to the near clip plane.

• Distance to the far clip plane.

• Horizontal field of view.

• Vertical field of view.

Setting the Clip Planes

You use the following fields to set the distance to the near and far clip planes:

void setNearClip(csFloat nearClip); void setFarClip(csFloat farClip);

There is a corresponding get...() field for each set...() field.

Setting the Fields of View

You use the following fields to set the horizontal and vertical fields of view (FOV) of the frustum. The arguments are the angles, in degrees, of the fields of view.

void setHorizFOV(csFloat horizFOV); void setVertFOV(csFloat vertFOV);

There is a corresponding get...() field for each set...() field.

Offsetting the Fields of View

By default, the fields of view are centered around the –Z axis. csPerspCamera, however, enables you to offset the fields of view both horizontally and vertically, as shown in Figure 9-5.

Figure 9-5. Horizontal and Vertical Fields of View Offsets

The offset angles are measured starting at the -z axis, following the right-hand rule. For example, the horizontal FOV offset angle shown in Figure 9-5 is positive.

To specify the offsets, use one or both of the following csPerspCamera methods:

void setHorizFOVOff(csFloat horizFOV); void setVertFOVOff(rfcsFloat vertFOV);

There is a corresponding get...() field for each set...() field.

csFrustumCamera allows you to work directly with a frustum without worrying about the specifics of a camera. You define the frustum using the csFrustumCamera's only method:

setFrustum(csFrustum * frustum)

For a definition of csFrustum, see csGeoMath.h.