pfvPicker(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
NAMEpfvPicker - Coordinate user-interaction with 3D scene elements
FUNCTION SPECIFICATION
#include <Performer/pfv/pfvPicker.h>
int pfvPicker::getState();
static void pfvPicker::printState(char*t, int s);
pfScene* pfvPicker::getScene();
void pfvPicker::setScene( pfScene* _scene );
pfChannel* pfvPicker::getChannel();
void pfvPicker::setChannel(pfChannel*_chan);
int pfvPicker::setNodeDataSlot(int slot_index);
int pfvPicker::setNodeDataSlot(char* slot_name);
int pfvPicker::getNodeDataSlot();
virtual void pfvPicker::update();
pfvInteractor* pfvPicker::pick();
virtual int pfvPicker::computeIsectSeg();
void pfvPicker::getPickResults(pfvInteractor** ia);
void pfvPicker::getPickResults(pfNode** node);
pfHit ** pfvPicker::getPickList();
pfvSelector* pfvPicker::getDefaultSelector();
pfvSelector* pfvPicker::setDefaultSelector(pfvSelector* s);
pfvSelector* pfvPicker::getCurSelector();
pfvInteractor* pfvPicker::getCurInteractor();
virtual int pfvPicker::grantRequest(pfvPickerRequest* req,
int event=0);
virtual int pfvPicker::setState(int s, pfvSelector*sel,
pfvInteractor* ia);
Page 1
pfvPicker(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
virtual int pfvPicker::collectEvents();
pfList* pfvPicker::getEventList();
DESCRIPTION
The pfvPicker class is used to set up and coordinate user-interaction
with 3D scene elements. pfvPicker is a generic, virtual base-class that
should not be created directly by users. Derived pickers such as
pfvMousePicker or pfvInputMngrPicker should be used instead.
pfvPicker::getState() returns the current state of picker. Returned
value is a bitmask. The following bits could be set:
PFPICKER_ALLOW_HLITE indicates that hliting is currently ON. ie, the
picker will determine which scene element has current focus by carrying
out intersection tests on every frame. The pfvInteractor associated with
the picked geometry will be given a chance to accept hlite state.
PFPICKER_FOCUS_EVENT indicates that hliting is currently OFF, and picker
will not carry out intersection tests on each frame unless events have
been generated, in which case an intersection test will determine which
geometry is currently in focus, and events will be sent to the
pfvInteractor associated with such geometry.
PFPICKER_HLITE indicates that some pfvInteractor is currently detaining
hlited status. A handle to this pfvInteractor can be obtained through
method pfvPicker::getCurInteractor().
PFPICKER_INTERACT indicates that some pfvInteractor is currently carrying
out interaction. A handle to this pfvInteractor can be obtained through
method pfvPicker::getCurInteractor().
PFPICKER_SELECT indicates that some pfvSelector is currently managing
object selection. A handle to this pfvSelector can be obtained through
method pfvPicker::getCurSelector().
PFPICKER_MANIP that some pfvSelector is currently carrying out
interaction while managing object selection. A handle to this pfvSelector
can be obtained through method pfvPicker::getCurSelector().
pfvPicker::printState() prints out a list of tokens representing current
picker state and may be used for debugging.
pfvPicker::getScene() returns a handle to the pfScene associated with
picker.
pfvPicker::setScene() associates a pfScene to picker. This is the scene
that will be traversed by picker in order to determine which scene
elements and corresponding pfvInteractors have current focus.
pfvPicker::getChannel() returns a handle to the pfChannel associated with
picker.
Page 2
pfvPicker(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
pfvPicker::setChannel() associates pfChannel _chan to picker. Note that
pfScene associated with picker will automatically be updated to be equal
to the pfScene returned by _chan->getScene.
pfvPicker::setNodeDataSlot(int slot_index) associates picker with
userslot with index slot_index. This means that when a pfNode is found to
be under current focus, a pointer to pfvInteractor will be looked for at
node's userslot with index slot_index (see man page for
pfObject::getUserData).
pfvPicker::setNodeDataSlot(char* slot_name) associates picker with
userslot with name slot_name. This means that when a pfNode is found to
be under current focus, a pointer to pfvInteractor will be looked for at
node's userslot with name slot_name (see man page for
pfObject::getNamedUserDataSlot). Note that this method looks up and
stores the slot index associated with slotname. If a slot name with such
name does not exist, it will be created by this call.
pfvPicker::getNodeDataSlot() returns the slot index associated with
picker. If no data slot has been assigned through
pfvPicker::setNodeDataSlot, this method returns -1.
pfvPicker::update instructs picker to carry out its per-frame
functionality. If picker's state includes PFPICKER_ALLOW_HLITE, picker
will start by determining which pfNode has current focus, and will
dispatch endHlite and startHlite callbacks to pfvInteractors falling out
of and into focus respectively.
Note that if picker's state also includes PFPICKER_SELECT, current
selector will be asked to grant permissions before other pfvInteractors
will be offered the opportunity to hlite. This is done through method
pfvSelector::getPermissions. (see man page for pfvSelector).
After dealing with hlite updates, picker will examine the list of events
that have been collected since the last call to pfvPicker::update.
Events are collected through the virtual method pfvPicker::collectEvents,
thus the type of events collected by picker depends on the actual picker
implementation. (see man pages for pfvMousePicker and pfvInputMngrPicker
for two examples of picker implementations). If no events have been
collected, a NULL event will be added to event list.
The list of collected events is then examined, and for each event, picker
will do the following:
if picker state includes PFPICKER_MANIP, event is passed on to current
selector through pfvSelector::updateManip,
else if picker state includes PFPICKER_INTERACT, event is passed on to
current interactor through pfvInteractor::updateInteraction.
else if picker state includes PFPICKER_HLITE, event is passed on to
current interactor through pfvInteractor::updateHlite.
Page 3
pfvPicker(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
else if picker state includes PFPICKER_FOCUS_EVENT, picker will isect the
scene to determine if some geometry is currently under focus, and will
look for a pointer to pfvInteractor in pfNodes' user slots. If a
pfvInteractor is found, event will be passed on to it through
pfvInteractor::specialFocus.
Note that NULL events (inserted by picker on frames where no events were
generated) will not be passed on through the specialFocus method.
Note also that if there is a current selector, it will be asked to grant
permissions through pfvSelector::getPermissions before events are passed
on to any other interactor.
pfvPicker::pick() causes a 3d segment into the 3d scene to be computed,
and an intersection test carried out between that segment and 3d geometry
contained in scene. The 3d segment that will be tested for intersection
depends on the actual picker implementation. Both pfvMousePicker and
pfvInputMngrPicker will compute isect segment based on current mouse
position. Other pickers could be implemented which compute their isect
segment based on the position of a tracked input device, such as a space
wand, for example.
pfvPicker::computeIsectSeg() is the virtual method that picker will call
in order to compute the 3D segment that will be used for scene
intersection. Aaplication code should never need to call this method
directly.
pfvPicker::getPickResults(pfvInteractor** ia) will copy a pointer to the
pfvInteractor assigned to the geometry that was picked by the last call
to pfvPicker::pick. If no geometry was picked, or if no pfvInteractors
were associated with picked geometry, this method returns NULL.
pfvPicker::getPickResults(pfNode** node) will copy a pointer to the
pfNode that was picked by the last call to pfvPicker::pick. If no
geometry was picked, this method returns NULL.
pfvPicker::getPickList() returns a pointer to an array of pfHit pointers,
each pointing to a pfHit record as returned by picker's intersection
test. If multiple hits are returned, the first element of the returned
array will point to the pfHit record corresponding to the nearest
intersection point.
Note that in current implementation of pfvPicker only one pick result is
returned as the first element of the returned array.
The following example shows how to obtain a pointer to the pfGeoSet
picked by picker's isect traversal:
Page 4
pfvPicker(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
pfvPicker* picker;
...
p->pick();
pfHits**hits = p->getPickedList();
pfGeoSet* gset;
if(hits[0])
hits[0]->query(PFQHIT_GSET,&gset);
pfvPicker::setDefaultSelector() sets the default selector for picker. If
a default selector has been set, picker will automatically make it the
current selector whenever state would otherwise have no current selector.
pfvPicker::getDefaultSelector() returns a pointer to picker's default
selector, if one has been set through pfvPicker::setDefaultSelector(), or
NULL otherwise.
pfvPicker::getCurSelector() will return the current selector if picker's
state includes PFPICKER_SELECT or PFPICKER_MANIP, else it will return
NULL.
pfvPicker::getCurInteractor() will return the current interactor if
picker's state includes PFPICKER_HLITE or PFPICKER_INTERACT, else it will
return NULL.
pfvPicker::setState() requests a state change for picker. Parameter s
indicates the desired new state. If state s implies that a current
interactor or current selector should be known to picker, the sel and ia
arguments will be used to provide pointers to the desired current
selector and interactor. Note that this method may trigger interactor
and/or selector callbacks to be called by picker in order to inform them
of the state change.
pfvPicker::grantRequest is an alternative method for requesting a new
state for picker. The argument is a pointer to a pfvPickerRequest
structure which contains three members: an integer indicating desired new
state, a pointer to pfvInteractor and one to pfvSelector indicating the
desired current interactor and/or selector.
pfvPicker::collectEvents() is the virtual method that picker will call in
order to produce a list of all events generated since last frame.
Aaplication code should never need to call this method directly.
pfvPicker::getEventList() can be called to obtain a pointer to a list of
all the events collected by the last call to pfvPicker::collectEvents().
Page 5
pfvPicker(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
NOTES
For examples of uses of the pfvPicker API, look at the sample code in
/usr/share/Performer/src/pguide/libpfv/picker and the README file
contained in that directory.
SEE ALSO
pfvInputMngr, pfvMousePicker, pfvInputMngrPicker, pfvInteractor,
pfvSelector
Page 6
