pfEngine(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfEngine(3pf)NAME
pfNewEngine, pfGetEngineClassType, pfEngineSrc, pfGetEngineSrc,
pfGetEngineNumSrcs, pfEngineDst, pfGetEngineDst, pfEngineIterations,
pfGetEngineIterations, pfGetEngineFunction, pfEngineUserFunction,
pfGetEngineUserFunction, pfEngineMode, pfGetEngineMode, pfEngineMask,
pfGetEngineMask, pfEngineEvaluationRange, pfGetEngineEvaluationRange,
pfEngineSrcChanged, pfEngineEvaluate, pfEngineEvaluateEye, - Create,
initialize, and manage a pfEngine
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfEngine* pfNewEngine(int function, void *arena);
pfType* pfGetEngineClassType(void);
void pfEngineSrc(pfEngine* engine, int index, void *data,
ushort *ilist, int icount, int offset,
int stride);
void pfGetEngineSrc(const pfEngine* engine, int index,
void **data, ushort **ilist, int *icount,
int *offset, int *stride);
int pfGetEngineNumSrcs(const pfEngine* engine);
void pfEngineDst(pfEngine* engine, void *data,
ushort *ilist, int offset, int stride);
void pfGetEngineDst(const pfEngine* engine, void **data,
ushort **ilist, int *offset, int *stride);
void pfEngineIterations(pfEngine* engine, int iterations,
int items);
void pfGetEngineIterations(const pfEngine* engine,
int *iterations, int *items);
int pfGetEngineFunction(const pfEngine* engine);
void pfEngineUserFunction(pfEngine* engine,
pfEngineFuncType func);
pfEngineFuncType pfGetEngineUserFunction(const pfEngine* engine);
void pfEngineMode(pfEngine* engine, int mode, int val);
int pfGetEngineMode(const pfEngine* engine, int mode);
void pfEngineMask(pfEngine* engine, uint mask);
Page 1
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfEngine(3pf)
uint pfGetEngineMask(const pfEngine* engine);
void pfEngineEvaluationRange(pfEngine* engine,
pfVec3 center, float min, float max);
void pfGetEngineEvaluationRange(pfEngine* engine,
pfVec3 center, float *min, float *max);
void pfEngineSrcChanged(pfEngine* engine);
void pfEngineEvaluate(pfEngine* engine, int mask);
void pfEngineEvaluateEye(pfEngine* engine, 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. Casting an object of
class pfEngine 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 pfEngine 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);
Page 2
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfEngine(3pf)
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);
PARAMETERS
engine identifies a pfEngine.
DESCRIPTION
A pfEngine is an object for controlling the dynamic data in a pfFlux.
pfNewEngine creates and returns a handle to a pfEngine. arena specifies
a malloc arena out of which the pfEngine is allocated or NULL for
allocation off the process heap. A NULL pointer is returned to indicate
failure. pfEngine can be deleted with pfDelete. 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
pfGetEngineClassType returns the pfType* for the class pfEngine. The
pfType* returned by pfGetEngineClassType is the same as the pfType*
returned by invoking pfGetType 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 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.
pfGetEngineFunction returns the function of a pfEngine.
pfEngineIterations and pfGetEngineIterations 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
Page 3
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfEngine(3pf)
the functions.
pfEngineSrc and pfGetEngineSrc 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 pfMalloc.
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
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 pfEngineIterations.
Both offset and stride are measured in items, where an item is the basic
data type of the source. This is usually floats.
pfGetEngineNumSrcs returns the highest source index set plus one.
pfEngineDst and pfGetEngineDst set and get the destination of a pfEngine.
data should be either a pfFlux* or a pointer to a block of memory
allocated with pfMalloc. 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: pfEngineDst does not have an icount because the iterations set with
pfEngineIterations 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 pfEngineIterations.
Both offset and stride are measured in items, where an item is the basic
Page 4
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfEngine(3pf)
data type of the source. This is usually floats.
pfEngineSrcChanged will mark the destination pfFlux of a pfEngine as
dirty for the current flux frame.
pfEngineMode and pfGetEngineMode 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
____________________________________
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
pfEngineEvaluateEye 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.
pfEngineMask and pfGetEngineMask set and get the evaluation mask of a
pfEngine. The default mask is PFFLUX_BASIC_MASK.
pfEngineEvaluationRange and pfGetEngineEvaluationRange set and get the
evaluation range of a pfEngine.
pfEngineEvaluate and pfEngineEvaluateEye 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 pfEngineEvaluateEye is used.
pfEngineUserFunction and pfGetEngineUserFunction 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 pfFluxWriteComplete on its destination pfFlux, as that
will be done by pfEngineEvaluate.
FUNCTIONS
PFENG_SUM
This function will add arrays of floats together to form a destination
Page 5
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfEngine(3pf)
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
_________________________________________________________________
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
Page 6
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfEngine(3pf)
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],
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
Page 7
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfEngine(3pf)
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
______________________________________________________________________
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 pfDCSRot.
PFENG_MATRIX_TRANS contains a xyz translation and does the equivalent of
pfDCSTrans.
PFENG_MATRIX_SCALE_UNIFORM contains a scale and does the equivalent of
pfDCSScale
PFENG_MATRIX_SCALE_XYZ contains a zyz scale and does the equivalent of
pfDCSScaleXYZ.
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
__________________
|
Page 8
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfEngine(3pf)
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
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 pfDCSRot.
PFENG_ANIMATE_TRANS contains an array of xyz translations and does the
equivalent of pfDCSTrans.
PFENG_ANIMATE_SCALE_UNIFORM contains an array of scales and does the
equivalent of pfDCSScale
PFENG_ANIMATE_SCALE_XYZ contains an array of zyz scales and does the
equivalent of pfDCSScaleXYZ.
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
|
|
|
|
Page 9
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfEngine(3pf)
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
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.
Page 10
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfEngine(3pf)
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 */
{
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
Page 11
pfEngine(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfEngine(3pf)
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
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 pfEngineUserFunction.
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
