pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)NAME
pfNewGSet, pfGetGSetClassType, pfCompileGSet, pfDrawGSet,
pfDrawHlightedGSet, pfGSetNumPrims, pfGetGSetNumPrims, pfGSetPrimType,
pfGetGSetPrimType, pfGSetPrimLengths, pfGetGSetPrimLengths,
pfGetGSetPrimLength, pfGSetAttr, pfGetGSetAttrBind, pfGetGSetAttrLists,
pfGetGSetAttrRange, pfGSetMultiAttr, pfGetGSetMultiAttrBind,
pfGetGSetMultiAttrLists, pfGetGSetMultiAttrRange, pfGSetDecalPlane,
pfGetGSetDecalPlane, pfGSetDrawMode, pfGetGSetDrawMode, pfGSetGState,
pfGetGSetGState, pfGSetGStateIndex, pfGetGSetGStateIndex,
pfGSetLineWidth, pfGetGSetLineWidth, pfGSetPntSize, pfGetGSetPntSize,
pfGSetHlight, pfGetGSetHlight, pfGSetDrawBin, pfGetGSetDrawBin,
pfGSetDrawOrder, pfGetGSetDrawOrder, pfGSetPassFilter,
pfGetGSetPassFilter, pfHideGSetStripPrim, pfUnhideGSetStripPrim,
pfIsGSetStripPrimHidden, pfQueryGSet, pfMQueryGSet, pfGSetBBox,
pfGetGSetBBox, pfGSetBBoxFlux, pfGetGSetBBoxFlux, pfGSetIsectMask,
pfGetGSetIsectMask, pfGSetIsectSegs, pfGSetPassList, pfGetGSetPassList,
pfGSetUpdateCteRefs, pfGSetCalcTexBBox, pfGSetTexBBox_i, pfGSetTexBBox_f,
pfGetGSetTexBBox_i, pfGetGSetTexBBox_f, pfGSetCteAttr, pfGetGSetCteAttr,
pfGSetAppearance, pfGetGSetAppearance, pfGSetIsShaded, pfQuickCopyGSet,
pfGSetQuickAttr, pfGSetQuickMultiAttr, pfGSetQuickPrimLengths,
pfQuickResetGSet, pfGSetOptimize, pfGetGSetOptimize, pfFluxedGSetInit -
Create, modify and query geometry set objects
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfGeoSet * pfNewGSet(void *arena);
pfType * pfGetGSetClassType(void);
void pfCompileGSet(pfGeoSet *gset);
void pfDrawGSet(pfGeoSet *gset);
void pfDrawHlightedGSet(pfGeoSet* gset);
void pfGSetNumPrims(pfGeoSet *gset, int num);
int pfGetGSetNumPrims(const pfGeoSet *gset);
void pfGSetPrimType(pfGeoSet *gset, int type);
int pfGetGSetPrimType(const pfGeoSet *gset);
void pfGSetPrimLengths(pfGeoSet* gset, int *lengths);
int * pfGetGSetPrimLengths(const pfGeoSet* gset);
int pfGetGSetPrimLength(const pfGeoSet* gset, int i);
Page 1
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
void pfGSetAttr(pfGeoSet *gset, int attr, int bind,
void *alist, ushort *ilist);
int pfGetGSetAttrBind(const pfGeoSet *gset, int attr);
void pfGetGSetAttrLists(const pfGeoSet *gset, int attr,
void **alist, ushort **ilist);
int pfGetGSetAttrRange(const pfGeoSet *gset, int attr,
int *minIndex, int *maxIndex);
void pfGSetMultiAttr(pfGeoSet *gset, int attr, int index,
int bind, void *alist, ushort *ilist);
int pfGetGSetMultiAttrBind(const pfGeoSet *gset, int attr,
int index);
void pfGetGSetMultiAttrLists(const pfGeoSet *gset, int attr,
int index, void **alist, ushort **ilist);
int pfGetGSetMultiAttrRange(const pfGeoSet *gset, int attr,
int index, int *minIndex, int *maxIndex);
void pfGSetDecalPlane(pfGeoSet *gset, pfPlane *plane);
pfPlane * pfGetGSetDecalPlane(pfGeoSet *gset);
void pfGSetDrawMode(pfGeoSet *gset, int mode, int val);
int pfGetGSetDrawMode(const pfGeoSet *gset, int mode);
void pfGSetGState(pfGeoSet *gset, pfGeoState *gstate);
pfGeoState * pfGetGSetGState(const pfGeoSet *gset);
void pfGSetGStateIndex(pfGeoSet *gset, int id);
int pfGetGSetGStateIndex(const pfGeoSet *gset);
void pfGSetLineWidth(pfGeoSet *gset, float width);
float pfGetGSetLineWidth(const pfGeoSet *gset);
void pfGSetPntSize(pfGeoSet *gset, float size);
float pfGetGSetPntSize(const pfGeoSet *gset);
void pfGSetHlight(pfGeoSet* gset, pfHighlight *hlight);
pfHighlight * pfGetGSetHlight(const pfGeoSet* gset);
Page 2
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
void pfGSetDrawBin(pfGeoSet *gset, short bin);
int pfGetGSetDrawBin(const pfGeoSet *gset);
void pfGSetDrawOrder(pfGeoSet * gset, unsigned int order);
unsigned int pfGetGSetDrawOrder(const pfGeoSet *gset)
void pfGSetPassFilter(uint mask);
uint pfGetGSetPassFilter(void);
void pfHideGSetStripPrim(const pfGeoSet* gset, int i);
void pfUnhideGSetStripPrim(const pfGeoSet* gset, int i);
int pfIsGSetStripPrimHidden(const pfGeoSet* gset, int i);
int pfQueryGSet(const pfGeoSet* gset, uint which,
void* dst);
int pfMQueryGSet(const pfGeoSet* gset, uint* which,
void* dst);
void pfGSetBBox(pfGeoSet *gset, pfBox *box, int mode);
int pfGetGSetBBox(pfGeoSet *gset, pfBox *box);
void pfGSetBBoxFlux(pfGeoSet *gset, pfFlux *flux);
pfFlux* pfGetGSetBBoxFlux(pfGeoSet *gset);
void pfGSetIsectMask(pfGeoSet *gset, uint mask, int setMode,
int bitOp);
uint pfGetGSetIsectMask(pfGeoSet *gset);
int pfGSetIsectSegs(pfGeoSet *gset, pfSegSet *segSet,
pfHit **hits[]);
void pfGSetPassList(pfGeoSet *gset, pfPassList *passList);
pfPassList * pfGetGSetPassList(pfGeoSet *gset);
void pfGSetUpdateCteRefs(pfGeoSet *gset);
void pfGSetCalcTexBBox(pfGeoSet *gset);
void pfGSetTexBBox_i(pfGeoSet *gset, uint centerS,
uint centerT, uint halfwidth, uint halfheight);
Page 3
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
void pfGSetTexBBox_f(pfGeoSet *gset, float minS, float maxS,
float minT, float maxT);
int pfGetGSetTexBBox_i(pfGeoSet *gset, uint* centerS,
uint* centerT, uint* halfwidth, uint* halfheight);
int pfGetGSetTexBBox_f(pfGeoSet *gset, float* minS,
float* maxS, float* minT, float* maxT);
void pfGSetCteAttr(pfGeoSet *gset, int which, void* val);
void* pfGetGSetCteAttr(pfGeoSet *gset, int which);
void pfGSetAppearance(pfGeoSet *gset,
islAppearance *appearance);
islAppearance* pfGetGSetAppearance(const pfGeoSet* gset);
int pfGSetIsShaded(pfGeoSet *gset);
void pfQuickCopyGSet(pfGeoSet *gset, pfGeoSet *src);
void pfGSetQuickAttr(pfGeoSet *gset, int _attr, void* _alist,
unsigned short* _ilist);
void pfGSetQuickMultiAttr(pfGeoSet *gset, int _attr,
int _index, void* _alist, unsigned short* _ilist);
void pfGSetQuickPrimLengths(pfGeoSet *gset, int *_lengths);
void pfQuickResetGSet(pfGeoSet *gset, int extRefOnly);
void pfGSetOptimize(int _state);
int pfGetGSetOptimize(void);
int pfFluxedGSetInit(pfFluxMemory *fmem);
typedef struct
{
int mode;
void* userData;
pfSeg segs[PFIS_MAX_SEGS];
uint activeMask;
uint isectMask;
void* bound;
int (*discFunc)(pfHit*);
} pfSegSet;
Page 4
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)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. Casting an object of
class pfGeoSet to an object of class pfObject is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfGeoSet 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);
PARAMETERS
gset identifies a pfGeoSet.
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,
Page 5
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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
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.
pfNewGSet creates and returns a handle to a pfGeoSet. arena specifies a
malloc arena out of which the pfGeoSet is allocated or NULL for
allocation off the process heap. pfGeoSets can be deleted with pfDelete.
pfGeoSet Attributes
pfGSetAttr 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
Page 6
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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. pfGSetMultiAttr 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.
Calling pfGSetAttr with attribute PFGS_TEXCOORD2 and PFGS_TEXCOORD3 is
equivalent to calling pfGSetMultiAttr 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:
Page 7
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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
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
Page 8
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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,
pfGSetAttr will correctly update the reference counts of the lists.
Specifically, pfGSetAttr 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
Page 9
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
coordinates (facial animation), and texture coordinates (ocean
waves, surf). pfGSetAttr 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.
pfGetGSetAttrBind returns the binding type of attr and pfGetGSetAttrLists
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, pfGetGSetMultiAttrBind returns the binding type of attr at the
index'th position, and pfGetGSetMultiAttrLists returns the attribute and
index list base pointers at the index'th position.
pfGetGSetAttrRange returns the range of attributes in the attribute list
identified by attr that are used by gset. (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, pfGetGSetAttrRange returns the
number of contiguous attributes accessed by gset (the range implicitly
beginning at 0). If the list is indexed, pfGetGSetAttrRange 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.
pfGetGSetAttrRange is typically used to allocate a new attribute array
when cloning a pfGeoSet:
int numVerts = pfGetGSetAttrRange(gset, PFGS_COORD3, NULL, &max);
numVerts = PF_MAX2(numVerts, max + 1);
newVerts = (pfVec3*) pfMalloc(sizeof(pfVec3) * numVerts, arena);
Similarly, pfGetGSetMultiAttrRange returns the range of attributes in the
attribute list identified by attr for a multi-valued attribute at
position index.
pfGeoSet Primitive Types
pfGSetPrimType specifies the type of primitives found in a pfGeoSet.
type is a symbolic token and is one of:
PFGS_POINTS
Page 10
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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. pfGetGSetPrimType returns the primitive type of gset.
pfGSetNumPrims and pfGetGSetNumPrims sets/gets the number of primitives
in gset. A primitive is a single point, line segment, line strip,
triangle, quad, triangle strip, or polygon depending on the primitive
type.
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 pfGSetPrimLengths. 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
pfGSetNumPrims. pfGetGSetPrimLengths returns a pointer to the lengths
array of gset. pfGetGSetPrimLength 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. pfHideGSetStripPrim will force the
length of the i'th primitive of a stripped pfGeoSet to be the negative of
its proper length; pfUnhideGSetStripPrim will set the primitive length to
be the positive value. pfisGSetStripPrimHidden will return 1 if the ith
primitive of the pfGeoSet is negative and 0 otherwise.
pfGetGSetPrimLength 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
Page 11
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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.
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.
Page 12
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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]
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 pfGSetDrawMode.
2. Use the wireframe mode set by the attached pfGeoState, if any,
as described in pfGSetGState 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. pfDrawGSet will
automatically set the shading model to FLAT before rendering PFGS_FLAT_
primitives.
Example 1:
/* Set up a non-indexed, FLAT_TRISTRIP pfGeoSet */
gset = pfNewGSet(NULL);
pfGSetPrimType(gset, PFGS_FLAT_TRISTRIPS);
pfGSetNumPrims(gset, 2);
Page 13
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
lengths[0] = 4;
lengths[1] = 3;
pfGSetPrimLengths(gset, lengths);
/* Only need 3 colors: 2 for 1st strip and 1 for 2nd */
colors = (pfVec4*) pfMalloc(sizeof(pfVec4) * 3, NULL);
pfGSetAttr(gset, PFGS_COLOR4, PFGS_PER_VERTEX, colors, NULL);
pfGSetAttr(gset, PFGS_COORD3, PFGS_PER_VERTEX, coords, NULL);
pfGeoSet Special Rendering Characteristics
When colortable mode is enabled, either through pfEnable or through
pfApplyGState, 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.
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.
pfGSetPntSize and pfGSetLineWidth set the point size and line width of
gset. 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.
pfGetGSetPntSize and pfGetGSetLineWidth return gset's point size and line
width respectively.
pfGSetDrawMode 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:
Page 14
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
PFGS_FLATSHADE Always render gset with a flat shading
model.
PFGS_WIREFRAME Always render and intersect gset 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
gset'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 gset's packed attribute arrays,
set with the PFGS_PACKED_ATTRS to
pfGSetAttr, to render geometry with 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 pfDrawGSet 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
pfGSetDrawMode.
Page 15
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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 */
pfGSetDrawMode(gset, 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.
*/
pfDrawGSet(gset);
:
/* This time we draw the GL display list */
pfDrawGSet(gset);
:
/* Disable GL display list mode */
pfGSetDrawMode(gset, PFGS_COMPILE_GL, PF_OFF);
/* Free the GL display list and render 'gset' in immediate mode */
pfDrawGSet(gset);
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 pfGSetDrawMode.
2. Use the shading model specified by the pfGeoState bound to the
pfGeoSet. This is the typical case in OpenGL Performer. See
the pfGSetGState description below for further details.
3. Use the shading model set by pfShadeModel.
pfGetGSetDrawMode 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
Page 16
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
attached to a pfGeoSet via pfGSetGState, gset 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.
pfGSetGState "attaches" gstate to gset so that gset may be drawn with a
certain graphics state. When drawn by pfDrawGSet, a pfGeoSet will apply
its pfGeoState (if it has one) with pfApplyGState and the graphics
library will be initialized to the proper state for drawing gset. A
gstate value of NULL will remove any previous pfGeoState and cause gset
to inherit whatever graphics state is around at the time of rendering.
pfGSetGStateIndex 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.
Indexed pfGeoStates use a global table of pfGeoState* specified by
pfApplyGStateTable. When indexing a pfGeoState, pfDrawGSet calls
pfApplyGState with the indexth entry of this table if the index can be
properly resolved. Otherwise no pfGeoState is applied.
pfGetGSetGStateIndex returns the pfGeoState index of gset or -1 if gset
directly references its pfGeoState.
pfGSetGState 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. pfGSetGStateIndex 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.
pfGetGSetGState returns the pfGeoState associated with gset or NULL if
there is none. If gset indexes its pfGeoState, pfGetGSetGState will look
up the pfGeoState index in the global pfGeoState table and return the
result or NULL if it cannot resolve the reference.
pfGSetDecalPlane sets plane to be the reference plane used for the gset
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
Page 17
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
pfQueryFeature can be used for run-time queries for the support of decal
reference planes. See the pfDecal man page for more information.
pfGSetHlight sets hlight to be the highlighting structure used for gset.
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. pfGetGSetHlight returns the current GeoSet
highlight definition.
pfDrawHlightedGSet is a convenience routine for drawing ONLY the
highlighting stage of gset, according to the currently active
highlighting structure.
Drawing pfGeoSets
pfDrawGSet is a display-listable command. If a pfDispList has been
opened by pfOpenDList, pfDrawGSet will not have immediate effect but will
be captured by the pfDispList and will only have effect when that
pfDispList is later drawn with pfDrawDList.
If gset has an attached pfGeoState, then pfDrawGSet first calls
pfApplyGState before rendering the pfGeoSet geometry, as shown in the
following examples.
Example 3a:
/* Make sure 'gset' has not attached pfGeoState */
pfGSetGState(gset, NULL);
/* Apply graphics state encapsulated by 'gstate' */
pfApplyGState(gstate);
/* Draw 'gset' with graphics state encapsulated by 'gstate' */
pfDrawGSet(gset);
Example 3b:
/* Attach 'gstate' to 'gset' */
pfGSetGState(gset, gstate);
/* Draw 'gset' with graphics state encapsulated by 'gstate' */
pfDrawGSet(gset);
Example 3c:
Page 18
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
/* Use indexed pfGeoState */
pfGSetGStateIndex(gset, 2);
/* Set up and apply pfGeoState table */
pfSet(list, 2, gstate);
pfApplyGStateTable(list);
/* Draw 'gset' with graphics state encapsulated by 'gstate' */
pfDrawGSet(gset);
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.
pfGSetDrawBin sets gset's draw bin identifier to bin. bin identifies a
drawing bin to which gset belongs and is used for controlling the
rendering order of a database. The pfGeoSet draw bin is currently used
only by libpf applications (see pfChanBinOrder) and is ignored by
libpr-only applications. The default pfGeoSet draw bin identifier is -1.
pfGetGSetDrawBin returns the draw bin identifier of gset.
pfGSetDrawOrder sets gset's order in the bin if the bin sort order is
PFSORT_DRAW_ORDER. It is necessary to set the Draw Order of each gset
that contains calligraphic light points (see pfCalligraphic man pages).
Do not set the DrawBin for those gsets, as they will automatically go in
the light point display list if a LPoint Process has been started.
The mask argument to pfGSetPassFilter is a bitmask which specifies a
pfGeoSet drawing "filter". Only pfGeoSets which pass the filter test are
rendered by pfDrawGSet. 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.
Page 19
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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. pfGetGSetPassFilter returns the current
pfGeoSet filtering mask.
pfCompileGSet 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 pfCompileGSet
does not execute the pfGeoSet display list, the display list will not
affect or be downloaded to the graphics pipeline. pfCompileGSet is not a
display-listable command.
Intersecting with pfGeoSets
pfGSetIsectMask enables intersections and sets the intersection mask for
gset. 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 (pfGSetIsectSegs) indicates that the pfGeoSet should
be tested. The default mask is all 1's, i.e. 0xffffffff.
pfGetGSetIsectMask 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
pfGSetIsectMask 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.
pfGSetBBox sets the bounding volume of gset. 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 pfGSetBBox specifies whether or not the bounding
volume for node should be recomputed when an attribute of gset is
Page 20
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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 pfGSetBBox 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 pfNodeBSphere on the parent
Geode to recompute the bounding volume.
pfGetGSetBBox copies the bounding box of gset into bbox and returns the
current bounding mode.
pfGSetBBoxFlux and pfGetGSetBBoxFlux set and get a pfFlux that can be
used to contain the bounding box of a pfGeoSet.
pfGSetIsectSegs tests for intersection between the pfGeoSet gset and the
group of line segments specified in segSet. The resulting intersections
(if any) are returned in hits. The return value of pfGSetIsectSegs 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
Page 21
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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. pfCylAroundSegs will construct a
cylinder around the segments.
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
pfGetUserData.
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,
Page 22
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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
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
|
|
pfQueryGSet 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
pfQueryGSet. pfMQueryGSet 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
Page 23
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
written to the destination buffer.
pfGetGSetClassType returns the pfType* for the class pfGeoSet. The
pfType* returned by pfGetGSetClassType is the same as the pfType*
returned by invoking pfGetType 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 pfIsOfType to test if an object is of a type derived from a
Performer type rather than to test for strict equality of the pfType*'s.
pfGSetPassList and pfGetGSetPassList 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
pfPassList pointers to pfGeoSets is by using a pfShader and a
pfShaderManager.
Clip-texture emulation support
pfGSetUpdateCteRefs 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 pfGSetGState automatically calls
pfGSetUpdateCteRefs.
pfGSetCalcTexBBox 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 pfGSetUpdateCteRefs. Note also that pfGSetUpdateCteRefs
automatically calls pfGSetCalcTexBBox.
pfGSetTexBBox_i and pfGSetTexBBox_f 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;
Page 24
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
Note that this has no effect on pfGeoSets that have not been identified
as using an emulated cliptexture by a previous call to
pfGSetUpdateCteRefs. Note also that pfGeoSet's texture coordinate bounds
are internally stored in the integer representation, so using the integer
method is faster.
pfGetGSetTexBBox_i and pfGetGSetTexBBox_f 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 pfGSetUpdateCteRefs.
Note that both functions return FALSE if pfGeoSet has not been identified
as using an emulated cliptexture, or TRUE otherwise.
pfGeoSetCteAttr and pfGetGeoSetCteAttr will be used to set and get
cliptexture emulation specific parameters in future releases, and have
currently no effect.
OpenGL Shader support
pfGSetAppearance 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.
pfGetGSetAppearance 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.
pfGSetIsShaded 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 functions 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 pfNewGSet may
result in incorrect memory management (memory corruption, incorrect
malloc/free, etc). For clarity, all bypass functions contain the keyword
Quick.
Page 25
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
pfQuickCopyGSet copies the contents of pfGeoSet src onto gset. Unlike
pfCopy, 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.
pfGSetQuickAttr sets a pfGeoSet attribute array similar to pfGSetAttr.
However, pfGSetQuickAttr 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 used for quickly
replacing an existing attribute array of a temporary pfGeoSet as
mentioned above.
pfGSetQuickMultiAttr is similar to pfGSetQuickAttr. It enables quick
setting of pfGeoSet multi-value attributes. See the description of
pfGSetMultiAttr for more information about multi-value attributes.
pfGSetQuickPrimLengths is similar to pfGSetPrimLengths. Much like
pfGSetQuickAttr, it ignores reference counts and pfGeoSet internal state
variables.
pfQuickResetGSet resets the contents of a pfGeoSet, ignoring any
reference counts. If extRefOnly is non-zero, pfQuickResetGSet 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, pfQuickResetGSet also resets all internal pfGeoSet
variables to their default values.
For more information about temporary pfGeoSets and about using the quick
functions, see pfDispListOptimizer.
pfGSetOptimize 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. pfGetGSetOptimize
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}
Page 26
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
};
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 */
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 = pfNewGSet(NULL);
pfGSetPrimType(gset, PFGS_QUADS);
pfGSetNumPrims(gset, 6);
pfGSetAttr(gset, PFGS_COORD3, PFGS_PER_VERTEX,
memdup(coords, sizeof(coords), NULL),
(ushort*)memdup(cindex, sizeof(cindex), NULL));
pfGSetAttr(gset, PFGS_NORMAL3, PFGS_PER_PRIM,
memdup(norms, sizeof(norms), NULL),
(ushort*)memdup(nindex, sizeof(nindex), NULL));
Page 27
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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 },
{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];
Page 28
pfGeoSet(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfGeoSet(3pf)
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));
}
}
/* set the attributes on the pfGeoSet */
gset = pfNewGSet(NULL);
pfGSetPrimType(gset, PFGS_TRISTRIPS);
pfGSetPrimLengths(gset, lengths);
pfGSetNumPrims(gset, 4);
pfGSetAttr(gset, PFGS_PACKED_ATTRS, PFGS_PA_C4UBN3ST2FV3F, strip, NULL);
pfGSetAttr(gset, PFGS_COLOR4, PFGS_PER_VERTEX, NULL, NULL);
pfGSetAttr(gset, PFGS_TEXCOORD2, PFGS_PER_VERTEX, NULL, NULL);
pfGSetAttr(gset, PFGS_NORMAL3, PFGS_PER_VERTEX, NULL, NULL);
pfGSetDrawMode(gset, 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
