.\"##
.\" $XConsortium: p051,v 5.3 94/04/17 20:54:50 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" 3P "16 August 1991"
.SH NAME
EVALUATE VIEW MAPPING MATRIX  \- generate a transformation matrix to
map a \s-2\&2D VRC\s+2 window to a \s-2\&2D NPC\s+2 viewport
.IX "Viewing" "EVALUATE VIEW MAPPING MATRIX"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
peval_view_map_matrix ( map, error_ind, m )
Pview_map	*map;	\fIview mapping\fP
Pint	*error_ind;	\fI\s-2OUT\s+2 error indicator\fP
Pmatrix	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\s+2
to calculate the viewing transformation matrix that transforms
a specified window in View Reference Coordinates (\s-2VRC\s+2)
to a specified viewport in Normalized Projection Coordinates (\s-2NPC\s+2).
.LP
The view mapping matrix returned by this function may be used as an
argument to the \s-2SET VIEW REPRESENTATION\s+2 function to specify
the mapping from \s-2VRC\s+2 to \s-2NPC\s+2.
See the descriptions for the functions \s-2SET VIEW REPRESENTATION\s+2 and
\s-2EVALUATE VIEW ORIENTATION MATRIX\s+2 in this function reference
for more information.
.SS C Input Parameters
.IP \fImap\fP
A pointer to a Pview_map structure defining the view mapping.
This structure is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Plimit     'u +\w'viewport;     'u
.nf
typedef struct {
.sp .2
	Plimit	win;	/* window limits */
	Plimit	proj_vp;	/* viewport limits */
.sp .2
} Pview_map;
.fi
.IP
\fIwin\fP is a Plimit structure containing \fIu\fP and \fIv\fP
\s-2VRC\s+2 values defining the window to be mapped to \s-2NPC\s+2.
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 .2
.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
.IP
\fIproj_vp\fP
is a Plimit structure containing the definition of the \s-2NPC\s+2 viewport.
.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
A Pmatrix structure containing the \s-2\&2D\s+2 (3\ \(mu\ 3) transformation matrix
that performs the specified view mapping.
Pmatrix is defined in phigs.h as follows:
.IP
typedef Pfloat Pmatrix[3][3];
.SS Execution
If the input parameters are properly defined,
\s-2EVALUATE VIEW MAPPING MATRIX\s+2 returns a \s-2\&2D\s+2 (3\ \(mu\ 3)
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 viewport.
.LP
The following restrictions apply to the VRC window definition:
.sp .2
.nf
	\fIu\fP minimum < \fIu\fP maximum
	\fIv\fP minimum < \fIv\fP maximum
.fi
.LP
The following restrictions apply to the viewport definition:
.sp .2
.nf
	0 <= \fIx\fP minimum < \fIx\fP maximum <= 1
	0 <= \fIy\fP minimum < \fIy\fP maximum <= 1
.fi
Where zero and 1 are the \s-2NPC\s+2 limits.
.IP
The range of \s-2VRC\s+2 coordinate units is determined by the view orientation
transformation.
.LP
.fi
The window to be mapped is specified in \s-2VRC\s+2 by the window
input parameter.
It is a rectangle located on the \fIn\fP \(eq 0 plane whose sides are parallel
to the \fIu\fP and \fIv\fP axes.
The rectangle is defined by minimum \fIu\fP and \fIv\fP values at the lower left hand
corner and by the maximum \fIu\fP and \fIv\fP values at the upper right hand corner.
.LP
The viewport to which the window is mapped is specified in \s-2NPC\s+2 by the
viewport input parameter.
It is a rectangle located
in \s-2NPC\s+2 space
on the \fIz\fP \(eq 0 plane whose sides are parallel to the 
\fIx\f and \fIy\f axes. The rectangle is defined by the \fIx\f 
and \fIy\f coordinates of the lower left
corner and by the \fIx\f and \fIy\f coordinates of the upper right corner.
The coordinate values must be within the closed unit square range of \s-2NPC\s+2
space, [0,1] x [0,1].
.SH ERRORS
.IP 002
Ignoring function, function requires state (\s-2PHOP, *, *, *\s+2)
.IP 151
Ignoring function, invalid window;
\s-2XMIN\s+2 \(>= \s-2XMAX\s+2 or \s-2YMIN\s+2 \(>= \s-2YMAX\s+2.
.IP 152
Ignoring function, invalid viewport;
\s-2XMIN\s+2 \(>= \s-2XMAX\s+2 or \s-2YMIN\s+2 \(>= \s-2YMAX\s+2.
.IP 155
Ignoring function, the projection viewport limits are not within \s-2NPC\s+2
range