pfFlux(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfFlux(3pf)NAMEpfFlux - Create, initialize, and manage a pfFluxFUNCTION SPECIFICATION
#include <Performer/pr/pfFlux.h>
pfFlux::pfFlux(size_t nbytes, int numBuffers)
pfFlux::pfFlux(pfFluxInitFuncType initFunc,
int numBuffers)
pfFluxInitFuncType pfFlux::getInitFunc(void);
static pfType * pfFlux::getClassType(void);
size_t pfFlux::getDataSize(void);
int pfFlux::getNumBuffers(int type);
void pfFlux::initData(void *data);
void pfFlux::callDataFunc(pfFluxDataFuncType func,
void *funcData);
void* pfFlux::getCurData(void);
static void* pfFlux::getCurData(void *data);
void* pfFlux::getWritableData(void);
static void* pfFlux::getWritableData(void *data);
void* pfFlux::getBufferData(int bufferId);
void pfFlux::writeComplete(void);
static void pfFlux::writeComplete(void *data);
void pfFlux::setMode(int mode, int val);
int pfFlux::getMode(int mode);
void pfFlux::srcChanged(void);
pfEngine* pfFlux::getSrcEngine(int index);
int pfFlux::getNumSrcEngines(void);
pfEngine* pfFlux::getClientEngine(int index);
Page 1
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfFlux(3pf)
int pfFlux::getNumClientEngines(void);
void pfFlux::setMask(uint mask);
uint pfFlux::getMask(void);
void pfFlux::evaluate(int mask);
void pfFlux::evaluate(int mask, pfVec3 eyePos);
void pfFlux::setSyncGroup(uint syncGroup);
uint pfFlux::getSyncGroup(void);
static uint pfFlux::getNamedSyncGroup(const char *name);
static const char* pfFlux::getSyncGroupName(uint syncGroup);
static int pfFlux::getNumNamedSyncGroups(void);
static void pfFlux::syncGroupReady(uint syncGroup);
static void pfFlux::enableSyncGroup(uint syncGroup);
static void pfFlux::disableSyncGroup(uint syncGroup);
static int pfFlux::getEnableSyncGroup(uint syncGroup);
static void pfFlux::syncComplete(void);
static int pfFlux::setDefaultNumBuffers(int numBuffers);
static int pfFlux::getDefaultNumBuffers(void);
static pfFlux* pfFlux::getFlux(void *data);
static void pfFlux::setFrame(int frame);
static int pfFlux::getFrame(void);
typedef int (*pfFluxInitFuncType)(pfFluxMemory *_fmem);
typedef void (*pfFluxDataFuncType)(void *_data, void *_funcData);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfFlux is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfFlux. This is also true for
ancestor classes of class pfObject.
Page 2
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfFlux(3pf)
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, void *arena);
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 pfFlux 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();
void * pfMemory::getArena();
int pfMemory::getSize();
DESCRIPTION
A pfFlux is a container for holding dynamic data. It contains multiple
buffers of data each associated with a frame number. This allows
multiple processes to each have a copy of the data appropriate to the
frame they are working on.
new(arena) pfFlux(nbytes,numBuffers) allocates a pfFlux from the
specified memory arena, or from the process heap if arena is NULL. new
allocates a pfFlux from the default memory arena (see pfGetSharedArena).
Like other pfObjects, pfFluxes cannot be created statically,
automatically on the stack or in arrays. The argument nbytes specifies
the length of each associated pfFluxMemory. The argument numBuffers
specifies the number of pfFluxMemory data buffers that the pfFlux will be
created with. numBuffers can be set to PFFLUX_DEFAULT_NUM_BUFFERS in
which case the number of buffers will be a number determined to be
appropriate to the current multi processing mode.
PFFLUX_DEFAULT_NUM_BUFFERS can also also be used in additive expressions
Page 3
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfFlux(3pf)
such as (PFFLUX_DEFAULT_NUM_BUFFERS + 1), to creat a number of buffers
that is one greater then the default number of buffers.
new(arena) pfFlux(initFunc,numBuffers) also allocates a pfFlux from the
specified memory arena. However the size of the associated pfFluxMemorys
and their initialization is determined by the call back function initFunc
of type pfFluxInitFuncType. The initFunc takes a pfFluxMemory fmem, and
returns an int. It will be called once to determine the size of
pfFluxMemorys to create and it will be called once for each pfFluxMemory
created. If fmem is NULL it should return the size of pfFluxMemorys to
create. If fmem is not NULL it should do any desired initialization of
the data portion of the pfFluxMemory. For example it might call
pfFluxedGSetInit to turn the data portion into a pfGeoSet and then add
coordinate attributes etc. to that pfGeoSet. This is how a fluxed
pfGeoSet is created.
A pfFlux should be deleted with pfDelete rather than the delete operator.
pfFlux::getClassType returns the pfType* for the class pfFlux. The
pfType* returned by pfFlux::getClassType is the same as the pfType*
returned by invoking the virtual function getType on any instance of
class pfFlux. Because OpenGL Performer allows subclassing of built-in
types, when decisions are made based on the type of an object, it is
usually better to use the member function isOfType to test if an object
is of a type derived from a Performer type rather than to test for strict
equality of the pfType*'s.
pfFlux::getDataSize returns the size of the data buffers in a pfFlux.
pfFlux::getNumBuffers the number of data buffers a pfFlux contains, if
type is set to PFFLUX_BUFFERS_GENERATED. If type is set to
PFFLUX_BUFFERS_SPECIFIED, it will return what the numBuffers argument was
set to when the pfFlux was created.
pfFlux::initData initializes all data buffers of a pfFlux to the data
referenced by data. data should be at least as large as the data buffers
of the pfFlux.
pfFlux::callDataFunc calls func for each data buffers of a pfFlux. func
will be called with the pointer to the data buffer and with funcData.
This function is useful in manipulating the buffers of a pfFlux when they
contained fluxed Performer objects such as fluxed pfGeoSets.
pfFlux::getCurData returns a pointer to the current data buffer of a
pfFlux. The current buffer is the readable data buffer whose frame
number is the closest to the current flux frame number, but not greater
then the current flux frame number.
Example of reading data:
Page 4
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfFlux(3pf)
pfVec3 *cur_verts;
cur_verts = (pfVec3*)flux->getCurData();
pfFlux::getWritableData returns a pointer to the data buffer whose frame
number matches the current flux frame number. NULL will be returned if
the PFLUX_WRITE_ONCE mode is set to PF_ON and there is already a readable
buffer with a frame number that matches the current flux frame number.
pfFlux::writeComplete will mark the data buffer whose frame number
matches the current flux frame number, as readable. It has no effect if
there is no buffer for the current flux frame number.
Example of writing data:
pfVec3 *verts;
int i, num_verts;
verts = (pfVec3*)flux->getWritableData();
/* Set all verts to 1.0, 2.0, 3.0 */
num_verts = flux->getDataSize() / sizeof(pfVec3);
for (i = 0; i < num_verts; i++)
verts[i].set(1.0f, 2.0f, 3.0f);
flux->writeComplete();
pfFlux::getBufferData returns the untyped data pointer associated with
buffer bufferId of the pfFlux.
pfFlux::setMode and pfFlux::getMode set and get the modes of a pfFlux.
mode is the mode you are setting and val is the value you are setting the
mode to. The modes are:
mode default
_______________________________
PFFLUX_PUSH PF_OFF
PFFLUX_ON_DEMAND PF_OFF
PFFLUX_COPY_LAST_DATA PF_OFF
PFFLUX_WRITE_ONCE PF_OFF
|
PFFLUX_PUSH controls what is done to a pfFlux's client pfEngines when
pfFlux::writeComplete is done. Setting it to PF_ON will cause
pfEngine::evaluate to be done to its clients. Setting it to PF_OFF will
cause pfEngine::srcChanged to be done to its clients.
Page 5
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfFlux(3pf)
PFFLUX_ON_DEMAND controls on demand evaluation triggering. Setting it to
PF_ON will cause an evaluation of the pfFlux to occur, if
pfFlux::getCurData is called and the data buffer for the current flux
frame is dirty.
PFFLUX_COPY_LAST_DATA controls what happens when a buffer is assigned a
new frame number. Setting it to PF_ON will cause the data, from the data
buffer with the frame number that is closest to but not greater then the
new frame number, to be copied to the data buffer that is getting the new
frame number. This is useful when a random portion of a pfFluxes data
will be updated with each write.
PFFLUX_WRITE_ONCE is used to avoid multiple writes on a pfFlux within the
same frame. It controls what happens when pfFlux::getWritableData is
called and there is already a readable data buffer with the current frame
number (Having a readable data buffer means that someone called
pfFlux::getWritableData and pfFlux::writeComplete this frame). Setting
the flag to PF_ON will cause NULL to be returned from
pfFlux::getWritableData. Setting it to PF_OFF will cause the pointer to
the readable data buffer to be returned. Using the PFFLUX_WRITE_ONCE
flag is a good idea when you have multiple writing processes to a Flux,
and you wish to make sure that only one of them writes at any given
frame.
pfFlux::srcChanged will mark the data buffer, with a frame number
matching the current flux frame number, as dirty.
pfFlux::getSrcEngine returns the ith source pfEngine of a pfFlux. A
pfFlux gains source pfEngines by being the destination of a pfEngine.
pfFlux::getNumSrcEngines returns the number of source pfEngines of a
pfFlux.
pfFlux::getClientEngine returns the ith client pfEngine of a pfFlux. A
pfFlux gains client pfEngines by being a source of a pfEngine.
pfFlux::getNumClientEngines returns the number of client pfEngines of a
pfFlux.
pfFlux::setMask and pfFlux::getMask set and get the evaluation mask of a
pfFlux. The default mask is PFFLUX_BASIC_MASK.
pfFlux::evaluate(mask) and pfFlux::evaluate(mask, eyePos) trigger an
evaluation of a pfFlux if any of the bits in mask match any of the bits
in the evaluation mask of the pfFlux. The evaluation of a pfFlux is
equivalent to calling pfEngine::evaluate on the source engines of the
pfFlux followed by calling pfFlux::writeComplete on the pfFlux.
pfFlux::setSyncGroup and pfFlux::getSyncGroup set and get the sync group
of a pfFlux.
pfFlux sync groups are used to synchronize the completion of multiple
Page 6
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfFlux(3pf)
pfFluxes. When pfFlux::writeComplete id called on a pfFlux that is part
of an enabled sync group the data buffer for the current flux frame will
not be made readable and instead the pfFlux will be scheduled for later
completion. All pfFluxes are created as part of sync group 0, which can
never be enabled. One example where sync groups are useful is, when
pfFluxes are being evaluated in an asynchronys process.
pfFlux::getNamedSyncGroup will returns a sync group number associated
with name. If name is not yet associated with a sync group, the next
unused sync group number will be named name. Once a sync group has been
named its name can never be changed.
pfFlux::getSyncGroupName returns the name of syncGroup.
pfFlux::getNumNamedSyncGroups returns the number of named sync groups.
pfFlux::syncGroupReady specifies that the syncGroup is ready for
completion if it has been enabled. This will have no effect if syncGroup
has not been enabled.
pfFlux::enableSyncGroup and pfFlux::disableSyncGroup enable and disable a
sync group. pfFlux::getEnableSyncGroup returns whether a sync group is
enabled.
pfFlux::syncComplete will cause the completion of all pfFluxes that have
been scheduled for completion and are part of a ready sync group. In
addition to making the buffer readable it will also mark it with the
current flux frame number. Normally there is no reason to call this
function, as it is called by pfFrame.
pfFlux::getFlux will return the pfFlux that the data buffer pointer data
is a part of. It will return NULL if data is not part of a pfFlux. This
is useful to find out if an attribute of a pfGeoSet is a pfFlux.
pfFlux::setDefaultNumBuffers sets the default number of buffers that are
allocated when a pfFlux is created using PFFLUX_DEFAULT_NUM_BUFFERS.
Normally there is no reason to call this function, as it is called by
pfConfig. If you are not calling pfConfig in your application and you
are using pfFlux you should call pfFlux::setDefaultNumBuffers before you
fork any processes. pfFlux::getDefaultNumBuffers returns the current
default number of buffers.
pfFlux::setFrame will set the current flux frame number for the process
that is invoking it. This is the frame number that pfFlux::getCurData
pfFlux::getWritableData and pfFlux::writeComplete will use in determining
which buffers to operate on. Normally there is no reason to call this
function, as it is called by pfFrame for all Performer processes.
pfFlux::getFrame returns the current flux frame number.
pfFluxes can be connected to other Performer objects using the following
functions:
Page 7
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfFlux(3pf)
pfEngine::setSrc
pfEngine::setDst
new pfFCS
pfFCS::setFlux
pfGeoSet::setAttr
pfGeoSet::setBoundFlux
pfASD::addQueryArray
pfBillboard::setPosFlux
pfLOD::setRangeFlux
pfSwitch::setValFlux
NOTESpfFlux replaces the obsoleted pfCycleBuffers. The following shows how to
convert code using pfCycleBuffers to use pfFlux:
pfFlux *flux = new pfFluxBuffer(size, PFFLUX_DEFAULT_NUM_BUFFERS);
/* replace getting of read-only data
* pfCBufGetCurData() for read becomes:
*/
flux->getCurData();
/* replace getting of data to edit */
/* get writable buffer BEFORE editing data
*
*/
flux->getWritableData();
/* ... edit data */
/* declare data edited after editing for the frame is done.
* Replace pfCBufferChanged(pfCycleBuffer *cbuf) becomes:
*/
flux->writeComplete();
BUGSSEE ALSO
pfFluxMemory, pfEngine, pfFCS, pfFrame, pfGetFrameTimeFlux, pfASD,
pfBillboard, pfGeoSet, pfLOD, pfSwitch
Page 8
