pfDispListOptimizer(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
NAME
pfGetDLOptimizerTmpMemory, pfGetDLOptimizerTmpGSet,
pfGetDLOptimizerMatrix, pfDLOptimizerCloneGSet, pfDLOptimizerOptimize,
pfGetDLOptimizerChannel, pfGetDLOptimizerNumServers,
pfGetDLOptimizerMyId, pfGetDLOptimizerOptimizationMask - Set and get
pfDispListOptimizer environment, Allocate temporary objects.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
void* pfGetDLOptimizerTmpMemory(pfDispListOptimizer* _op,
int size);
pfGeoSet* pfGetDLOptimizerTmpGSet(pfDispListOptimizer* _op);
pfMatrix* pfGetDLOptimizerMatrix(pfDispListOptimizer* _op,
int which);
pfGeoSet* pfDLOptimizerCloneGSet(pfDispListOptimizer* _op,
pfGeoSet *gset, unsigned int copyMask);
pfGeoSet* pfDLOptimizerOptimize(pfDispListOptimizer* _op,
pfGeoSet *gset);
pfChannel* pfGetDLOptimizerChannel(pfDispListOptimizer* _op);
int pfGetDLOptimizerNumServers(pfDispListOptimizer* _op);
int pfGetDLOptimizerMyId(pfDispListOptimizer* _op);
unsigned int -
pfGetDLOptimizerOptimizationMask(pfDispListOptimizer* _op);
typedef pfGeoSet *(*pfSidekickFunc)(pfGeoSet *gset, pfDispListOptimizer *op, void *userData);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfDispListOptimizer is derived from the parent
class pfObject, so each of these member functions of class pfObject are
also directly usable with objects of class pfDispListOptimizer. Casting
an object of class pfDispListOptimizer 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);
Page 1
pfDispListOptimizer(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfDispListOptimizer 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);
DESCRIPTION
A pfDispListOptimizer is the active component of any CULL_SIDEKICK
process. A CULL_SIDEKICK process allocates a pfDispListOptimizer for
every pfDispList on every pfChannel on its pfPipe. An application never
allocates a pfDispListOptimizer. Performer provides a pointer to a
pfDispListOptimizer when invoking a CULL_SIDEKICK user function.
The CULL_SIDEKICK set of processes runs in parallel with any CULL
process. When the CULL process decides that some pfGeoSets are visible,
it puts them on a pfDispList. The CULL_SIDEKICK process traverses this
pfDispList as it fills up. The CULL_SIDEKICK tracks some graphic state
elements defined on the pfDispList. When the CULL_SIDEKICK process hits a
pfGeoSet, it has two choices: (1) If the application didn't specify a
user function, the CULL_SIDEKICK process runs per-orimitive culling on
the pfGeoSet primitives. (2) If the application specified a user
function, the CULL_SIDEKICK process calls the user function providing a
pointer to the pfDispListOptimizer object processing the current
pfDispList.
An application callback of type pfSidekickFunc receives as input a
pointer to a pfGeoSet gset, a pointer to a pfDispListOptimizer op and a
pointer to a user-data buffer userData. It may access the
pfDispListOptimizer pointer in order to retrieve some contextual
Page 2
pfDispListOptimizer(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
information about the calling CULL_SIDEKICK process and about the current
graphic state. The application may also access the pfDispListOptimizer
pointer in order to allocate temporary memory blocks and temporary
pfGeoSets. The application should treat the gset pointer as read-only.
gset isn't multi-buffered by default.
pfGetDLOptimizerMatrix provides access to the current transformation
matrices. When the DRAW process renders gset it would load this matrix
to OpenGL. which selects the returned matrix. It should be one of the
following values:
PFSK_MODELVIEW
Return the MODELVIEW matrix.
PFSK_PROJECTION
Return the PROJECTION matrix.
PFSK_COMBINED
Return the concatenation of the the MODELVIEW and PROJECTION
matrices.
pfDLOptimizerCloneGSet returns a temporary clone of gset. This clone
pfGeoSet should not be used outside the context of the
pfDispListOptimizer user function. Performer keeps no reference counts
on the temporary pfGeoSets. They are re-used as soon as the DRAW process
finishes rendering their corresponding pfDispList. copyMask specifies
what attributes of the original pfGeoSet are to be copied to the clone
pfGeoSet. It is a bitwose OR of the constants: PFSK_COORD3, PFSK_COLOR4,
PFSK_NORMAL3, PFSK_TEXCOORD2, PFSK_ATTR_LENGTHS.
pfGetDLOptimizerTmpMemory returns a temporary buffer of side at least
size bytes. This buffer use useful for replacing pfGeoSet attribute
buffers. Similar to the temporary pfGeoSet above, this buffer should not
be used outside the context of the pfDispListOptimizer user function.
pfDLOptimizerOptimize runs the default optimization algorithm on gset. It
returns a pointer to a pfGeoSet. This returned value may be any of the
following:
The same as gset -
This means that the optimization algorithm left gset unchanged.
Either because it is completely visible, or because its
primitive type is not supported.
A new non-NULL pointer -
This means that the optimization algorithm cloned gset and
replaced its contents with the visible postions of the original
pfGeoSet gset. A user function may make farther changes to the
returned pfGeoSet, or it may clone it again and change the
cloned pfGeoSet.
Page 3
pfDispListOptimizer(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
NULL -
This means that the optimization algorithm decided that all the
primitives in gset are not visible.
pfGetDLOptimizerChannel returns a pointer to the pfChannel where gset was
visible.
pfGetDLOptimizerNumServers returns the number of CULL_SIDEKICK processes
participating in optimizing the pfDispLists in this pfPipe. The default
number is 1. It may be changed by calling pfMultithread.
pfGetDLOptimizerMyId returns the index of this CULL_SIDEKICK process.
This index is always between zero and pfGetDLOptimizerNumServers.
pfGetDLOptimizerOptimizationMask returns the optimization mask for this
CULL_SIDEKICK process. The optimization mask is specified per-pfPipe
using pfMultithreadParami (see man page).
The pfDispListOptimizer user function should return a pfGeoSet pointer.
This pointer replaces the original gset pointer on the pfDispList. In
other words, instead of rendering gset, the DRAW process would render the
returned pfGeoSet. The user function may also return NULL. This means
that the original pfGeoSet gset should be skipped by the DRAW process.
Here is a sample user function. This function changes the contents of one
vertex of a pfGeoSet.
pfGeoSet *
myUserFunction(pfGeoSet *gset, pfDispListOptimizer *op, void *userData)
{
pfGeoSet *new_gset;
float *v;
ushort *ilist;
// Clone gset. Request a complete copy of all its attributes
new_gset = op -> cloneGSet(gset,
PFSK_COORD3 |
PFSK_COLOR4 |
PFSK_NORMAL3 |
PFSK_TEXCOORD2 |
PFSK_ATTR_LENGTHS);
// Get a pointer to the PFGS_COORD3 attribute of the cloned pfGeoSet
new_gset -> getAttrLists(PFGS_COORD3, &v, &ilist);
// Set the first vertex of the cloned pfGeoSet to (10,10,10)
v[0] = 10.0;
v[1] = 10.0;
v[2] = 10.0;
// Return the cloned pfGeoset: tell the pfDispListOptimizer to
Page 4
pfDispListOptimizer(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
// replace the pointer `gset' by `new_gset' in the display list.
// The DRAW process shall render new_gset instead of gset.
return new_gset;
}
An application can turn optimization of specific pfGeoSets on or off by
calling pfGSetOptimize. By default, all pfGeoSets are optimized.
SEE ALSO
pfMultithreadParami, pfMultithreadParamf, pfMultithreadParam,
pfMultiprocess
Page 5
