pfdBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
NAME
pfdInitBldr, pfdExitBldr, pfdNewBldr, pfdDelBldr, pfdSelectBldr,
pfdGetCurBldr, pfdAddBldrGeom, pfdAddIndexedBldrGeom, pfdBldrStateVal,
pfdGetBldrStateVal, pfdBldrStateMode, pfdGetBldrStateMode,
pfdBldrStateAttr, pfdGetBldrStateAttr, pfdBldrStateInherit,
pfdGetBldrStateInherit, pfdCaptureDefaultBldrState, pfdResetBldrState,
pfdPushBldrState, pfdPopBldrState, pfdSaveBldrState, pfdLoadBldrState,
pfdBldrGState, pfdGetBldrGState, pfdBuild, pfdBuildNode,
pfdSelectBldrName, pfdGetCurBldrName, pfdGetTemplateObject,
pfdResetAllTemplateObjects, pfdResetObject, pfdMakeDefaultObject,
pfdResetBldrGeometry, pfdGetBldrShare, pfdSetBldrShare,
pfdResetBldrShare, pfdCleanBldrShare, pfdDefaultGState,
pfdGetDefaultGState, pfdMakeSceneGState, pfdOptimizeGStateList,
pfdBldrMode, pfdGetBldrMode, pfdBldrAttr, pfdGetBldrAttr,
pfdBldrDeleteNode - Provides a simple interface between model input code
and internal Performer model representations.
FUNCTION SPECIFICATION
#include <Performer/pfdu.h>
void pfdInitBldr(void);
void pfdExitBldr(void);
pfdBuilder * pfdNewBldr(void);
void pfdDelBldr(pfdBuilder *bldr);
void pfdSelectBldr(pfdBuilder *bldr);
pfdBuilder * pfdGetCurBldr(void);
void pfdAddBldrGeom(pfdGeom *prims, int count);
void pfdAddIndexedBldrGeom(pfdGeom *prims, int count);
void pfdBldrStateVal(int which, float val);
float pfdGetBldrStateVal(int which);
void pfdBldrStateMode(int mode, int val);
int pfdGetBldrStateMode(int mode);
void pfdBldrStateAttr(int which, const void *attr);
const void * pfdGetBldrStateAttr(int attr);
void pfdBldrStateInherit(uint mask);
Page 1
pfdBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
uint pfdGetBldrStateInherit(void);
void pfdCaptureDefaultBldrState(void);
void pfdResetBldrState(void);
void pfdPushBldrState(void);
void pfdPopBldrState(void);
void pfdSaveBldrState(void *name);
void pfdLoadBldrState(void *name);
void pfdBldrGState(const pfGeoState *gstate);
const pfGeoState * pfdGetBldrGState(void);
pfNode * pfdBuild(void);
pfNode * pfdBuildNode(void *name);
void pfdSelectBldrName(void *name);
void * pfdGetCurBldrName(void);
pfObject * pfdGetTemplateObject(pfType *type);
void pfdResetAllTemplateObjects(void);
void pfdResetObject(pfObject *obj);
void pfdMakeDefaultObject(pfObject *obj);
void pfdResetBldrGeometry(void);
pfdShare * pfdGetBldrShare(void);
void pfdSetBldrShare(pfdShare *share);
void pfdResetBldrShare(void);
void pfdCleanBldrShare(void);
void pfdDefaultGState(pfGeoState *def);
const pfGeoState * pfdGetDefaultGState(void);
pfGeoState * pfdMakeSceneGState(pfList *gstateList,
pfGeoState *previousGlobalState);
Page 2
pfdBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
void pfdOptimizeGStateList(pfList *gstateList,
pfGeoState *globalGState);
void pfdBldrMode(int mode, int val);
int pfdGetBldrMode(int mode);
void pfdBldrAttr(int which, void *attr);
void * pfdGetBldrAttr(int which);
void pfdBldrDeleteNode(pfNode *node);
DESCRIPTION
Converting a model database into Performer runtime structures is a very
common task which almost all Performer applications must do. However,
the form in which databases are modeled does not necessarily correspond
to Performer runtime structures. Therefore, the task of reading database
information can be tedious.
The Performer Builder is meant to manage most of the details of
constructing efficient runtime structures. It provides a simple and
convenient interface for bringing scene data into the application without
the need for considering how best to structure that data for efficient
rendering in Performer. The Builder provides a comprehensive interface
between model input code (such as database file parsers) and the internal
mechanisms of scene representation in Performer.
The operational state of the Builder is encapsulated in a pfdBuilder
object. During execution, there is always a current pfdBuilder defined.
pfdInitBldr initializes the current (default) pfdBuilder and pfdExitBldr
terminates its use. For those who wish to explicitly manage the use of
several builders, pfdNewBldr creates a new pfdBuilder object and
pfdDelBldr destroys a pfdBuilder object. pfdSelectBldr and pfdGetCurBldr
set and query the current pfdBuilder, respectively.
The Builder is used in an immediate mode fashion. A typical client will
feed a series of geometric primitives to the Builder, occasionally
setting certain graphics states, and finally request that the Builder
convert all the input data into a Performer scene graph.
pfdAddBldrGeom is the means by which a new geometric primitive is entered
into the Builder. It accepts a pointer to a single pfdGeom structure
prims. If the indicated pfdGeom is a line-strip, then the count argument
provides the number of line segments in the strip. pfdAddIndexedBldrGeom
provides the same functions for indexed primitives. See the
documentation for the Performer geometry builder (pfdGeoBuilder) for
documentation on the structure and use of the pfdGeom structure.
In addition to geometry, we need to specify various graphics states.
There is always a current graphics state being applied to input geometric
primitives. pfdBldrStateVal, pfdGetBldrStateVal, pfdBldrStateMode,
Page 3
pfdBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
pfdGetBldrStateMode, pfdBldrStateAttr, pfdGetBldrStateAttr,
pfdBldrStateInherit, and pfdGetBldrStateInherit are used to access and
alter this state. These functions are an exact duplication of the
interface to pfGeoStates; refer to the pfGeoState documentation for
details on graphics states and their use.
The current graphics state can also be manipulated as a whole.
pfdPushBldrState and pfdPopBldrState manipulate a stack of graphics
states, the top of which is the current state. pfdDefaultGState records
the state defined by pfGeoState def as the Builder's default state.
pfdResetBldrState resets the current graphics state to the default state,
and pfdCaptureDefaultBldrState makes the current state the default state.
Finally, pfdSaveBldrState saves the current state with the given name,
and pfdLoadBldrState loads the named state into the current state.
For convenience, the current graphics state can be set directly from a
pfGeoState using pfdBldrGState. The given pfGeoState will be used as a
template to set the current Builder graphics state. pfdGetBldrGState
returns the current Builder state as a pfGeoState. The returned
pfGeoState should not be modified in any way.
By default the Builder will use the global pfdShare structure to store
shared graphics state. It is possible to set the pfdShare structure used
by the current pfdBuilder using pfdSetBldrShare. pfdSetBldrShare returns
the pfdShare structure used by the current pfdBuilder.
pfdBuild takes all the geometry data and graphics state information that
has been input into the Builder and constructs a Performer scene graph
for it. The function returns a pfNode which is the root of this graph.
While transferring database information to the Builder, it is possible to
partition the database into logical units. Each unit is given a name; in
normal operation, all data is tagged with the same default name. Every
named partition will correspond to a disjoint subgraph in the scene graph
generated by pfdBuild. The function pfdBuildNode can be used to build
the graph for a single specific partition, rather than the entire input
database. pfdSelectBldrName sets the name being applied to input data
and pfdGetCurBldrName queries the current name being used.
It is also possible to remove all accumulated data in the Builder.
pfdResetBldrGeometry clears away all geometry information stored in the
Builder. pfdResetBldrShare deletes all shared graphics state in the
Builder. pfdCleanBldrShare deletes all shared graphics state that is
only referenced through the current pfdBuilder's share structure (this is
accomplished through pfdCleanShare which in turn uses pfUnrefDelete to
delete individual state elements that are only referenced by the
pfdBuilder).
pfdBldrDeleteNode gets a list of all state attributes attached to leaf
nodes under node, activates pfDelete on node, then proceeds to remove
each state attribute from the current pfdBuilder's share structure via
pfdRemoveSharedObject.
Page 4
pfdBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
The Builder also tries to alleviate the need for the user to manipulate
Performer objects while building the database. pfdGetTemplateObject
returns a standard object of the given type. The user can then fill in
the appropriate slots of this object and pass this object to the Builder.
This allows the Builder to deal with some of the details of Performer
data structures as well as accept the burden of managing memory for
database objects. pfdResetObject fills in a template object with the
default values for that object type. pfdMakeDefaultObject sets the
default values using the given object as a template. Use
pfdResetAllTemplateObjects to restore all of the template objects to the
values defined by the Builder's default pfGeoState.
As another form of sharing, Performer databases can also utilize a
default global pfGeoState. For example, pfSceneGState sets the global
pfGeoState for an entire scene. All pfGeoStates in the relevant scene
graph would inherit state from the global default. See the manual pages
for pfGeoState for further details on state inheritance.
The construction of this default state is also incorporated into the
Builder. While processing incoming data, the Builder remembers the
default pfGeoState. pfdDefaultGState sets this default state and
pfdGetDefaultGState can be used to query it. All pfGeoStates constructed
by the Builder will inherit the attributes of this default pfGeoState.
If a series of pfGeoStates have already been constructed,
pfdMakeSceneGState can be used to extract a default pfGeoState which
maximizes sharing through inheritance. In order to do this,
pfdMakeSceneGState requires the list of pfGeoStates to be optimized and
the default pfGeoState in effect when they were originally constructed.
Finally, pfdOptimizeGStateList takes a list of pfGeoStates and forces
them to inherit state wherever that state agrees with the specified
default.
The behavior of the Builder can be controlled by changing various Builder
modes and attributes. pfdBldrMode and pfdGetBldrMode set and query the
Builder modes, respectively. pfdBldrAttr and pfdGetBldrAttr set and
query Builder attributes.
The supported Builder modes are:
PFDBLDR_MESH_ENABLE
PFDBLDR_AUTO_COLORS
PFDBLDR_AUTO_ORIENT
PFDBLDR_AUTO_NORMALS
These modes are used to control the geometry builder. See the
documentation for pfdGeoBldrMode for details.
PFDBLDR_MESH_SHOW_TSTRIPS
PFDBLDR_MESH_INDEXED
PFDGBLDR_SHARE_INDEX_LISTS
PFDBLDR_MESH_MAX_TRIS
PFDBLDR_MESH_RETESSELLATE
These modes are used to control the triangle strip mesher.
Refer to the documentation for pfdMesherMode.
Page 5
pfdBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
PFDBLDR_BREAKUP
When this mode is enabled (its value is non-NULL), input
geometry will be fed through pfdBreakup. This utility takes
the unstructured input geometry and creates an output graph
reflecting a spatial subdivision of the input.
PFDBLDR_BREAKUP_SIZE
PFDBLDR_BREAKUP_BRANCH
PFDBLDR_BREAKUP_STRIP_LENGTH
If pfdBreakup is called, the values of these modes determine
the argument values passed to it.
PFDBLDR_SHARE_MASK
This is a bitwise-OR of the attributes that should be shared in
the Performer scene graph constructed by the Builder (see
pfdShare).
PFDBLDR_ATTACH_NODE_NAMES
If this mode is enabled, every pfNode constructed by the
Builder will have its name set to the name assigned to it
during input to the Builder; that is, the name set using
pfdSelectBldrName will become the name of the new nodes.
PFDBLDR_DESTROY_DATA_UPON_BUILD
If this mode is set, all the data in the builder along with
associated state information (except for information about
attributes that should be shared) will be destroyed when
pfdBuild returns.
The available attributes are:
PFDBLDR_NODE_NAME_COMPARE
The value of this attribute is a function to compare two node
names. If its value is NULL, the == operator is used for
comparisons.
PFDBLDR_STATE_NAME_COMPARE
The value of this attribute is a function to compare two state
names. If its value is NULL, the == operator is used for
comparisons.
The following code sample illustrates the use of the Builder. It is
designed to read a database file which is simply a list of vertex
coordinates. Every vertex triple defines a triangle.
pfNode * pfdLoadFile_tri (char *fileName)
{
FILE *triFile = NULL;
pfNode *node = NULL;
pfdGeom *prim = NULL;
int v = 0;
int t;
/* open ".tri" file */
if ((triFile = pfdOpenFile(fileName)) == NULL)
Page 6
pfdBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
return NULL;
/* allocate primitive buffer */
prim = pfdNewGeom(3);
/* discard any lingering geometry in the builders */
pfdResetBldrGeometry();
/* pick a random not-too-dark color */
pfuRandomColor(prim->colors[0], 0.4f, 0.8f);
/* specify control data */
prim->numVerts = 3;
prim->primtype = PFGS_POLYS;
prim->nbind = PFGS_PER_VERTEX;
prim->cbind = PFGS_PER_PRIM;
for (t = 0 ; t < PF_MAX_TEXTURES ; t ++)
prim->tbind = PFGS_OFF;
/* read triangles from ".tri" file */
while (!feof(triFile))
{
/* read vertices from ".tri" file */
for (v = 0; v < 3; v++)
{
/* read vertex data */
fscanf(triFile, "%f %f %f",
&prim->coords[v][PF_X],
&prim->coords[v][PF_Y],
&prim->coords[v][PF_Z]);
fscanf(triFile, "%f %f %f",
&prim->norms[v][PF_X],
&prim->norms[v][PF_Y],
&prim->norms[v][PF_Z]);
}
/* add this line to builder */
pfdAddBldrGeom(prim, 1);
}
/* close ".tri" file */
fclose(triFile);
/* release primitive buffer */
pfdDelGeom(prim);
/* get a complete scene graph representing file's primitives */
node = pfdBuild();
return node;
}
Page 7
pfdBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
NOTES
The libpfdu source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
SEE ALSO
pfGeoSet, pfGeoState, pfObject, pfdBreakup, pfdGeoBuilder, pfdMeshGSet,
pfdMesherMode, pfdShare, pfSceneGState
Page 8
