pfvInteractor(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
NAMEpfvInteractor - Manage user-interaction with a scene or a subset of a
scene.
FUNCTION SPECIFICATION
#include <Performer/pfv/pfvPicker.h>
pfvInteractor::pfvInteractor(pfvXmlNode* xml=NULL);
virtual int pfvInteractor::getActive(pfvPicker*p);
virtual int pfvInteractor::startHlite( pfvPicker*p, int prmsn );
virtual int pfvInteractor::updateHlite( pfvPicker* p, int ev,
int prmsn, pfvPickerRequest*r );
virtual void pfvInteractor::endHlite( pfvPicker* p );
virtual int pfvInteractor::specialFocus( pfvPicker* p, int ev,
int prmsn, pfvPickerRequest*r );
virtual int pfvInteractor::startInteraction( pfvPicker*p, int ev /*,
int prmsn*/ );
virtual int pfvInteractor::updateInteraction( pfvPicker* p, int ev,
int prmsn, pfvPickerRequest*r );
virtual void pfvInteractor::endInteraction( pfvPicker* p );
int pfvInteractor::getState();
int pfvInteractor::isHlited();
int pfvInteractor::isInteracting();
virtual void pfvInteractor::nodeSetup( pfNode* node, int slotIndex );
void pfvInteractor::nodeSetup( pfNode* node, pfvPicker* p );
void pfvInteractor::nodeSetup( pfNode* node, char*slotName );
void pfvInteractor::nodeSetup( pfNode*node );
static void pfvInteractor::clearNodeSlot( pfNode* node,
int slotIndex );
static void pfvInteractor::clearNodeSlot( pfNode* node,
pfvPicker* p );
static void pfvInteractor::clearNodeSlot( pfNode* node,
char*slotName );
Page 1
pfvInteractor(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
static void pfvInteractor::clearNodeSlot( pfNode*node );
DESCRIPTION
The pfvInteractor class is a base class for setting up and managing
user-interaction with a scene or a portion of a scene. Instances of
pfvInteractor objects are not expected to be created by applications;
instead applications should derive their own classes from pfvInteractor,
and implement specific interaction through the implementation of
pfvinteractor's virtual methods.
pfvInteractors work in conjunction with pfvPicker objects. A single
ppfvPicker may coordinate the action of multiple interactors. Basically,
the picker will isect a scene to determine which pfNode is currently
under focus; It will then try to find the pfvInteractor that has been set
up to manage interaction for picked node. Assignment of a pfvinteractor
to a pfNode is done through the use of Named Data Slots (see man page for
pfObject::getNamedUserDataSlot). Each picker will be configured to look
at a certain slot index. The picked node user-slot is examined first: if
slot contains a pointer to an active pfvInteractor, the search ends. If
user-slot is NULL, then picker continues its search for an interactor by
looking at node's parent data-slot, and walks up the pfNode hierarchy
until a pointer to an active interactor is found or the pfScene root-
node is found. Note that pfvinteractors can also be assigned to pfScene
nodes.
A pfvInteractor supports the following functionalities:
HLITE: If picker state includes PFPICKER_ALLOW_HLITE, when picker focus
is on some geometry managed by interactor, interactor can accept hlite
state. A pfvInteractor may decide to render hlited geometry in a
different style (eg: wireframe), or to change cursor shape, in order to
signal to the user that interaction with hlited geometry will take place
if user generates the right events (actual event types depend on picker
implementation).
FOCUS_EVENTS: When picker state includes PFPICKER_FOCUS_EVENT,
interactor will receive events from picker if these are generated while
focus is over some geometry managed by interactor. Interactor can ignore
each event, or respond to it by carrying out a one-time action, or by
accepting INTERACT state, which allows interactions to be carried out
over a number of frames, such as for example dragging a slider, or
rotating an object.
INTERACTION: Once interactor has requested INTERACT state, picker will
guarantee at least one call to pfvInteractor::updateInteraction on each
frame (the number of updates is greater if more than one event were
collected by picker during current frame).
pfvInteractor::getActive will be called by picker (with a pointer to
itself passed on as an argument) in order to establish whether interactor
can be used for managing interaction with picked geometry. Base class
pfvInteractor implementation of this method simply returns 1, derived
Page 2
pfvInteractor(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
interactors may decide to override this behavior based on their specific
requirements. A return of 0 from pfvInteractor::getActive causes the
picker to continue its search for an active interactor among ancestors of
queried node.
pfvInteractor::startHlite will be called by picker to offer interactor a
chance to accept hlite state. This will only happen if picker's state
includes PFPICKER_ALLOW_HLITE, and if focus is currently over geometry
assigned to this interactor through node data slot assignment. Interactor
may return 0 to reject hlite state, or non-zero to accept it. The value
of parameter prmsn will contain the permission mask granted by picker's
current selector. prmsn is a bitwise integer containing any of the
following tokens:
o PFPICKER_HLITE, indicating that interactor has permissions
to accept hlite state.
o PFPICKER_INTERACT, indicating that interactor has permission
to request and enter
interact state.
o PFPICKER_SELECT, indicating that interactor has permission to
request select state.
Note however that pfvInteractors cannot accept select state. See man page
for pfvSelector for details of how to carry out object selection through
the pfvPicker API. Note also that if picker has no current selector,
permissions will be equal to PFPICKER_FULL_PERMISSIONS.
pfvInteractor::updateHlite will be called by picker on every frame while
interactor maintains hlited state. If events have been collected by
picker while interactor is in hlited state, events will be passed as
argument ev in pfvInteractor::updateHlite. Parameter prmsn indicates the
level of permissions granted by picker's current selector.
pfvInteractor::endHlite will be called by the picker to indicate that
focus is no longer over geometry assigned to interactor, and thus
interactor must leave hlite state. Interactor is expected to restore
normal appearance of hlited geometry, or restore cursor shape
accordingly.
pfvInteractor::specialFocus will be called by picker when picker's state
includes PFPICKER_FOCUS_EVENT, and an event has been generated while
focus is over geometry assigned to this interactor. Parameter ev will
indicate which event was generated, prmsn will indicate the permission
level granted by picker's current selector, and r will point to a
pfvPickerRequest structure initialized to picker's current state, which
can be modified by interactor in order to request a state change.
pfvInteractor::startInteraction will be called by picker in order to
offer interactor a chance to accept INTERACT state. Usually this will
happen in response to a request made by interactor itself through methods
updateHlite or specialFocus. Alternatively, this can happen if method
Page 3
pfvInteractor(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
pfvPicker::setState or pfvPicker::grantRequest were called with request
state including PFPICKER_HLITE or PFPICKER_INTERACT, and a pointer to
this as requested interactor.
pfvInteractor::updateInteraction will be called by picker on every frame
while interactor maintains INTERACT state. If events have been collected
by picker while interactor is in hlited state, events will be passed as
argument ev in pfvInteractor::updateInteraction. Parameter prmsn
indicates the level of permissions granted by picker's current selector.
pfvInteractor::endInteraction will be called by the picker to indicate
that interactor must leave INTERACT state.
pfvInteractor::getState returns interactor's current state. This may
include PFPICKER_HLITE or PFPICKER_INTERACT indicating that interactor is
currently in hlite or in interact state respectively.
pfvInteractor::isHlited returns 1 if interactor is currently in HLITED
state, 0 otherwise.
pfvInteractor::isInteracting returns 1 if interactor is currently in
INTERACT state, 0 otherwise
pfvInteractor::nodeSetup(pfNode* node, int slotIndex) sets the data slot
with index slotIndex of node to point to this interactor.
pfvInteractor::nodeSetup(pfNode* node, pfvPicker* p) first queries picker
to find out which data slot is of interest to it, then sets the
appropriate data slot of node to point to this interactor.
pfvInteractor::nodeSetup(pfNode* node, char*slotName) sets the named slot
of node to point to this interactor.
pfvInteractor::nodeSetup(pfNode*node) sets the slot named "PFPICKER" of
node to point to this interactor.
pfvInteractor::clearNodeSlot(pfNode* node, int slotIndex) sets the slot
with index slotIndex of node to NULL.
pfvInteractor::clearNodeSlot(pfNode* node, pfvPicker* p) first queries
picker to find out which data slot is of interest to it, then sets the
appropriate data slot of node to NULL.
pfvInteractor::clearNodeSlot(pfNode* node, char*slotName) sets the named
slot of node to NULL.
pfvInteractor::clearNodeSlot(pfNode*node) sets the slot named "PFPICKER"
of node to NULL.
Page 4
pfvInteractor(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
pfvPicker, pfvMousePicker, pfInputMngrPicker, pfSelector, pfObject
Page 5
