sync code with last improvements from OpenBSD

doc/gl-docs/GLU/perspective.3gl

@@ -0,0 +1,96 @@
+.\" $XFree86$
+'\" e
+'\"! eqn | mmdoc
+'\"macro stdmacro
+.ds Vn Version 1.2
+.ds Dt 6 March 1997
+.ds Re Release 1.2.0
+.ds Dp May 02 11:53
+.ds Dm 37 perspecti
+.ds Xs 14699 5 perspective.gl
+.TH GLUPERSPECTIVE 3G
+.SH NAME
+.B "gluPerspective
+\- set up a perspective projection matrix
+
+.SH C SPECIFICATION
+void \f3gluPerspective\fP(
+GLdouble \fIfovy\fP,
+.nf
+.ta \w'\f3void \fPgluPerspective( 'u
+	GLdouble \fIaspect\fP,
+	GLdouble \fIzNear\fP,
+	GLdouble \fIzFar\fP )
+.fi
+
+.EQ
+delim $$
+.EN
+.SH PARAMETERS
+.TP \w'\fIaspect\fP\ \ 'u 
+\f2fovy\fP
+Specifies the field of view angle, in degrees, in the \f2y\fP direction.
+.TP
+\f2aspect\fP
+Specifies the aspect ratio that determines
+the field of view in the \f2x\fP direction.
+The aspect ratio is the ratio of \f2x\fP (width) to \f2y\fP (height).
+.TP
+\f2zNear\fP
+Specifies the distance from the viewer to the near clipping plane
+(always positive).
+.TP
+\f2zFar\fP
+Specifies the distance from the viewer to the far clipping plane
+(always positive).
+.SH DESCRIPTION
+\%\f3gluPerspective\fP specifies a viewing frustum into the world coordinate system.
+In general, the aspect ratio in \%\f3gluPerspective\fP should match the aspect ratio
+of the associated viewport. For example, $ "aspect" ~=~ 2.0 $ means 
+the viewer's
+angle of view is twice as wide in \f2x\fP as it is in \f2y\fP.
+If the viewport is
+twice as wide as it is tall, it displays the image without distortion.
+.P
+The matrix generated by \%\f3gluPerspective\fP is multiplied by the current matrix,
+just as if \f3glMultMatrix\fP were called with the generated matrix.
+To load the perspective matrix onto the current matrix stack instead,
+precede the call to \%\f3gluPerspective\fP with a call to \f3glLoadIdentity\fP.
+.P
+Given \f2f\fP defined as follows:
+.sp
+.ce
+.EQ
+f  ~=~ cotangent"("{"fovy" over 2}")"
+.EN
+.bp
+The generated matrix is
+.sp
+.ce
+.EQ
+left ( ~~ down 130 { matrix {
+   ccol { {f over "aspect"} above 0 above 0 above 0 }
+   ccol { 0 above f above 0 above 0 }
+   ccol { 0 above 0 above {{"zFar" + "zNear"} over {"zNear" - "zFar"}} above -1 }
+   ccol { 0 above 0 above {{2 * "zFar" * "zNear"} over {"zNear" - "zFar"}} above 0}
+}}  ~~~ right )
+.EN
+
+.SH NOTES
+Depth buffer precision is affected by the values specified for
+\f2zNear\fP and \f2zFar\fP.
+The greater the ratio of \f2zFar\fP to \f2zNear\fP is,
+the less effective the depth buffer will be at distinguishing between
+surfaces that are near each other.
+If 
+.sp
+.ce
+$r ~=~ "zFar" over "zNear"$
+.sp
+.P
+roughly $log sub 2 r$ bits of depth buffer precision are lost.
+Because $r$ approaches infinity as \f2zNear\fP approaches 0,
+\f2zNear\fP must never be set to 0.
+.SH SEE ALSO
+\f3glFrustum(3G)\fP, \f3glLoadIdentity(3G)\fP,
+\f3glMultMatrix(3G)\fP, \%\f3gluOrtho2D(3G)\fP