SoDB(3IV)NAMESoDB (SoDB) - scene graph database class
INHERITS FROMSoDBSYNOPSIS
#include <Inventor_c/SoDB.h>
typedef void SoDBHeaderCB(void *userData, SoInput *in)
Functions from class SoDB:
void SoDBInit()
const char * SoDBGetVersion()
SbBool SoDBRead(SoInput *in, SoNode **rootNode)
SbBool SoDBReadPath(SoInput *in, SoPath **path)
SoSeparator * SoDBReadAll(SoInput *in)
SbBool SoDBIsValidHeader(const char *testString)
SbBool SoDBRegisterHeader(const SbString *headerString,
SbBool isBinary, float ivVersion, SoDBHeaderCB
*preCB, SoDBHeaderCB *postCB, void *userData)
SbBool SoDBGetHeaderData(const SbString *headerString,
SbBool *isBinary, float *ivVersion, SoDBHeaderCB
**preCB, SoDBHeaderCB **postCB, void **userData,
SbBool substringOK = FALSE)
int SoDBGetNumHeaders()
SbString SoDBGetHeaderString(int i)
SoField * SoDBCreateGlobalField(const char *name, SoType type)
SoField * SoDBGetGlobalField(const char *name)
void SoDBRenameGlobalField(const char *oldName, const char
*newName)
void SoDBSetRealTimeInterval(const SbTime *deltaT)
const SbTime * SoDBGetRealTimeInterval()
void SoDBSetDelaySensorTimeout(const SbTime *t)
const SbTime * SoDBGetDelaySensorTimeout()
int SoDBDoSelect(int nfds, fd_set *readfds, fd_set
*writefds, fd_set *exceptfds, struct timeval
*userTimeOut)
DESCRIPTION
The SoDB class holds all scene graphs, each representing a 3D scene used
by an application. A scene graph is a collection of SoNode objects which
come in several varieties (see SoNode). Application programs must
initialize the database by calling SoDBInit() before calling any other
database routines and before constructing any nodes, paths, functions, or
actions. Note that SoDBInit() is called by SoInteractionInit(),
SoNodeKitInit(), and SoXtInit(), so if you are calling any of these
functions, you do not need to call SoDBInit() directly.
Typical program database initialization and scene reading is as follows:
Page 1SoDB(3IV)FUNCTIONS
void SoDBInit()
Initializes the database. This must be called before calling any
other database routines, including the construction of any nodes,
paths, engines, or actions.
const char * SoDBGetVersion()
Returns a character string identifying the version of the Inventor
library in use.
SbBool SoDBRead(SoInput *in, SoNode **rootNode)
SbBool SoDBReadPath(SoInput *in, SoPath **path)
Reads a graph from the file specified by the given SoInput,
returning a pointer to the resulting root node in rootNode, or a
pointer to the resulting path in path. The programmer is responsible
for determining which routine to use, based on the contents of the
input. These routines return FALSE if any error occurred during
reading.
If the passed SoInput was used to open a file and the name of the
file contains a directory, SoDB automatically adds the directory to
the end of the current directory search path in the SoInput. This
means that nested files named in SoFile nodes may be found relative
to that directory. The directory is removed from the search path
when reading is complete.
SoSeparator * SoDBReadAll(SoInput *in)
Reads all graphs and paths from the file specified by the given
SoInput. If there is only one graph in the file and its root is an
SoSeparator, a pointer to the root is returned. In all other cases,
this creates an SoSeparator, adds the root nodes of all graphs read
as children of it, and returns a pointer to it. This returns NULL on
error. This processes directory paths in the same way as the other
reading routines.
SbBool SoDBIsValidHeader(const char *testString)
This returns TRUE if the given character string is one of the valid
Inventor file headers, (e.g. "#Inventor V2.0 binary"), or if the
string has been registered as a valid header through the
registerHeader method.
SbBool SoDBRegisterHeader(const SbString *headerString,
SbBool isBinary, float ivVersion, SoDBHeaderCB
*preCB, SoDBHeaderCB *postCB, void *userData)
Registers the given string as a valid header for input files. The
string must be 80 characters or less, and start with the comment
character '#'. If the passed isBinary flag is true, any file with
this header will be read as a binary file. Usually, a user-defined
header represents a file format that is a superset of the Inventor
file format. The ivVersion number indicates which Inventor file
version this header corresponds to. The user-defined callback
functions preCB and postCB are called before and after a file with
Page 2SoDB(3IV)
this header is read. The userData is passed to both callback
functions. The method returns TRUE if the header is successfully
registered. Note, nothing prevents you from registering the same
string multiple times.
SbBool SoDBGetHeaderData(const SbString *headerString,
SbBool *isBinary, float *ivVersion, SoDBHeaderCB
**preCB, SoDBHeaderCB **postCB, void **userData,
SbBool substringOK = FALSE)
Passes back the data registered with the given header string,
including the flag specifying whether the string is for a binary
file, pointers to the callback functions invoked before and after
reading the file, and a pointer to the user data passed to the
callback functions. If the given header string does not match any of
the registered headers, and the substringOK flag is TRUE, then the
method will search for a registered header that is a substring of
the given string. The method returns TRUE if a matching registered
header, or subheader, was found.
int SoDBGetNumHeaders()
Returns the number of valid headers, including standard Inventor
headers, and user-registered headers.
SbString SoDBGetHeaderString(int i)
Returns the i'th header.
SoField * SoDBCreateGlobalField(const char *name, SoType type)
The database maintains a namespace for global fields, making sure
that there is at most one instance of a global field with any given
name in the database. This routine is used to create new global
fields. If there is no global field with the given name, it will
create a new global field with the given name and type. If there is
already a global field with the given name and type, it will return
it. If there is already a global field with the given name but a
different type, this returns NULL.
All global fields must be derived from SoField; typically the result
of this routine is cast into the appropriate type; for example:
SoSInt32 *longField =
(SoSInt32 *) SoDBCreateGlobalField("Frame",
SoSInt32GetClassTypeId());
SoField * SoDBGetGlobalField(const char *name)
Returns the global field with the given name, or NULL if there is
none. The type of the field may be checked using the
SoFieldIsOfType(), SoFieldGetClassTypeId(), and SoFieldGetTypeId()
functions.
void SoDBRenameGlobalField(const char *oldName, const char
*newName)
Page 3SoDB(3IV)
Renames the global field named oldName. Renaming a global field to
an empty name ("") deletes it. If there is already a global field
with the new name, that field will be deleted (the
SoDBGetGlobalField function can be used to guard against this).
void SoDBSetRealTimeInterval(const SbTime *deltaT)
The database automatically creates one global field when SoDBInit()
is called. The realTime global field, which is of type SoSFTime, can
be connected to engines and nodes for real-time animation. The
database will automatically update the realTime global field 12
times per second, using a timer sensor. Typically, there will be a
node sensor on the root of the scene graph which schedules a redraw
whenever the scene graph changes; by updating the realTime global
field periodically, scene graphs that are connected to realTime (and
are therefore animating) will be redrawn. The rate at which the
database updates realTime can be controlled with this routine.
Passing in a zero time will disable automatic update of realTime. If
there are no enabled connections from the realTime field to any
other field, the sensor is automatically disabled. .p Note that the
SoSceneManager class automatically updates realTime immediately
after redrawing, which will result in as high a frame rate as
possible if the scene is continuously animating. The
SoDB::setRealTimeInterval method ensures that engines that do not
continuously animate (such as SoTimeCounter) will eventually be
scheduled.
const SbTime * SoDBGetRealTimeInterval()
Returns how often the database is updating realTime.
void SoDBSetDelaySensorTimeout(const SbTime *t)
This sets the timeout value for sensors that are delay queue sensors
(one-shot sensors, data sensors). Delay queue sensors are triggered
whenever there is idle time. If a long period of time elapses
without any idle time (as when there are continuous events to
process), these sensors may not be triggered. Setting this timeout
value ensures that if the specified length of time elapses without
any idle time, the delay queue sensors will be processed anyway.
const SbTime * SoDBGetDelaySensorTimeout()
Returns the current delay queue timeout value.
int SoDBDoSelect(int nfds, fd_set *readfds, fd_set
*writefds, fd_set *exceptfds, struct timeval
*userTimeOut)
In order to keep timer and idle sensors running as expected, it is
necessary that an Inventor application not block waiting for input.
If the Inventor application uses the Xt utility library, this can be
handled automatically. However, if the application is using its own
event loop, this function is provided as a wrapper around select(2)
that will handle Inventor tasks if necessary instead of blocking.
Page 4SoDB(3IV)SEE ALSO
SoBase, SoNode, SoEngine, SoField, SoInput, SoFile, SoPath,
SoOneShotSensor, SoDataSensor, SoXt
Page 5
