pfb(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages pfb(3pf)NAME
pfdLoadFile_pfb, pfdStoreFile_pfb, pfdConverterMode_pfb,
pfdGetConverterMode_pfb, pfdConverterVal_pfb, pfdGetConverterVal_pfb,
pfdConverterAttr_pfb, pfdGetConverterAttr_pfb, pfdUserData_pfb,
pfdAddCustomNode_pfb, pfdDeleteCustomNode_pfb, pfdLoadData_pfb,
pfdStoreData_pfb, pfdDescendObject_pfb, pfdLoadObjectRef_pfb,
pfdStoreObjectRef_pfb, - Utilities for loading and storing pfb files in
Performer applications.
FUNCTION SPECIFICATION
#include <Performer/pfdb/pfpfb.h>
pfNode* pfdLoadFile_pfb(const char *fileName);
int pfdStoreFile_pfb(pfNode *root, const char *fileName);
void pfdConverterMode_pfb(int mode, int value);
int pfdGetConverterMode_pfb(int mode);
void pfdConverterVal_pfb(int which, float val);
float pfdGetConverterVal_pfb(int which);
void pfdConverterAttr_pfb(int which, void *attr);
void* pfdGetConverterAttr_pfb(int which);
int pfdCrypt_pfb(uint *key,
pfdEncryptFuncType_pfb encrypt_func,
pfdDecryptFuncType_pfb decrypt_func);
int -
pfdUserData_pfb(pfdDescendUserDataFuncType_pfb descend_func,
pfdStoreUserDataFuncType_pfb store_func,
pfdLoadUserDataFuncType_pfb load_func);
int pfdAddCustomNode_pfb(pfType *type, const char *name,
pfdDescendCustomNodeFuncType_pfb descend_func,
pfdStoreCustomNodeFuncType_pfb store_func,
pfdNewCustomNodeFuncType_pfb new_func,
pfdLoadCustomNodeFuncType_pfb load_func);
int pfdDeleteCustomNode_pfb(pfType *type);
size_t pfdLoadData_pfb(void *data, int size, void *handle);
size_t pfdStoreData_pfb(void *data, int size, void *handle);
int pfdDescendObject_pfb(pfObject *obj, void *handle);
Page 1
pfb(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages pfb(3pf)
int pfdLoadObjectRef_pfb(pfObject **obj, void *handle);
int pfdStoreObjectRef_pfb(pfObject *obj, void *handle);
typedef void (*pfdDecryptFuncType_pfb)(int size, uint *key,
void *data);
typedef void (*pfdEncryptFuncType_pfb)(int size, uint *key,
void *src, void *dst);
typedef int (*pfdDescendUserDataFuncType_pfb)(void *udata,
pfObject *parent, void *handle);
typedef int (*pfdStoreUserDataFuncType_pfb)(void *udata,
pfObject *parent, void *handle);
typedef void * (*pfdLoadUserDataFuncType_pfb)(void *handle);
typedef int (*pfdDescendCustomNodeFuncType_pfb)(pfNode *node,
void *handle);
typedef int (*pfdStoreCustomNodeFuncType_pfb)(pfNode *node,
void *handle);
typedef pfNode * (*pfdNewCustomNodeFuncType_pfb)(void);
typedef int (*pfdLoadCustomNodeFuncType_pfb)(pfNode *node,
void *handle);
DESCRIPTION
pfdLoadFile_pfb builds in-memory data structures from an external pfb
database file. If no path to the file is given, the directories in the
active Performer file search path (see pfFilePath) are scanned for the
given filename. pfdLoadFile_pfb may only be called after pfConfig.
pfdStoreFile_pfb writes a subgraph of a Performer scene rooted at root to
a file named fileName in the pfb format.
pfdConverterMode_pfb, pfdGetConverterMode_pfb, pfdConverterAttr_pfb,
pfdGetConverterAttr_pfb, pfdConverterVal_pfb and pfdGetConverterVal_pfb
allow the user to access and alter the modes, attributes and values of
the pfb loader/storer. The pfb converter modes are:
PFPFB_SAVE_TEXTURE_IMAGE
By default texture images are not saved in pfb files if the
name of the file names an image file. Setting this mode to
PF_ON forces the texture image to be saved.
PFPFB_SAVE_TEXTURE_PATH
By default only the name of texture files are saved in pfb
files. Setting this mode to PF_ON causes the full path to
texture files to be saved.
Page 2
pfb(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages pfb(3pf)
PFPFB_SHARE_GS_OBJECTS
By default graphics state objects loaded from pfb files are
shared using the global pfdShare structure (see
pfdGetGlobalShare). Setting this mode to PF_OFF disables this
sharing.
PFPFB_COMPILE_GL
This mode controls the setting of the PFGS_COMPILE_GL draw mode
for pfGeoSets loaded from pfb files. It defaults to
PFPFB_COMPILE_GL_OFF which sets PFGS_COMPILE_GL to PF_OFF.
Setting it to PFPFB_COMPILE_GL_ON sets PFGS_COMPILE_GL to
PF_ON. Setting it to PFPFB_COMPILE_GL_AS_SAVED will cause
PFGS_COMPILE_GL to be set the same way as it was when the pfb
file was created.
PFPFB_DISABLE_REP_SAVE
Setting this parameter to PF_ON will make the pfb loader save
all curve/surface information as simple pfGeodes.
There are currently no pfb converter values or attributes.
The pfb format supports encryption of vertex and image data. Control of
encryption/decryption is done through pfdCrypt_pfb. To enable encryption
key should be a non NULL pointer to an array of unsigned integers. The
first element of the array is the number of elements in the rest of the
array. Pfb has its own built in encryption/decryption functions. To use
these NULL should be passed to encrypt_func and decrypt_func. One can
define there own encryption/decryption functions by setting encrypt_func
and decrypt_func to appropriate functions of the type
pfdEncryptFuncType_pfb and pfdDecryptFuncType_pfb. A function of type
pfdEncryptFuncType_pfb should encrypt size bytes of data from src and put
the result in dst. A function of type pfdDecryptFuncType_pfb should
decrypt size bytes of data from data and leaving the results in data.
For both these functions key is the key set in pfdCrypt_pfb.
There are some portions of a performer scene graph that it can be
impossible to know how to store or load without application specific
knowledge. Two examples of this are pfUserData and custom pfTypes. For
this reason one can set up call backs for the pfdStoreFile_pfb and
pfdLoadFile_pfb to call to handle this data. The functions
pfdLoadData_pfb, pfdStoreData_pfb, pfdDescendObject_pfb,
pfdLoadObjectRef_pfb, and pfdStoreObjectRef_pfb are meant to be called by
these call backs.
pfdLoadData_pfb reads size bytes of data into data from the pfb file
that is specified by handle. It should be called by the store_func
of pfdUserData_pfb and pfdCustomNode_pfb.
pfdStoreData_pfb writes size bytes of data from data into the pfb
file that is specified by handle. It should be called by the
store_func of pfdUserData_pfb and pfdCustomNode_pfb.
Page 3
pfb(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages pfb(3pf)
pfdDescendObject_pfb descends a pfObject pointer and adds it and any
of its children to the lists of items to be stored into the pfb file
that is specified by handle. It returns 0 if it can store an object
and -1 if it can not. Generally any pfObject that normally can
reside in a Performer scene graph can be stored.
pfdDescendObject_pfb should be called by the descend_func of
pfdUserData_pfb and pfdCustomNode_pfb.
pfdStoreObjectRef_pfb writes a reference to the pfObject pointed to
by obj into the pfb file that is specified by handle. It should be
called by the store_func of pfdUserData_pfb and pfdCustomNode_pfb.
It should only be called for those pfObject that
pfdDescendObject_pfb returned 0 on.
pfdLoadObjectRef_pfb reads a reference to a pfObject from the pfb
file that is specified by handle. At some later time, but before
the completion of pfdLoadFile_pfb, the address of the pfObject that
was referenced will be written into the pointer location pointed to
by obj. This is done because at the time that pfdLoadObjectRef_pfb
is called the referenced object might not have been read from the
pfb file. pfdLoadObjectRef_pfb should be called by the load_func of
pfdUserData_pfb and pfdCustomNode_pfb.
pfUserData can be of many forms. It can be a pointer to a block of
memory, a pointer to some pfObject, or a pointer to a complex structure
containing many other pointers. pfdUserData_pfb can be called to set up
call backs to handle the storing and loading of complex user data. To
set up a custom user data store descend_func and store_func must be
defined. To set up a custom load load_func must be defined.
The descend_func must be of the type pfdDescendUserDataFuncType_pfb. If
defined it will get called for each piece of user data that is not a
pointer to a savable pfObject. udata is the pointer to the user data.
parent is the parent pfObject of the user data. handle defines the
current pfb file. The descend_func should call pfdDescendObject_pfb for
any pfObjects that are referenced by the user data. It should return 0
if it wants to store this user data. It should return -1 if this user
data should not be stored.
The store_func must be of the type pfdStoreUserDataFuncType_pfb. If
defined it will get called for each piece of user data that the
descend_func said should be stored. udata is the pointer to the user
data. parent is the parent pfObject of the user data. handle defines
the current pfb file. The store_func should call pfdStoreData_pfb and
pfdStoreObjectRef_pfb zero or more times each to store the data and
pfObject references of this user data.
The load_func must be of the type pfdLoadUserDataFuncType_pfb. It will
get called for each piece of user data that is not a pointer to a
pfObject. handle defines the current pfb file. The load_func should
call pfdLoadData_pfb and pfdLoadObjectRef_pfb zero or more times each to
Page 4
pfb(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages pfb(3pf)
load the data and pfObject references of this user data.
pfUserData is descended based on the following scheme:
if (user_data is a pointer to savable pfObject)
{
mark it for storing;
descend the pfObject;
}
else if (descend_func)
{
if (descend_func(user_data))
mark it for storing;
}
else if (pfGetSize(user_data) > 0)
mark it for storing;
pfUserData is stored based on the following scheme:
if (user_data is a pointer to savable pfObject)
store the a reference to that object;
else if (store_func)
store_func(user_data);
else if (pfGetSize(user_data) > 0)
store pfGetSize(user_data) bytes of data;
Pfb files have the ability to store custom pfNodes. You should call
pfdAddCustomNode_pfb for each custom pfNode. type is the pfType of the
custom node. name is a string that will be used to identify the custom
nodes type in the pfb file. descend_func, store_func, new_func, and
load_func are call back functions. To store a custom node descend_func
and store_func must be defined. To load a custom node new_func and
load_func must be defined.
The descend_func must be of the type pfdDescendCustomNodeFuncType_pfb.
If defined it will get called for each custom node of pfType type found
in the scene graph. node is the pointer to the custom node. handle
defines the current pfb file. The descend_func should call
pfdDescendObject_pfb for any pfObjects that are referenced by the custom
node and not part of its parent pfType.
The store_func must be of the type pfdStoreCustomNodeFuncType_pfb. If
defined it will get called for each custom node of pfType type found in
the scene graph. node is the pointer to the custom node. handle defines
the current pfb file. The store_func should call pfdStoreData_pfb and
pfdStoreObjectRef_pfb zero or more times each to store the custom data
and pfObjects references of node. It should not store any of the data of
Page 5
pfb(3pf) OpenGL Performer 3.2.2 libpfdb Reference Pages pfb(3pf)
the standard Performer pfNode type it is derived from.
The new_func must be of the type pfdNewCustomNodeFuncType_pfb. It should
new a pfNode of pfType type.
The load_func must be of the type pfdLoadCustomNodeFuncType_pfb. If
defined it will get called for each custom node of pfType type found in
the pfb file. node is the pointer to the custom node. At the time
load_func is called node will have already been newed by new_func and all
of the data of its parent pfType will have been loaded. handle defines
the current pfb file. The load_func should call pfdLoadData_pfb and
pfdLoadObjectRef_pfb zero or more times each to load the custom data and
pfObject references of node.
NOTES
The libpfdb source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
SEE ALSOpfdLoadFile(3pf), pfb(5pf)
Page 6
