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); 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. 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. 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 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 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 ALSO pfdLoadFile(3pf), pfb(5pf) Page 6