.\"##
.\" $XConsortium: p054,v 5.2 94/04/17 20:54:53 rws Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         All Rights Reserved
.\"## 
.\"## Permission to use, copy, modify, and distribute this software and its 
.\"## documentation for any purpose and without fee is hereby granted, 
.\"## provided that the above copyright notice appear in all copies and that
.\"## both that copyright notice and this permission notice appear in 
.\"## supporting documentation, and that the name of Sun Microsystems,
.\"## not be used in advertising or publicity 
.\"## pertaining to distribution of the software without specific, written 
.\"## prior permission.  
.\"## 
.\"## SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\"## INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\"## EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\"## CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\"## USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\"## OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\"## PERFORMANCE OF THIS SOFTWARE.
.TH "EVALUATE VIEW ORIENTATION MATRIX 3" 3P "29 February 1991"
.SH NAME
EVALUATE VIEW ORIENTATION MATRIX 3 \- calculate a transformation matrix that
orients the View Reference Coordinate (VRC) system in the World Coordinate
(WC) system
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
peval_view_ori_matrix3 ( vrp, vpn, vup, error_ind, m )
Ppoint3	*vrp;	\fIview reference point\fP
Pvec3	*vpn;	\fIview plane normal\fP
Pvec3	*vup;	\fIview up vector\fP
Pint	*error_ind;	\fIOUT error indicator\fP
Pmatrix3	m;	\fIOUT view orientation matrix\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, *, *)
.SH DESCRIPTION
.SS Purpose
Use \s-2EVALUATE VIEW ORIENTATION MATRIX 3\s+2 to calculate a
\fIview orientation matrix\fP, used to transform World Coordinates (WC) to
View Reference Coordinates (VRC).
This matrix establishes the \fIu\fP, \fIv\fP and \fIn\fP VRC axes
in relation to World Coordinate Space.
The \fIview orientation matrix\fP calculated by this function can be
passed as an argument to \s-2SET VIEW REPRESENTATION 3\s+2.
.LP
See the descriptions of the functions \s-2SET VIEW REPRESENTATION 3\s+2 and
\s-2EVALUATE VIEW MAPPING MATRIX 3\s+2 in this function reference
for more information.
.SS C Input Parameters
.IP \fIvrp\fP
A pointer to a Ppoint3 structure containing
\fIx\fP, \fIy\fP and \fIz\fP
world coordinates that specify the view reference point.
Ppoint3 is defined in phigs.h as follows:
.sp
.ta .5i +1.0i +1i
.nf
typedef struct {
.sp .2
	Pfloat	x;	/* x coordinate */
	Pfloat	y;	/* y coordinate */
	Pfloat	z;	/* z coordinate */
.sp .2
} Ppoint3;
.fi
.IP \fIvpn\fP
A pointer to a Pvec3 structure containing
\fIx\fP, \fIy\fP, and \fIz\fP
World Coordinate values that specify the view plane normal vector.
Pvec3 is defined in phigs.h as follows:
.sp
.ta .5i +1i +1i
.nf
typedef struct {
.sp .2
	Pfloat	delta_x;	/* x magnitude */
	Pfloat	delta_y;	/* y magnitude */
	Pfloat	delta_z;	/* z magnitude */
.sp .2
} Pvec3;
.fi
.IP \fIvup\fP
A pointer to a Pvec3 structure containing
\fIx\fP, \fIy\fP, and \fIz\fP
world coordinate values that specify the view up vector.
Pvec3 is defined above.
.SS C Output Parameters
.IP \fIerror_ind\fP
A pointer to the location to store the error number of any error detected
by this function.
.IP \fIm\fP
The \s-2\&3D\s+2 homogeneous (4 \(mu 4) view orientation matrix.
Pmatrix3 is defined in phigs.h as follows:
.IP
typedef  Pfloat  Pmatrix3[4][4];
.SS Execution
If the input parameters are consistent and well-defined,
\s-2EVALUATE VIEW ORIENTATION MATRIX 3\s+2 returns a \s-2\&3D\s+2 homogeneous
(4\ \(mu\ 4) transformation matrix in the output parameter
\fIview orientation matrix\fP.
This matrix transforms World Coordinates to View Reference Coordinates
according to the values of the input parameters.
.LP
The \fIview reference point\fP defines the point in World Coordinate
Space that is to be used as the origin of the View Reference Coordinate
system.
It is specified as a \s-2\&3D\s+2 world coordinate point
and is usually a point on or near the object to be viewed.
.LP
The \fIview plane normal\fP is a \s-2\&3D\s+2 vector defined
in World Coordinates relative to the view reference point.
It defines the \fIn\fP axis  of the VRC system.
The plane in WC that contains the view reference point and is perpendicular
to the view plane normal is called the \fIview reference plane\fP.
.LP
The \fIview up vector\fP is a \s-2\&3D\s+2 vector defined
in World Coordinates relative to the view reference point.
The projection of this vector onto the view reference plane parallel to
the \fIview plane normal\fP determines the \fIv\fP axis of the VRC system.
.LP
The \fIu\fP axis of VRC is determined so that the \fIuvn\fP axes form a
right-handed coordinate system.
.SH ERRORS
.IP 002
Ignoring function, function requires state (PHOP, *, *, *)
.IP 159
Ignoring function, the view plane normal vector has length zero
.IP 160
Ignoring function, the view up vector has length zero
.IP 161
Ignoring function, the view up and view plane normal vectors
are parallel thus the viewing coordinate system cannot be established