pfvViewer(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
NAMEpfvViewer - Set up Multi-World, Multi-View, Modular applications through
XML file configuration or through API calls.
FUNCTION SPECIFICATION
#include <Performer/pfv/pfvViewer.h>
pfvViewer::pfvViewer();
pfvViewer::pfvViewer(char *filename);
pfvViewer::pfvViewer(pfvXmlNode *xml);
int pfvViewer::parseXml(pfvXmlNode* xml);
static pfvViewer* pfvViewer::getViewer();
void pfvViewer::config();
void pfvViewer::sync();
void pfvViewer::frame();
void pfvViewer::run(float time=-1.0f);
pfvWorld* pfvViewer::createWorld();
pfvWorld* pfvViewer::createWorld(pfvXmlNode* xml);
pfvWorld* pfvViewer::createWorld(char* name);
int pfvViewer::getNumWorlds();
pfvWorld* pfvViewer::getWorld(int i=-1);
pfvWorld* pfvViewer::findWorld(char*_name);
int pfvViewer::addNode(pfNode*node);
pfvWorld* pfvViewer::getCurWorld();
int pfvViewer::getCurWorldIndex();
void pfvViewer::setCurWorld(pfvWorld*w);
void pfvViewer::setCurWorldIndex(int i);
void pfvViewer::autoPos();
void pfvViewer::setTargetWorld(pfvWorld*w);
Page 1
pfvViewer(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
void pfvViewer::setTargetWorld(int i);
pfvView* pfvViewer::getCurView();
int pfvViewer::getCurViewIndex();
void pfvViewer::setCurView(pfvView*v);
void pfvViewer::setCurViewIndex(int i);
int pfvViewer::addModule(pfvModule*m,
int scope=PFV_SCOPE_GLOBAL, int scopeIndex=-1);
pfvModule* pfvViewer::addModule( char*className,
char* dsoName=NULL, int scope=PFV_SCOPE_AUTO,
int scopeIndex=-1 );
int pfvViewer::getNumModules();
pfvModule* pfvViewer::getModule(int i);
pfvModule* pfvViewer::findModule(char*_name);
pfvModule* pfvViewer::findModule(char*name, pfType*classType,
pfObject*scopeTarget=NULL);
pfvModule* pfvViewer::findModule(char*name,
pfObject*scopeTarget, pfType*classType=NULL);
static const char* pfvViewer::getCallbackName(int cb);
static char* pfvViewer::getCBNames(int cbmask);
int pfvViewer::dispatchCallback(int cb,
uint64_t viewMask, pfvDispChan*chan);
static int pfvViewer::getStage();
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfvViewer is derived from the parent class
pfvDisplayMngr, so each of these member functions of class pfvDisplayMngr
are also directly usable with objects of class pfvViewer. This is also
true for ancestor classes of class pfvDisplayMngr.
virtual int pfvDisplayMngr::loadFile(char* filename);
virtual int pfvDisplayMngr::parseXml(pfvXmlNode* xml);
virtual void pfvDisplayMngr::preConfig();
virtual void pfvDisplayMngr::postConfig();
virtual pfvDispPipe* pfvDisplayMngr::createPipe(pfvXmlNode* xml);
int pfvDisplayMngr::getNumPipes();
Page 2
pfvViewer(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
pfvDispPipe* pfvDisplayMngr::getPipe(int i);
pfvDispPipe* pfvDisplayMngr::findPipe(char* _name);
virtual pfvDispView* pfvDisplayMngr::createView(pfvXmlNode* xml);
int pfvDisplayMngr::getNumViews();
pfvDispView* pfvDisplayMngr::getView(int i);
pfvDispView* pfvDisplayMngr::findView(char* _name);
int pfvDisplayMngr::getNumPWins();
pfvDispPWin* pfvDisplayMngr::getPWin(int i);
pfvDispPWin* pfvDisplayMngr::findPWin(char* _name);
pfvDispPWin* pfvDisplayMngr::findPWin(pfPipeWindow* pw);
int pfvDisplayMngr::getNumChans();
pfvDispChan* pfvDisplayMngr::getChan(int i);
pfvDispChan* pfvDisplayMngr::findChan(char* _name);
Since the class pfvDisplayMngr is itself derived from the parent class
pfObject, objects of class pfvViewer 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 pfvViewer 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);
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();
Page 3
pfvViewer(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
void * pfMemory::getArena();
int pfMemory::getSize();
DESCRIPTION
The pfvViewer class simplifies setting up multi-scene, multi-view,
modular applications through XML configuration files and through API
calls. A pfvViewer extends the pfvDisplayMngr class by providing
management for multiple scenes (see pfvWorld) and by supporting modular
extensibility through pfvModules.
new pfvViewer creates and returns a handle to a pfvViewer. Only one
pfvViewer can be created during the course of an application. Deletion
of pfvViewer is not supported.
new pfvViewer(char *filename) creates and returns a handle to a
pfvViewer. Before returning, the XML file named filename is parsed and
its contents are used to create and configure display objects, worlds and
modules.
new pfvViewer(pfXmlNode*xml) creates and returns a handle to a pfvViewer.
Before returning, the pfvXmlNode xml is examined and its contents are
used to create and configure display objects, worlds and modules.
pfvViewer::parseXml() examines the specified pfvXmlNode using its
contents to create and configure any number of display objects (pipes,
pwins, channels and views), worlds, and modules.
The File Format for XML pfvViewer Configuration files (.pfv extension) is
as follows:
<?xml version="1.0" ?>
<viewer>
<display>
<pipe>
<pwin>
<chan> ... </chan>
</pwin>
</pipe>
</display>
<view> ... </view>
<world> ...</world>
<modulepath>../modules/DSOs</modulepath>
<module> ... </module>
<module> ... </module>
Page 4
pfvViewer(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
</viewer>
At the highest level, pfvViewer accepts the following tokens:
<display> : this tag may contain any number of Display Objects
declarations, such as pipes, pwins, channels and views. See the
man page for pfvDisplayMngr for more details.
<view> : this tag defines a new view and is equivalent to a <view>
tag contained inside the <display> tag. Note that for
pfvViewer-based apps, it is recommended that views be declared
outside the <display> tag. See the man pages for pfvDispView
and pfvView for more details.
<world> : this tag defines a new world (scene). See the man
page for pfvWorld for more details.
<modulepath> : this tag can be used to set the search path for
modules' DSOs. Multiple, colon-separated paths can be provided.
See the man page for pfvModule::setLoadPath for more details.
<module> : this tag instructs the viewer to load a new module. See
the man page for pfvModule for more details.
pfvViewer::getViewer() returns a handle to the pfvViewer, if one has been
created, or NULL otherwise.
pfvViewer::config() should be called after all Display Objects, Worlds
and Modules have been created/loaded. It does the following:
o If no worlds have been created, create a default world.
o If no views have been created, create a default view.
o Traverse module list and dispatch PRECONFIG callbacks
o Call pfvDispMngr::preConfig() (see pfvDispMngr man page)
o Call pfConfig()
o Call pfvDispMngr::postConfig()
o Call pfvInputMngr::init() (see pfvInputMngr man page)
o Create a pfScene for each world
o Traverse module list and dispatch POSTCONFIG callbacks
pfvViewer::sync() may be called after a call to pfvViewer::frame(), and
causes the pfvViewer to call pfSync() then traverse module list and
dispatch SYNC callbacks.
Page 5
pfvViewer(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
pfvViewer::frame() will trigger a new simulation frame. If
pfvViewer::config() has not been called when pfvViewer::frame() is called
the first time, pfvViewer::config() will automatically be called. If
pfvViewer::sync() has not been called since the last call to
pfvViewer::frame(), it will also be automatically called here.
After this, pfvViewer::frame() will call pfFrame(), and do the following:
o Dispatch EXIT_WORLD callbacks to view-scoped modules who are
exiting a world this frame.
o Dispatch EXIT_VIEW callbacks to world-scoped modules who are
being exited by one or more views on this frame.
o Dispatch ENTER_VIEW callbacks to world-scoped modules who are
being entered by one or more views on this frame.
o Dispatch ENTER_WORLD callbacks to view-scoped modules who are
entering a new world this frame.
o Update windows position and sizes
o Collect input events and dispatch input event callbacks
o Traverse module list and dispatch FRAME callbacks to all
active modules.
pfvViewer::run will enter a loop in which pfvViewer::frame() is called
repeatedly. If a non-negative duration is passed as the argument time,
pfvViewer will exit the loop and terminate the application after the
specified time has elapsed.
pfvViewer::createWorld() creates and returns a handle to a new pfvWorld
object. All worlds must be created before pfvViewer::config is called.
The pfvWorld created by this function becomes the currently selected
world.
pfvViewer::getNumWorlds() returns the number of worlds that have been
created.
pfvViewer::getWorld() returns a handle to the world at position i in
viewer's world-list if i is a non-negative number. If a world does not
exist at index i, NULL is returned. Setting i to a negative number will
return the pfvWorld associated with the currently selected view, or NULL
if no view has been selected.
pfvViewer::findWorld() returns a handle to the first world in viewer's
world-list whose name matches _name. If no world's name matches, this
method returns NULL.
pfvViewer::addNode() will add the specified pfNode to the scene
associated with the currently selected world. Note this method must be
called after pfScenes have been created for worlds (no earlier than
POSTCONFIG module callbacks).
Page 6
pfvViewer(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
pfvViewer::getCurWorld() returns a handle to the currently selected
world, or NULL if there are no worlds yet.
pfvViewer::getCurWorldIndex() returns the index of the currently selected
world, or -1 if there are no worlds yet.
pfvViewer::setCurWorld() sets currently selected world.
pfvViewer::setCurWorldIndex() sets world i to be the currently selected
world.
pfvViewer::createView(), pfvViewer::getView(), pfvViewer::findView() :
see the pfvDisplayMngr man page for a description. The newly created
pfvView becomes the currently selected view.
pfvViewer::autoPos() calls pfvView::autoPos on currently selected view.
See the pfvView man page.
pfvViewer::setTargetWorld() calls pfvView::setTargetWorld on currently
selected view. See the pfvView man page.
pfvViewer::getCurView() returns a handle to the currently selected view,
or NULL if there are no views yet.
pfvViewer::getCurViewIndex() returns the index of the currently selected
view, or -1 if there are no views yet.
pfvViewer::setCurView() sets currently selected view.
pfvViewer::setCurViewIndex() sets view i to be the currently selected
view.
pfvViewer::addModule(pfvModule*m, int scope, int scopeIndex) will add
module m to the viewer's module list. The value of parameter scope can
be one of the following:
PFV_SCOPE_GLOBAL will cause the modue to be globally scoped.
PFV_SCOPE_VIEW will cause module to be scoped to the scopeIndex-th
view in the viewer's view list. If scopeIndex is -1, module
will be scoped to the currently selected view.
PFV_SCOPE_WORLD will cause module to be scoped to scopeIndex-th
world in the viewer's world list. If scopeIndex is -1, module
will be scoped to the currently selected world.
PFV_SCOPE_AUTO will cause module scope to be determined by module itself.
This is the default. See pfvModule::autoScope for more details.
This method returns the index of the module after it has been added to
viewer'm module list.
Page 7
pfvViewer(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
Parameter scopeIndex is ignored if scope is either PFV_SCOPE_GLOBAL or
BPFV_SCOPE_AUTO.
Note that modules can be scoped to the first pfvWorld or the first
pfvView even before such world (or view) has been created. Scoping to
worlds or views with index greater than 0 however requires that the world
or view be created first.
Differently scoped modules will receive different types of callbacks.
See the man pages for pfvModule and for individual pfvm* modules.
pfvViewer::addModule( char*className, char* dsoName, int scope, int
scopeIndex) will first call pfvModule::load to load the pfvModule, then
add it to viewer's module list. This method returns a handle to the newly
loaded module, or NULL if module couldn't be loaded or if it couldn't be
added to viewer.
pfvViewer::getNumModules() returns the number of modules currently in the
viewer's module-list.
pfvViewer::getModule() returns a handle to the i-th module in viewer's
module-list if i is a valid index, or NULL otherwise.
pfvViewer::findModule(char*name) returns a handle to the first module in
viewer's module-list whose name matches _name. If no module's name
matches, the method will return NULL.
pfvViewer::findModule(char*name, pfType*classType,
pfObject*scopeTarget=NULL) and pfvViewer::findModule(char*name,
pfObject*scopeTarget, pfType*classType=NULL) can be used to search for a
module in viewer's module list by providing an optional module name, an
optional class type identifier, and an optional pointer to a scope-target
(pfvWorld or pfvView). Both methods will return a handle to the first
module which match all non-null parameters. If all specified parameters
are NULL, this method will return NULL.
pfvViewer::getCallbackName() will return a string containing the name of
a specific viewer callback (for example,
pfvViewer::getCallbackName(PFV_CB_POSTCULL) will return "PostCull".
pfvViewer::getCBNames() will create a string containing the names of all
the callbacks associateds with all set bits in the specified mask.
pfvViewer::dispatchCallback()pfvViewer::getStage() returns the current stage of the viewer. The
tokens for the different stages are:
PFV_STAGE_PRECONSTRUCT a viewer has not yet been created
Page 8
pfvViewer(3pf) OpenGL Performer 3.2.2 libpfv C++ Reference Pages
PFV_STAGE_POSTCONSTRUCT viewer has been created, not configed
PFV_STAGE_PRECONFIG viewer is dispatching PRECONFIG callbacks
PFV_STAGE_POSTCONFIG viewer is dispatching POSTCONFIG callbacks
yet
PFV_STAGE_CONFIGED viewer->config() is done, viewer-
>frame() not called
PFV_STAGE_RUNTIME viewer->frame() already called
NOTESSEE ALSO
pfvInputMngr, pfvDisplayMngr, pfvModule, pfvView, pfvWorld
Page 9
