pfvModule(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
NAMEpfvModule - Base Class for Modular Extension in pfvViewer Applications.
FUNCTION SPECIFICATION
#include <Performer/pfv/pfvViewer.h>
static pfvModule* pfvModule::load(char*className, char* dsoName=NULL,
pfvXmlNode*xml=NULL);
static pfvModule* pfvModule::load(char*className, pfvXmlNode*xml,
char* dsoName=NULL);
static char* pfvModule::getLoadPath();
static void pfvModule::setLoadPath(char*path);
int pfvModule::getScope();
int pfvModule::getScopeIndex();
pfvObject* pfvModule::getScopeTarget();
int pfvModule::autoScope( int*scopeIndex );
void pfvModule::bindCallback(int which);
void pfvModule::unbindCallback(int which);
int pfvModule::getCBMask();
virtual void pfvModule::preConfig();
virtual void pfvModule::postConfig();
virtual void pfvModule::enterView(pfvView*v);
virtual void pfvModule::exitView(pfvView*v);
virtual void pfvModule::enterWorld();
virtual void pfvModule::exitWorld();
virtual void pfvModule::sync();
virtual void pfvModule::frame();
virtual void pfvModule::preCull(pfvDispChan*chan);
virtual void pfvModule::postCull(pfvDispChan*chan);
Page 1
pfvModule(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
virtual void pfvModule::preDraw(pfvDispChan*chan);
virtual void pfvModule::postDraw(pfvDispChan*chan);
virtual void pfvModule::overlay(pfvDispChan*chan);
int pfvModule::bindKeys(char*keys);
int pfvModule::unbindKeys(char*keys)
char* pfvModule::getEventMask()
void pfvModule::setEventMask(char* str);
virtual int pfvModule::handleEvent(int evType, char key);
uint64_t pfvModule::getViewMask();
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfvModule is derived from the parent class
pfvobject, so each of these member functions of class pfvobject are also
directly usable with objects of class pfvModule. This is also true for
ancestor classes of class pfvobject.
virtual int pfvObject::parseXml(pfvXmlNode*xml);
virtual int pfvObject::setXmlField(pfvXmlNode*xml);
char* pfvObject::getName();
void pfvObject::setName(char*_name);
Since the class pfvobject is itself derived from the parent class
pfObject, objects of class pfvModule can also be used with these
functions designed for objects of class pfObject.
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, pfFluxMemory *fmem);
void pfObject::setUserData(void *data);
void pfObject::setUserData(int slot, void *data);
void* pfObject::getUserData(pfObject *obj);
void* pfObject::getUserData(pfObject *obj, int slot);
int pfObject::getNumUserData();
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfvModule can also be used with these
functions designed for objects of class pfMemory.
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
Page 2
pfvModule(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
int pfMemory::isExactType(pfType *type);
const char * pfMemory::getTypeName();
int pfMemory::copy(pfMemory *src);
int pfMemory::compare(const pfMemory *mem);
void pfMemory::print(uint which, uint verbose, char *prefix,
FILE *file);
int pfMemory::getArena(void *ptr);
void* pfMemory::getArena();
int pfMemory::ref();
int pfMemory::unref();
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
DESCRIPTION
The pfvModule class is a virtual base-class from which all pfvViewer
modular extenders (Modules) must be derived. pfvModule allows derived
classes to register callbacks with the pfvViewer, and through these a
range of different features/functionalities can be implemented.
Furthermore, when creating applications with multiple worlds or multiple
views, the action of individual modules can be restricted to only affect
a single world or a single view. This is referred to as Module Scoping.
pfvModule::load(char*className, char* dsoName, pfvXmlNode*xml) and
pfvModule::load(char*className, pfvXmlNode*xml, char* dsoName) will
attempt to load a new module. A ClassName must be provided. A dsoName
(eg: libfoo.so) may also be provided, otherwise dsoName will be derived
from className like this: sprintf(dsoName,"lib%s.%s", className, ext ),
ext being equal to "so" on IRIX and LINUX, and to "dll" on WIN32. The
viewer will look for a library with the required name, trying the
provided name first, then prepending all paths listed in the environment
variable PFV_MODULE_PATH, then prepending all paths provided through
pfvModule::setLoadPath (or through XML configuration file). Finally,
libraries will be looked for in libpfv standard location:
($PFROOT)/usr/lib/libpfv/3.1. The module will be loaded through a C
function that must be defined in the module library. The name of this C
function is derived by prepending 'pfvLoadModule_' to the module's
className, For examples of pfvModule implementations, look at the code
and Makefiles for the sample pfvm modules in
/usr/share/Performer/src/pguide/libpfv/viewer/modules/.
pfvModule::setLoadPath() specifies one or more search path locations.
These locations are directories to be searched for module libraries by
method pfvModule::load. Note that search path specified through the
environment variable PFV_MODULE_PATH take precedence over the path
specified by pfvModule::setLoadPath().
pfvModule::getLoadPath() returns the current search path for module
Page 3
pfvModule(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
libraries, as set by the last call to pfvModule::setLoadPath().
pfvModule::getScope() will return an integer indicating how module is
scoped. Possible values are: PFV_SCOPE_GLOBAL (module is scoped
globally, the default), PFV_SCOPE_VIEW (module is scoped to a single
view), or PFV_SCOPE_WORLD (module is scoped to a single world). If module
has not yet been attached to the viewer through method
pfvViewer::addModule, this method will return 0.
If module is scoped to a world, pfvModule::getScopeIndex will return the
index of target world. If a module is scoped to a view,
pfvModule::getScopeIndex will return the index of target view. If module
has not yet been attached to the viewer through method
pfvViewer::addModule, or if module is globally scoped, this method will
return -1.
If module is scoped to a world, pfvModule::getScopeTarget() will return a
pointer to the target world. If module is scoped to a view,
pfvModule::getScopeTarget() will return a pointer to the target view. If
module has not yet been attached to the viewer through method
pfvViewer::addModule, or if module is globally scoped, this method will
return NULL.
If a pfvModule is added to the pfvViewer through method
pfvViewer::addModule with PFV_SCOPE_AUTO as scope, the pfvViewer will
call the module's autoScope method to determine module's scope.
pfvModule::autoScope must return one of: PFV_SCOPE_GLOBAL,
PFV_SCOPE_WORLD or PFV_SCOPE_VIEW. Additionally, if module is not to be
scoped globally, the index of the target world or view should be returned
in parameter scopeIndex. See man page for pfvViewer for additional info
on module auto scoping.
pfvModules implement their functionalities through callback functions
that will be dispatched by the pfvViewer from a number of entry points in
various processes throughout the life of the application.
pfvModule::bindCallback() adds the callback associated with index 'which'
to the list of active callbacks for this module.
pfvModule::unbindCallback() removes the callback associated with index
'which' from the list of active callbacks for this module.
The following callbacks may be bound by a module:
PFV_CB_PRECONFIG
PFV_CB_POSTCONFIG
PFV_CB_SYNC
PFV_CB_FRAME
PFV_CB_PRECULL
FV_CB_POSTCULL
Page 4
pfvModule(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
PFV_CB_PREDRAW
PFV_CB_POSTDRAW
PFV_CB_OVERLAY
PFV_CB_ENTER_VIEW
PFV_CB_EXIT_VIEW
PFV_CB_ENTER_WORLD
PFV_CB_EXIT_WORLD
pfvModule::getCBMask() returns a bit mask indicating which callbacks are
currently bound to module. Each callback is associated with a bit in
mask. For example, callback PFV_CB_PRECULL corresponds to bit
(1<<PFV_CB_PRECULL)
If a module has bound its PFV_CB_PRECONFIG callback, the
pfvModule::preConfig() method will be called by the pfvViewer in the APP
process, from within pfvViewer::config method, just before calling
pfDisplayMngr::preConfig() and pfConfig().
If a module has bound its PFV_CB_POSTCONFIG callback, the
pfvModule::postConfig() method will be called by the pfvViewer in the APP
process, from within pfvViewer::config method, after calling pfConfig().
If a module is scoped to a pfvWorld and has bound its PFV_CB_ENTER_VIEW
callback, the pfvModule::enterView() method will be called by the
pfvViewer in the APP process from within pfvViewer::frame, to indicate
that module's target world will be viewed by a new view on next frame. A
world-scoped module may receive more than one call to this method on a
particular frame if more than one view are directed to target world on
same frame. Note that a handle to the pfvView being entered is passed as
an argument to pfvModule::enterView().
If a module is scoped to a pfvWorld and has bound its PFV_CB_EXIT_VIEW
callback, the pfvModule::exitView() method will be called by the
pfvViewer in the APP process from within pfvViewer::frame, to indicate
that module's target world will no longer be viewed by a specific view on
next frame. A world-scoped module may receive more than one call to this
method on a particular frame if more than one view are directed away from
target world on same frame. Note that a handle to the pfvView being
exited is passed as an argument to pfvModule::exitView().
If a module is scoped to a pfvView and has bound its PFV_CB_ENTER_WORLD
callback, the pfvModule::enterWorld() method will be called by the
pfvViewer in the APP process from within pfvViewer::frame, to indicate
that module's target view will be viewing a new pfvWorld on next frame.
No more than one call to this method may be received by any view-scoped
module on any one frame.
If a module is scoped to a pfvView and has bound its PFV_CB_EXIT_WORLD
callback, the pfvModule::exitWorld() method will be called by the
Page 5
pfvModule(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
pfvViewer in the APP process from within pfvViewer::frame, to indicate
that module's target view will no longer be viewing a certain pfvWorld on
next frame. No more than one call to this method may be received by any
view-scoped module on any one frame.
If a module has bound its PFV_CB_SYNC callback, the pfvModule::sync()
method will be called by the pfvViewer in the APP process from within
pfvViewer::sync. Note that if pfvViewer::sync is not called directly by
the application, it will automatically be called by pfvViewer::frame on
each frame. SYNC callbacks should only be used for latency critical
tasks (such as for example updating tracking device input). See man page
for pfSync for more info. Note that SYNC callbacks (as with other run-
time module callbacks) will not be dispatched for modules which are
scoped to a pfvWorld that is not being viewed by any visible view.
If a module has bound its PFV_CB_FRAME callback, the pfvModule::frame()
method will be called by the pfvViewer in the APP process from within
pfvViewer::frame, after all EXIT* and ENTER* callbacks have been
dispatched. FRAME callbacks is where most run-time processing is
expected to be carried out. Note that FRAME callbacks (as with other
run-time module callbacks) will not be dispatched for modules which are
scoped to a pfvWorld that is not being viewed by any visible view.
If a module has bound its PFV_CB_PRECULL callback, the
pfvModule::preCull() method will be called by the pfvViewer in a CULL
process just before calling pfCull() for a channel.
If a module has bound its PFV_CB_POSTCULL callback, the
pfvModule::postCull() method will be called by the pfvViewer in a CULL
process just after calling pfCull() for a channel.
Globally scoped modules will receive PRECULL and POSTCULL callbacks from
all channels in pfvViewer's channel-list. View-scoped modules will
receive PRECULL and POSTCULL callbacks from all channels in target-view
channel list, but not from channels belonging to other views. World-
scoped modules will receive PRECULL and POSTCULL callbacks from all
channels belonging to any view which is currently viewing target-world.
If a module has bound its PFV_CB_PREDRAW callback, the
pfvModule::preDraw() method will be called by the pfvViewer in a DRAW
process just after clearing a channel but just before calling pfDraw().
If a module has bound its PFV_CB_POSTDRAW callback, the
pfvModule::postDraw() method will be called by the pfvViewer in a DRAW
process just after calling pfDraw() for a channel.
Globally scoped modules will receive PREDRAW and POSTDRAW callbacks from
all channels in pfvViewer's channel-list. View-scoped modules will
receive PREDRAW and POSTDRAW callbacks from all channels in target-view
channel list, but not from channels belonging to other views. World-
scoped modules will receive PREDRAW and POSTDRAW callbacks from all
channels belonging to any view which is currently viewing target-world.
Page 6
pfvModule(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
After rendering 3D scene and dispatching POSTDRAW callbacks, the
pfvViewer will set up an orthogonal frustum suitable for 2D overlay
rendering, and will dispatch OVERLAY callbacks for modules which have
bound their PFV_CB_OVERLAY callback. As with other CULL and DRAW
callbacks, the pfvModule::overlay() method will be called depending on
module scope. Globally scoped modules will receive OVERLAY callbacks
from all channels in pfvViewer's channel-list. View-scoped modules will
receive OVERLAY callbacks from all channels in target-view channel list,
but not from channels belonging to other views. World-scoped modules
will receive OVERLAY callbacks from all channels belonging to any view
which is currently viewing target-world.
Note that in order to coordinate 2D rendering over multichannel views,
each channel may be assigned a 2d interval (referred to as the channel's
view-range, see man page for pfvDispChan::setViewRange). Before
dispatching OVERLAY callbacks for a channel, pfvViewer will setup ortho
projection such that channel's view-range will map exactly to channel's
viewport.
Modules can also register a keyboard-input callback to respond to key
down events. Any combination of keys can be declared active for each
module through the following methods:
pfvModule::bindKeys() will add all characters contained in the keys
string to the list of active keys held for module. (see man page for
pfvInputMngrCallback)
pfvModule::unbindKeys() will remove all characters contained in the keys
string from the list of active keys held for module.
pfvModule::getEventMask() will return a pointer to a string containing
all currently keys for module. Note that returned string is guaranteed to
be sorted, and to have no duplications.
pfvModule::setEventMask() will set the list of active keys for a module.
Note that provided string will be sorted and multiple references will be
eliminated automatically. Note also that any previously bound key will be
unbound by this call.
If module has one or more active keys, the pfvModule::handleEvent() will
be called by pfvViewer whenever one of the active keys is pressed by user
over a channel belonging to a view asoosciated with module.
A module is said to be associated with a view, if bit corresponding to
view is set in the mask value returned by pfvModule::getViewMask(). The
bit corresponding to any pfvView v is given by 1<<(v->getIndex()).
Globally scoped modules are associated with all views throughout the
lifetime of the application. View-scoped modules are only associated with
their target-view, while World-scoped modules will be associated with all
views that are currently viewing target-world.
Page 7
pfvModule(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
NOTESSEE ALSO
pfvInputMngr, pfvInputMngrCallback, pfvViewer, pfvView, pfvmDrawStyle,
pfvmEarthSky, pfvmLoader, pfvmLogo, pfvmNavigator, pfvmPicker,
pfvmSnapshot, pfvmSceneTree, pfvmSkyDome, pfvmStats, pfvmTrackball,
pfvmWorldSwitcher
Page 8
