GLFRUSTUM

NAME

glFrustum - multiply the current matrix by a perspective matrix

C SPECIFICATION

void f3glFrustumfP( GLdouble fIleftfP,

f2leftfP, f2rightfP
Specify the coordinates for the left and right vertical clipping planes.

f2bottomfP, f2topfP
Specify the coordinates for the bottom and top horizontal clipping planes.
f2near_valfP, f2far_valfP
Specify the distances to the near and far depth clipping planes.
Both distances must be positive.

DESCRIPTION

%f3glFrustumfP describes a perspective matrix that produces a perspective projection. The current matrix (see %f3glMatrixModefP) is multiplied by this matrix and the result replaces the current matrix, as if %f3glMultMatrixfP were called with the following matrix as its argument:

down 150 {left [ ~~~ { down 165 matrix {
   ccol { {{2 ~ "near_val"} over {"right" ~-~ "left"}} above 0 above 0 above 0 }
   ccol { 0 above {{2 ~ "near_val"} over {"top" ~-~ "bottom"}} ~ above 0 above 0 }
   ccol { A ~~~~ above B ~~~~ above C ~~~~ above -1 ~~~~}
   ccol { 0 above 0 above D above 0} }} ~~~ right ]}

down 130 {A ~=~ {"right" ~+~ "left"} over {"right" ~-~ "left"}}

down 130 {B ~=~ {"top" ~+~ "bottom"} over {"top" ~-~ "bottom"}}

down 130 {C ~=~ -{{"far_val" ~+~ "near_val"} over {"far_val" ~-~ "near_val"}}}

down 130 {D ~=~ -^{{2 ~ "far_val" ~ "near_val"} over {"far_val" ~-~ "near_val"}}}

Typically, the matrix mode is %f3GL_PROJECTIONfP, and (f2leftfP, f2bottomfP, -f2near_valfP) and (f2rightfP, f2topfP, -f2near_valfP) specify the points on the near clipping plane that are mapped to the lower left and upper right corners of the window, assuming that the eye is located at (0, 0, 0). -f2far_valfP specifies the location of the far clipping plane. Both f2near_valfP and f2far_valfP must be positive. Use %f3glPushMatrixfP and %f3glPopMatrixfP to save and restore the current matrix stack.

NOTES

Depth buffer precision is affected by the values specified for f2near_valfP and f2far_valfP. The greater the ratio of f2far_valfP to f2near_valfP is, the less effective the depth buffer will be at distinguishing between surfaces that are near each other. If

$r ~=~ "far_val" over "near_val"$

roughly $log sub 2 (r)$ bits of depth buffer precision are lost. Because $r$ approaches infinity as f2near_valfP approaches 0, f2near_valfP must never be set to 0.

ERRORS

%f3GL_INVALID_VALUEfP is generated if f2near_valfP or f2far_valfP is not positive, or if f2leftfP = f2rightfP, or f2bottomfP = f2topfP. %f3GL_INVALID_OPERATIONfP is generated if %f3glFrustumfP is executed between the execution of %f3glBeginfP and the corresponding execution of %f3glEndfP.

ASSOCIATED GETS

%f3glGetfP with argument %f3GL_MATRIX_MODEfP
%f3glGetfP with argument %f3GL_MODELVIEW_MATRIXfP
%f3glGetfP with argument %f3GL_PROJECTION_MATRIXfP
%f3glGetfP with argument %f3GL_TEXTURE_MATRIXfP
%f3glGetfP with argument %f3GL_COLOR_MATRIXfP