pfdConverter(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
NAME
pfdOpenFile, pfdLoadFile, pfdStoreFile, pfdConvertFrom, pfdConvertTo,
pfdAddExtAlias, pfdInitConverter, pfdExitConverter, pfdConverterMode,
pfdGetConverterMode, pfdConverterVal, pfdGetConverterVal,
pfdConverterAttr, pfdGetConverterAttr, pfdPrintSceneGraphStats -
Utilities for loading object databases into Performer applications.
FUNCTION SPECIFICATION
#include <Performer/pfdu.h>
FILE* pfdOpenFile(const char *file);
pfNode* pfdLoadFile(const char *fileName);
int pfdStoreFile(pfNode *root, const char *fileName);
pfNode* pfdConvertFrom(const char *ext, void *root);
void* pfdConvertTo(const char *ext, pfNode *root);
void pfdAddExtAlias(const char *ext, const char *alias);
int pfdInitConverter(const char *ext);
int pfdExitConverter(const char *ext);
void pfdConverterMode(const char *ext, int mode, int value);
int pfdGetConverterMode(const char *ext, int mode);
void pfdConverterVal(const char *ext, int which, float val);
float pfdGetConverterVal(const char *ext, int which);
void pfdConverterAttr(const char *ext, int which, void *attr);
void* pfdGetConverterAttr(const char *ext, int which);
void pfdPrintSceneGraphStats(pfNode *node, double elapsedTime);
DESCRIPTION
pfdOpenFile searches through the OpenGL Performer search path for the
named file and opens it using fopen(). It is a convenience function used
by several of the functions described here.
pfdLoadFile builds in-memory data structures from an external database
file. The filename's extension is used to determine the file format. 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 may only be called after pfConfig.
pfdStoreFile writes a subgraph of a Performer scene rooted at root to a
Page 1
pfdConverter(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
file named fileName in the format specified by the file name's extension
string.
pfdConvertFrom converts the in-memory data structure root of the format
specified by ext into an in-memory Performer scene. pfdConvertTo
reverses the process taking an in-memory Performer scene and converting
into the specified in-memory format.
pfdAddExtAlias registers an alias for the given file name extension.
Whenever a file with extension alias is encountered, the loader for type
ext will be used.
pfdInitConverter dynamically links the converter corresponding to the
extension ext into the current executable. This routine should be called
before pfConfig for all extensions that an executable will use to ensure
that any routines and static data required at run-time are available in
all Performer processes. If the corresponding loader is already in the
executable, e.g. as a statically linked object, pfdInitConverter takes no
action. pfdInitConverter returns TRUE if the loader is available or
FALSE if it could not be found or loaded.
The search for the converter DSO proceeds through the following locations
in order:
1. In the directory indicated by the environment variable
PFLD_LIBRARY{,N32,64}_PATH, if it is defined. The empty, "N32"
and "64" substrings correspond to O32, N32 and N64 modes of
compilation and execution.
2. In the current directory.
3. In the directory indicated by the rld environment variable
LD_LIBRARY{,N32,64}_PATH, if it is defined.
4. In the directory "$PFHOME/usr/lib{,32,64}/libpfdb", if the
environment variable PFHOME is defined. The empty, "32" and
"64" lib suffix strings correspond to O32, N32 and N64 modes of
compilation and execution.
5. In the directory "$PFHOME/usr/share/Performer/lib/libpfdb", if
the environment variable PFHOME is defined.
The loader DSO name is created as "libpf{-g}.so" where the "-g" suffix is
for a full symbol table debug version. pfdInitConverter will only load
the debug version of the converter DSO if it is unable to find the
optimized version of the DSO in any of paths mentioned above.
pfdLoadFile also requires that the DSO version number match that of
libpfdu. When PFLD_LIBRARY{,N32,64}_PATH is set, pfdLoadFile prints
diagnostic information about the DSO search using pfNotify at the
PFNFY_DEBUG notification level.
pfdExitConverter discards the database loader for the extension ext and
Page 2
pfdConverter(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
unlinks any dynamically linked objects from the current executable. The
only reason to call this function is to save swap space. If ext is NULL,
all converters are unlinked.
pfdConverterMode, pfdGetConverterMode, pfdConverterAttr,
pfdGetConverterAttr, pfdConverterVal and pfdGetConverterVal allow the
user to access and alter the modes, attributes and values of specific
loaders. These modes, attributes and values are defined inside each
individual loader. These functions are provided as a means for the user
to communicate with the loaders which are usually loaded as Dynamic
Shared Objects at run-time.
pfdPrintSceneGraphStats uses pfNotify to print some simple statistics
about the primitives in the scene graph. The elapsedTime argument is
provided by the caller and indicates the time it took for the scene graph
to be loaded. It is used by pfdPrintSceneGraphStats to print primitive
loading rate statistics. When the value is zero, none of the loading rate
statistics are printed
The routines that take an extension as an argument may be passed a full
file name, in which case the extension is extracted and used.
NOTES
The libpfdu source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
Very few of the database DSOs provided in the current release support
pfdStoreFile, none of them support pfdConvertTo, and only the Open
Inventor loader supports pfdConvertFrom. More pervasive support of these
operations is planned for future releases, however, and developers of new
database conversion tools are encouraged to provide the full set of
conversion functions in the database tools they develop.
When statically linking a loader library into an executable that calls
pfdLoadFile, you can use the '-u' option to ld to force the inclusion of
the loader object even though it is never referenced in the executable,
e.g. "cc -o myapp myapp.o -u pfdLoadFile_iv libpfiv_igl.a ..."
SEE ALSO
pfFilePath, pfNotify, ld
Page 3
