NAME

DdPick − This function is obsolete and has been replaced by DdPickObjs

SYNOPSIS

C:

void DdPick(device, pick_point, hit_count, index_size,
                index, list_size, hit_list, z_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[];
DtObject views[];
DtInt ∗error_word;

FORTRAN:

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

DESCRIPTION

DdPick 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 number of hits found within the pick aperture whose paths are being returned.

index_size
The size of the array index. 

index   
A pointer to user supplied space large enough for index_size number of 32-bit integers. 

list_size
The size of the array hit_list. 

hit_list
A pointer to user supplied space (an array) large enough for list_size/3 number of pick path elements.  Note that a pick path element is three DtInts large.  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."

z_values
An optional pointer to a user supplied space (an array) large enough for (index_size - 1) DtReals.  Returned here are the depth values in picking coordinates 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. 

viewsAn optional pointer to a user supplied space (an 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
The 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>
DcPickListOverflow <DCPLOV>
DcPickIndexOverflow <DCPIOV>

A bad status error results from an illegal pick control status returned by a pick callback (see DdSetPickCallback).  List and index overflows occur when either the array hit_list or index are 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

DdPick will fail if passed an invalid device handle. 

[WARNING - invalid device handle]

DdPick will fail if index_size or list_size are invalid

[WARNING - non-positive index or list size]

DdPick will fail if Doré is already performing a traversal of the database

[WARNING - traversal already in progress]

SEE ALSO

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

September 02, 1992