pfEngine(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfEngine(3pf)NAME
pfEngine, - Create, initialize, and manage a pfEngineFUNCTION SPECIFICATION
#include <Performer/pr/pfEngine.h>
pfEngine* pfEngine::pfEngine(int function);
static pfType * pfEngine::getClassType(void);
void pfEngine::setSrc(int index, void *data, ushort *ilist,
int icount, int offset, int stride);
void pfEngine::getSrc(int index, void **data,
ushort **ilist, int *icount, int *offset,
int *stride);
int pfEngine::getNumSrcs(void);
void pfEngine::setDst(void *data, ushort *ilist,
int offset, int stride);
void pfEngine::getDst(void **data, ushort **ilist,
int *offset, int *stride);
void pfEngine::setIterations(int iterations, int items);
void pfEngine::getIterations(int *iterations, int *items);
int pfEngine::getFunction(void);
void pfEngine::setUserFunction(pfEngineFuncType func);
pfEngineFuncType pfEngine::getUserFunction(void);
void pfEngine::setMode(int mode, int val);
int pfEngine::getMode(int mode);
void pfEngine::setMask(uint mask);
uint pfEngine::getMask(void);
void pfEngine::setEvaluationRange(pfVec3 ¢er,
float min, float max);
void pfEngine::getEvaluationRange(pfVec3 ¢er,
float *min, float *max);
void pfEngine::srcChanged(void);
Page 1
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfEngine(3pf)
void pfEngine::evaluate(int mask);
void pfEngine::evaluate(int mask, pfVec3 eye_pos);
typedef void (*pfEngineFuncType)(pfEngine *engine);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfEngine is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfEngine. This is also true for
ancestor classes of class pfObject.
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 pfEngine 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 pfEngine is an object for controlling the dynamic data in a pfFlux.
new(arena) allocates a pfEngine from the specified memory arena, or from
the process heap if arena is NULL. new allocates a pfEngine from the
Page 2
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfEngine(3pf)
default memory arena (see pfGetSharedArena). Like other pfObjects,
pfEngines cannot be created statically, automatically on the stack or in
arrays. pfEngines should be deleted with pfDelete rather than the delete
operator. function is a symbolic token that specifies the function the
pfEngine will execute. The function may be one of:
PFENG_SUM
PFENG_MORPH
PFENG_BLEND
PFENG_TRANSFORM
PFENG_ALIGN
PFENG_MATRIX
PFENG_ANIMATE
PFENG_BBOX
PFENG_TIME
PFENG_STROBE
PFENG_USER_FUNCTION
pfEngine::getClassType returns the pfType* for the class pfEngine. The
pfType* returned by pfEngine::getClassType is the same as the pfType*
returned by invoking the virtual function getType on any instance of
class pfEngine. 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.
pfEngine::getFunction returns the function of a pfEngine.
pfEngine::setIterations and pfEngine::getIterations set and get the
number of iterations and items a pfEngine should operate on. iterations
is the number of times the engine should iterate. items is the number of
items that are operated on each iteration. For example, if you wanted to
add two arrays of 100 pfVec3s each, you would set iterations to 100 and
items to 3.
For some functions iterations and items are meaningless, and they have
special meanings in some functions. This is noted in the descriptions of
the functions.
pfEngine::setSrc and pfEngine::getSrc set and get the sources of a
pfEngine.
index specifies which source of a function is being set. There are
symbolic tokens that define the sources for each of the functions.
data should be either a pfFlux* or a pointer to a block of memory
allocated with pfMemory::malloc.
ilist is an array of indexes into the destination and specifies which
destination elements this source effects. It can, and often will be, set
to NULL in which case this source effects all elements of the
Page 3
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfEngine(3pf)
destination. Also if the ilist is set to NULL and the destination has a
non NULL ilist the destinations ilist will be used as the source ilist.
icount is the number of indexes the ilist contains.
offset is the starting offset of the first element of this source. This
will often be 0.
stride is how much the pointer should be advanced after each iteration of
the function. This is often equal to items from pfEngine::setIterations.
Both offset and stride are measured in items, where an item is the basic
data type of the source. This is usually floats.
pfEngine::getNumSrcs returns the highest source index set plus one.
pfEngine::setDst and pfEngine::getDst set and get the destination of a
pfEngine.
data should be either a pfFlux* or a pointer to a block of memory
allocated with pfMemory::malloc. However, if this pfEngine is going to
be part of a Performer scene graph, data can only be a pfFlux*.
ilist is an array of indexes into the destination and specifies which
destination elements are effected by this engine. It can, and often will
be, set to NULL in which case this engine effects all elements of the
destination. For engines to work properly it is important that the
destination ilist be a superset of all source ilists.
Note: pfEngine::setDst does not have an icount because the iterations set
with pfEngine::setIterations specifies the number of indexes that the
ilist contains.
offset is the starting offset of the first element of the destination.
This will often be 0.
stride is how much the pointer should be advanced after each iteration of
the function. This is often equal to items from pfEngine::setIterations.
Both offset and stride are measured in items, where an item is the basic
data type of the source. This is usually floats.
pfEngine::srcChanged will mark the destination pfFlux of a pfEngine as
dirty for the current flux frame.
pfEngine::setMode and pfEngine::getMode set and get the modes of a
pfEngine. mode is the mode you are setting and val is the value you are
setting the mode to. The modes are:
mode default
|
Page 4
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfEngine(3pf)
_____________________________________
PFENG_RANGE_CHECK PF_OFF
PFENG_MATRIX_MODE PF_OFF
PFENG_TIME_MODE PFENG_TIME_CYCLE
PFENG_TIME_TRUNC PF_OFF
|
PFENG_RANGE_CHECK controls whether a range check is done when
pfEngine::evaluate(mask, eyePos) is called. Setting it to PF_ON will
cause the range check to be done.
PFENG_MATRIX_MODE is only applicable to the PFENG_MATRIX and
PFENG_ANIMATE functions and is describes with those functions.
PFENG_TIME_MODE and PFENG_TIME_TRUNC are only applicable to the
PFENG_TIME function and are described with that functions.
pfEngine::setMask and pfEngine::getMask set and get the evaluation mask
of a pfEngine. The default mask is PFFLUX_BASIC_MASK.
pfEngine::setEvaluationRange and pfEngine::getEvaluationRange set and get
the evaluation range of a pfEngine.
pfEngine::evaluate(mask) and pfEngine::evaluate(mask, eyePos) trigger an
evaluation of a pfEngine if any of the bits in mask match any of the bits
in the evaluation mask of the pfEngine. The evaluation will also be
conditional on eyePos being within the evaluation range, if the pfEngine
has its PFENG_RANGE_CHECK mode set to PF_ON and pfEngine::evaluate(mask,
eyePos) is used.
pfEngine::setUserFunction and pfEngine::getUserFunction set and get the
user function of a pfEngine. This only has effect if the function of the
pfEngine is PFENG_USER_FUNCTION. The user function func, must be of type
pfEngineFuncType. The user function of a pfEngine will be called when
ever the pfEngine is evaluated. The user function will only be called if
the pfEngine has passed its evaluation criteria. The user function
should not call pfFlux::writeComplete on its destination pfFlux, as that
will be done by pfEngine::evaluate.
FUNCTIONS
PFENG_SUM
This function will add arrays of floats together to form a destination
array of floats. This function is very general and can be used in many
situations. One use for it is in aligning objects such as buildings to a
pfASD. Since PFENG_SUM can have as few as one source it can be used to
simply copy data from one location to another.
Source index Data ilist offset stride
or Destination Type Applicable Applicable Applicable
|
|
|
|
Page 5
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfEngine(3pf)
__________________________________________________________________
PFENG_SUM_SRC(n) float[] yes yes yes
Destination float[] yes yes yes
|
|
|
|
iterations items
__________________
yes yes
|
PFENG_MORPH
This function sets the destination to a weighted sum of its sources. You
can use either the PFENG_MORPH_FRAME or the PFENG_MORPH_WEIGHTS source to
drive this function.
PFENG_MORPH_WEIGHTS contains a float for each of the PFENG_MORPH_SRC(n)
sources. Element zero of PFENG_MORPH_WEIGHTS gets multiplied against
PFENG_MORPH_SRC(0), element one gets multiplied against
PFENG_MORPH_SRC(1), and so on.
PFENG_MORPH_FRAME contains a single float. This float specifies the
weighting between two of the PFENG_MORPH_SRC(n) sources. The integer
portion specifies the sources and the fractional portion the weighting
between those sources. For example, a PFENG_MORPH_FRAME of 3.8 would
mean PFENG_MORPH_SRC(3) * 0.2 + PFENG_MORPH_SRC(4) * 0.8.
Source index Data ilist offset stride
or Destination Type Applicable Applicable Applicable
_____________________________________________________________________
PFENG_MORPH_FRAME float[1] no no no
PFENG_MORPH_WEIGHTS float[n] no no no
PFENG_MORPH_SRC(n) float[] yes yes yes
Destination float[] yes yes yes
|
|
|
|
iterations items
__________________
yes yes
|
PFENG_BLEND
This function is sort of a light version of the PFENG_MORPH function. It
sets the destination to a weighted sum of elements in the PFENG_BLEND_SRC
source. You can use either the PFENG_BLEND_FRAME or the
PFENG_BLEND_WEIGHTS source to drive this function.
PFENG_BLEND_SRC should contain iterations elements. An element is a set
of items floats. The stride of the PFENG_BLEND_SRC source should
generally be equal to items.
PFENG_BLEND_WEIGHTS contains a float for each of the elements in the
PFENG_BLEND_SRC source. PFENG_BLEND_WEIGHTS[0] gets multiplied against
the items stating at PFENG_BLEND_SRC[0*stride], PFENG_BLEND_WEIGHTS[1]
gets multiplied against the items stating at PFENG_BLEND_SRC[1*stride],
Page 6
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfEngine(3pf)
and so on.
PFENG_BLEND_FRAME contains a single float. This float specifies the
weighting between two of the elements in the PFENG_BLEND_SRC source. The
integer portion specifies the elements and the fractional portion the
weighting between those elements. For example, a PFENG_BLEND_FRAME of
3.8 would mean the items stating at PFENG_BLEND_SRC[3*stride] * 0.2 + the
items stating at PFENG_BLEND_SRC[4*stride] * 0.8.
Source index Data ilist offset stride
or Destination Type Applicable Applicable Applicable
_____________________________________________________________________
PFENG_BLEND_FRAME float[1] no no no
PFENG_BLEND_WEIGHTS float[n] no no no
PFENG_BLEND_SRC float[] no yes yes
Destination float[] no yes yes
|
|
|
|
iterations items
__________________
special yes
|
PFENG_TRANSFORM
This function transforms the PFENG_TRANSFORM_SRC array of floats by the
matrix contained in the PFENG_TRANSFORM_MATRIX source.
Source index Data ilist offset stride
or Destination Type Applicable Applicable Applicable
________________________________________________________________________
PFENG_TRANSFORM_SRC float[] yes yes yes
PFENG_TRANSFORM_MATRIX pfMatrix no no no
Destination float[] yes yes yes
|
|
|
|
iterations items
__________________
yes yes
|
PFENG_ALIGN
This function generates an alignment matrix based on the sources.
PFENG_ALIGN_POSITION is used to determine the translational portion of
the matrix. If PFENG_ALIGN_POSITION is NULL then the translational
portion of the matrix will be set to all zeros. PFENG_ALIGN_NORMAL and
PFENG_ALIGN_AZIMUTH are used to determine the rotation portion of the
matrix. If either are NULL then the rotation portion of the matrix will
be set to all zeros. One use for the PFENG_ALIGN function is in aligning
moving objects, such as vehicles, to a pfASD.
Source index Data ilist offset stride
or Destination Type Applicable Applicable Applicable
|
|
|
|
Page 7
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfEngine(3pf)
_______________________________________________________________________
PFENG_ALIGN_POSITION float[3] no yes no
PFENG_ALIGN_NORMAL float[3] no yes no
PFENG_ALIGN_AZIMUTH float[3] no yes no
Destination pfMatrix no no no
|
|
|
|
iterations items
__________________
no no
|
PFENG_MATRIX
This function generates a matrix based on its sources.
PFENG_MATRIX_ROT contains a heading pitch and roll rotations, and does
the equivalent of pfDCS::setRot.
PFENG_MATRIX_TRANS contains a xyz translation and does the equivalent of
pfDCS::setTrans.
PFENG_MATRIX_SCALE_UNIFORM contains a scale and does the equivalent of
pfDCS::setScale
PFENG_MATRIX_SCALE_XYZ contains a zyz scale and does the equivalent of
pfDCS::setScale(x, y, z).
PFENG_MATRIX_BASE_MATRIX contains a pfMatrix that is either pre or post
multiplied against the matrix generated by the other sources depending on
the PFENG_MATRIX_MODE mode.
Any or all of the sources can be NULL, in which case they have no effect
on the resulting matrix.
Source index Data ilist offset stride
or Destination Type Applicable Applicable Applicable
____________________________________________________________________________
PFENG_MATRIX_ROT float[3] no yes no
PFENG_MATRIX_TRANS float[3] no yes no
PFENG_MATRIX_SCALE_UNIFORM float[1] no yes no
PFENG_MATRIX_SCALE_XYZ float[3] no yes no
PFENG_MATRIX_BASE_MATRIX pfMatrix no no no
Destination pfMatrix no no no
|
|
|
|
iterations items
__________________
no no
|
PFENG_ANIMATE
This function will animate a matrix based on its sources. It is similar
to PFENG_MATRIX, but instead of having single values for its rotations
translations and scales, it has arrays of values. Either the
Page 8
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfEngine(3pf)
PFENG_ANIMATE_FRAME or the PFENG_ANIMATE_WEIGHTS should be used to
control which or what combination of the values are used.
iterations specifies the number of values in the rotation, translation,
scale sources, and the size of the PFENG_ANIMATE_WEIGHTS source.
PFENG_ANIMATE_WEIGHTS contains a float for each of the values in the
rotation, translation, and scale sources. Element zero of
PFENG_ANIMATE_WEIGHTS gets multiplied against 0th value, element one gets
multiplied against 1st value, and so on.
PFENG_ANIMATE_FRAME contains a single float. This float specifies the
weighting between two of the values in the rotation, translation, and
scale sources. The integer portion specifies the values and the
fractional portion the weighting between those values. For example, a
PFENG_ANIMATE_FRAME of 3.8 would mean value[3] * 0.2 + value[4] * 0.8.
PFENG_ANIMATE_ROT contains an array of heading pitch and roll rotations,
and does the equivalent of pfDCS::setRot.
PFENG_ANIMATE_TRANS contains an array of xyz translations and does the
equivalent of pfDCS::setTrans.
PFENG_ANIMATE_SCALE_UNIFORM contains an array of scales and does the
equivalent of pfDCS::setScale
PFENG_ANIMATE_SCALE_XYZ contains an array of zyz scales and does the
equivalent of pfDCS::setScale(x, y, z).
PFENG_ANIMATE_BASE_MATRIX contains a pfMatrix that is either pre or post
multiplied against the matrix generated by the other sources depending on
the PFENG_MATRIX_MODE mode.
Any or all of the sources can be NULL, in which case they have no effect
on the resulting matrix.
Source index Data ilist offset stride
or Destination Type Applicable Applicable Applicable
______________________________________________________________________________
PFENG_ANIMATE_FRAME float[1] no no no
PFENG_ANIMATE_WEIGHTS float[n] no no no
PFENG_ANIMATE_ROT pfVec3[n] no yes no
PFENG_ANIMATE_TRANS pfVec3[n] no yes no
PFENG_ANIMATE_SCALE_UNIFORM float[n] no yes no
PFENG_ANIMATE_SCALE_XYZ pfVec3[n] no yes no
PFENG_ANIMATE_BASE_MATRIX pfMatrix no no no
Destination pfMatrix no no no
|
|
|
|
n = iterations
Page 9
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfEngine(3pf)
iterations items
__________________
special no
|
PFENG_BBOX
This function generates a bounding box that contains the coordinates in
the PFENG_BBOX_SRC source.
Source index Data ilist offset stride
or Destination Type Applicable Applicable Applicable
________________________________________________________________
PFENG_BBOX_SRC pfVec3[] no yes yes
Destination pfBox no no no
|
|
|
|
iterations items
__________________
yes 3
|
PFENG_TIME
This function takes a time in seconds and makes it into a frame number
that is useful in driving the frame source of the PFENG_MORPH,
PFENG_BLEND and PFENG_ANIMATE functions.
PFENG_TIME_TIME is the source time in seconds. This is usually connected
to the pfFlux returned from pfGetFrameTimeFlux.
PFENG_TIME_SCALE contains 4 floats that are used to modify the incoming
time. PFENG_TIME_SCALE[0] is an initial offset. PFENG_TIME_SCALE[1] is
a scale factor. PFENG_TIME_SCALE[2] is a range. PFENG_TIME_SCALE[3] is
a final offset.
The PFENG_TIME_MODE mode determines how the destination number moves
between its start and end point. PFENG_TIME_CYCLE will cause it to go
from start to end then restart at begin. PFENG_TIME_SWING will cause it
to go back and forth between start to end. This mode is related to the
interval mode of a pfSequence.
If the PFENG_TIME_TRUNC mode is set to PF_ON the result is truncated.
The following pseudo code defines how the destination is calculated.
dst is the destination
t is PFENG_TIME_TIME
s is PFENG_TIME_SCALE
if (PFENG_TIME_MODE == PFENG_TIME_CYCLE)
dst = fmodf((t + s[0]) * s[1], s[2]) + s[3];
else /* PFENG_TIME_MODE == PFENG_TIME_SWING */
{
Page 10
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfEngine(3pf)
tmp = fmodf((t + s[0]) * s[1], s[2] * 2.0f);
if (tmp >= s[2])
dst = ((s[2] * 2.0f) - tmp) + s[3];
else
dst = tmp + s[3];
}
if (PFENG_TIME_TRUNC == PF_ON)
dst = (int)dst;
Source index Data ilist offset stride
or Destination Type Applicable Applicable Applicable
__________________________________________________________________
PFENG_TIME_TIME float[1] no no no
PFENG_TIME_SCALE float[4] no no no
Destination float[1] no no no
|
|
|
|
iterations items
__________________
no no
|
PFENG_STROBE
This function switches iterations sets of items floats between an on and
off state based on the time. One use of the PFENG_STROBE function is
light point animations.
PFENG_STROBE_TIME is the source time in seconds. This is usually
connected to the pfFlux returned from pfGetFrameTimeFlux.
PFENG_STROBE_TIMING contains iterations sets of 3 floats that are used to
determine whether the destination for an iteration should be set to the
on or off time whether incoming time. PFENG_STROBE_TIMING[n*stride + 0]
is the on duration. PFENG_STROBE_TIMING[n*stride + 1] is the off
duration. PFENG_STROBE_TIMING[n*stride + 2] is an offset.
PFENG_STROBE_ON contains iterations sets of items floats.
PFENG_STROBE_OFF contains iterations sets of items floats. If
PFENG_STROBE_OFF is NULL, all off states are 0.0.
The following pseudo code defines how the destination is calculated for a
set of items floats.
dst is the destination
t is PFENG_STROBE_TIME
timing is PFENG_STROBE_TIMING
on is PFENG_STROBE_ON
off is PFENG_STROBE_OFF
Page 11
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfEngine(3pf)
if (timing[0] > fmodf(t + timing[2], timing[0] + timing[1]))
for (i = 0; i < items; i++)
dst[i] = on[i];
else
dst[i] = off[i];
Source index Data ilist offset stride
or Destination Type Applicable Applicable Applicable
_______________________________________________________________________
PFENG_STROBE_TIME float[1] no no no
PFENG_STROBE_TIMING float[n*3] no yes yes
PFENG_STROBE_ON float[] no yes yes
PFENG_STROBE_OFF float[] no yes yes
Destination float[] no yes yes
|
|
|
|
n = iterations
iterations items
__________________
no no
|
PFENG_USER_FUNCTION
The function executes the function set using pfEngine::setUserFunction.
Source index Data ilist offset stride
or Destination Type Applicable Applicable Applicable
________________________________________________________________________
PFENG_USER_FUNCTION_SRC(n) * * * *
Destination * * * *
|
|
|
|
iterations items
__________________
* *
|
SEE ALSO
pfFlux, pfGetFrameTimeFlux, pfFCS, pfASD
Page 12
