.\"##
.\" $XConsortium: p388,v 5.2 94/04/17 20:58:59 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 "SET VIEW TRANSFORMATION INPUT PRIORITY" 3P "29 February 1991"
.SH NAME
SET VIEW TRANSFORMATION INPUT PRIORITY \-
assign relative priority of a view representation to be used when
transforming input values
.IX "Viewing" "SET VIEW TRANSFORMATION INPUT PRIORITY"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pset_view_tran_in_pri ( ws, index, ref_index, priority )
Pint	ws;	\fIworkstation identifier\fP
Pint	index;	\fIview index\fP
Pint	ref_index;	\fIreference view index\fP
Prel_pri	priority;	\fIrelative priority\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET VIEW TRANSFORMATION INPUT PRIORITY\s+2
assigns a relative priority to an entry
in the workstation's view table, to be used when transforming
\s-2LOCATOR\s+2 or \s-2STROKE\s+2 operator input coordinates
from Device Coordinates (\s-2DC\s+2) to World Coordinates (\s-2WC\s+2).
.SS C Input Parameters
.IP \fIws\fP
The identifier of the workstation for which the view transformation
input priority is being set.
.IP \fIindex\fP
The priority is being set for this \fIview index\fP.
.IP \fIref_index\fP
The priority of \fIindex\fP is set just higher or lower than
that of this \fIreference view index\fP.
.IP \fIpriority\fP
The \fIrelative priority\fP for \fIindex\fP,
relative to the \fIref_index\fP; one of the enumerated values:
.sp
.ta .5i +\w'0     'u +\w'PPRI_LOWER     'u
.nf
	PPRI_HIGHER	\fIHigher\fP
	PPRI_LOWER	\fILower\fP
.fi
.sp
.SS Execution
\s-2SET VIEW TRANSFORMATION INPUT PRIORITY\s+2
assigns a relative priority to a view representation entry
in the workstation's view table, to be used when transforming
\s-2LOCATOR\s+2 or \s-2STROKE\s+2 operator input coordinates 
from \s-2DC\s+2 to \s-2WC\s+2.  The priority of view index is set just
higher or just lower than the priority of the reference view index.
.LP
\s-2LOCATOR\s+2 or \s-2STROKE\s+2 operator input data
are transformed by the inverse viewing pipeline,
from \s-2DC\s+2 to \s-2WC\s+2.
First, the inverse workstation transformation (in effect when the
input is generated) maps the \s-2DC\s+2 values to Normalized Projection
Coordinates (\s-2NPC\s+2), always
resulting in values in the \s-2NPC\s+2 unit cube.
Then, the \s-2NPC\s+2 positions need to be mapped to \s-2WC\s+2 by the inverse
of one of the viewing transformations; the relative priority order
of the viewing transformations is used to determine which viewing
transformation inverse to apply.
.LP
Views with lower priority than view 0's will never be used to
map input data.
View 0 is the identity transformation encompassing the entire \s-2NPC\s+2 space cube
and cannot be changed.  Therefore, any input position is necessarily
in view 0, and lower priority views are effectively disabled.
The initial ordering, when a workstation is opened, gives view number 0
the highest priority, view 1 the next highest, and so on.
All views except 0 are disabled.
.LP
If the view index is the same as the reference view index,
the function has no effect.
.LP
The relative view transformation input priorities may be obtained using
\s-2INQUIRE LIST OF VIEW INDICES\s+2.
.DT
.SH ERRORS
.IP 003
Ignoring function, function requires state (\s-2PHOP, WSOP, *, *\s+2)
.IP 054
Ignoring function, the specified workstation is not open
.IP 057
Ignoring function, specified workstation is of category \s-2MI\s+2
.IP 114
Ignoring function, the view index value is less than zero
.IP 101
Ignoring function, the specified representation has not been defined
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "SET VIEW REPRESENTATION 3 (3P)"
.SM "INQUIRE LIST OF VIEW INDICES (3P)"
.fi