pfdShare(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages pfdShare(3pf)NAME
pfdNewShare, pfdGetGlobalShare, pfdSetGlobalShare, pfdDelShare,
pfdPrintShare, pfdCountShare, pfdGetSharedList, pfdFindSharedObject,
pfdAddSharedObject, pfdRemoveSharedObject, pfdNewSharedObject,
pfdMakeShared, pfdMakeSharedScene, pfdCleanShare, pfdGetNodeGStateList -
Facilitate the sharing of graphics state objects in a Performer scene
graph.
FUNCTION SPECIFICATION
#include <Performer/pfdu.h>
pfdShare * pfdNewShare(void);
pfdShare * pfdGetGlobalShare(void);
void * pfdSetGlobalShare(pfdShare *share);
void pfdDelShare(pfdShare *share, int deepDelete);
void pfdPrintShare(pfdShare *share);
int pfdCountShare(pfdShare *share);
pfList * pfdGetSharedList(pfdShare *share, pfType *type);
pfObject * pfdFindSharedObject(pfdShare *share, pfObject *object);
int pfdAddSharedObject(pfdShare *share, pfObject *object);
int pfdRemoveSharedObject(pfdShare *share, pfObject *object);
pfObject * pfdNewSharedObject(pfdShare *share, pfObject *object);
void pfdMakeShared(pfNode *node);
void pfdMakeSharedScene(pfScene *scene);
int pfdCleanShare(pfdShare *share);
pfList * pfdGetNodeGStateList(pfNode *node);
DESCRIPTION
It is obviously desirable to share state between database objects in
OpenGL Performer whenever possible. The notion of pervasive state
sharing underpins the entire pfGeoState mechanism. Common data such as
texture, materials, and lighting models are often duplicated in many
different objects throughout a database. This collection of functions
provides the means necessary to easily achieve sharing among these
objects by automatically producing a non-redundant set of states.
pfdNewShare constructs a new pfdShare structure in shared memory. This
structure is the object used to track shared state objects.
Page 1
pfdShare(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages pfdShare(3pf)
pfdGetGlobalShare returns the global pfdShare structure. This structure
is used by both the pfdBuilder and by loaders that do not use the
pfdBuilder.
pfdSetGlobalShare sets the global pfdShare structure.
pfdDelShare deletes a pfdShare structure. If deepDelete is non-NULL, all
the data referenced by the pfdShare will also be deleted.
pfdPrintShare will print statistics about how many object references are
being held in the given sharing structure.
pfdCountShare returns the total number of shared objects referenced by
the given sharing structure.
Each pfdShare structure maintains lists of shared objects with distinct
types of objects stored in distinct lists. pfdGetSharedList returns the
list of shared objects of the given type.
pfdNewSharedObject returns a shared object matching object. If a
matching object was already present in the sharing structure, that object
is returned. If no such object exists, a new object is created using
object as a template. This new object is entered into the sharing
structure and is returned to the caller.
pfdFindSharedObject looks through the given pfdShare structure for an
object matching object. A NULL is returned if no matching object is
found.
pfdAddSharedObject adds object to the given sharing structure, if it is
not already present. The object's index in the sharing list is returned.
pfdRemoveSharedObject removes object from the given sharing structure, if
it is present. The object's index in the sharing list is returned. The
object is deleted if its reference count reaches zero via pfUnrefDelete.
pfdMakeShared can be used to force sharing of state within an already
existing scene graph. It will traverse the graph rooted at node looking
for duplicate state objects. Any references to such objects will be made
to point to a single shared copy, and the duplicates will be freed.
pfdMakeSharedScene is similar to pfdMakeShared except that it works on a
scene and computes an optimal pfScene pfGeoState based on all of the
pfGeoStates referenced in scene (see pfdMakeSceneGState for further
information about the scene pfGeoState computation itself). The
pfGeoStates in scene are then optimized based on the new scene GeoState
(see pfdOptimizeGStateList). Lastly, the optimized pfGeoState is
assigned as the scene's pfGeoState so that the inheritance for the newly
optimized states will be effective (see pfSceneGState).
pfdCleanShare removes all shared objects that are referenced only by the
shared structure itself. It is useful to call pfdCleanShare after
Page 2
pfdShare(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages pfdShare(3pf)
deleting parts of database that were created using this share structure
to release the memory allocated for currently unused state elements.
pfdCleanShare returns the number of elements actually removed.
pfdGetNodeGStateList creates and returns a pfList of unique pfGeoStates
that are referenced by geometry under node.
NOTES
The libpfdu source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
SEE ALSO
pfGeoSet, pfGeoState, pfList
Page 3
