.\" @(#)PEXPolarViewMatrix.3 1.5 95/03/24 SMI;
.so man3/pex.macs
.TH PEXPolarViewMatrix 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXPolarViewMatrix - utility function
.SH SYNTAX
.HP
int PEXPolarViewMatrix\^(\^PEXCoord *\fIfrom\fP, double \fIdistance\fP, double \fIazimuth\fP, double \fIaltitude\fP, double \fItwist\fP, PEXMatrix \fImatrix_return\fP\^)
.SH PARAMETERS
.IP \fIfrom\fP 1i
The viewing position.
.IP \fIdistance\fP 1i
The distance between the
.I from
position and the position being viewed.
.IP \fIazimuth\fP 1i
The angle in the x,z plane from the +z axis to the line of sight, in radians.
Positive values are counter-clockwise when viewed from the positive y axis.
.IP \fIaltitude\fP 1i
The angular inclination of the line of sight from the x,z plane.
The 
.I altitude
argument is the angle in radians.  Positive values are towards
the positive y axis.
.IP \fItwist\fP 1i
The up direction of the view, given as an angle, in radians, about the line of
sight.  Positive values of
.I twist
are in the counter-clockwise direction.
.IP \fImatrix_return\fP 1i
Matrix in which result is stored.
.SH RETURNS
.LP
Zero if successful; otherwise, one of the following:
.LP
.RS
.B PEXBadDistance
.RE
.SH DESCRIPTION
.\" indexing
.IX PEXPolarViewMatrix
.IX "Utility Functions" PEXPolarViewMatrix
.LP
This routine formats a polar view orientation matrix.  This routine is
similar to
.BR PEXLookAtViewMatrix (3) ,
except that the viewing parameters
are specified in spherical coordinates.
The
.I from
position defines one end of the view plane normal; the position
indicated by
.I distance,
.I azimuth,
and
.I altitude
define the base of the view plane normal, and the origin of VRC.
.LP
The view is defined with respect to the
.I from
position (the viewing position) and the distance between it and the
position being viewed.  The
.I azimuth
angle specifies the direction of
the line of sight going toward the position being viewed.
Positive values of
.I azimuth
are counter-clockwise when viewed from the
positive y axis.
.LP
The
.I azimuth
and
.I altitude
angles apply to the coordinate system
with
.I from
at the origin and the line of sight emanating from it.  The
.I azimuth
specifies the angle between the line of sight and
the +z axis, and the
.I altitude
defines the angle between it and the x,z plane.
.LP
When applied, the transformation places the viewing position at the
origin, aligns the viewpoint with the +z axis, applies any
.I twist
to the coordinates, and then places the viewed point at the origin.
.SH ERRORS
None
.SH SEE ALSO
.LP
.nf
.BR PEXLookAtViewMatrix (3)
.BR PEXViewOrientationMatrix (3)
.BR PEXViewMappingMatrix (3)
.fi