PEXPerspProjMatrix Utility

Synopsis

 
   int PEXPerspProjMatrix(
       double fovy,
       double distance,
       double aspect,
       double near,
       double far,
       PEXMatrix matrix_return
   )

Arguments

fovy: Field of view (in radians) in the horizontal direction.
distance: The distance to the eye-point from the VRC origin.
aspect: The aspect ratio (width/height) of the perspective viewing frustum.
near: The distance to the near clipping plane from the VRC origin.
far: The distance to the far clipping plane from the VRC origin.
matrix_return: Matrix in which result is stored.

Returns

Zero if successful; otherwise, one of the following:

PEXBadLimits: near <= far, fovy = 0, aspect = 0, or distance <= near

Description

Invoke PEXPerpProjMatrix to create a view mapping matrix.

A projection matrix defines the visible region of the coordinate space. A perspective projection defines the visible region as a truncated pyramid or frustum. The amount of perspective in the projection is specified by the field of view argument, fovy. The perspective increases as the angle increases to a value of pi radians.

The distance between the eye-point and the origin is specified by the distance. If the application program invokes PEXLookAtViewMatrix to calculate the view orientation matrix, then the distance is typically the distance between the from and to points specified to that utility. If the application program invokes PEXPolarViewMatrix to calculate the view orientation matrix, then the distance is typically the same distance specified to that routine.

The height of the frustum at the near clipping plane is determined by fovy and the distance to the near plane. The width of the frustum is determined from the aspect ratio.

The reference point for the projection is the origin of VRC; the near and far clipping planes are defined with respect to it. Clipping at the planes is controlled by the clip flags in the selected view table entry.

It is useful to think of PEXPerspProjMatrix as defining a camera. The object being viewed is defined near the origin. The lens is defined by fovy; a larger value of fovy defines a wide angle lens. For those who wish to keep the height at the near plane constant and automatically back up the camera to frame the subject, the relationship between the field of view, the eye distance, which is the distance between the eye-point and the near plane, and the height, which is the height at the near plane, is:

   tan (fovy/2) = ((height/2) / eye_distance)

For example, if a unit cube is being viewed, a "look at" view with the to point at the center of the cube or a "polar" view with the viewed point at the center of the cube, places the cube at the origin. A matrix created by PEXPerspProjMatrix with aspect = 1, near = 0.5, and far = -0.5 makes the entire cube visible, with the field of view and distance controlling the amount of perspective applied.

Errors