.\"##
.\" $XConsortium: p052,v 5.3 94/04/17 20:54:51 hersh 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 MAPPING MATRIX 3" 3P "16 August 1991"
.SH NAME
EVALUATE VIEW MAPPING MATRIX 3 \- generate a transformation matrix to
map a \s-2\&3D\s+2 \s-2VRC\s+2 window to a \s-2\&3D\s+2 \s-2NPC\s+2 viewport
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
peval_view_map_matrix3 ( map, error_ind, m )
Pview_map3	*map;	\fIview mapping\fP
Pint	*error_ind;	\fI\s-2OUT\s+2 error indicator\fP
Pmatrix3	m;	\fI\s-2OUT\s+2 view mapping matrix\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, *, *)
.SH DESCRIPTION
.SS Purpose
Use \s-2EVALUATE VIEW MAPPING MATRIX 3\s+2
to calculate the viewing transformation matrix that transforms
a specified \s-2\&3D\s+2 window in View Reference Coordinates (\s-2VRC\s+2)
to a specified \s-2\&3D\s+2 viewport in Normalized
Projection Coordinates (\s-2NPC\s+2).
The viewing transformation may be either a parallel or perspective
transformation.
.LP
The view mapping matrix returned by this function may be used as an
argument to the \s-2SET VIEW REPRESENTATION 3\s+2 function.
See the descriptions of the functions \s-2SET VIEW REPRESENTATION 3\s+2 and
\s-2EVALUATE VIEW ORIENTATION MATRIX 3\s+2 for more information.
.SS C Input Parameters
.IP \fImap\fP
A pointer to a Pview_map3 structure defining the view mapping.
This structure is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Pproj_type     'u +\w'proj_ref_point;     'u
.nf
typedef struct {
.sp .2
	Plimit	win;	/* window limits */
	Plimit3	proj_vp;	/* viewport limits */
	Pproj_type	proj_type;	/* projection type */
	Ppoint3	proj_ref_point;	/* projection reference point */
	Pfloat	view_plane;	/* view plane distance */
	Pfloat	back_plane;	/* back plane distance */
	Pfloat	front_plane;	/* front plane distance */
.sp .2
} Pview_map3;
.fi
.IP
\fIwin\fP is a Plimit structure containing \fIu\fP and \fIv\fP
\s-2VRC\s+2 values defining the window limits.
Plimit is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Pfloat     'u +\w'x_min;     'u
.nf
typedef struct {
.sp .2
	Pfloat	x_min;	/* x minimum */
	Pfloat	x_max;	/* x maximum */
	Pfloat	y_min;	/* y minimum */
	Pfloat	y_max;	/* y maximum */
.sp .2
} Plimit;
.fi
.IP
The fields in Plimit define the \s-2VRC\s+2 window as follows:
.sp
.nf
	Plimit.x_min \(eq minimum \fIu\fP coordinate value
	Plimit.x_max \(eq maximum \fIu\fP coordinate value
	Plimit.y_min \(eq minimum \fIv\fP coordinate value
	Plimit.y_max \(eq maximum \fIv\fP coordinate value
.fi
.sp
.IP
\fIproj_vp\fP is a Plimit3 structure containing the \s-2NPC\s+2 viewport limits.
\fImin\fP and \fImax\fP correspond to the back lower left and front upper
right coordinates of the viewport volume, respectively.
Plimit3 is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Pfloat     'u +\w'x_min;     'u
.nf
typedef struct {
.sp .2
	Pfloat	x_min;	/* x minimum */
	Pfloat	x_max;	/* x maximum */
	Pfloat	y_min;	/* y minimum */
	Pfloat	y_max;	/* y maximum */
	Pfloat	z_min;	/* z minimum */
	Pfloat	z_max;	/* z maximum */
.sp .2
} Plimit3;
.fi
.IP
\fIproj_type\fP is an enumerated type that may take the following values:
.sp
.nf
	\(bu  PTYPE_PARAL
	\(bu  PTYPE_PERSPECT
.fi
.IP
\fIproj_ref_point\fP
is the Projection Reference Point, defined in \s-2VRC\s+2.
Ppoint3 is defined in  phigs.h as follows
.sp .4
.ta .5i +\w'Pfloat     'u +\w'x;     'u
.nf
typedef struct {
.sp .2
	Pfloat	x;	/* x coordinate */
	Pfloat	y;	/* y coordinate */
	Pfloat	z;	/* z coordinate */
.sp .2
} Ppoint3;
.fi
.IP
\fIview_plane\fP
is the \s-2VRC\s+2 location of the view plane on the \fIn\fP axis
of the \s-2VRC\s+2 coordinate system.
.IP
\fIback_plane\fP
is the \s-2VRC\s+2 location of the back plane on the \fIn\fP axis
of the \s-2VRC\s+2 coordinate system.
.IP
\fIfront_plane\fP
is the \s-2VRC\s+2 location of the front plane on the \fIn\fP axis
of the \s-2VRC\s+2 coordinate system.
.SS C Output Parameters
.IP \fIerr_ind\fP
A pointer to the location to store the error number of any error detected
by this function.
.IP \fIm\fP
A Pmatrix3 structure containing the \s-2\&3D\s+2 (4\ \(mu\ 4) transformation matrix
that performs the specified mapping.
Pmatrix3 is defined in phigs.h as follows:
.IP
typedef Pfloat Pmatrix3[4][4];
.SS Execution
If the input parameters are properly defined,
\s-2EVALUATE VIEW MAPPING MATRIX 3\s+2 returns a \s-2\&3D\s+2 (4\ \(mu\ 4)
transformation matrix in the output parameter view mapping matrix.
This transformation matrix performs the specified mapping from the \s-2VRC\s+2
window to the \s-2NPC\s+2 \fIviewport\fP.
.LP
The \fIfront plane\fP, \fIback plane\fP, and \fIview plane\fP all
define planes in \s-2VRC\s+2 space parallel to the \fIuv\fP plane
of the \s-2VRC\s+2 system. The
location of front and back along the \fIn\fP axis of \s-2VRC\s+2
defines the front and back of the volume of \s-2VRC\s+2
that will be mapped to \s-2NPC\s+2.
The view plane locates the view window on the \s-2VRC\s+2 \fIn\fP axis, and
window defines the size of the view window by specifying maximum and
minimum \fIu\fP and \fIv\fP values that establish the edges of the window.
These values taken together establish the volume of \s-2VRC\s+2 space that is
mapped into the \s-2NPC\s+2 viewport.
.LP
The type of projection may be parallel or perspective.
The \fIprojection reference point\fP orients the projectors defining the
surfaces of the view volume.
If the projection type is parallel, the projectors are all parallel to the
vector joining the projection reference point and the center of the
view window (located on the view plane).
If the projection type is perspective, the projectors all converge at the
projection reference point.
Thus, the view volume is a parallelpiped for parallel views, and a portion of
a double rectangular cone for perspective views.
.SH ERRORS
.IP 002
Ignoring function, function requires state (\s-2PHOP, *, *, *\s+2)
.IP 151
Ignoring function, invalid window;
\s-2XMIN \(>= XMAX\s+2 or \s-2YMIN \(>= YMAX\s+2
.IP 152
Ignoring function, invalid viewport;
\s-2XMIN \(>= XMAX, YMIN \(>= YMAX, or ZMIN > ZMAX\s+2
.IP 158
Ignoring function, front plane and back plane distances are
equal when \fIz\fP-extent of the projection viewport is zero
.IP 162
Ignoring function, the projection reference point is between the front
and back planes
.IP 163
Ignoring function, the projection reference point cannot be positioned
on the view plane
.IP 164
Ignoring function, the back plane is in front of the front plane
.IP 155
Ignoring function, the projection viewport limits are not
within \s-2NPC\s+2 range