NAME

ESCAPE -4 − map a X drawable point to a PHIGS pick path

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;pointer to the buffer
Pescape_out_data∗∗out; OUT output data of the function

Required PHIGS Operating States

(PHOP, ∗, WSOP ∗)

DESCRIPTION

Purpose

ESCAPE -4 attempts to map a single X drawable coordinate point to a PHIGS pick path using the specified workstation. 

ESCAPE -4 provides similar functionality to a PHIGS pick device, but it uses a point provided by the application rather than directly by the operator.  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 pick device using the standard X Event mechanism. 

C Input Parameters

Applications using the C binding must create a buffer to be used by this function as memory space for storing data associated with the device state.  This buffer is passed as the store argument. 

The store buffer is a data area managed by PHIGS. While the application is responsible for creating the inital buffer through a call to CREATE STORE, PHIGS manages this area such that there is sufficient memory for the specific inquiry. The data record within the store buffer is accessed by the pointer pointed to by out. 

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

inA pointer to a Pescape_in_data union, which contains the escape_in_u4 member used by this escape function.  This member is defined in phigs.h as:

struct {
Pintws_id;
Ppointpoint;/∗ a drawable point -- not DC ∗/
Pfloatap_size;/∗ aperture size, half-width in DC units ∗/
Ppath_orderorder;
Pintdepth;/∗ depth of path to return ∗/
Pintpet;
Pecho_switchecho_switch;
Plimit3echo_volume;
Pfilterfilter; /∗ detectibility filter ∗/
} escape_in_u4;/∗ drawable point to pick ∗/

ws_idIndicates the workstation to use.  The structures posted to this workstation and the current workstation state will be used to attempt the mapping. 

pointA point, in X drawable units, that indicates the location of the pick aperture. 

ap_size
The size of the pick aperture, specified as the half-width of the aperture box in DC units.

orderThe order of the returned pick path.  The order can be either PORDER_TOP_FIRST, in which case the pick path will be returned in traversal order, or PORDER_BOTTOM_FIRST, in which case the pick path will be returned in the reverse of traversal order.  The order and depth parameters specify which portion of the complete pick path, if any, is returned. 

depthThe portion of the pick path to return.  If the order parameter is PORDER_TOP_FIRST then the first "depth" elements will be returned, if the order parameter is PORDER_BOTTOM_FIRST then the first "depth" elements in the inversely ordered pick path will be returned. 

petIndicates the echo method to use for picked primitives. 

echo_switch
Indicates whether or not picked primitives should be echoed.

echo_volume
The echo volume.

filterThe detectibility filter to use for the pick. 

storeThis parameter is not used for this escape. 

C Output Parameters

outA pointer to a pointer to a Pescape_out_data union, which contains the escape_out_u4 member used by this escape function.  PHIGS copies a pointer to the pick status and pick path, if any, to this member of the Pescape_out_data union.  This member is defined in phigs.h as:

struct {
Pin_statusstatus;
Ppick_pathpick;
} escape_out_u4;

status contains the status of the pick.  PIN_STATUS_OK indicates that the pick was successful and a pick path is returned in the pick field.  PIN_STATUS_NONE indicates that no primitive met the pick criteria.  The contents of the pick field are undefined in this case. 

pick contains the pick path if the status is PIN_STATUS_OK. 

ERRORS

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

054Ignoring function, the specified workstation is not open

254Ignoring function, invalid echo area/volume; XMIN >= XMAX, YMIN >= YMAX, or ZMIN > ZMAX

255Ignoring function, one of the echo area/volume boundary points is outside the range of the device

SEE ALSO

ESCAPE (3P)
INITIALIZE PICK 3 (3P)
CREATE STORE (3P)
DELETE STORE (3P)

September 02, 1992