pfFlux(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFlux(3pf)NAME
pfNewFlux, pfNewFluxInitFunc, pfGetFluxInitFunc, pfGetFluxClassType,
pfGetFluxDataSize, pfGetFluxNumBuffers, pfFluxInitData,
pfFluxCallDataFunc, pfGetFluxCurData, pfGetFluxCurDataFromData,
pfGetFluxWritableData, pfGetFluxWritableDataFromData,
pfGetFluxBufferData, pfFluxWriteComplete, pfFluxWriteCompleteFromData,
pfFluxMode, pfGetFluxMode, pfFluxSrcChanged, pfGetFluxSrcEngine,
pfGetFluxNumSrcEngines, pfGetFluxClientEngine, pfGetFluxNumClientEngines,
pfFluxMask, pfGetFluxMask, pfFluxEvaluate, pfFluxEvaluateEye,
pfFluxSyncGroup, pfGetFluxSyncGroup, pfGetFluxNamedSyncGroup,
pfGetFluxSyncGroupName, pfGetFluxNumNamedSyncGroups,
pfFluxSyncGroupReady, pfFluxEnableSyncGroup, pfFluxDisableSyncGroup,
pfGetFluxEnableSyncGroup, pfFluxSyncComplete, pfFluxDefaultNumBuffers,
pfGetFluxDefaultNumBuffers, pfGetFlux, pfFluxFrame, pfGetFluxFrame -
Create, initialize, and manage a pfFlux
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfFlux* pfNewFlux(size_t nbytes, int numBuffers,
void *arena);
pfFlux* pfNewFluxInitFunc(pfFluxInitFuncType initFunc,
int numBuffers, void *arena);
pfFluxInitFuncType pfGetFluxInitFunc(const pfFlux* _flux);
pfType* pfGetFluxClassType(void);
size_t pfGetFluxDataSize(const pfFlux* flux);
int pfGetFluxNumBuffers(const pfFlux* flux, int type);
void pfFluxInitData(pfFlux* flux, void *data);
void pfFluxCallDataFunc(pfFlux* flux,
pfFluxDataFuncType func, void *funcData);
void* pfGetFluxCurData(pfFlux* flux);
void* pfGetFluxCurDataFromData(void *data);
void* pfGetFluxWritableData(pfFlux* flux);
void* pfGetFluxWritableDataFromData(void *data);
void* pfGetFluxBufferData(int bufferId);
void pfFluxWriteComplete(pfFlux* flux);
Page 1
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFlux(3pf)
void pfFluxWriteCompleteFromData(void *data);
void pfFluxMode(pfFlux* flux, int mode, int val);
int pfGetFluxMode(const pfFlux* flux, int mode);
void pfFluxSrcChanged(pfFlux* flux);
pfEngine* pfGetFluxSrcEngine(const pfFlux* flux, int index);
int pfGetFluxNumSrcEngines(const pfFlux* flux);
pfEngine* pfGetFluxClientEngine(const pfFlux* flux,
int index);
int pfGetFluxNumClientEngines(const pfFlux* flux);
void pfFluxMask(pfFlux* flux, uint mask);
uint pfGetFluxMask(const pfFlux* flux);
void pfFluxEvaluate(pfFlux* flux, int mask);
void pfFluxEvaluateEye(pfFlux* flux, int mask,
pfVec3 eyePos);
void pfFluxSyncGroup(pfFlux* flux, uint syncGroup);
uint pfGetFluxSyncGroup(pfFlux* flux);
uint pfGetFluxNamedSyncGroup(const char *name);
const char* pfGetFluxSyncGroupName(uint syncGroup);
int pfGetFluxNumNamedSyncGroups(void);
void pfFluxSyncGroupReady(uint syncGroup);
void pfFluxEnableSyncGroup(uint syncGroup);
void pfFluxDisableSyncGroup(uint syncGroup);
int pfGetFluxEnableSyncGroup(uint syncGroup);
void pfFluxSyncComplete(void);
int pfFluxDefaultNumBuffers(int numBuffers);
int pfGetFluxDefaultNumBuffers(void);
Page 2
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFlux(3pf)
pfFlux* pfGetFlux(void *data);
void pfFluxFrame(int frame);
int pfGetFluxFrame(int frame);
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. Casting an object of class
pfFlux to an object of class pfObject is taken care of automatically.
This is also true for casts to objects of ancestor classes of class
pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
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.
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
Page 3
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFlux(3pf)PARAMETERS
flux identifies a pfFlux.
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.
pfNewFlux creates and returns a handle to a pfFlux. arena specifies a
malloc arena out of which the pfFlux is allocated or NULL for allocation
off the process heap. 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 such as (PFFLUX_DEFAULT_NUM_BUFFERS + 1),
to creat a number of buffers that is one greater then the default number
of buffers.
pfNewFluxInitFunc 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 can be deleted with pfDelete.
pfGetFluxClassType returns the pfType* for the class pfFlux. The pfType*
returned by pfGetFluxClassType is the same as the pfType* returned by
invoking pfGetType 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 pfIsOfType 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.
pfGetFluxDataSize returns the size of the data buffers in a pfFlux.
pfGetFluxNumBuffers 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.
pfFluxInitData initializes all data buffers of a pfFlux to the data
referenced by data. data should be at least as large as the data buffers
Page 4
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFlux(3pf)
of the pfFlux.
pfFluxCallDataFunc 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.
pfGetFluxCurData 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:
pfVec3 *cur_verts;
cur_verts = (pfVec3*)pfGetFluxCurData(flux);
pfGetFluxWritableData 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.
pfFluxWriteComplete 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*)pfGetFluxWritableData(flux);
/* Set all verts to 1.0, 2.0, 3.0 */
num_verts = pfGetFluxDataSize(flux) / sizeof(pfVec3);
for (i = 0; i < num_verts; i++)
pfSetVec3(verts[i], 1.0f, 2.0f, 3.0f);
pfFluxWriteComplete(flux);
pfGetFluxBufferData returns the untyped data pointer associated with
buffer bufferId of flux.
Page 5
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFlux(3pf)
pfFluxMode and pfGetFluxMode 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
pfFluxWriteComplete is done. Setting it to PF_ON will cause
pfEngineEvaluate to be done to its clients. Setting it to PF_OFF will
cause pfEngineSrcChanged to be done to its clients.
PFFLUX_ON_DEMAND controls on demand evaluation triggering. Setting it to
PF_ON will cause an evaluation of the pfFlux to occur, if
pfGetFluxCurData 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 pfGetFluxWritableData is called
and there is already a readable data buffer with the current frame number
(Having a readable data buffer means that someone called
pfGetFluxWritableData and pfFluxWriteComplete this frame). Setting the
flag to PF_ON will cause NULL to be returned from pfGetFluxWritableData.
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.
pfFluxSrcChanged will mark the data buffer, with a frame number matching
the current flux frame number, as dirty.
pfGetFluxSrcEngine returns the ith source pfEngine of a pfFlux. A pfFlux
gains source pfEngines by being the destination of a pfEngine.
pfGetFluxNumSrcEngines returns the number of source pfEngines of a
pfFlux.
pfGetFluxClientEngine returns the ith client pfEngine of a pfFlux. A
pfFlux gains client pfEngines by being a source of a pfEngine.
pfGetFluxNumClientEngines returns the number of client pfEngines of a
Page 6
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFlux(3pf)
pfFlux.
pfFluxMask and pfGetFluxMask set and get the evaluation mask of a pfFlux.
The default mask is PFFLUX_BASIC_MASK.
pfFluxEvaluate and pfFluxEvaluateEye 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
pfEngineEvaluate on the source engines of the pfFlux followed by calling
pfFluxWriteComplete on the pfFlux.
pfFluxSyncGroup and pfGetFluxSyncGroup set and get the sync group of a
pfFlux.
pfFlux sync groups are used to synchronize the completion of multiple
pfFluxes. When pfFluxWriteComplete 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.
pfGetFluxNamedSyncGroup 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.
pfGetFluxSyncGroupName returns the name of syncGroup.
pfGetFluxNumNamedSyncGroups returns the number of named sync groups.
pfFluxSyncGroupReady specifies that the syncGroup is ready for completion
if it has been enabled. This will have no effect if syncGroup has not
been enabled.
pfFluxEnableSyncGroup and pfFluxDisableSyncGroup enable and disable a
sync group. pfGetFluxEnableSyncGroup returns whether a sync group is
enabled.
pfFluxSyncComplete 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.
pfGetFlux 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.
pfFluxDefaultNumBuffers 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
Page 7
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFlux(3pf)
pfConfig. If you are not calling pfConfig in your application and you
are using pfFlux you should call pfFluxDefaultNumBuffers before you fork
any processes. pfGetFluxDefaultNumBuffers returns the current default
number of buffers.
pfFluxFrame will set the current flux frame number for the process that
is invoking it. This is the frame number that pfGetFluxCurData
pfGetFluxWritableData and pfFluxWriteComplete 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.
pfGetFluxFrame returns the current flux frame number.
pfFluxes can be connected to other Performer objects using the following
functions:
pfEngineSrc
pfEngineDst
pfNewFCS
pfFCSFlux
pfGSetAttr
pfGSetBBoxFlux
pfASDAddQueryArray
pfBboardPosFlux
pfLODRangeFlux
pfSwitchValFlux
NOTES
pfFlux replaces the obsoleted pfCycleBuffers. The following shows how to
convert code using pfCycleBuffers to use pfFlux:
/* Replace pfCyclebuffer creation with pfFlux: */
pfFlux *flux = pfNewFlux(size, PFFLUX_DEFAULT_NUM_BUFFERS);
/* replace getting of read-only data
* pfCBufGetCurData() for read becomes:
*/
pfFluxGetCurData();
/* replace getting of data to edit */
/* get writable buffer BEFORE editing data
*
*/
pfGetFluxWritableData();
/* ... edit data */
/* declare data edited after editing for the frame is done.
* Replace pfCBufferChanged(pfCycleBuffer *cbuf) becomes:
*/
pfFluxWriteComplete();
Page 8
pfFlux(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFlux(3pf)BUGSSEE ALSO
pfFluxMemory, pfEngine, pfFCS, pfFrame, pfGetFrameTimeFlux, pfASD,
pfBillboard, pfGeoSet, pfLOD, pfSwitch
Page 9
