DdPickObjs(3D)

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;
long  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.

index
    A 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 long large. For 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.

views
    An 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)