To create a pfGeoSet from the shared memory arena, use the following line of code:

pfGeoSet *pfNewGSet(void *arena)

Use the following pfGeoSet method to specify the type of primitive in the pfGeoSet:

void pfGSetPrimType(pfGeoSet *gset, int type);

type is one of the primitives provided by OpenGL Performer:

PFGS_FLAT_* primitives are flat-shaded. PFGS_POLYS draws polygons of arbitrary vertex lengths.

Figure 7-1 shows some of these primitives.

Figure 7-1. Primitives

The numbers in Figure 7-1 show the order in which the vertex attributes should appear in the attribute array.

Use the following pfGeoSet method to specify the number of primitives in the pfGeoSet:

void pfGSetNumPrims(pfGeoSet *gset, int num);

num is the number of primitives.

When using one of the following pfGeoSet primitives, which have an arbitrary number of vertices, you must define the number of vertices of each primitive in the pfGeoSet:

Use pfGSetPrimLengths() to specify the number of vertices of each primitive in the pfGeoSet:

void pfGSetPrimLengths(pfGeoSet* gset, int *lengths);

lengths is an array of the number of strips in a pfGeoSet. Each element of the lengths array is the number of vertices in a corresponding strip. For example:

lengths[0] = 8;
lengths[1] = 5;

These lines of code mean that the number 0 primitive has 8 vertices, and the number 1 primitive has 5 vertices. Use pfGetGSetPrimLength() to return the length of an individual primitive from the lengths array.

---

Note: pfGetGSetPrimLength() checks for NULL or negative lengths.

---

To set the attributes of a pfGeoSet, use pfGSetAttr() as follows:

void setAttr(int attr, int bind, void *alist, ushort *ilist);

attr specifies the attribute array to set. The tokens for the different attribute lists are:

bind is the binding type. The tokens are listed in Table 7-1.

alist is a pointer to an attribute array for appropriate, corresponding data.

ilist is a pointer to an index array for used to access the attribute array.

A ttribute bindings specify whether attributes are as follows:

For example, you can specify the following:

Table 7-1 shows the possible bindings per attribute type.

A cube has 6 sides; together those sides have 24 vertices. In a vertex array, you could specify the primitives in the cube using 24 vertices. However, most of those vertices overlap. If more than 1 primitive can refer to the same vertex, the number of vertices can be streamlined to 8. To get more than 1 primitive to refer to the same vertex, use an index; 3 vertices of 3 primitives use the same index, which points to the same vertex information. Adding the index array adds an extra step in the determination of the attribute, as shown in Figure 7-3.

Figure 7-3. Indexing Arrays

Indexing can save system memory, but rendering performance is often lost.

Whether or not attributes should be indexed depends on how many vertices in a geometry are shared:

Consider the following two examples in Figure 7-4, in which each dot marks a vertex.

Figure 7-4. Deciding whether to Index Attributes

In the triangle strip, each vertex is shared by 2 adjoining triangles. In the square, the same vertex is shared by 8 triangles. Consider moving these vertices when, for example, morphing the object. If the vertices were not indexed in the square, the application would have to search for and alter 8 triangles to change one vertex. In the case of the square, it is much more efficient to index the attributes.

On the other hand, if the attributes in the triangle strip were indexed, because each vertex is shared by only 2 triangles, the index search time would exceed the time required to simply update the vertices sequentially. In the case of the triangle strip, rendering is improved by handling the attributes sequentially.

The choice of using indexed or sequential attributes applies to all of the primitives in a pfGeoSet. All of the primitives within one pfGeoSet must be referenced sequentially or by index; you cannot mix the two.

Using p acked attributes is an optimized way of sending formatted data to the graphics pipeline under OpenGL operation. Using packed attributes can help host traversal performance because they remove subroutine call overhead. Packed attributes can also reduce memory usage because they allow for the format specification of attributes such as normals, texture coordinates as floats, and colors as unsigned bytes. Some small additional overhead might be incurred by the geometry subsystem of the graphics pipeline, which has to unpack the data.

The packed attribute array holds the currently bound per-vertex attribute data packed into a single non-indexed array and is specified with the matching format of the data with pfGSetAttr() as follows:

pfGSetAttr(gset, PFGS_PACKED_ATTRS, PFGS_PA_C4UBN3ST2F /*the format*/);

V ertex coordinate attributes can be placed in this array and do not need to be duplicated in their regular arrays. Specify NULL for the attribute list to pfGSetAttr(). Vertex coordinates themselves must always be provided in the normal vertex coordinate list. They can, based on the packed format, be duplicated in the packed array.

To create packed attributes, you can use the utility pfuTravCreatePackedAttrs(), which traverses a scene graph to create packed attributes according to the specified format for pfGeoSets and, optionally, pfDelete redundant attribute arrays. This utility packs the pfGeoSet attributes using pfuFillGSetPackedAttrs(). To then render geometry with packed attributes, use the pfGSetDrawMode(PFGS_PACKED_ATTRS) method when using OpenGL.

For more information on packed arrays, see the examples in the following: /usr/share/Performer/src/pguide/libpr/C/packedattrs.c /usr/share/Performer/src/sample/C/perfly.c /usr/share/Performer/src/sample/C++/perfly/perfly.C.

Chapter 8, “Geometry ,” in the OpenGL Performer Programmer's Guide.

pfGeoSets are the lowest-level OpenGL Performer object that can be rendered. To directly draw a pfGeoSet, use pfDrawGset().

pfGeoSets are pfObjects, so they can have their contents printed for debugging with different levels of verbosity via the pfObject routine, pfPrint().You can also use other pfObject methods, such as pfCopy() and pfDelete(), can also be used with pfGeoSets.

Table 7-2 shows the libpf utilities that generate pfGeoSets of l arger geometric shapes.