glFrustum(3)

NAME

       glFrustum - multiply the current matrix by a perspective matrix

C SPECIFICATION

       void glFrustum( GLdouble left,
                       GLdouble right,
                       GLdouble bottom,
                       GLdouble top,
                       GLdouble near_val,
                       GLdouble far_val )

       delim $$

PARAMETERS

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

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

       near_val, far_val
                   Specify  the  distances  to the near and far depth clipping
                   planes.  Both distances must be positive.

DESCRIPTION

       glFrustum describes a perspective matrix that  produces  a  perspective
       projection.   The  current  matrix  (see glMatrixMode) is multiplied by
       this  matrix  and  the  result  replaces  the  current  matrix,  as  if
       glMultMatrix 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  GL_PROJECTION,  and  (left,  bottom,
       -near_val)  and (right, top,  -near_val) specify the points on the near
       clipping plane that are mapped to the lower left and upper  right  cor-
       ners  of  the  window,  assuming  that the eye is located at (0, 0, 0).
       -far_val specifies the  location  of  the  far  clipping  plane.   Both
       near_val and far_val must be positive.

       Use glPushMatrix and glPopMatrix to save and restore the current matrix
       stack.

NOTES

       Depth buffer precision is affected by the values specified for near_val
       and far_val.  The greater the ratio of far_val to near_val 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 near_val approaches 0, near_val must
       never be set to 0.

ERRORS

       GL_INVALID_VALUE  is  generated if near_val or far_val is not positive,
       or if left = right, or bottom = top.

       GL_INVALID_OPERATION is generated if glFrustum is executed between  the
       execution of glBegin and the corresponding execution of glEnd.

ASSOCIATED GETS

       glGet with argument GL_MATRIX_MODE
       glGet with argument GL_MODELVIEW_MATRIX
       glGet with argument GL_PROJECTION_MATRIX
       glGet with argument GL_TEXTURE_MATRIX
       glGet with argument GL_COLOR_MATRIX

SEE ALSO

       glOrtho(3G),   glMatrixMode(3G),   glMultMatrix(3G),  glPushMatrix(3G),
       glViewport(3G)

                                                                 GLFRUSTUM(3G)