! eqn | mmdoc
macro stdmacro
 GLFRUSTUM
 NAME
 "glFrustum - multiply the current matrix by a perspective matrix


 C SPECIFICATION
void \f3glFrustum(
GLdouble left,

 GLdouble right,
 GLdouble bottom,
 GLdouble top,
 GLdouble zNear,
 GLdouble zFar )



delim $$
.EN

 PARAMETERS
 \w'\f2left \f2right  'u 
\f2left, \f2right
Specify the coordinates for the left and right vertical clipping planes.


\f2bottom, \f2top
Specify the coordinates for the bottom and top horizontal clipping planes.


\f2zNear, \f2zFar
Specify the distances to the near and far depth clipping planes.
Both distances must be positive.

 DESCRIPTION
\f3glFrustum describes a perspective matrix that produces a perspective projection.
The current matrix (see \f3glMatrixMode) is multiplied by this matrix
and the result replaces the current matrix, as if
\f3glMultMatrix were called with the following matrix
as its argument:




down 130 {left ( ~~ matrix {
 ccol { {{2 ~ "zNear"} over {"right" - "left"}} above 0 above 0 above 0 }
 ccol { 0 above {{2 ~ "zNear"} over {"top" - "bottom"}} ~ above 0 above 0 }
 ccol { A ~~~~ above B ~~~~ above C ~~~~ above -1 ~~~~}
 ccol { 0 above 0 above D above 0}
} ~~~ right )}
.EN


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


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


down 130
{C ~=~ -{{"zFar" + "zNear"} over {"zFar" - "zNear"}}}
.EN


down 130
{D ~=~ -{{2 ~ "zFar" ~ "zNear"} over {"zFar" - "zNear"}}}
.EN


Typically, the matrix mode is \f3GL_PROJECTION, and
(\f2left, \f2bottom, -\f2zNear) and (\f2right, \f2top, -\f2zNear)
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).
-\f2zFar specifies the location of the far clipping plane.
Both \f2zNear and \f2zFar must be positive.


Use \f3glPushMatrix and \f3glPopMatrix to save and restore
the current matrix stack.

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


$r ~=~ "zFar" over "zNear"$
roughly $log sub 2 (r)$ bits of depth buffer precision are lost.
Because $r$ approaches infinity as \f2zNear approaches 0,
\f2zNear must never be set to 0.

 ERRORS
\f3GL_INVALID_VALUE is generated if \f2zNear or \f2zFar is not positive.


\f3GL_INVALID_OPERATION is generated if \f3glFrustum
is executed between the execution of \f3glBegin
and the corresponding execution of \f3glEnd.

 ASSOCIATED GETS
\f3glGet with argument \f3GL_MATRIX_MODE


\f3glGet with argument \f3GL_MODELVIEW_MATRIX


\f3glGet with argument \f3GL_PROJECTION_MATRIX


\f3glGet with argument \f3GL_TEXTURE_MATRIX

 SEE ALSO
\f3glOrtho,
\f3glMatrixMode,
\f3glMultMatrix, 
\f3glPushMatrix,
\f3glViewport