These classes are public structs with exposed data members. They include pfVec2, pfVec3, pfVec4, pfMatrix, pfQuat, pfSeg, pfSphere, pfBox, pfCylinder, and pfSegSet.

These classes derive from pfMemory. When multiprocessing, all processes share the same copy of the object's data members.

These classes derive from pfUpdatable and when multiprocessing, each APP, CULL, and ISECT process has a unique copy of the object's data members.

As with the C API, information about the class hierarchy is maintained with pfType objects.

For IRIX and Linux, the C++ include files for libpf and libpr are in /usr/include/Performer/pf and /usr/include/Performer/pr, respectively. For Microsoft Windows, the corresponding header files are in %PFROOT%\Include\pf and %PFROOT%\Include\pr. An application using a class should include the corresponding header file.

There are additional C++ object classes in the utility libraries. Header files for those classes are similarly named with their own library name for the directory and prefix for the header file name. The libpui C++ has a full C++ API and its header files are named like the example <Performer/pfui/pfiTrackball.h>. The libpfutil library has some C++ classes and the header files are named as <Performer/pfu/pfuProcessManager.h>.

The OpenGL Performer base classes all provide operator new and operator delete. All libpr and libpf objects, except pfObject, pfMemory, and their derivatives, must be explicitly created with operator new and deleted with operator delete. Objects of these classes cannot be created statically on the stack or in arrays.

All objects of classes derived from pfObject or pfMemory are reference counted and must be deleted using pfDelete(), rather than the delete operator. pfDelete() checks the reference count of the object and, when multiprocessing, delays the actual deletion until other processes are done with the object. To decrement the reference count and delete with a single call use pfUnrefDelete().

---

Note: Public structs such as pfVec3, pfSphere, etc. may be deleted either with pfDelete() or the delete operator.

---

The default new operator creates objects in the current shared memory arena if one exists. libpr objects and public structures have an additional new operator that takes an arena argument. This new operator allows allocation from the heap (indicated by an arena of NULL) or from a shared memory arena created by the application with acreate().

// valid creation of libpf objects
pfDCS    *dcs = new pfDCS;         // only way
 
// valid creation of libpr objects
pfGeoSet *gs = new pfGeoSet;       // from default arena
pfGeoSet *gs = new(NULL) pfGeoSet; // from heap
 
// valid creation of public structs
pfVec3 *vert = new pfVec3;            // from default arena
pfVec3 *verts = new pfVec3[10];       // array from default 
static pfVec3 vert(0.0f, 0.0f, 0.0f); // static

Example 26-2. Invalid Creation of Objects in C++

// invalid creation of libpf objects pfDCS  *dcs = new(NULL) pfDCS; // not in shared mem pfDCS  *dcs = new pfDCS[10];  // array // invalid creation of libpr objects pfGeoSet *gs = new pfGeoSet[10]; // array // invalid creation of public structs pfVec3 *vert = new(NULL) pfVec3[10];// array, non-default new

---

Caution: This last item in Example 26-2 is invalid because C++ does not provide a mechanism to delete arrays of objects allocated with a new operator defined to take additional arguments, for example, operator new(size_ts, void *arena). Attempting to delete an array of objects allocated in this manner can cause unpredictable and fatal results such as the invocation of the destructor a large number of times on pointers inside and outside of the original allocation.

---

Since libpr and libpf objects are allocated, they can only be maintained by reference.

Passing arrays of floats is very common in graphics programming. Calls to OpenGL often require an array of floats or a matrix. In the C API, the data types such as pfMatrix are arrays and so can be passed straight through to OpenGL routines; the following is an example:

     pfMatrix ident;
     pfMakeIdentMat(ident);
     glLoadMatrix(ident);

In the C++ API, the data field of the pfMatrix must be passed instead, as in this example:

     pfMatrix ident;
     ident.makeIdent();
     glLoadMatrix(ident.mat);

In the C API, the pfVec2, pfVec3, pfVec4, pfMatrix and pfQuat data types are all typedefed arrays. In the C++ API, they are all structs. When converting C code to use the C++ API or when compiling C API code with both APIs enabled, be sure to change routines in your code that pass objects of these types. In the C++ API, you almost always want to pass arguments of these types by reference rather than by value.

For example, the following C API routine should be rewritten for the C++ API to pass by reference:

     void MyVectorAdd(pfVec2 dst, pfVec2 v1, pfVec2 v2)
     {
         dst[0] = v1[0] + v2[0];
         dst[1] = v1[1] + v2[1];
     }

Two possible alternatives follow:

     void MyVectorAdd(pfVec2& dst, pfVec2& v1, pfVec2& v2)
     {
         dst[0] = v1[0] + v2[0];
         dst[1] = v1[1] + v2[1];
     }

or

     void MyVectorAdd(pfVec2* dst, pfVec2* v1, pfVec2* v2)
     {
         dst->vec[0] = v1->vec[0] + v2->vec[0];
         dst->vec[1] = v1->vec[1] + v2->vec[1];
     }

Without this change, time will be wasted copying v1 and v2 by value and the result will not be returned to the routine calling MyVectorAdd().

The same difference in passing conventions applies if you are calling a C function from code that uses the C++ API. Functions passing typedefed arrays with the C API must have a different prototype for use with the C++ API. Macros for use in C prototypes bilingual can be found in /usr/include/Performer/prmath.h for IRIX and Linux and in %PFROOT%\Include\prmath.h for Microsoft Windows.

#if PF_CPLUSPLUS_API
#define 
PFVEC2 pfVec2&
#define 
PFVEC3 pfVec3&
#define 
PFVEC4 pfVec4&
#define 
PFQUAT pfQuat&
#define 
PFMATRIX pfMatrix&
#else
#define PFVEC2 pfVec2
#define PFVEC3 pfVec3
#define PFVEC4 pfVec4
#define PFQUAT pfQuat
#define PFMATRIX pfMatrix
#endif /* PF_CPLUSPLUS_API */

These macros are used in the C API prototypes for OpenGL Performer that pass typedefed arrays, as shown in the following example:

   extern float pfDotVec2(const PFVEC2 v1, const PFVEC2 v2);

But they are not necessary or appropriate for when passing pointers to typedefed arrays in C, because a pointer to a struct is passed in the same manner as a pointer to an array. This is shown in the following example:

     extern void pfFontCharSpacing(pfFont *font, int ascii,
         pfVec3 *spacing);

The new object should provide two static functions, a constructor that initializes the instances pfType*, and a static data member for the type system as shown in the following table:

The init() member function should initialize any data structures that are related to the class as a whole, as opposed to any particular instance. The most important of these is the entry of the class into the type system. For example, the Rotor class defined in the Open Inventor loader (see Rotor.h and Rotor.C in /usr/share/Performer/src/lib/libpfdb/libpfiv for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfiv for Microsoft Windows) is a subclass of pfDCS. Its initialization function merely enters the class into the type system.

public Rotor : public pfDCS 
{
    static void init();
    static pfType* getClassType(){ return classType; };
    static pfType* classType;
}
 
pfType *Rotor::classType = NULL;
 
Rotor::Rotor()
{
    setType(classType);  // set the type of this instance
    ...
}
 
void
Rotor::init()
{
    if (classType == NULL)
    {
        pfDCS::init();
        classType = 
            new pfType(pfDCS::getClassType(), “Rotor”);
    }
}

As described in the following section, the initialization function, Rotor::init() should be called before pfConfig().

Below is the example of the Rotor class, which specifies the traversal function for the libpf application traversal. When overloading a traversal function, it is usually desirable to invoke the parent class function, in this case, pfDCS::app(). It is not currently possible to overload libpf's intersection or culling traversals. See “Multiprocessing and libpf Objects”.

int 
Rotor::app(pfTraverser *trav)
{
    if (enable)
    {
    pfMatrix mat;
        double now = pfGetFrameTimeStamp();
 
        // use delta and renorm for large times
        prevAngle += (now - prevTime)*360.0f*frequency;
        if (prevAngle > 360.0f)
            prevAngle -= 360.0f;
        mat.makeRot(prevAngle, axis[0], axis[1], axis[2]);
        setMat(mat);
        prevTime = now;
    }
 
    return pfDCS::app(trav);
}
 
int
Rotor::needsApp(void)
{
    return TRUE;
}

The same behavior could also be implemented in either the C or C++ OpenGL Performer API using a callback function specified with pfNodeTravFuncs().

---

Note: Classes of pfNodes that need to be visited during the application traversal even in the absence of any application callbacks should define the virtual function needsApp() to return TRUE.

---

Accesses to parent class data is made through the functions on the parent class. Data members on built-in classes should never be accessed directly.

In general, to assure safe multiprocess operation with any DSOs providing C++ virtual functions or defining new pfTypes, initialization should be carried out in the following sequence:

More on Shared Memory and the Type System

---

Note: This is an advanced section.

---

OpenGL Performer objects or other objects that use pfTypes can only be shared between related processes. Related processes are those created with fork() or sproc() from the main process after pfInit() in a libpf application, for example, processes created by pfConfig().

New pfTypes should be added before pfConfig() forks off other processes so that the static data member containing the class type is visible in all processes, otherwise pf<Class>::getClassType() will return NULL in other processes. This effectively precludes the creation of subclasses of OpenGL Performer objects after pfConfig().

Virtual Address Spaces and Virtual Functions

---

Note: This is an advanced section.

---

When using virtual functions, it is very important that the object code reside at the same address in all processes. Normally, this is not an issue since the object code for all OpenGL Performer classes is loaded (whether statically linked or loaded as dynamic shared objects, DSOs) before pfConfig() is called to fork off processes. For user-defined C++ classes with virtual functions, it is important that the object code reside at the same virtual address space in all processes that access them. For this reason, the DSOs for any user-defined classes should be loaded before pfConfig(), regardless of whether they use the pfType system or not.

---

Note: This is an advanced topic.

---

The multiprocessing behavior of libpf objects (that is, those deriving from pfNode or pfUpdatable) differs from that of libpr objects. Both are typically created in shared memory but, with a libpr object, all processes share the same data members while libpf objects have a built-in multiprocessing data mechanism that provides different copies in the APP, CULL, and ISECT stages of the OpenGL Performer pipeline. The term multibuffering refers to the maintenance and frame-accurate updating of these data.

With a user-defined subclass of a libpf class, the original data elements of the libpf parent class are still multibuffered. However, the parallel multibuffer copies maintained in the other processes are instances of the parent class rather than the subclass. This is not normally visible to the application, since even for callbacks in the CULL and ISECT processes, the application always works from the pointer to the copy used in the APP process, in part, so that objects can be identified by comparison of pointers. However, this difference would be visible if the virtual traversal functions for culling or intersection were overloaded. These virtual functions should not be overloaded by the subclass since they will not have any effect when the CULL or ISECT stages are in separate processes. Node callbacks specified with pfNodeTravFuncs() should be used instead.

If you require multibuffering of your subclassed data members, use a pfCycleBuffer or a pfFlux to hold this data.

It is quite natural to frequently construct and destroy arrays of public structs such as pfVec3 on the stack. Beware, even though the constructors for these classes are empty, it still requires a function call for each element of the array. The same applies to classes that contain arrays of structs; for example, pfSegSet contains an array of pfSegs.

Assignment operators, for example, “+=”, are significantly faster than their corresponding binary operators, for example, “+”, because the latter involves constructing a temporary object for the return value.