pfdGeoBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
NAME
pfdNewGeom, pfdResizeGeom, pfdDelGeom, pfdCopyGeom, pfdReverseGeom,
pfdNewGeoBldr, pfdDelGeoBldr, pfdGeoBldrMode, pfdGetGeoBldrMode,
pfdTriangulatePoly, pfdAddGeom, pfdAddPoint, pfdAddLine, pfdAddTri,
pfdAddPoly, pfdAddPoints, pfdAddLines, pfdAddLineStrips,
pfdAddIndexedPoints, pfdAddIndexedLines, pfdAddIndexedLineStrips,
pfdAddIndexedTri, pfdAddIndexedPoly, pfdGetNumTris, pfdBuildGSets,
pfdPrintGSet - Create optimized pfGeoSets from independent geometry.
FUNCTION SPECIFICATION
#include <Performer/pfdu.h>
pfdGeom * pfdNewGeom(int numV);
void pfdResizeGeom(pfdGeom *geom, int numV);
void pfdDelGeom(pfdGeom *geom);
void pfdCopyGeom(pfdGeom *dst, pfdGeom *src);
int pfdReverseGeom(pfdGeom *geom);
pfdGeoBuilder * pfdNewGeoBldr(void);
void pfdDelGeoBldr(pfdGeoBuilder* bldr);
void pfdGeoBldrMode(pfdGeoBuilder* bldr, int mode, int val);
int pfdGetGeoBldrMode(pfdGeoBuilder* bldr, int mode);
int pfdTriangulatePoly(pfdGeom *pgon, pfdPrim *triList);
void pfdAddGeom(pfdGeoBuilder *bldr, pfdGeom *Geom,
int num);
void pfdAddPoint(pfdGeoBuilder *bldr, pfdPrim *Point);
void pfdAddLine(pfdGeoBuilder *bldr, pfdPrim *line);
void pfdAddTri(pfdGeoBuilder *bldr, pfdPrim *tri);
void pfdAddPoly(pfdGeoBuilder *bldr, pfdGeom *poly);
void pfdAddPoints(pfdGeoBuilder *bldr, pfdGeom *points);
void pfdAddLines(pfdGeoBuilder *bldr, pfdGeom *lines);
void pfdAddLineStrips(pfdGeoBuilder *bldr,
pfdGeom *lineStrips, int num);
Page 1
pfdGeoBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
void pfdAddIndexedPoints(pfdGeoBuilder *bldr,
pfdGeom *points);
void pfdAddIndexedLines(pfdGeoBuilder *bldr,
pfdGeom *lines);
void pfdAddIndexedLineStrips(pfdGeoBuilder *bldr,
pfdGeom *lines, int num);
void pfdAddIndexedTri(pfdGeoBuilder *bldr, pfdPrim *tri);
void pfdAddIndexedPoly(pfdGeoBuilder *bldr, pfdGeom *poly);
int pfdGetNumTris(pfdGeoBuilder *bldr);
pfList * pfdBuildGSets(pfdGeoBuilder *bldr);
void pfdPrintGSet(pfGeoSet *gset);
typedef struct _pfdPrim
{
int flags;
int nbind, cbind, tbind[PF_MAX_TEXTURES];
float pixelsize;
pfVec3 coords[3];
pfVec3 norms[3];
pfVec4 colors[3];
pfVec2 texCoords[PF_MAX_TEXTURES][3];
pfVec3 *coordList;
pfVec3 *normList;
pfVec4 *colorList;
pfVec2 *texCoordList[PF_MAX_TEXTURES];
ushort icoords[3];
ushort inorms[3];
ushort icolors[3];
ushort itexCoords[PF_MAX_TEXTURES][3];
int numTextures;
struct _pfdPrim *next;
} pfdPrim;
typedef struct _pfdGeom
{
int flags;
int nbind, cbind, tbind[PF_MAX_TEXTURES];
Page 2
pfdGeoBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
int numVerts;
short primtype;
float pixelsize;
pfVec3 *coords;
pfVec3 *norms;
pfVec4 *colors;
pfVec2 *texCoords[PF_MAX_TEXTURES];
pfVec3 *coordList;
pfVec3 *normList;
pfVec4 *colorList;
pfVec2 *texCoordList[PF_MAX_TEXTURES];
ushort *icoords;
ushort *inorms;
ushort *icolors;
ushort *itexCoords[PF_MAX_TEXTURES];
int numTextures;
struct _pfdGeom *next;
} pfdGeom;
typedef pfdGeom pfdPoly;
typedef pfdPrim pfdTri;
DESCRIPTION
The pfdGeoBuilder tools greatly simplify the task of creating OpenGL
Performer geometry structures (pfGeoSets). More importantly, the
pfdGeoBuilder utility creates optimized line-strip and triangle-strip
pfGeoSets that can significantly improve rendering performance and
decrease memory usage.
The pfdGeoBuilder only manages geometry. For managing geometry and state
(appearance attributes such as texture and material) there is a higher
level pfdBuilder tool that itself uses the pfdGeoBuilder.
Typically the higher-level pfdBuilder (rather than the low-level
pfdGeoBuilder) is used when writing a database importer for OpenGL
Performer. In either case, the loaders take external data in popular
database file formats and convert them into OpenGL Performer runtime
scene-graph structures. There are many examples of file loaders based on
the pfdBuilder and pfdGeoBuilder facilities in the libpfdb database
loader library.
The pfdGeoBuilder is used to build pfGeoSets from arbitrary input
geometry in the following way:
Page 3
pfdGeoBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
1. Create a pfdGeoBuilder data structure by calling pfdNewGeoBldr.
2. Create a pfdGeom data structure by calling pfdNewGeom with the
maximum number of vertices required. This size can be changed
later via calls to pfdResizeGeom.
3. Add geometric objects one at a time to the builder created in
Step 1 via calls to pfdAddGeom, pfdAddPoint, pfdAddLine,
pfdAddTri, pfdAddPoly, pfdAddPoints, pfdAddLines,
pfdAddLineStrips, pfdAddIndexedPoints, pfdAddIndexedLines,
pfdAddIndexedLineStrips, pfdAddIndexedTri, or
pfdAddIndexedPoly.
4. Once all geometry has been added to the builder, call
pfdBuildGSets to obtain a list of pfGeoSets representing the
geometry in line strips and triangle strips wherever possible.
pfdNewGeom allocates a pfdGeom structure capable of containing a single
geometric object with up to numV vertices. This object contains a number
of internal arrays whose sizes scale with numV, so allocating a large
pfdGeom can require a considerable amount of storage.
pfdResizeGeom is used to change the vertex limit of the pfdGeom geom.
The old vertex values are retained in this reallocation, so that loaders
can simply invoke pfdResizeGeom to enlarge a pfdGeom without special
attention to the existing data. When the new size (numV) is smaller than
the previous size, only the first numV old vertices are kept.
pfdDelGeom frees the storage allocated for the pfdGeom geom.
pfdCopyGeom copies the contents of the pfdGeom src to dst. Use
pfdResizeGeom if necessary to ensure that the arrays internal to dst are
of an appropriate size prior to the copy.
pfdReverseGeom reverses the order of the vertices in geom. Use this to
generate polygonal objects with a consistent vertex ordering (clockwise
or counterclockwise) when viewed from the outside. When this is the case,
backface culling can be enabled for improved graphics performance.
pfdNewGeoBldr allocates a new pfdGeoBuilder structure and initializes it
to accept geometry. The pfdGeoBuilder's internal data is self-sizing and
will grow as needed when points, lines, and polygons are added to it.
pfdDelGeoBldr frees the storage allocated to the pfdGeoBuilder bldr.
pfdGeoBldrMode specifies modes to be used by the pfdGeoBuilder bldr as it
processes input geometry and constructs pfGeoSets. The supported modes
are:
Page 4
pfdGeoBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
PFDGBLDR_AUTO_COLORS
Generate random colors for geometric objects. There are four
options for this mode, and they are:
PFDGBLDR_COLORS_PRESERVE
Leave color definitions as they are. This is the default
mode.
PFDGBLDR_COLORS_MISSING
Generate colors for those primitives that do not provide
them. This mode only replaces missing colors, it does not
override any colors that have been defined.
PFDGBLDR_COLORS_GENERATE
Generate a new random color for each primitive.
PFDGBLDR_COLORS_DISCARD
Discard existing color definitions and do not generate any
replacement colors.
PFDGBLDR_AUTO_NORMALS
Generate normals for geometric objects. There are four options
for this mode, and they are:
PFDGBLDR_NORMALS_PRESERVE
Leave normal definitions as they are. This is the default
mode.
PFDGBLDR_NORMALS_MISSING
Generate normals for those primitives that do not provide
them. This mode only replaces missing normals, it does
not override any normals that have been defined.
PFDGBLDR_NORMALS_GENERATE
Generate a new normal for each primitive.
PFDGBLDR_NORMALS_DISCARD
Discard existing normal definitions and do not generate
any replacement normals.
PFDGBLDR_AUTO_TEXTURE
Generate texture coordinates for geometric objects. There are
four options for this mode, and they are:
PFDGBLDR_TEXTURE_PRESERVE
Leave texture coordinate definitions as they are. This is
the default mode.
Page 5
pfdGeoBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
PFDGBLDR_TEXTURE_MISSING
Generate texture coordinates for those primitives that do
not provide them. This mode only replaces missing texture
coordinates, it does not override any texture coordinates
that have been defined. This option is provided for
future expansion. It is not currently implemented.
PFDGBLDR_TEXTURE_GENERATE
Generate texture coordinates for each primitive. This
option is provided for future expansion. It is not
currently implemented.
PFDGBLDR_TEXTURE_DISCARD
Discard existing texture coordinate definitions and do not
generate any replacement texture coordinates.
PFDGBLDR_AUTO_ORIENT
Automatically reverse normal vector direction or vertex order
for polygons that have a supplied overall normal or per-vertex
normals if the internally computed normal value indicates that
the input vertices had clockwise rather than counterclockwise
orientation.
PFDGBLDR_ORIENT_PRESERVE
Do not modify vertex orientation or normal direction.
PFDGBLDR_ORIENT_NORMALS
Reverse direction (by negating normals) to make the
sidedness of polygons consistent with the standard
orientation, which is counterclockwise when viewed from
the outside of the surface. The outside is defined as the
direction in which the normal points.
PFDGBLDR_ORIENT_VERTICES
Reverse direction (by reversing the order of vertices) to
make the sidedness of polygons consistent with the
standard orientation, which is counterclockwise when
viewed from the outside of the surface. The outside is
defined as the direction in which the normal points. This
is the default method, since people who provide a normal
usually know which way they want it to point.
PFDGBLDR_MESH_ENABLE
Generate triangle meshes from input geometry. This task is
actually performed using the pfdMeshGSet function. See the
pfdTMesher man page for further details. The default is TRUE.
pfdGetBldrMode returns the current value of pfdGeoBuilder bldr's internal
processing mode, mode. The valid mode arguments are those listed for
pfdGeoBldrMode above.
Page 6
pfdGeoBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
pfdTriangulatePoly triangulates a polygon defined by pfdGeom pgon and
appends the resulting triangles to the list of triangles in triList. If
the input polygon is concave, pfdTriangulatePoly will OR the
PFDPOLY_CONCAVE bit into the flags member of the poly structure. The
return value is TRUE if poly is concave and FALSE otherwise. Note that
pfdTriangulatePoly will not "fan out" convex polygons but will "zigzag"
them so the resultant triangles can be easily formed into a single
triangle strip (see pfdMeshGSet).
Geometric objects are added to a pfdGeoBuilder using the general
pfdAddGeom function or via the related functions described below.
pfdAddGeom adds one a pfdGeom object to the designated pfdGeoBuilder
bldr. If the pfdGeom is a line strip, then the argument num specifies the
number of lines in the line strip pfdAddGeom is the general way to add
geometry to a pfdGeoBuilder.
Four distinct types of geometric objects can be defined in a pfdGeom:
points, lines, line strips, and polygons, and there is a lower-level
primitive adding function for each: pfdAddPoints, pfdAddLines,
pfdAddLineStrips, and pfdAddPoly. These functions are invoked by
pfdAddGeom to process input geometry and are not usually called directly
by users.
The pfdGeoBuilder also supports the optimization of indexed geometric
data. It is only necessary to specify index list information in the
pfdGeom structure and then call one of the indexed versions of the
geometry adding functions: pfdAddIndexedPoints, pfdAddIndexedLines,
pfdAddIndexedLineStrips, or pfdAddIndexedPoly.
There are four remaining geometry adding functions. These accept low-
level pfdPrim geometry definitions rather than the higher-level pfdGeom
definitions. Use of these functions is discouraged. pfdAddPoint adds the
point pfdPrim Point to pfdGeoBuilder bldr, pfdAddLine adds the line line,
pfdAddTri adds the triangle tri, and pfdAddIndexedTri adds the indexed
triangle tri.
In all cases, these geometry processing functions copy the geometric
definition into internal pfdGeoBuilder memory so that the application
need not manage multiple pfdGeom or pfdPrim data structures. The fields
of the pfdGeom or pfdPrim structure should be set as follows:
nbind, cbind, tbind specify the normal, color, and texture coordinate
binding respectively. They may be one of the following values:
PFGS_PER_VERTEX
An attribute is specified for each vertex of the point, line,
or polygon.
PFGS_PER_PRIM, PFGS_OVERALL
The first element of the attribute array specifies the
attribute for the point, line, or polygon, e.g. norms[0] is the
Page 7
pfdGeoBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
normal for the entire object.
PFGS_OFF
No attribute value is specified.
pixelsize defines the width in pixels to be used when drawing the
indicated point or line. pixelsize is ignored for polygon data.
coords, norms, colors, texCoords specify the coordinates, normals,
colors, and texture coordinates of the point, line, or polygon according
to the binding types described above, e.g. coords[0], coords[1],
coords[2] define the coordinates of a pfdTri.
Example 1:
pfdGeoBuilder *bldr;
pfdGeom *geom;
pfList *gsetList;
int t;
/* allocate pfdGeoBuilder and pfdGeom storage */
bldr = pfdNewGeoBldr();
geom = pfdNewGeom(4);
/* feed polygons to pfdGeoBuilder */
while (!done)
{
:
geom->flags = 0;
geom->nbind = PFGS_PER_PRIM;
geom->cbind = PFGS_OFF;
for (t = 0 ; t < PF_MAX_TEXTURES ; t ++)
geom->tbind[t] = PFGS_OFF;
geom->numVerts = 4;
pfCopyVec3(geom->coords[0], myCoords[i]);
pfCopyVec3(geom->coords[1], myCoords[i+1]);
pfCopyVec3(geom->coords[2], myCoords[i+2]);
pfCopyVec3(geom->coords[3], myCoords[i+3]);
pfCopyVec3(geom->norms[0], myNorms[j]);
pfdAddGeom(bldr, geom, 1);
:
}
/* generate optimized triangle mesh GeoSet */
gsetList = pfdBuildGSets(bldr);
/* add returned pfGeoSets to geode */
for (i=0; i<pfGetNum(gsetList); i++)
pfAddGSet(geode, pfGet(gsetList, i));
Page 8
pfdGeoBuilder(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
/* release pfdGeoBuilder and pfdGeom storage */
pfdDelGeoBldr(bldr);
pfdDelGeom(geom);
pfdGetNumTris returns the number of triangles currently contained in the
pfdGeoBuilder structure bldr.
pfdBuildGSets converts all accumulated points, lines, and polygons into
point, line, line strip, triangle, and triangle-strip pfGeoSets and
returns a pfList referencing these pfGeoSets. pfdBuildGSets also resets
bldr, removing the geometric definitions therein. The pfGeoSets created
by the builder are meshed by pfdMeshGSet, subject to the meshing mode set
by pfdMesherMode.
pfdPrintGSet prints a representation of pfGeoSet gset using the pfNotify
mechanism.
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, pfGeode, pfList, pfdMeshGSet, pfdMesherMode, pfdTMesher
Page 9
