.\"
.\" $XConsortium: p048,v 5.3 94/04/17 20:54:48 hersh Exp $
.\"
.\" 
$XMCOPY
.\" Copyright (c) 1990, 1991 by Sun Microsystems, Inc. and the X Consortium.
.\" 
.\"                         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 names of Sun Microsystems,
.\" and the X Consortium 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.
.\" "@(#)escape_-5.3 1.15 90/02/24 Copyr 1988 Sun Micro"
.ds f \s-2ESCAPE -5\s+2
.ds e \s-2ESCAPE\s+2
.ds s Sun\s-2PHIGS\s+2
.TH "ESCAPE -5" 3P "29 February 1991"
.SH NAME
ESCAPE -5 \- map a list of X drawable points to PHIGS World Coordinate
points
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pescape ( func_id, in, store, out )
Pint	func_id;	\fIescape function identifier\fP
Pescape_in_data	*in;	\fIinput data for the function\fP
Pstore	store;	\fInot used\fP
Pescape_out_data	**out;	\fIOUT output data of the function\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, WSOP *)
.SH DESCRIPTION
.SS Purpose
\*f attempts to map a list of X drawable coordinate points to a list of
\s-2PHIGS\s+2 World Coordinate points using the views of the specified workstation.
This provides similar functionality to a \s-2PHIGS\s+2 stroke device, but uses
points provided by the application rather than directly by the operator.
The method used to map the points is the same one used by \s-2PHIGS\s+2 stroke
devices.

This escape is not associated with any \s-2PHIGS\s+2 input device and can be used
without initializing any \s-2PHIGS\s+2 input device.
It is intended to allow the application to implement its own stroke device
using the standard X Event mechanism.
.SS C Input Parameters
.IP \fIfunc_id\fP
The function identifier for this escape is \s-2PUESC_DRAWABLE_POINTS_TO_WC\s+2,
which is defined in phigs.h to be -5.
.IP \fIin\fP
A pointer to a Pescape_in_data union, which contains the escape_in_u5 member
used by this escape function.
This member is defined in phigs.h as:
.nf
.ta .5i +.75i +1i
.sp .4
struct {
.sp .2
	Pint	ws_id;	/* workstation identifier */
	Ppoint_list3	points;	/* x,y are drawable coords, z is DC*/
.sp .2
} escape_in_u5;	/* drawable points to WC */
.fi
.RS
.IP \fIws_id\fP
Indicates the workstation to use.  The views on this workstation will be
used in the conversion to World Coordinates.
mapping.
.IP \fIpoints\fP
The list of points to map.  The x and y coordinates are drawable coordinate
values, as typically provided by X events.  
The Z coordinate is a \s-2PHIGS DC Z\s+2 value.
Ppoint_list3 is defined in phigs.h as follows:
.nf
.ta .5i +.75i +1i
.sp .4
struct {
.sp .2
	Pint	num_points;	/* number of Ppoint3s in the list */
	Ppoint3	*points;	/* list of points */
.sp .2
} Ppoint_list3
.fi
Ppoint3 is defined in phigs.h as follows:
.nf
.ta .5i +.75i +1i
.sp .4
struct {
.sp .2
	Pfloat	x;	/* x coordinate */
	Pfloat	y;	/* y coordinate */
	Pfloat	z;	/* z coordinate */
.sp .2
} Ppoint_list3
.fi
.RE
.IP \fIstore\fP
This parameter is not used in this escape function.
.SS C Output Parameters
.IP \fIout\fP
A pointer to a pointer to a Pescape_out_data union, which contains the escape_out_u5
member used by this escape function.
\s-2PHIGS\s+2 copies a pointer to the converted points, if any, to this member
of the Pescape_out_data union.
This member is defined in phigs.h as:
.nf
.ta .5i +1.2i  +1.5i
.sp .4
struct {
.sp .2
	Pint	view_index;
	Ppoint_list3	points;
.sp .2
} escape_out_u5;
.fi
.IP
\fIview_index\fP
The index of the highest priority view that contains all the points and is
used to transform the points to World Coordinates.
The view index is only meaningful if the number of points returned is
greater than zero.
.IP
\fIpoints\fP
The World Coordinate points.
The points array in this structure must be allocated prior to calling this
function and must be large enough to hold at least the number of points
specified in the input parameters.
The number of points returned will be 0 if the input points do not all lie
within one of the workstation's current view representations.
.SH ERRORS
.IP 003
Ignoring function, function requires state (PHOP, WSOP, *, *)
.IP 054
Ignoring function, the specified workstation is not open
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "ESCAPE (3P)"
.SM "INITIALIZE STROKE 3 (3P)"
.fi