NAME

DdPickObjs − Initiate a pick on a device

SYNOPSIS

C:

void DdPickObjs(device, pick_point, hit_count,
                index_size, index, list_size, hit_list,
z_values, wcs_values, lcs_values,
views, error_word)
DtObject device;
DtPoint3 pick_point;
DtInt ∗hit_count;
DtInt index_size;
DtInt index[];
DtInt list_size;
DtInt hit_list[];
DtReal z_values[];
DtReal wcs_values[];
DtReal lcs_values[];
DtObject views[];
DtInt ∗error_word;

FORTRAN:

CALL DDPO(DEVICE, PICKPT, HITCNT, IDXSIZ,
INDEX, LSTSIZ, HITLST, ZVALUS,
WCSVAL, LCSVAL, VIEWS,
ERRWRD)
INTEGER∗4 DEVICE
REAL∗8(3) PICKPT
INTEGER∗4 HITCNT
INTEGER∗4 IDXSIZ
INTEGER∗4 INDEX(∗)
INTEGER∗4 LSTSIZ
INTEGER∗4 HITLST(∗)
REAL∗8 ZVALUS(∗)
REAL∗8 WCSVAL(∗)
REAL∗8 LCSVAL(∗)
INTEGER∗4 VIEWS(∗)
INTEGER∗4 ERRWRD

DESCRIPTION

DdPickObjs initiates a pick on a device.  Picking is a method of identifying the drawable objects that fall within a specified volume known as a pick aperture (see DdSetPickAperture).  These objects are known as "hits" and are uniquely identified by a pick path (see DdSetPickCallback for the definition of a pick path).  Picking is usually initiated via an input device by a user who wants to address a particular object on the screen. 

pick_point
A coordinate triple that specifies a point in device coordinates around which to search for hits.

hit_count
The integer count of the number of hits found within the pick aperture whose paths are being returned.

index_size
The size of the array index. 

indexA user-supplied array large enough for index_size number of 32-bit integers.  Returned in the array index are the indices into the hit_list array of the beginnings of the pick paths being returned.  The last element in the path beginning at hit_list[index[i]] is always one element before hit_list[index[i+1]].  This is true for the last path as well, which means that if the application expects to find n hits, it must provide an index array with a size of at least n + 1. 

list_size
The size of the array hit_list. 

hit_list
A user-supplied array large enough for list_size/3 number of pick path elements, where each pick path element is three DtInts large.  FORTRANr a definition of pick path elements, see DdSetPickCallback.)  hit_count pick paths are returned in this array, where each pick path may have a different number of pick path elements in it. 

z_values
An optional user-supplied array large enough for index_size - 1 DtReals.  Returned here are the depth values in device coordinate units of the closest point within the pick aperture of the corresponding hits whose paths are referred to in index.  The value DcNullPtr <DCNULL> may be given if the user is not concerned with the depth values. 

wcs_values
An optional user-supplied array large enough for 3∗(index_size - 1) DtReals.  Returned here are the world coordinate values of the closest point within the pick aperture of the corresponding hits whose paths are referred to in index.  The world coordinate of hit n is wcs_values[n∗3], wcs_values[n∗3+1], wcs_values[n∗3+2].  The value DcNullPtr <DCNULL> may be given if the user is not concerned with the world coordinate values. 

lcs_values
An optional user-supplied array large enough for 3∗(index_size - 1) DtReals.  Returned here are the local coordinate values of the closest point within the pick aperture of the corresponding hits whose paths are referred to in index.  The local coordinates are the coordinates in which the object’s geometry was defined.  The local coordinate of hit n is lcs_values[n∗3], lcs_values[n∗3+1], lcs_values[n∗3+2].  The value DcNullPtr <DCNULL> may be given if the user is not concerned with the local coordinate values. 

viewsAn optional user-supplied array large enough for (index_size - 1) DtObjects.  Returned here is an array of view objects that corresponds to the views in which the hits were found.  The value DcNullPtr <DCNULL> may be given if the user is not concerned with views. 

error_word
A returned error word.

The value of the error word returned is a bit field that is the logical or of zero or more of the following constants:

DcPickBadStatus <DCPBAD>
A bad status error results from an illegal pick control status returned by a pick callback (see DdSetPickCallback). 

DcPickListOverflow <DCPLOV>
A list overflow occurs when the array hit_list is too small to accommodate another hit. 

DcPickIndexOverflow <DCPIOV>
An index overflow occurs when the array index is too small to accommodate another hit. 

In all these cases, the user is still returned data from the previous hits that were recorded.  Application programs may still wish to use this data or, if the errors result from lack of space, they may decide either to allocate more space or to use a smaller pick aperture and then try the same pick again. 

ERRORS

DdPickObjs will fail if passed an invalid device handle. 

[WARNING - invalid device handle]

SEE ALSO

DdInqPickAperture(3D), DdInqPickCallback(3D), DdInqPickPathOrder(3D), DdSetPickAperture(3D), DdSetPickCallback(3D), DdSetPickPathOrder(3D), DoFilter(3D), DoPickID(3D), DoPickSwitch(3D)

September 02, 1992