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.

The C++ include files for libpf and libpr are in /usr/include/Performer/pf and /usr/include/Performer/pr, respectively. An application using a class should include the corresponding header file.

The IRIS Performer base classes all provide operator new and operator delete. All libpr and libpf objects 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.

The default new operator creates objects in the current shared memory arena, if one exists. libpr objects and public structs 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 IRIX acreate().

// legal creation of libpf objects
pfDCS    *dcs = new pfDCS;         // only way

// legal creation of libpr objects
pfGeoSet *gs = new pfGeoSet;       // from default arena
pfGeoSet *gs = new(NULL) pfGeoSet; // from heap

// legal 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

// illegal creation of libpf objects
pfDCS    *dcs = new(NULL) pfDCS;    // not in shared mem
pfDCS    *dcs = new pfDCS[10];      // array

// illegal creation of libpr objects
pfGeoSet *gs = new pfGeoSet[10];    // array

// illegal creation of public structs
pfVec3 *vert = new(NULL) pfVec3[10];// array, non-default new

---

Caution: This last item in Example 14-2 is illegal because C++ does not provide a mechanism to delete arrays of objects allocated with a new operator defined to take additional arguments, e.g. operator new(size_t s, 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.

---

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().

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

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 IRIS GL or 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, e.g.

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

In the C++ API, the data field of the pfMatrix must be passed instead, e.g.

     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 CAPI 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 C API routine

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

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];
     }

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.

#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 IRIS Performer that pass typedefed arrays, e.g.

   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, e.g.

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

because a pointer to a struct is passed in the same manner as a pointer to an array.

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) is a subclass of pfDCS. It's 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 section below, 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 “libpf Objects and Multiprocessing”.

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++ IRIS 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:

---

Note: Pure libpr applications that do their own multiprocessing outside of IRIS Performer with fork() should explicitly create shared memory with pfInitArenas() before calling pfInit(). Otherwise, the type system will not be visible in the address space of other processes.

---

The multiprocessing behavior of libpf objects (i.e. 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 IRIS 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.

Subclassing will be vastly simplified and more flexible in a future release.

It's 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 such which contain arrays of structs, e.g. pfSegSet contains an array of pfSegs.

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