pfObject(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfObject(3pf)NAME
pfGetObjectClassType, pfUserDataSlot, pfUserData, pfGetUserDataSlot,
pfGetUserData, pfGetNumUserData, pfGetNamedUserDataSlot,
pfGetUserDataSlotName, pfGetNumNamedUserDataSlots, pfCopyFuncSlot,
pfCopyFunc, pfGetCopyFuncSlot, pfGetCopyFunc, pfDeleteFuncSlot,
pfDeleteFunc, pfGetDeleteFuncSlot, pfGetDeleteFunc, pfPrintFuncSlot,
pfPrintFunc, pfGetPrintFuncSlot, pfGetPrintFunc, pfGetGLHandle,
pfDeleteGLHandle - pfObject, callback and user data operations
FUNCTION SPECIFICATION
#include <Performer/pf.h>
pfType* pfGetObjectClassType(void);
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);
void pfCopyFuncSlot(int slot, pfCopyFuncType func);
void pfCopyFunc(pfCopyFuncType func);
pfCopyFuncType pfGetCopyFuncSlot(int slot);
pfCopyFuncType pfGetCopyFunc(void);
void pfDeleteFuncSlot(int slot, pfDeleteFuncType func);
void pfDeleteFunc(pfDeleteFuncType func);
pfDeleteFuncType pfGetDeleteFuncSlot(int slot);
pfDeleteFuncType pfGetDeleteFunc(void);
void pfPrintFuncSlot(int slot, pfPrintFuncType func);
void pfPrintFunc(pfPrintFuncType func);
Page 1
pfObject(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfObject(3pf)
pfPrintFuncType pfGetPrintFuncSlot(int slot);
pfPrintFuncType pfGetPrintFunc(void);
int pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
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. Casting an object of
class pfObject to an object of class pfMemory is taken care of
automatically. This is also true for casts to objects of ancestor
classes 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);
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.
pfGetObjectClassType returns the pfType* for the class pfObject. The
pfType* returned by pfGetObjectClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfObject.
Page 2
pfObject(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfObject(3pf)
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.
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.
pfGetNamedUserDataSlot 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.
pfGetUserDataSlotName returns the name of user data slot.
pfGetNumNamedUserDataSlots returns the number of named user data slots.
pfUserDataSlot attaches the user-supplied data pointer, data, to user
data slot of obj. pfUserData attaches the user-supplied data pointer,
data, to user data slot 0 of obj.
Example 2: How to use User Data.
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 = pfNewMtl(NULL);
pfUserData(graniteMtl, granite);
pfGetUserDataSlot returns the user-data pointer for slot of obj.
pfGetUserData returns the user-data pointer for slot 0 of obj.
Note that memory from pfMalloc is not an considered a pfObject so user-
data pointers are not provided for pfMalloc'ed memory.
Page 3
pfObject(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfObject(3pf)
User data is reference counted if it is a libpr-type object like
pfTexture, pfGeoSet, or memory allocated from pfMalloc. Thus user data
is deleted if its reference count reaches 0 when its parent pfObject is
deleted.
pfGetNumUserData returns 1 + greatest non-NULL user data slot number of
obj, or 0 if no slot contains non-NULL user data.
pfDeleteFunc, pfDeleteFuncSlot, pfCopyFunc, pfCopyFuncSlot, and
pfPrintFunc, pfPrintFuncSlot 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];
3. Print: Print the address of the user data.
pfGetDeleteFunc, pfGetDeleteFuncSlot, pfGetCopyFunc, pfGetCopyFuncSlot,
and pfGetPrintFunc, pfGetPrintFuncSlot 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 = pfGetUserData(obj);
pfFree(mtl->dataPoints);
pfFree(mtl);
}
:
/* allocate a new material */
graniteMtl = pfNewMtl(NULL);
/* bind user data to material */
Page 4
pfObject(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfObject(3pf)
pfUserData(graniteMtl, granite);
/* set deletion callback */
pfDeleteFunc(myDeleteFunc);
/*
* This will trigger callback only if graniteMtl has
* a reference count <= 0.
*/
pfDelete(graniteMtl);
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.
pfGetGLHandle is a back-door mechanism for those who need to tweak the
graphics library objects which underly many libpr objects. pfGetGLHandle
returns the graphics library identifier associated with obj or -1 if obj
has no associated graphics library handle. pfDeleteGLHandle will delete
the object's associated GL object. Currently this is supported only for
pfTextures.
SEE ALSO
pfDelete, pfMemory
Page 5
