NAME

vzObject - Reference counting and deletion notification.

INHERITS FROM

vzMemory

HEADER FILE

#include <Volumizer2/Object.h>

PUBLIC METHOD SUMMARY

void ref (

);

void unref (

);

void addDeletionCallback (

vzObjectCallback callback, void* userData);

void removeDeletionCallback (

vzObjectCallback callback, void* userData);

PROTECTED METHOD SUMMARY

vzObject (

);

virtual ~vzObject (

);

CLASS DESCRIPTION

The vzObject class provides simple reference counting for each Volumizer object type. It also provides a callback mechanism for deletion notification: A user can install callbacks that will be invoked whenever an object is deleted. The class is derived from vzMemory, which provides additional memory management functionality.

METHOD DESCRIPTIONS

   vzObject()

vzObject (

);

Constructor for objects. The reference count field is initialized to one.

   ~vzObject()

virtual ~vzObject (

);

Destructor for objects. The destructor is protected to enforce that all deletion must be performed through the use of the unref() method.

   addDeletionCallback()

void addDeletionCallback (

vzObjectCallback callback, void* userData);

Adds the specified callback to the list of callbacks to be executed just before the object is finally deleted. The deletion callback has the following form:

typedef void (*vzObjectCallback) (vzObject *object, void *userData);

When the deletion callback is invoked, two parameters are passed: the object which is about to disappear, and the user data pointer.

The deletion callback can be a useful tool in performing memory management for user-allocated data structures. The following code sets a deletion callback to free the volume data when the corresponding parameter is about to be deleted -

// Add a deletion callback to the given volume texture
void addDeletionCB(vzParameterVolumeTexture *texture) {

      // Get the data pointer to be deleted
      void *dataPtr = texture->getDataPtr();

      // Add the deletion callback with the dataPtr as the user data
      texture->addDeletionCallback(textureDeletionCB, dataPtr);
} 

// The texture deletion callback function
void textureDeletionCB(vzObject *object, void *userData) { 

    // The user data pointer
    delete [] userData;
}

Note: It is legal to add multiple deletion callbacks with the same function pointer but different user data pointers. Hence the above callback function could be used for multiple textures, each with a different user data pointer. If this method is called with the same function and user data pointers, no action is taken.

   ref()

void ref (

);

Increases the reference count for the object by one.

   removeDeletionCallback()

void removeDeletionCallback (

vzObjectCallback callback, void* userData);

Removes the specified callback from the deletion callback list. For a callback to be removed, both its function pointer and user data pointer must match the input arguments. If the given callback is not found, a vzError::warn() is issued.

   unref()

void unref (

);

Decreases the reference count for the object by one. Deletes the object if reference count drops to zero.

SEE ALSO

vzMemory

Back to Index