DdSetPickCallback(3D) — Kubota Pacfic Computer Inc. (Doré)

NAME

DdSetPickCallback − Set the picking callback object of a device

SYNOPSIS

void DdSetPickCallback(device, pickcallbackobj)
DtObject device;
DtObject pickcallbackobj;

FORTRAN:

CALL DDSPCB(DEVICE, PKCBOJ)
INTEGER∗4 DEVICE
INTEGER∗4 PKCBOJ

DESCRIPTION

DdSetPickCallback sets the device picking callback object, pickcallbackobj, to be used on the device, device.

Picking is a method of identifying displayable primitive objects that fall within a specified volume known as a device pick aperture (see DdSetPickAperture). A pick is initiated by a call to DdPickObjs <DDPO>. The pick callback is a callback object that selects which primitive objects found within the pick aperture during a pick (known as "hits") will actually be returned. Dor´
e currently provides three standard pick callback objects that may be used; however, users may also easily provide their own. The standard callback objects are:

DcPickFirst <DCPKFR>
Accept only the first hit found.

DcPickClosest <DCPKCL>
Accept only the hit that was frontmost (closest to the viewer) in the pick aperture.

DcPickAll <DCPKAL>
Add all hits found to the hit list.

Users may want to add other types of callback objects such as those that accept or exclude only hits on certain types of objects or those that accept only up to a maximum number of hits before terminating a search.

The following information is intended mainly for users who wish to create their own pick callback objects.

DdSetPickCallback specifies a callback object that is called each time a hit is detected. That callback gets to peek at each pick path generated by pick hits and decide what to do with the hit. Users create their own pick callback objects by writing a function and making the function into an object using the function, DoCallback <DOCB>. The function in C should look like this:

DtHitStatus my_callback_fcn(data, path_elements, path,
         z_value, view, hits);
DtPtr data;               /∗ if data is a pointer to data ∗/
Dt32Bits data;            /∗ if data is a value ∗/
DtInt path_elements;
DtInt ∗path;
DtReal z_value;
DtObject view;
DtInt hits;

FORTRAN:

INTEGER∗4 FCN(DATA,PTHELE,PATH,ZVAL,VIEW,
+ HITS)
INTEGER∗4 DATA
INTEGER∗4 PTHELE
INTEGER∗4 PATH
REAL∗8 ZVAL
INTEGER∗4 VIEW
INTEGER∗4 HITS

The function takes the following six arguments:

data A Dt32Bits or DtPtr that contains associated run-time data to be passed to the function (see DoCallback).

path_elements
An integer specifying the number of pick elements in the pick path.

path A returned integer that is the beginning of the pick path (described below).

z_value
A real number specifying the depth of the closest point of the hit (in device coordinates).

view An object specifying the view in which the hit was found.

hits An integer specifying the total number of hits accepted so far during this pick.

A "hit" primitive is uniquely identified by its pick path. A pick path is a list of pick elements that trace the display tree nodes between the root object and the picked primitive. Each pick element, for a particular node, consists of three values in the display tree:

The object handle for this node’s object.

The current pick ID for this node.

The location within this group of the next node. This location is the same as the group element number of the next node in the pick path. Note that the last pick element in the path (or first, if the pick path order is DcBottomFirst <DCBOTF>) refers to the primitive that was hit instead of a containing group object. The location of the next node within this primitive object is undefined because this primitive object is the last node (and this primitive object is not a group).

The pick path passed to the callback function will always be ordered from the root node of the group network down to the picked primitive regardless of the current value of the device’s pick path order. The function can choose whether to accept this hit and add it to the hit list that will be returned by the current pick, reject the hit, or overwrite the previous hit (path) accepted.

The pick callback function must return a value of type DtHitStatus. Valid values are:

DcHitAccept <DCHACC>
DcHitReject <DCHREJ>
DcHitOverwrite <DCHOVW>

Returning DcHitOverwrite <DCHOVW> when no hits have yet been accepted behaves the same as DcHitAccept <DCHACC>. Any other returned value will result in a DcPickBadStatus <DCPBAD> error word being generated and returned by the current call to DdPickObjs <DDPO>.

The callback function can choose to stop the execution of the current group or can abort the pick altogether by calling DsExecutionReturn <DSER> or DsExecutionAbort <DSEA>. An aborted pick will still return the paths of all the hits previously accepted.

Pickability is controlled by the pickability switch attribute. Its value is determined by DoPickSwitch <DOPS> and also by name sets and filters (see DoNameSet and DoFilter). The invisibility attribute is treated similarly. Primitive objects which are invisible or unpickable cannot be picked. By default, all objects are not pickable.

ERRORS

DdSetPickCallback will fail if passed an invalid device handle or pick callback object.

[WARNING - invalid device handle]

[WARNING - invalid pick callback object]

DEFAULTS

The default DdSetPickCallback is DcPickFirst <DCPKFR>.

Museum