NAME

ESCAPE -5 − map a list of X drawable points to PHIGS World Coordinate points

SYNOPSIS

C Syntax

void
pescape ( func_id, in, store, out )
Pintfunc_id;escape function identifier
Pescape_in_data∗in; input data for the function
Pstorestore;not used
Pescape_out_data∗∗out; OUT output data of the function

Required PHIGS Operating States

(PHOP, ∗, WSOP ∗)

DESCRIPTION

Purpose

ESCAPE -5 attempts to map a list of X drawable coordinate points to a list of PHIGS World Coordinate points using the views of the specified workstation.  This provides similar functionality to a PHIGS 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 PHIGS stroke devices. 
 
This escape is not associated with any PHIGS input device and can be used without initializing any PHIGS input device.  It is intended to allow the application to implement its own stroke device using the standard X Event mechanism. 

C Input Parameters

func_id
The function identifier for this escape is PUESC_DRAWABLE_POINTS_TO_WC, which is defined in phigs.h to be -5. 

inA 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:

struct {
Pintws_id;/∗ workstation identifier ∗/
Ppoint_list3points; /∗ x,y are drawable coords, z is DC∗/
} escape_in_u5;/∗ drawable points to WC ∗/

ws_idIndicates the workstation to use.  The views on this workstation will be used in the conversion to World Coordinates.  mapping. 

pointsThe 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 PHIGS DC Z value.  Ppoint_list3 is defined in phigs.h as follows:

struct {
Pintnum_points;/∗ number of Ppoint3s in the list ∗/
Ppoint3∗points;/∗ list of points ∗/
} Ppoint_list3

Ppoint3 is defined in phigs.h as follows:

struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
Pfloatz;/∗ z coordinate ∗/
} Ppoint_list3

storeThis parameter is not used in this escape function. 

C Output Parameters

outA pointer to a pointer to a Pescape_out_data union, which contains the escape_out_u5 member used by this escape function.  PHIGS 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:

struct {
Pintview_index;
Ppoint_list3points;
} escape_out_u5;

view_index 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. 

points 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. 

ERRORS

003Ignoring function, function requires state (PHOP, WSOP, ∗, ∗)

054Ignoring function, the specified workstation is not open

SEE ALSO

ESCAPE (3P)
INITIALIZE STROKE 3 (3P)

September 02, 1992