pfObject(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfObject(3pf)NAMEpfObject - pfObject, callback and user data operations
FUNCTION SPECIFICATION
#include <Performer/pr/pfObject.h>
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, void *arena);
void* pfObject::operator new(size_t,
pfFluxMemory *fmem);
static pfType * pfObject::getClassType(void);
void pfObject::setUserData(void *data);
void pfObject::setUserData(int slot, void *data);
static void pfObject::setUserData(pfObject *obj,
void *data);
static void pfObject::setUserData(pfObject *obj, int slot,
void *data);
void* pfObject::getUserData(pfObject *obj);
void* pfObject::getUserData(pfObject *obj, int slot);
static void * pfObject::getUserData(pfObject *obj);
static void * pfObject::getUserData(pfObject *obj, int slot);
int pfObject::getNumUserData();
static int pfObject::getNumUserData(pfObject *obj);
static int -
pfObject::getNamedUserDataSlot(const char *name);
static const char* pfObject::getUserDataSlotName(int slot);
static int pfObject::getNumNamedUserDataSlots(void);
static void pfObject::setCopyFunc(pfCopyFuncType func);
static void pfObject::setCopyFunc(int slot,
pfCopyFuncType func);
static pfCopyFuncType pfObject::getCopyFunc(void);
Page 1
pfObject(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfObject(3pf)
static pfCopyFuncType pfObject::getCopyFunc(int slot);
static void pfObject::setDeleteFunc(pfDeleteFuncType func);
static void pfObject::setDeleteFunc(int slot,
pfDeleteFuncType func);
static pfDeleteFuncType pfObject::getDeleteFunc(void);
static pfDeleteFuncType pfObject::getDeleteFunc(int slot);
static void pfObject::setPrintFunc(pfPrintFuncType func);
static void pfObject::setPrintFunc(int slot,
pfPrintFuncType func);
static pfPrintFuncType pfObject::getPrintFunc(void);
static pfPrintFuncType pfObject::getPrintFunc(int slot);
static int pfObject::getGLHandle(void);
static int pfObject::deleteGLHandle(void);
typedef void (*pfCopyFuncType)(pfObject *dst, const pfObject *src);
typedef void (*pfDeleteFuncType)(pfObject *obj);
typedef void (*pfPrintFuncType)(const pfObject *obj, uint which, uint verbose, char *, FILE *);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfObject is derived from the parent class
pfMemory, so each of these member functions of class pfMemory are also
directly usable with objects of class pfObject. This is also true for
ancestor classes of class pfMemory.
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
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();
Page 2
pfObject(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfObject(3pf)
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
DESCRIPTION
A pfObject is the abstract data type from which the major OpenGL
Performer data structures are derived. pfObject in turn derives from
pfMemory which is the basic memory allocation unit. Although pfObjects
cannot be created directly, most OpenGL Performer data structures are
derived from them and thus inherit the functionality of the pfObject
routines described here and those for pfMemory.
new(arena) allocates a pfObject from the specified memory arena, or from
the heap if arena is NULL. new allocates a pfObject from the default
memory arena (see pfGetSharedArena). pfObjects cannot be allocated on
the stack, statically or in arrays. pfObjects allocated with new should
be deleted with pfDelete rather than the delete operator.
pfObject::getClassType returns the pfType* for the class pfObject. The
pfType* returned by pfObject::getClassType is the same as the pfType*
returned by invoking the virtual function getType on any instance of
class pfObject. 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.
User data provides a mechanism for associating application specific data
with OpenGL Performer objects. pfObjects have multiple slots for
attaching user data. User data slots can not be used until they are
named. By default only slot 0 is named.
pfObject::getNamedUserDataSlot will returns a user data slot number
associated with name. If name is not yet associated with a slot, the
next unused slot will be named name. Once a slot has been named its name
can never be changed.
pfObject::getUserDataSlotName returns the name of user data slot.
pfObject::getNumNamedUserDataSlots returns the number of named user data
slots.
pfObject::setUserData attaches the user-supplied data pointer, data, to
user data slot of the pfObject. If slot is not specified slot 0 is
assumed.
Example 2: How to use User Data.
Page 3
pfObject(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfObject(3pf)
typedef struct
{
float coeffFriction;
float density;
float *dataPoints;
}
myMaterial;
myMaterial *granite;
granite = (myMaterial *)pfMalloc(sizeof(myMaterial), NULL);
granite->coeffFriction = 0.5f;
granite->density = 3.0f;
granite->dataPoints = (float *)pfMalloc(sizeof(float)*8, NULL);
graniteMtl = new pfMaterial;
graniteMtl->setUserData(granite);
pfObject::getUserData returns the user-data pointer for slot of the
pfObject. If slot is not specified slot 0 is assumed.
Note that memory from pfMemory::malloc is not an considered a pfObject so
user-data pointers are not provided for pfMalloc'ed memory.
User data is reference counted if it is a libpr-type object like
pfTexture, pfGeoSet, or memory allocated from pfMemory::malloc. Thus
user data is deleted if its reference count reaches 0 when its parent
pfObject is deleted.
pfObject::getNumUserData returns 1 + greatest non-NULL user data slot
number of the pfObject, or 0 if no slot contains non-NULL user data.
pfObject::setDeleteFunc, pfObject::setCopyFunc, and
pfObject::setPrintFunc set global function callbacks which are called
when deleting, copying, and printing a pfObject with non-NULL user data
in slot. If slot is not specified slot 0 is assumed. These callbacks
are provided so you can change the default behavior of user data. If a
callback is not specified or is NULL, the default behaviors are:
1. Delete: Call pfUnrefDelete on the user data.
2. Copy: Decrement the reference count of the user data attached
to the destination pfObject (but do not delete it), increment
the reference count of the user data attached to the source
pfObject and copy the user data pointer from the source to the
destination pfObject. In pseudo-code:
pfUnref(dst->userData[slot]);
pfRef(src->userData[slot]);
dst->userData[slot] = src->userData[slot];
Page 4
pfObject(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfObject(3pf)
3. Print: Print the address of the user data.
pfObject::getDeleteFunc, pfObject::getCopyFunc, and
pfObject::getPrintFunc return the global deletion, copy, and print
callbacks respectively for slot. If slot is not specified slot 0 is
assumed.
Example 3: How to delete the user data of Example 2.
void
myDeleteFunc(pfObject *obj)
{
myMaterial *mtl = obj->getUserData();
pfFree(mtl->dataPoints);
mtl->free();
}
:
/* allocate a new material */
graniteMtl = new pfMaterial;
/* bind user data to material */
graniteMtl->setUserData(granite);
/* set deletion callback */
graniteMtl->setDeleteFunc(myDeleteFunc);
/*
* This will trigger callback only if graniteMtl has
* a reference count <= 0.
*/
graniteMtl->checkDelete();
In the above example, the 'dataPoints' array of the 'myMaterial'
structure would not have been freed without the deletion callback since
pfDelete would have simply deleted the myMaterial structure.
pfObject::getGLHandle is a back-door mechanism for those who need to
tweak the graphics library objects which underly many libpr objects.
pfObject::getGLHandle returns the graphics library identifier associated
with obj or -1 if obj has no associated graphics library handle.
pfObject::deleteGLHandle will delete the object's associated GL object.
Currently this is supported only for pfTextures.
SEE ALSO
pfDelete, pfMemory
Page 5
