pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)NAME
pfGeoSet, pfFluxedGSetInit - Create, modify and query geometry set
objects
FUNCTION SPECIFICATION
#include <Performer/pr/pfGeoSet.h>
pfGeoSet::pfGeoSet()
static pfType * pfGeoSet::getClassType(void);
void pfGeoSet::compile(void);
void pfGeoSet::draw(void);
void pfGeoSet::drawHlightOnly(void);
void pfGeoSet::setNumPrims(int num);
int pfGeoSet::getNumPrims(void);
void pfGeoSet::setPrimType(int type);
int pfGeoSet::getPrimType(void);
void pfGeoSet::setPrimLengths(int *lengths);
int * pfGeoSet::getPrimLengths(void);
int * pfGeoSet::getPrimLength(int i);
void pfGeoSet::setAttr(int attr, int bind, void *alist,
ushort *ilist);
int pfGeoSet::getAttrBind(int attr);
void pfGeoSet::getAttrLists(int attr, void **alist,
ushort **ilist);
int pfGeoSet::getAttrRange(int attr, int *minIndex,
int *maxIndex);
void pfGeoSet::setMultiAttr(int attr, int index, int bind,
void *alist, ushort *ilist);
int pfGeoSet::getMultiAttrBind(int attr, int index);
void pfGeoSet::getMultiAttrLists(int attr, int index,
void **alist, ushort **ilist);
Page 1
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
int pfGeoSet::getMultiAttrRange(int attr, int index,
int *minIndex, int *maxIndex);
void pfGeoSet::setDrawMode(int mode, int val);
int pfGeoSet::getDrawMode(int mode);
void pfGeoSet::setDecalPlane(pfPlane *plane);
pfPlane * pfGeoSet::getDecalPlane(int mode);
void pfGeoSet::setGState(pfGeoState *gstate);
pfGeoState * pfGeoSet::getGState(void);
void pfGeoSet::setGStateIndex(int id);
int pfGeoSet::getGStateIndex(void);
void pfGeoSet::setLineWidth(float width);
float pfGeoSet::getLineWidth(void);
void pfGeoSet::setPntSize(float size);
float pfGeoSet::getPntSize(void);
void pfGeoSet::setHlight(pfHighlight *hlight);
pfHighlight * pfGeoSet::getHlight(void);
void pfGeoSet::setDrawBin(short bin);
int pfGeoSet::getDrawBin(void);
void pfGeoSet::setDrawOrder(unsigned int order);
unsigned int pfGeoSet::getDrawOrder(void);
static void pfGeoSet::setPassFilter(uint mask);
static uint pfGeoSet::getPassFilter(void);
void pfGeoSet::hideStripPrim(int i);
void pfGeoSet::unhideStripPrim(int i);
int pfGeoSet::isStripPrimHidden(int i);
int pfGeoSet::query(uint which, void* dst);
Page 2
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
int pfGeoSet::mQuery(uint* which, void* dst);
void pfGeoSet::setBound(pfBox *bbox, int mode);
int pfGeoSet::getBound(pfBox *bbox);
void pfGeoSet::setBoundFlux(pfFlux *flux);
pfFlux* pfGeoSet::getBoundFlux(void);
void pfGeoSet::setIsectMask(uint mask, int setMode,
int bitOp);
uint pfGeoSet::getIsectMask(void);
int pfGeoSet::isect(pfSegSet *segSet, pfHit **hits[]);
void pfGeoSet::setPassList(pfPassList *passList_);
pfPassList* pfGeoSet::getPassList();
void pfGeoSet::updateCteRefs(void);
void pfGeoSet::calcTexBBox(void);
void pfGeoSet::setTexBBox(uint centerS, uint centerT,
uint halfwidth, uint halfheight);
void pfGeoSet::setTexBBox(float minS, float maxS,
float minT, float maxT);
int pfGeoSet::getTexBBox(uint* centerS, uint* centerT,
uint* halfwidth, uint* halfheight);
int pfGeoSet::getTexBBox(float* minS, float* maxS,
float* minT, float* maxT);
void pfGeoSet::setCteAttr(int which, void* val);
void* pfGeoSet::getCteAttr(int which);
void pfGeoSet::setAppearance(islAppearance *appearance);
islAppearance * pfGeoSet::getAppearance(void);
int pfGeoSet::isShaded(void);
void pfGeoSet::quickCopy(pfGeoSet *src);
void pfGeoSet::quickSetAttr(int _attr, void* _alist,
unsigned short* _ilist);
Page 3
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
void pfGeoSet::quickSetMultiAttr(int _attr, int _index,
void* _alist, unsigned short* _ilist);
void pfGeoSet::quickSetPrimLengths(int *_lengths);
void pfGeoSet::quickReset(int extRefOnly);
void pfGeoSet::setOptimize(int _state);
int pfGeoSet::getOptimize(void);
int pfFluxedGSetInit(pfFluxMemory *fmem);
struct pfSegSet
{
int mode;
void* userData;
pfSeg segs[PFIS_MAX_SEGS];
uint activeMask;
uint isectMask;
void* bound;
int (*discFunc)(pfHit*);
};
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfGeoSet is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfGeoSet. 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 pfGeoSet 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);
Page 4
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
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();
PARAMETERS
attr is a symbolic token that identifies a specific attribute type and
is one of:
PFGS_COLOR4 alist must be list of pfVec4 colors
PFGS_NORMAL3 alist must be list of pfVec3 normals,
PFGS_TEXCOORD2 alist must be list of pfVec2 texture
coordinates,
PFGS_COORD3 alist must be list of pfVec3 coordinates.
bind is a symbolic token that specifies an attribute binding type and is
one of:
PFGS_OFF attr is not specified and is thus
inherited,
PFGS_OVERALL attr is specified once for the entire
pfGeoSet,
PFGS_PER_PRIM attr is specified once per primitive,
PFGS_PER_VERTEX attr is specified once per vertex.
DESCRIPTION
The pfGeoSet (short for "Geometry Set") is a fundamental OpenGL Performer
data structure. Each pfGeoSet is a collection of geometry with one
primitive type, such as points, lines, triangles. Each pfGeoSet also has
a single combination of texture, normal, and color attribute bindings,
such as "untextured with colors per vertex and normals per primitive". A
pfGeoSet forms primitives out of lists of attributes which may or may not
be indexed. An indexed pfGeoSet uses a list of unsigned shorts to index
Page 5
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
an attribute list.
Indexing provides a more general mechanism for specifying geometry than
hardwired attribute lists and also has the potential for substantial
memory savings due to shared attributes. Nonindexed pfGeoSet's are
sometimes easier to construct and may save memory in situations where
vertex sharing is not possible since index lists are not required.
Nonindexed pfGeoSet's also require fewer CPU cycles to traverse and may
exhibit better caching behavior. A pfGeoSet must be either completely
indexed or non-indexed; hybrid pfGeoSets that have some attributes
indexed and others non-indexed are not supported. For theses cases,
simply construct an identity-map index list and specify it with each
"non-indexed" pfGeoSet attribute array.
new(arena) allocates a pfGeoSet from the specified memory arena, or from
the process heap if arena is NULL. new allocates a pfGeoSet from the
default memory arena (see pfGetSharedArena). Like other pfObjects,
pfGeoSets cannot be created statically, automatically on the stack or in
arrays. pfGeoSets should be deleted with pfDelete rather than the delete
operator.
pfGeoSet Attributes
pfGeoSet::setAttr sets a pfGeoSet attribute binding type, attribute list,
and attribute index list. These pfGeoSet attributes include vertex
coordinate, color specification, normal vector, texture coordinate, or
packed attribute array which is supplied in list form to the pfGeoSet.
The optional attribute index list is a list of unsigned short integers
which index the attribute list. The attribute binding type specifies how
the lists are interpreted to define geometry, specifying for example,
that the color attribute list provides a color for each vertex
(PFGS_PER_VERTEX) or just an overall color for the entire pfGeoSet
(PFGS_OVERALL).
pfGeoSet supports two multi-valued attributes: PFGS_TEXCOORD2 and
PFGS_TEXCOORD3. A multi-valued attribute is an ordered set of regular
attributes. pfGeoSet::setMultiAttr sets a pfGeoSet multi-valued
attribute. It has an additional parameter index identifying one of the
ordered set of attributes. The available multi-valued attributes enable
specifying multiple texture coordinate arrays on a pfGeoSet. pfGeoSet
uses these arrays on graphic hardware supporting the OpenGL multi-texture
extension.
index can be in the range 0 to (PF_MAX_TEXTURES-1). These value
correspond to hardware multi-texture units with the same indices. At
run-time, pfGeoSet rejects index values if the current hardware does not
have enough multi-texture units. pfGeoSet recognizes all multi-value
attributes from (index == 0) to the first index with a NULL attribute.
For example, when setting the PFGS_TEXCOORD2 multi-value attribute at
index 0, 1, and 3, pfGeoSet ignores the setting for (index == 3) because
the attribute with (index == 2) is NULL.
Page 6
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
Calling pfGeoSet::setAttr with attribute PFGS_TEXCOORD2 and
PFGS_TEXCOORD3 is equivalent to calling pfGeoSet::setMultiAttr on the
same attributes with (index == 0).
Only certain combinations of attributes and binding types make sense.
For example, vertices clearly must be specified per-vertex and the
utility of texture coordinates specified other than per-vertex is
questionable.
The following table shows the allowed combinations for the normal
attribute arrays:
Attribute Type
______________________________________
Binding COLOR4 NORMAL3 TEXCOORD2 COORD3
_______________________________________________________
PFGS_OFF yes yes yes no
PFGS_OVERALL yes yes no no
PFGS_PER_PRIM yes yes no no
PFGS_PER_VERTEX yes yes yes yes
|
In conjunction with specifying a vertex binding for a given vertex
attributes, packed attribute arrays may set with the PFGS_PACKED_ATTRS.
Packed attribute arrays must include all of the per-vertex data for the
normal attributes the single array, according to the packed attribute
format that is set as the PFGS_PACKED_ATTRS binding type. Only PFGS_OFF,
PFGS_OVERALL and PFGS_PER_VERTEX attribute bindings may be used for the
normal vertex attributes when using the packed attribute arrays. The
format of the PFGS_PACKED_ATTRS may be one of:
PFGS_PA_C4UBN3ST2FV3F
the packed attribute array contains all currently bound per-
vertex attributes, including the vertex coordinates. Colors
must be packed into one unsigned byte with RGBA byte ordering,
normals must be shorts scaled to the range [-32767, 32767],
texture coordinates and vertex coordinates are floats. Each
attribute for each vertex must start on a 32-bit word boundary.
PFGS_PA_C4UBN3ST2F
the packed attribute array contains all currently bound per-
vertex attributes, except the vertex coordinates. Colors must
be packed into one unsigned byte with RGBA byte ordering,
normals must be shorts scaled to the range [-32767, 32767],
texture coordinates are floats. The vertex coordinates will be
taken from the normal vertex attribute array specified with the
PFGS_COORD3 attribute. Each attribute for each vertex must
start on a 32-bit word boundary.
PFGS_PA_C4UBT2F
the packed attribute array contains colors as unsigned bytes
and 2D texture coordinates as floats. The vertex coordinates
will be taken from the normal vertex attribute array specified
Page 7
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
with the PFGS_COORD3 attribute and normals will be taken from
the normal attribute array specified with PFGS_NORMAL3.
PFGS_PA_C4UBN3ST2SV3F, PFGS_PA_C4UBN3ST2S, PFGS_PA_C4UBT2S
the packed attribute array contains the specified currently
bound per-vertex attributes. Colors are packed into unsigned
bytes, normals are signed shorts in the range [-32767, 32767]
and texture coordinates are unsigned shorts in the range [0,
65536]. A texture matrix should be used to rescale the texture
coordinates into the proper range. A texture matrix can be
specified for a pfGeoSet through its pfGeoState. See the set
pfGStateAttr(3pf) man page and the PFSTATE_TEXMAT attribute.
PFGS_PA_C4UBN3ST3FV3F, PFGS_PA_C4UBN3ST3F, PFGS_PA_C4UBT3F
the packed attribute array contains the specified currently
bound per-vertex attributes as above. Texture coordinates are
floats and are 3D texture coordinates, specifying s, t, and r.
PFGS_PA_C4UBN3ST3SV3F, PFGS_PA_C4UBN3ST3S, PFGS_PA_C4UBT3S the
packed attribute array contains the specified currently bound
per-vertex attributes as above. Texture coordinates are
unsigned shorts and are 3D texture coordinates, specifying s,
t, and r.
When only using packed attribute arrays, you may specify a NULL for the
redundant attribute data arrays for the individual attributes, such as
the colors, normals,, and texture coordinates. The normal vertex
attribute arrays is required if intersections are to be done with the
pfGeoSet. For examples of using PFGS_PACKED_ATTRS, see the example below,
as well as the example in
/usr/share/Performer/src/pguide/libpr/C/vertexarray.c. There are also
utility routines in libpfutil for creating the packed attribute arrays;
see the pfuTravCreatePackedAttrs and pfuFillGSetPackedAttrs man pages for
more information.
An OVERALL binding requires an index list of length 1 for indexed
pfGeoSets. The value of bind is unimportant for attr = PFGS_COORD3 since
vertices are always specified on a per-vertex basis. Default bindings
are OFF for all attributes except coordinates.
ilist, if not NULL, is an index array which indexes the attribute array,
alist. If ilist is NULL, the pfGeoSet is non-indexed and accesses the
attribute list in sequential order.
If any attribute's binding is not PFGS_OFF and the corresponding ilist is
defined as NULL, the pfGeoSet is considered to be non-indexed and ALL
other specified index lists will be ignored. Nonindexed interpretation
of an attribute list is equivalent to using an index list whose elements
are 0,1,2,...,N-1. Consequently it is possible to emulate a pfGeoSet
with mixed indexed and non-indexed attributes by using an index array
whose elements are 0,1,2,...,N-1 with N being the largest possible index.
If attribute and index lists are allocated from the pfMalloc routines,
Page 8
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
pfGeoSet::setAttr will correctly update the reference counts of the
lists. Specifically, pfGeoSet::setAttr will decrement the reference
counts of the old lists and increment the reference counts of the new
lists. It will not free any lists whose reference counts reach 0. When
a pfGeoSet is deleted with pfDelete, all pfMalloc'ed lists will have
their reference counts decremented by one and will be freed if their
count reaches 0.
When pfGeoSets are copied with pfCopy, all pfMalloc'ed lists of the
source pfGeoSet will have their reference counts incremented by one and
those pfMalloc'ed lists of the destination pfGeoSet will have their
reference counts decremented by one. pfCopy copies lists only by
reference (only the pointer is copied) and will not free any lists whose
reference counts reach 0.
Attribute lists may be any of the following types of memory:
1. Data allocated with pfMalloc. This is the usual, and
recommended memory type for pfGeoSet index and attribute
arrays.
2. Static, malloc(), amalloc(), usmalloc() etc, data subsequently
referred to as non-pfMalloc'ed data. This type of memory is
not generally recommended since it does not support reference
counting or other features provided by pfMalloc. In
particular, the use of static data is highly discouraged and
may result in segmentation violations.
3. pfFlux memory. In a pipelined, multiprocessing environment, a
pfFlux provides multiple data buffers which allow frame-
accurate data modifications to pfGeoSet attribute arrays like
coordinates (facial animation), and texture coordinates (ocean
waves, surf). pfGeoSet::setAttr will accept a pfFlux* or
pfFluxMemory* for the attribute list (index lists do not
support pfFlux) and the pfGeoSet will select the appropriate
buffer when rendered or intersected with. See pfFlux for more
details.
4. pfCycleBuffer and pfCycleMemory. However pfCycleBuffer has
been obsoleted by pfFlux. See pfCycleBuffer for more details.
Performer allows mixing pfMalloc'ed, pfFlux and pfCycleBuffer attributes
on a single pfGeoSet.
pfGeoSet::getAttrBind returns the binding type of attr and
pfGeoSet::getAttrLists returns the attribute and index list base
pointers. If the gset is non-indexed, send down a dummy ushort pointer
instead of NULL as ilist.
Similarly, pfGeoSet::getMultiAttrBind returns the binding type of attr at
the index'th position, and pfGeoSet::getMultiAttrLists returns the
attribute and index list base pointers at the index'th position.
Page 9
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
pfGeoSet::getAttrRange returns the range of attributes in the attribute
list identified by attr that are used by the pfGeoSet. (The total size,
in bytes, of the list may be queried through pfGetSize if the list was
allocated by pfMalloc.) If the list is non-indexed,
pfGeoSet::getAttrRange returns the number of contiguous attributes
accessed by the pfGeoSet (the range implicitly beginning at 0). If the
list is indexed, pfGeoSet::getAttrRange returns the same value as in the
non-indexed case but also copies the minimum and maximum indices into
minIndex and maxIndex. If the attribute list is non-indexed, or the
attribute binding type is PFGSS_OFF, 0 and -1 are returned in minIndex
and maxIndex. NULL may be passed instead of minIndex and/or maxIndex
when the min/max index is not required.
pfGeoSet::getAttrRange is typically used to allocate a new attribute
array when cloning a pfGeoSet:
int numVerts = gset->getAttrRange(PFGS_COORD3, NULL, &max);
numVerts = PF_MAX2(numVerts, max + 1);
newVerts = (pfVec3*) pfMalloc(sizeof(pfVec3) * numVerts, arena);
Similarly, pfGeoSet::getMultiAttrRange returns the range of attributes in
the attribute list identified by attr for a multi-valued attribute at
position index.
pfGeoSet Primitive Types
pfGeoSet::setPrimType specifies the type of primitives found in a
pfGeoSet. type is a symbolic token and is one of:
PFGS_POINTS
PFGS_LINES
PFGS_LINESTRIPS
PFGS_FLAT_LINESTRIPS
PFGS_TRIS
PFGS_QUADS
PFGS_TRISTRIPS
PFGS_FLAT_TRISTRIPS
PFGS_TRIFANS
PFGS_FLAT_TRIFANS
PFGS_POLYS
The primitive type dictates how the coordinate and coordinate index lists
are interpreted to form geometry. See below for a description of
primitive types. pfGeoSet::getPrimType returns the primitive type of the
pfGeoSet.
pfGeoSet::setNumPrims and pfGeoSet::getNumPrims sets/gets the number of
primitives in the pfGeoSet. A primitive is a single point, line segment,
line strip, triangle, quad, triangle strip, or polygon depending on the
primitive type.
Page 10
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
A single line strip, triangle strip, or polygon is considered to be a
primitive so a pfGeoSet may contain multiple strips of differing lengths
or multiple polygons with differing number of sides. Therefore, for
strip primitives and PFGS_POLYS, a separate array is necessary which
specifies the number of vertices in each strip or polygon. This array is
set by pfGeoSet::setPrimLengths. lengths is an array of vertex counts
such that lengths[0] = number of vertices in strip/polygon 0, lengths[1]
= number of vertices in strip/polygon 1,..., lengths[n-1] = number of
vertices in strip/polygon n-1 where n is the number of primitives set by
pfGeoSet::setNumPrims. pfGeoSet::getPrimLengths returns a pointer to the
lengths array of the pfGeoSet. pfGeoSet::getPrimLength returns the
positive length for the ith primitive of the pfGeoSet.
As of OpenGL Performer 2.2, the negative of the proper length may be
specified for an individual length of a strip prmitive in the lengths
array to indicate that this pfGeoSet primitive should be "hidden" from
drawing. The primitive will however be counted in drawing statistics (-
pfStats) and will be used in intersections and bounding box computations
and all other pfGeoSet processing. pfGeoSet::hideStripPrim will force
the length of the i'th primitive of a stripped pfGeoSet to be the
negative of its proper length; pfGeoSet::unhideStripPrim will set the
primitive length to be the positive value. pfGeoSet::isStripPrimHidden
will return 1 if the ith primitive of the pfGeoSet is negative and 0
otherwise. pfGeoSet::getPrimLength always returns a positive length for
the ith primitive of the pfGeoSet and can be used wherever the lengths of
pfGeoSets of unknown source must be inspected to protect against negative
values in the lengths array.
Assuming the coordinate index list is an array V indexed by i, num is the
number of primitives, lengths is the array of strip or polygon lengths
and Nv the size of the coordinate index list, the primitive type
interprets V in the following ways:
PFGS_POINTS
The pfGeoSet is a set of num points. Each V[i] is a point, i =
0, 1, 2, ..., num-1. Nv = num.
PFGS_LINES
The pfGeoSet is a set of num disconnected line segments. Each
line segment is drawn from V[i] to V[i+1], i = 0, 2, ...,
2*(num-1). Nv = 2 * num.
PFGS_LINESTRIPS
The pfGeoSet is a set of num line strips (also known as
polylines). Linestrip[i] is drawn between V[p+j], j = 0, 1,
..., lengths[i]-1, where p is sum of all lengths[k], 0 <= k <
i. Nv = sum of all lengths[k], k = 0, 1, ..., num-1. Note
that all lengths[i] values should be >= 2.
Page 11
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
PFGS_FLAT_LINESTRIPS
The pfGeoSet is a set of num line strips (also known as
polylines). Linestrip[i] is drawn between V[p+j], j = 0, 1,
..., lengths[i]-1, where p is sum of all lengths[k], 0 <= k <
i. Nv = sum of all lengths[k], k = 0, 1, ..., num-1. Note
that all lengths[i] value should be >= 2.
PFGS_TRIS
The pfGeoSet is a set of num independent triangles. Each
triangle is V[i], V[i+1], V[i+2], i = 0, 3, 6, ..., 3*(num-1).
Nv = 3 * num.
PFGS_QUADS
The pfGeoSet is a set of num independent quads. Each quad is
V[i], V[i+1], V[i+2], V[i+3], i = 0, 4, 8, ..., 4*(num-1). Nv
= 4 * num.
PFGS_TRISTRIPS
The pfGeoSet is a set of num triangle strips. Tristrip[i] is
drawn between V[p+j], j = 0, 1, ..., lengths[i]-1, where p is
sum of all lengths[k], 0 <= k < i. Nv = sum of all lengths[k],
k = 0, 1, ..., num-1. Note that all lengths[i] values should
be >= 3.
PFGS_FLAT_TRISTRIPS
The pfGeoSet is a set of num triangle strips. Tristrip[i] is
drawn between V[p+j], j = 0, 1, ..., lengths[i]-1, where p is
sum of all lengths[k], 0 <= k < i. Nv = sum of all lengths[k],
k = 0, 1, ..., num-1. Note that all lengths[i] should be >= 3.
The FLAT indicates that the strips should be flat shaded and
that additional attributes for the first two vertices are not
specified.
PFGS_TRIFANS
The pfGeoSet is a set of num triangle fans. Each trifan[i] is
a set of lengths[i] triangles. The fan starts with the center
vertex V[0], with the remaining lengths[i]-1 vertices
specifying the outside points.
PFGS_FLAT_TRIFANS
The pfGeoSet is a set of num triangle fans. Each trifan[i] is
a set of lengths[i] triangles. The fan starts with the center
vertex V[0], with the remaining lengths[i]-1 vertices
specifying the outside points. The FLAT indicates that the
strips should be flat shaded and that additional attributes for
the first two vertices are not specified.
PFGS_POLYS
The pfGeoSet is a set of num polygons. Polygon[i] is the
convex hull of the vertices V[p+j], j = 0, 1, ..., lengths[i]-1
where p is sum of all lengths[k], 0 <= k < i. Nv = sum of all
lengths[k], k = 0, 1, ..., num-1. Note that all lengths[i]
Page 12
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
should be >= 3.
PFGS_TRIS, PFGS_QUADS, PFGS_TRISTRIPS, PFGS_FLAT_TRISTRIPS, and
PFGS_POLYS are rendered as filled polygons but will be rendered in wire-
frame according to the following rules:
1. Always render in wireframe mode if PFEN_WIREFRAME mode is
enabled through pfGeoSet::setDrawMode.
2. Use the wireframe mode set by the attached pfGeoState, if any,
as described in pfGeoSet::setGState below.
3. Use the wireframe mode set by pfEnable or pfDisable with the
PFEN_WIREFRAME argument.
A PFGS_PER_VERTEX binding for PFGS_COLOR4 and PFGS_NORMAL3 is interpreted
differently for PFGS_FLAT_LINESTRIPS and PFGS_FLAT_TRISTRIPS primitive
types. With flat-shaded strip primitives, only the last vertex in each
primitive defines the shading of the primitive (see pfShadeModel.) Thus
the first vertex in a FLAT_LINESTRIP and the first two vertices in a
FLAT_TRISTRIP do not require normals or colors. Consequently when
specifying a PFGS_PER_VERTEX binding for either colors or normals, you
should not specify a color or normal for the first vertex of a line strip
or for the first 2 vertices of a triangle strip. pfGeoSet::draw will
automatically set the shading model to FLAT before rendering PFGS_FLAT_
primitives.
Example 1:
/* Set up a non-indexed, FLAT_TRISTRIP pfGeoSet */
gset = new pfGeoSet;
gset->setPrimType(PFGS_FLAT_TRISTRIPS);
gset->setNumPrims(2);
lengths[0] = 4;
lengths[1] = 3;
gset->setPrimLengths(lengths);
/* Only need 3 colors: 2 for 1st strip and 1 for 2nd */
colors = (pfVec4*) pfMalloc(sizeof(pfVec4) * 3, NULL);
gset->setAttr(PFGS_COLOR4, PFGS_PER_VERTEX, colors, NULL);
gset->setAttr(PFGS_COORD3, PFGS_PER_VERTEX, coords, NULL);
pfGeoSet Special Rendering Characteristics
When colortable mode is enabled, either through pfEnable or through
pfGeoState::apply, a pfGeoSet will not use its local color array but will
use the color array supplied by the currently active pfColortable (See
the pfColortable and pfEnable manual pages). pfColortables will affect
both indexed and non-indexed pfGeoSets.
Page 13
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
A pfGeoSet of type PFGS_POINTS will be rendered with the special
characteristics of light points if a pfLPointState has been applied.
Light point features include:
1. Perspective size.
2. Perspective fading.
3. Fog punch-through.
4. Directionality.
5. Intensity.
See pfLPointState for more details.
pfGeoSet::setPntSize and pfGeoSet::setLineWidth set the point size and
line width of the pfGeoSet. Point size has effect only when the
primitive type is PFGS_POINTS and line width is used only for primitive
types PFGS_LINES, PFGS_LINESTRIPS, PFGS_FLAT_LINESTRIPS and for all
primitives drawn in wireframe mode. A pfGeoSet sets point size and line
width immediately before rendering only if the size/width is greater than
zero. Otherwise it will inherit size/width through the Graphics Library.
pfGeoSet::getPntSize and pfGeoSet::getLineWidth return gset's point size
and line width respectively.
pfGeoSet::setDrawMode further characterizes a pfGeoSet's primitive type
as flat-shaded, wireframe or compiled. mode is a symbolic token
specifying the mode to set and is one of:
PFGS_FLATSHADE Always render the pfGeoSet with a flat
shading model.
PFGS_WIREFRAME Always render and intersect the pfGeoSet in
wireframe. For rendering in wireframe and
intersection with solid geometry, enable
wireframe on an attached pfGeoState (See
pfGSetGState).
PFGS_COMPILE_GL At the next draw for each pfState, compile
the pfGeoSet's geometry into a GL display
list and subsequently render the display
list.
PFGS_DRAW_GLOBJ Select the rendering of an already created
display list and do not force a compile.
PFGS_PACKED_ATTRS Use the the pfGeoSet's packed attribute
arrays, set with the PFGS_PACKED_ATTRS to
pfGeoSet::setAttr, to render geometry with
Page 14
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
GL vertex arrays. This mode is only
available under OpenGL operation.
val is PF_ON or PF_OFF to enable/disable the mode.
If a pfGeoSet has very few primitives, the CPU overhead in pfGeoSet::draw
may become noticeable. In this situation, it is reasonable to compile
the pfGeoSet into a GL display list which has very little CPU overhead.
However, GL display lists have several drawbacks that must be considered:
Storage
GL display lists will increase memory usage because every
vertex, color, etc is copied into the display list, thus
duplicating the pfGeoSet's attribute arrays. Additionally, GL
display lists cannot index and so do not benefit from vertex
sharing.
While it is possible to delete the attribute arrays after the
pfGeoSet has been compiled to free up some memory, it will no
longer be possible to intersect with the pfGeoSet's geometry
(see pfGSetIsectSegs).
Flexibility
Once in a GL display list, attributes like coordinates and
normals may not be modified. This precludes dynamic geometry
like water and facial animation.
Coherency
If any attribute of the pfGeoSet changes then the burden is on
the user to regenerate the GL display list through
pfGeoSet::setDrawMode.
In summary, applications with many very small pfGeoSets each of which
defines static unchanging geometry may be suitable for pfGeoSet
compilation into GL display lists.
The mechanism of PFGS_COMPILE_GL is illustrated in the following example:
/* We assume 'gset' is already "built" by this point */
/* Enable GL display list compilation and rendering */
gset->setDrawMode(PFGS_COMPILE_GL, PF_ON);
/*
* The first pfDrawGSet after pfGSetDrawMode will compile
* the pfGeoSet into a GL display list. Note that this is
* a very slow procedure and is generally done at
* initialization time.
*/
gset->draw();
:
Page 15
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
/* This time we draw the GL display list */
gset->draw();
:
/* Disable GL display list mode */
gset->setDrawMode(PFGS_COMPILE_GL, PF_OFF);
/* Free the GL display list and render 'gset' in immediate mode */
gset->draw();
Deciding which shading model to used when draw a pfGeoSet is performed
with the following decision hierarchy:
1. Use flat shading if pfGeoSet consists of either
PFGS_FLAT_TRISTRIPS or PFGS_FLAT_LINESTRIPS or if the mode
PFGS_FLATSHADE is enabled with pfGeoSet::setDrawMode.
2. Use the shading model specified by the pfGeoState bound to the
pfGeoSet. This is the typical case in OpenGL Performer. See
the pfGeoSet::setGState description below for further details.
3. Use the shading model set by pfShadeModel.
pfGeoSet::getDrawMode returns the value of mode or -1 if mode is an
unknown mode.
pfGeoSets (Geometry) and pfGeoStates (Appearance)
A pfGeoState is an encapsulation of libpr graphics modes and attributes
(see pfState). For example, a pfGeoState representing a glass surface
may reference a shiny pfMaterial and enable transparency. A pfGeoState
does not inherit state from other pfGeoStates. Consequently, when
attached to a pfGeoSet via pfGeoSet::setGState, the pfGeoSet will always
be rendered with the state encapsulated by gstate, regardless of the
order in which pfGeoSet/pfGeoState pairs are rendered. This behavior
greatly eases the burden of managing graphics state in the graphics
library. A pfGeoSet may directly reference or indirectly index a
pfGeoState through a global table.
pfGeoSet::setGState "attaches" gstate to the pfGeoSet so that the
pfGeoSet may be drawn with a certain graphics state. When drawn by
pfGeoSet::draw, a pfGeoSet will apply its pfGeoState (if it has one) with
pfGeoState::apply and the graphics library will be initialized to the
proper state for drawing the pfGeoSet. A gstate value of NULL will
remove any previous pfGeoState and cause the pfGeoSet to inherit whatever
graphics state is around at the time of rendering.
pfGeoSet::setGStateIndex allows a pfGeoSet to index its pfGeoState.
Indexing is useful for efficiently managing a single database with
multiple appearances, e.g., a normal vs. an infrared view of a scene
would utilize 2 pfGeoState tables, each referencing a different set of
pfGeoStates.
Page 16
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
Indexed pfGeoStates use a global table of pfGeoState* specified by
pfGeoState::applyTable. When indexing a pfGeoState, pfGeoSet::draw calls
pfGeoState::apply with the indexth entry of this table if the index can
be properly resolved. Otherwise no pfGeoState is applied.
pfGeoSet::getGStateIndex returns the pfGeoState index of the pfGeoSet or
-1 if the pfGeoSet directly references its pfGeoState.
pfGeoSet::setGState increments the reference count of the new pfGeoState
by one and decrements the reference count of the previous pfGeoState by
one but does not delete the previous pfGeoState if its reference count
reaches zero. pfGeoSet::setGStateIndex does not affect pfGeoState
reference counts.
It is important to understand and remember that any pfGeoSet without an
associated pfGeoState will not be rendered with the global, default state
but will be drawn with the current state. To inherit the global state, a
pfGeoState which inherits all state elements should be attached to the
pfGeoSet. pfGeoSets should share like pfGeoStates for space and rendering
time savings. See the pfGeoState reference page for full details.
pfGeoSet::getGState returns the pfGeoState associated with the pfGeoSet
or NULL if there is none. If the pfGeoSet indexes its pfGeoState,
pfGeoSet::getGState will look up the pfGeoState index in the global
pfGeoState table and return the result or NULL if it cannot resolve the
reference.
pfGeoSet::setDecalPlane sets plane to be the reference plane used for the
the pfGeoSet when the current decal mode has PFDECAL_PLANE selected.
Setting a decal plane on a pfGeoSet (as opposed to a pfGeoState) may add
a small amount of overhead to the drawing of that pfGeoSet which may be
visible for small pfGeoSets. However, this may be preferable to breaking
up pfGeoStates for handling many different reference planes. Reference
planes are only supported under OpenGL operation and require the
reference_plane SGI extension to the OpenGL. The PFQFTR_DECAL_PLANE to
pfQueryFeature can be used for run-time queries for the support of decal
reference planes. See the pfDecal man page for more information.
pfGeoSet::setHlight sets hlight to be the highlighting structure used for
the pfGeoSet. When this flag is not PFHL_OFF, this gset will be drawn as
highlighted unless highlighting has been overridden as off with
pfOverride. See the pfHighlight manual page for information of creating
and configuring a highlighting state structure. pfGeoSet::getHlight
returns the current GeoSet highlight definition.
pfGeoSet::drawHlightOnly is a convenience routine for drawing ONLY the
highlighting stage of the pfGeoSet, according to the currently active
highlighting structure.
Page 17
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
Drawing pfGeoSets
pfGeoSet::draw is a display-listable command. If a pfDispList has been
opened by pfDispList::open, pfGeoSet::draw will not have immediate effect
but will be captured by the pfDispList and will only have effect when
that pfDispList is later drawn with pfDispList::draw.
If gset has an attached pfGeoState, then pfGeoSet::draw first calls
pfGeoState::apply before rendering the pfGeoSet geometry, as shown in the
following examples.
Example 3a:
/* Make sure 'gset' has not attached pfGeoState */
gset->setGState(NULL);
/* Apply graphics state encapsulated by 'gstate' */
gstate->apply();
/* Draw 'gset' with graphics state encapsulated by 'gstate' */
gset->draw();
Example 3b:
/* Attach 'gstate' to 'gset' */
gset->setGState(gstate);
/* Draw 'gset' with graphics state encapsulated by 'gstate' */
gset->draw();
Example 3c:
/* Use indexed pfGeoState */
gset->setGStateIndex(2);
/* Set up and apply pfGeoState table */
list->set(2, gstate);
list->applyTable();
/* Draw 'gset' with graphics state encapsulated by 'gstate' */
gset->draw();
Examples 3a, 3b, and 3c are equivalent methods for drawing the same
thing. Method 3b is recommended though since the pfGeoState and pfGeoSet
pair can be set up at database initialization time.
pfGeoSet::setDrawBin sets the pfGeoSet's draw bin identifier to bin. bin
Page 18
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
identifies a drawing bin to which the pfGeoSet belongs and is used for
controlling the rendering order of a database. The pfGeoSet draw bin is
currently used only by libpf applications (see pfChannel::setBinOrder)
and is ignored by libpr-only applications. The default pfGeoSet draw bin
identifier is -1. ::getDrawBin returns the draw bin identifier of gset.
pfGeoSet::setDrawOrder sets the pfGeoSet's order in the bin if the bin
sort order is PFSORT_DRAW_ORDER. It is necessary to set the Draw Order
of each pfGeoSet that contains calligraphic light points (see
pfCalligraphic man pages). Do not set the DrawBin for those pfGeoSets, as
they will automatically go in the light point display list if a LPoint
Process has been started.
The mask argument to pfGeoSet::setPassFilter is a bitmask which specifies
a pfGeoSet drawing "filter". Only pfGeoSets which pass the filter test
are rendered by pfGeoSet::draw. mask consists of the logical OR of the
following:
PFGS_TEX_GSET
Draw only textured pfGeoSets
PFGS_NONTEX_GSET
Draw only non-textured pfGeoSets
PFGS_EMISSIVE_GSET
Draw only pfGeoSets which use an emissive pfMaterial or
pfLPointState.
PFGS_NONEMISSIVE_GSET
Draw only non-emissive pfGeoSets
PFGS_LAYER_GSET
Draw only pfGeoSets which are layer (as opposed to base)
geometry.
PFGS_NONLAYER_GSET
Draw only pfGeoSets which are not layer geometry.
A mask of 0 disables pfGeoSet filtering. Filtering is useful for
multipass rendering techniques. pfGeoSet::getPassFilter returns the
current pfGeoSet filtering mask.
pfGeoSet::compile will force the immediate creation of a GL display list
for the pfGeoSet in the current graphics context but will not draw or
select display list renderin for the pfGeoSet. This routine is usefull
for the preprocessing of pfGeoSets, possibly in a sproced non-rendering
process for OpenGL, for future GL display list rendering. Since
pfGeoSet::compile does not execute the pfGeoSet display list, the display
list will not affect or be downloaded to the graphics pipeline.
pfGeoSet::compile is not a display-listable command.
Page 19
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
Intersecting with pfGeoSets
pfGeoSet::setIsectMask enables intersections and sets the intersection
mask for the pfGeoSet. mask is a 32-bit mask used to determine whether a
particular pfGeoSet should be examined during a particular intersection
request. A non-zero bit-wise AND of the pfGeoSet's mask with the mask of
the intersection request (pfGeoSet::isect) indicates that the pfGeoSet
should be tested. The default mask is all 1's, i.e. 0xffffffff.
pfGeoSet::getIsectMask returns the intersection mask of the specified
pfGeoSet.
Intersections for geometry whose vertex coordinates don't change are more
efficient when information is cached for each pfGeoSet to be intersected
with. When setting the mask or changing caching, PFTRAV_SELF should
always be part of setMode. OR-ing PFTRAV_IS_CACHE into setMode causes
the creation or update of the cache. Because creating the cache requires
a moderate amount of computation, it is best done at setup time.
For objects whose geometry changes only occasionally, additional calls to
pfGeoSet::setIsectMask with PFTRAV_IS_CACHE OR-ed into setMode will
recompute the cached information. Alternately, OR-ing PFTRAV_IS_UNCACHE
into setMode will disable caching.
The bitOp argument is one of PF_AND, PF_OR, or PF_SET and indicates,
respectively, whether the new mask is derived from AND-ing with the old
mask, OR-ing with the old mask or simply set.
pfGeoSet::setBound sets the bounding volume of the pfGeoSet. Each
pfGeoSet has an associated bounding volume used for culling and
intersection testing and a bounding mode, either static or dynamic. By
definition, the bounding volume of a node encloses all the geometry
parented by node, which means that the node and all its children fit
within the node's bounding volume.
The mode argument to pfGeoSet::setBound specifies whether or not the
bounding volume for node should be recomputed when an attribute of the
pfGeoSet is changed. If the mode is PFBOUND_STATIC, OpenGL Performer
will not modify the bound once it is set or computed. If the mode is
PFBOUND_DYNAMIC, OpenGL Performer will recompute the bound if the number
of primitives, the primitive lengths array or the vertex coordinate
arrays are changed. Note that OpenGL Performer does not know if the
contents of these arrays changes, only when the pointer itself is set.
Recomputation of the bounding box can be forced by calling
pfGeoSet::setBound with a bbox that is NULL. Also note that a geoset can
not update the parent geode with this new bounding volume information, as
a result, a geoset will not propagate new bounding information up the
tree. Call pfNode::setBound on the parent Geode to recompute the
bounding volume.
pfGeoSet::getBound copies the bounding box of the pfGeoSet into bbox and
returns the current bounding mode.
Page 20
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
pfGeoSet::setBoundFlux and pfGeoSet::getBoundFlux set and get a pfFlux
that can be used to contain the bounding box of a pfGeoSet.
pfGeoSet::isect tests for intersection between the pfGeoSet the pfGeoSet
and the group of line segments specified in segSet. The resulting
intersections (if any) are returned in hits. The return value of
pfGeoSet::isect is the number of segments that intersected the pfGeoSet.
hits is an empty array supplied by the user through which results are
returned. The array must have an entry for each segment in segSet. Upon
return, hits[i][0] is a pfHit* which gives the intersection result for
the ith segment in segSet. The pfHit objects come from an internally
maintained pool and are reused on subsequent requests. Hence, the
contents are only valid until the next invocation of pfGSetIsectSegs in
the current process. They should not be freed by the application.
segSet is a pfSegSet public structure specifying the intersection
request. In the structure, segs is an array of line segments to be
intersected against the pfGeoSet. activeMask is a bit vector specifying
which segments in the SegSet are to be active for the current request.
If the i'th bit is set to 1, it indicates the corresponding segment in
the segs array is active.
The bit vector mode specifies the behavior of the intersection process
and is a bitwise OR of the following:
PFTRAV_IS_PRIM Intersect with primitives (quads or
triangles)
PFTRAV_IS_GSET Intersect with pfGeoSet bounding boxes
PFTRAV_IS_NORM Return normal in the pfHit structure
PFTRAV_IS_CULL_BACK Ignore backfacing polygons
PFTRAV_IS_CULL_FRONT Ignore front-facing polygons
The bit fields PFTRAV_IS_PRIM and PFTRAV_IS_GSET, indicate the level at
which intersections should be evaluated and discriminator callbacks, if
any, invoked. Note that if neither of these level selectors are
specified, no intersection testing is done at all. In the pfSegSet,
isectMask is another bit vector. It is bit-wise AND-ed with the
intersection mask of the pfGeoSet. If the result is zero no intersection
testing is done.
The bound field in a pfSegSet is an optional user provided bounding
volume around the set of segments. Currently, the only supported volume
is a cylinder. To use a bounding cylinder, bitwise OR PFTRAV_IS_BCYL
into the mode field of the pfSegSet and assign the pointer to the
bounding volume to the bound field. pfCylinder::around will construct a
cylinder around the segments.
Page 21
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
When a bounding volume is supplied, the bounding volume is tested against
the pfGeoSet bounding box before examining the individual segments. The
largest improvement is for groups of at least several segments which are
closely grouped segments. Placing a bounding cylinder around small
groups or widely dispersed segments can decrease performance.
The userData pointer allows an application to associate other data with
the pfSegSet. Upon return and in discriminator callbacks, the pfSegSet's
userData pointer can be obtained from the returned pfHit with the virtual
function pfObject::getUserData.
discFunc is a user supplied callback function which provides a more
powerful means for controlling intersections than the simple mask test.
The function acts as a discriminating function which examines information
about candidate intersections and judges their validity. When a
candidate intersection occurs, the discFunc callback is invoked with a
pfHit structure containing information about the intersection.
The callback may then return a value which indicates whether and how the
intersection should continue. This value is composed of the following
major action specifications with additional modifiers bitwise-OR-ed in as
explained below.
PFTRAV_CONT
Indicates that the process should continue traversing the
primitive list.
PFTRAV_PRUNE
Stops further testing of the line segment against the current
pfGeoSet.
PFTRAV_TERM
Stops further testing of the line segment completely.
To have PFTRAV_TERM or PFTRAV_PRUNE apply to all segments,
PFTRAV_IS_ALL_SEGS can be OR-ed into the discriminator return value.
This causes the entire traversal to be terminated or pruned.
The callback may OR into the status return value any of:
PFTRAV_IS_IGNORE
Indicates that the current intersection should be ignored,
otherwise the intersection is taken as valid.
PFTRAV_IS_CLIP_START
Indicates that for pruned and continued traversals that before
proceeding the segment should be clipped to start at the
current intersection point.
PFTRAV_IS_CLIP_END
Indicates that for pruned and continued traversals that before
proceeding the segment should be clipped to end at the current
Page 22
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
intersection point.
If discFunc is NULL, the behavior is the same as if the discriminator
returned (PFTRAV_CONT | PFTRAV_IS_CLIP_END), so that the intersection
nearest the start of the segment will be returned.
A pfHit object also conveys information to the discriminator callback, if
any. The following table lists the information which can be obtained
from an pfHit.
Query Type Contents
____________________________________________________________________
PFQHIT_FLAGS int Status flags
PFQHIT_SEGNUM int Index of segment in pfSegSet
PFQHIT_SEG pfSeg Segment, as clipped
PFQHIT_POINT pfVec3 Intersection point
PFQHIT_NORM pfVec3 Normal at intersection point
PFQHIT_VERTS pfVec3[3] Vertices of intersected triangle
PFQHIT_TRI int Index of triangle in pfGeoSet primitive
PFQHIT_PRIM int Index of primitive in pfGeoSet
PFQHIT_GSET pfGeoSet * Pointer to intersected pfGeoSet
PFQHIT_NODE pfNode * Pointer to pfGeode
PFQHIT_NAME char * Name of pfGeode
PFQHIT_XFORM pfMatrix Transformation matrix
PFQHIT_PATH pfPath * Path within scene graph
|
|
pfGeoSet::query is a convenience routine for determining the values of
implicit pfGeoSet parameters. The which argument is a token which
selects the parameter from the set PFQGSET_NUM_TRIS and
PFQGSET_NUM_VERTS. The result is written to the address indicated by
dst. The number of bytes written to dst is returned as the value of
pfGeoSet::query. pfGeoSet::mQuery is similar but copies a series of
items sequentially into the buffer specified by dst. The items and their
order are defined by a NULL-terminated array of query tokens pointed to
by which. For both functions, the return value is the number of bytes
written to the destination buffer.
pfGeoSet::getClassType returns the pfType* for the class pfGeoSet. The
pfType* returned by pfGeoSet::getClassType is the same as the pfType*
returned by invoking the virtual function getType on any instance of
class pfGeoSet. 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.
pfGeoSet::setPassList and pfGeoSet::getPassList set and get a pfPassList
pointer on a pfGeoSet. A pfPassList is an object generated by pfShader.
It changes the way in which a pfGeoSet is drawn. Instead of drawing the
pfGeoSet using its pfGeoState once, it draws the pfGeoSet multiple times
using pfGeoSet and pfFBState pointers from the pfPassList. This API is
used to implement multi-pass rendering algorithms. The best way to attach
Page 23
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
pfPassList pointers to pfGeoSets is by using a pfShader and a
pfShaderManager.
Clip-texture emulation support
pfGeoSet::updateCteRefs determines whether a pfGeoSet is to be rendered
with an emulated cliptexture by looking at the texture attr of the
pfGeoState associated with the pfGeoSet. If so, texture coordinate bounds
are computed and stored. If not, then any previously allocated texture
bounds data is freed. This should be called after changing the texture
attr (or the tex enable flag) on a pfGeoState that has already been
assigned to a pfGeoSet. Note that pfGeoSet::setGState automatically
calls pfGeoSet::updateCteRefs.
pfGeoSet::calcTexBBox forces the recomputation of a pfGeoSet's texture
coordinate bounds, used for cliptexture emulation. This should be called
after changing texcoords values for a pfGeoSet if this is to be rendered
with an emulated cliptexture. Note that this has no effect on pfGeoSets
that have not been identified as using an emulated cliptexture by a
previous call to pfGeoSet::updateCteRefs. Note also that
pfGeoSet::updateCteRefs automatically calls pfGeoSet::calcTexBBox.
pfGeoSet::setTexBBox(uint,uint,uint,uint) and
pfGeoSet::setTexBBox(float,float,float,float) allow to explicitly set
texture coordinate bounds for a pfGeoSet. TexCoord bounds may be set as
four floats, indicating minimum and maximum texture coordinate values for
s and t, or as four integers, as follows:
for a cliptexture with virtual size V, and texture coord bounding box of
minS, maxS, minT, maxT:
centerS = V*(minS+maxS)/2;
centerT = V*(minT+maxT)/2;
halfwidth = V*(maxS-minS)/2;
halfheight = V*(maxT-minT)/2;
Note that this has no effect on pfGeoSets that have not been identified
as using an emulated cliptexture by a previous call to
pfGeoSet::updateCteRefs. Note also that pfGeoSet's texture coordinate
bounds are internally stored in the integer representation, so using the
integer method is faster.
pfGeoSet::getTexBBox(uint*,uint*,uint*,uint*) and
pfGeoSet::getTexBBox(float*,float*,float*,float*) may be used to retrieve
the texture coordinate bounds for a pfGeoSet which has been identified as
using an emulated cliptexture by a previous call to
pfGeoSet::updateCteRefs. Note that both functions return FALSE if
pfGeoSet has not been identified as using an emulated cliptexture, or
Page 24
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
TRUE otherwise.
pfGeoSet::setCteAttr and pfGeoSet::getCteAttr will be used to set and get
cliptexture emulation specific parameters in future releases, and have
currently no effect.
OpenGL Shader support
pfGeoSet::setAppearance sets the OpenGL Shader islAppearance that will
render the specified pfGeoSet. Specifying an islAppearance on a pfGeoSet
is mutually exclusive with specifying a pfGeoState, so one or the other
will always be NULL. For a description of OpenGL Performer / OpenGL
Shader integration, please see the pfISL man page. The specified
islAppearance should be compiled. Performer will compile uncompiled
appearances, but this is an expensive process, so there may be
performance glitches when pfGeoSets with uncompiled islAppearances come
into view. OpenGL Shader is a C++ only api, so the C api functions accept
and return opaque void* pointers.
pfGeoSet::getAppearance are used to query the islAppearance on a
pfGeoSet. If the pfGeoSet is using a pfGeoState to represent its
appearance, the return value will be NULL, otherwise it will be an
islAppearance pointer. Since islAppearance is not in the arena, this
pointer is only valid within the APP process.
pfGeoSet::isShaded returns 0 when a pfGeoSet is being rendered using a
pfGeoState and non-zero when it is being rendered with an islAppearance.
Quick manipulation of temporary pfGeoSets
When assigning a pfGeoSet with various attribute arrays, it keeps
ownership of these arrays by changing their reference counts. It also
updates internal state variables tracking what attributes are set and how
they should be rendered. pfGeoSet provides a few methods for bypassing
this standard reference counting and internal state variables. These
should only be used on temporary pfGeoSets obtained from a
pfDispListOptimizer. Using them on pfGeoSets obtained using new(arena)pfGeoSet may result in incorrect memory management (memory corruption,
incorrect malloc/free, etc). For clarity, all bypass methods contain the
keyword quick.
pfGeoSet::quickCopy copies the contents of pfGeoSet src onto this. Unlike
pfGeoSet::copy, this function ignores the previous contents of the source
and target pfGeoSets. It doesn't increase/decrease any reference counts.
It should be used for copying a pfGeoSet onto a temporary pfGeoSet as
described above.
pfGeoSet::quickSetAttr sets a pfGeoSet attribute array similar to
pfGeoSet::setAttr. However, pfGeoSet::quickSetAttr doesn't perform any
reference count increase/decrease on the attribute arrays. It also
doesn't recompute any internal pfGeoSet state variables. It should be
Page 25
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
used for quickly replacing an existing attribute array of a temporary
pfGeoSet as mentioned above.
pfGeoSet::quickSetMultiAttr is similar to pfGeoSet::quickSetAttr. It
enables quick setting of pfGeoSet multi-value attributes. See the
description of pfGeoSet::setMultiAttr for more information about multi-
value attributes.
pfGeoSet::quickSetPrimLengths is similar to pfGeoSet::setPrimLengths.
Much like pfGeoSet::quickSetAttr, it ignores reference counts and
pfGeoSet internal state variables.
pfGeoSet::quickReset resets the contents of a pfGeoSet, ignoring any
reference counts. If extRefOnly is non-zero, pfGeoSet::quickReset sets
all pointers to outside arrays (attribute arrays, primitive length
arrays) to NULL and leaves the rest of the pfGeoSet variables unchanged.
If extRefOnly is zero, pfGeoSet::quickReset also resets all internal
pfGeoSet variables to their default values.
For more information about temporary pfGeoSets and about using the quick
methods, see pfDispListOptimizer.
pfGeoSet::setOptimize controls whether a pfGeoSet is optimized by a
pfDispListOptimizer (from within a CULL_SIDEKICK process). If _state is
0, a pfDispListOptimizer skips this pfGeoSet entirely.
pfGeoSet::getOptimize returns the current optimization state of a
pfGeoSet. The default optimization state of a pfGeoSet is 1.
NOTES
The following example shows one way to create a pfGeoSet defining a
hexahedron, which is also known as a cube.
static pfVec3 coords[] =
{
{-1.0, -1.0, 1.0},
{ 1.0, -1.0, 1.0},
{ 1.0, 1.0, 1.0},
{-1.0, 1.0, 1.0},
{-1.0, -1.0, -1.0},
{ 1.0, -1.0, -1.0},
{ 1.0, 1.0, -1.0},
{-1.0, 1.0, -1.0}
};
static ushort cindex[] =
{
0, 1, 2, 3, /* front */
0, 3, 7, 4, /* left */
4, 7, 6, 5, /* back */
1, 5, 6, 2, /* right */
3, 2, 6, 7, /* top */
Page 26
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
0, 4, 5, 1 /* bottom */
};
static pfVec3 norms[] =
{
{ 0.0, 0.0, 1.0},
{ 0.0, 0.0, -1.0},
{ 0.0, 1.0, 0.0},
{ 0.0, -1.0, 0.0},
{ 1.0, 0.0, 0.0},
{-1.0, 0.0, 0.0}
};
static ushort nindex[] =
{
0,
5,
1,
4,
2,
3
};
// Convert static data to pfMalloc'ed data
static void*
memdup(void *mem, size_t bytes, void *arena)
{
void *data = pfMalloc(bytes, arena);
memcpy(data, mem, bytes);
return data;
}
/* Set up an indexed PFGS_QUADS pfGeoSet */
gset = new pfGeoSet;
gset->setPrimType(PFGS_QUADS);
gset->setNumPrims(6);
gset->setAttr(PFGS_COORD3, PFGS_PER_VERTEX,
memdup(coords, sizeof(coords), NULL),
(ushort*)memdup(cindex, sizeof(cindex), NULL));
gset->setAttr(PFGS_NORMAL3, PFGS_PER_PRIM,
memdup(norms, sizeof(norms), NULL),
(ushort*)memdup(nindex, sizeof(nindex), NULL));
The following example shows one way to create a pfGeoSet with packed
attribute arrays.
/* declare some template arrays of data */
pfVec3 stripcoords[4][4] ={{{-1.0f, -1.0f, 1.0f }, {-1.0f, 1.0f, 1.0f },
{-0.5f, -1.0f, 1.0f }, {-0.5f, 1.0f, 1.0f }},
{{-0.5f, -1.0f, 1.0f }, {-0.5f, 1.0f, 1.0f },
Page 27
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
{0.0f, -1.0f, 1.0f }, {0.0f, 1.0f, 1.0f }},
{{0.0f, -1.0f, 1.0f }, {0.0f, 1.0f, 1.0f },
{0.5f, -1.0f, 1.0f }, {0.5f, 1.0f, 1.0f }, },
{{0.5f, -1.0f, 1.0f }, {0.5f, 1.0f, 1.0f },
{ 1.0f, -1.0f, 1.0f }, { 1.0f, 1.0f, 1.0f }}};
int lengths[5] = {4, 4, 4, 4};
uint pcolors[] = {0xffffffff, 0x0000ffff, 0xff0000ff, 0x00ff00ff};
short pnorms[][4] = { {0, 0, -MAX_SHORT, 0},
{0, 0, -MAX_SHORT, 0},
{0, 0, -MAX_SHORT, 0},
{0, 0, -MAX_SHORT, 0} };
float ptexcoords[][2] = { {0, 0}, {1.0f, 0}, {1.0f, 1.0f}, {0, 1.0f} };
...
/* allocate an array for the packed vertex data */
stripp = strip = (void *)pfCalloc(4, 4*12 * sizeof(float), NULL);
/* pack the data into the packed attr array for the PFGS_PA_C4UBN3ST2FV3F format
* and for all attributes with per-vertex binding
*/
for (j=0; j < 4; j++)
{
for (i=0; i < 4; i++)
{
switch(i)
{
case 0: t = 0; break;
case 1: t = 3; break;
case 2: t = 1; break;
case 3: t = 2; break;
}
*((long*)stripp) = pcolors[i];
stripp = (void*) (((char*)stripp) + sizeof(int));
*((short*)stripp) = pnorms[i][0];
stripp = (void*) (((char*)stripp) + sizeof(short));
*((short*)stripp) = pnorms[i][1];
stripp = (void*) (((char*)stripp) + sizeof(short));
*((short*)stripp) = pnorms[i][2];
stripp = (void*) (((char*)stripp) + sizeof(short)); /* pad to word-align next attr */
stripp = (void*) (((char*)stripp) + sizeof(short));
*((float*)stripp) = ptexcoords[t][0];
stripp = (void*) (((char*)stripp) + sizeof(float));
*((float*)stripp) = ptexcoords[t][1];
stripp = (void*) (((char*)stripp) + sizeof(float));
*((float*)stripp) = stripcoords[j][i][0];
stripp = (void*) (((char*)stripp) + sizeof(float));
*((float*)stripp) = stripcoords[j][i][1];
stripp = (void*) (((char*)stripp) + sizeof(float));
*((float*)stripp) = stripcoords[j][i][2];
stripp = (void*) (((char*)stripp) + sizeof(float));
Page 28
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfGeoSet(3pf)
}
}
gset = new pfGeoSet;
gset->setPrimType(PFGS_TRISTRIPS);
gset->setPrimLengths(lengths);
gset->setNumPrims(4);
gset->setAttr(PFGS_PACKED_ATTRS, PFGS_PA_C4UBN3ST2FV3F, strip, NULL);
gset->setAttr(PFGS_COLOR4, PFGS_PER_VERTEX, NULL, NULL);
gset->setAttr(PFGS_TEXCOORD2, PFGS_PER_VERTEX, NULL, NULL);
gset->setAttr(PFGS_NORMAL3, PFGS_PER_VERTEX, NULL, NULL);
gset->setDrawMode(PFGS_PACKED_ATTRS, 1);
pfGeoSets using with PFGS_PACKED_ATTRS for PFGS_TRISTRIPS,
PFGS_FLAT_TRISTRIPS, PFGS_TRIFANS, and PFGS_FLAT_TRIFANS primitive types
and whose standard coordinate attribute array is NULL do not draw the
standard full wireframe for the PFGS_WIREFRAME draw mode but instead draw
a faster quick-wireframe based on the exact vertex ordering in the
PFGS_PACKED_ATTRS attribute array.
pfGeoSets using with PFGS_PACKED_ATTRS for PFGS_QUADS primitives will be
drawn with as GL quads instead of as triangle strips as is done with
normal pfGeoSet rendering.
pfGeoSets drawn with PFGS_COMPILE_GL and PFGS_PACKED_ATTRS will ignore
subsequent changes to pfLPointStates.
SEE ALSO
pfApplyGState, pfColortable, pfCopy, pfCycleBuffer, pfDecal, pfDelete,
pfDisable, pfDispList, pfEnable, pfFlux, pfFluxMemory, pfGSetDrawMode,
pfGeoState, pfHit, pfISL, pfLPointState, pfMalloc, pfMaterial,
pfNewHlight, pfObject, pfGSetIsectSegs, pfShadeModel, pfState,
pfuFillGSetPackedAttrs, pfuTravCreatePackedAttrs, pfDispListOptimizer
Page 29
