NAME
SoDB -
The SoDB class keeps track of internal global data.
This class collects various methods for initializing, setting and
accessing common global data from the Coin library.
SYNOPSIS
#include <Inventor/SoDB.h>
Public Types
typedef SbBool ProgressCallbackType (const SbName &itemid, float
fraction, SbBool interruptible, void *userdata)
Static Public Member Functions
static void init (void)
static void finish (void)
static void cleanup (void)
static const char * getVersion (void)
static SbBool read (SoInput *input, SoPath *&path)
static SbBool read (SoInput *input, SoBase *&base)
static SbBool read (SoInput *input, SoNode *&rootnode)
static SoSeparator * readAll (SoInput *input)
static SoVRMLGroup * readAllVRML (SoInput *input)
static SbBool isValidHeader (const char *teststring)
static SbBool registerHeader (const SbString &headerstring, SbBool
isbinary, float ivversion, SoDBHeaderCB *precallback, SoDBHeaderCB
*postcallback, void *userdata=NULL)
static SbBool getHeaderData (const SbString &headerstring, SbBool
&isbinary, float &ivversion, SoDBHeaderCB *&precallback,
SoDBHeaderCB *&postcallback, void *&userdata, SbBool substringok=0)
static int getNumHeaders (void)
static SbString getHeaderString (const int i)
static SoField * createGlobalField (const SbName &name, SoType type)
static SoField * getGlobalField (const SbName &name)
static void renameGlobalField (const SbName &from, const SbName &to)
static void setRealTimeInterval (const SbTime &interval)
static const SbTime & getRealTimeInterval (void)
static void enableRealTimeSensor (SbBool on)
static SoSensorManager * getSensorManager (void)
static void setDelaySensorTimeout (const SbTime &t)
static const SbTime & getDelaySensorTimeout (void)
static int doSelect (int nfds, void *readfds, void *writefds, void
*exceptfds, struct timeval *usertimeout)
static void addConverter (SoType from, SoType to, SoType converter)
static SoType getConverter (SoType from, SoType to)
static SbBool isInitialized (void)
static void startNotify (void)
static SbBool isNotifying (void)
static void endNotify (void)
static void addProgressCallback (ProgressCallbackType *func, void
*userdata)
static void removeProgressCallback (ProgressCallbackType *func, void
*userdata)
static SbBool isMultiThread (void)
static void readlock (void)
static void readunlock (void)
static void writelock (void)
static void writeunlock (void)
static void createRoute (SoNode *from, const char *eventout, SoNode
*to, const char *eventin)
static void removeRoute (SoNode *from, const char *eventout, SoNode
*to, const char *eventin)
Detailed Description
The SoDB class keeps track of internal global data.
This class collects various methods for initializing, setting and
accessing common global data from the Coin library.
All methods on SoDB are static.
Make sure you call SoDB::init() (either directly or indirectly through
the init() method of the GUI glue library) before you use any of the
other Coin classes.
Member Typedef Documentation
SbBool SoDB::ProgressCallbackType Client code progress callback function
must be static functions of this type.
The itemid argument is a unique text identifier which says what is
being processed (use this for any GUI progress bar informational text),
and fraction is a value in the range [0, 1] which indicates how far the
process has got. If the task is successfully aborted, the callback will
be invoked a last time with fraction set to -1.0.
The return value is an abort flag indication from the client code. Note
that the process that is being run can only be aborted if the
interruptible flag is set.
See SoDB::addProgressCallback() for full documentation of how the
progress notification mechanism works.
Member Function Documentation
void SoDB::init (void) [static] Initialize the Coin system. This needs to
be done as the first thing before you start using the library, or
you’ll probably see an early crash.
void SoDB::finish (void) [static] Invoke this method as the last call of
the application code, to trigger a clean-up of all static resources
used by the Coin library.
This is usually not necessary for stand-alone executable applications,
as the operating system will take care of cleaning up after the process
as it exits.
It may be necessary to invoke this method to avoid leaks for ’special’
execution environments, though, like if the Coin library is used as
e.g. a browser plug-in, or some other type of component which can be
started, shut down and restarted multiple times.
Since:
Coin 2.4
TGS Inventor 5.0
void SoDB::cleanup (void) [static] This method was renamed from Coin
version 2.4 onwards, to SoDB::finish(). Consider this name for the
method obsolete.
Since:
Coin 2.0
const char * SoDB::getVersion (void) [static] Returns a text string
containing the name of the library and version information.
SbBool SoDB::read (SoInput * in, SoPath *& path) [static] Instantiates and
reads an SoPath object from in and returns a pointer to it in path.
The reference count of the SoPath object will initially be zero.
Returns FALSE on error. Returns TRUE with path equal to NULL if we hit
end of file instead of a new path specification in the file.
SbBool SoDB::read (SoInput * in, SoBase *& base) [static] Instantiates and
reads an object of type SoBase from in and returns a pointer to it in
base. base will be NULL on return if we hit end of file.
The reference count of the base object will initially be zero.
Returns FALSE on error.
SbBool SoDB::read (SoInput * in, SoNode *& rootnode) [static] Instantiates
and reads an object of type SoNode from in and returns a pointer to it
in rootnode.
The reference count of the node will initially be zero.
Returns FALSE on error. Returns TRUE with rootnode equal to NULL if we
hit end of file instead of a new node specification in the file.
SoSeparator * SoDB::readAll (SoInput * in) [static] Reads all graphs from
in and returns them under an SoSeparator node. If the file contains
only a single graph under an SoSeparator node (which is the most common
way of constructing and exporting scene graphs), no extra SoSeparator
root node will be made, but the returned root node will be the top-most
node from the file.
The reference count of the root separator returned from this method
will be zero. Other nodes in the returned scene graph will have
reference counts according to the number of parent-child relationships,
as usual.
The common layout for how to load, work with and then finally destruct
and return memory resources of scenegraphs usually goes like this:
// [snip]
SoInput in;
if (!in.openFile(filename)) { exit(1); }
SoSeparator * root = SoDB::readAll(&in);
if (!root) { exit(1); }
// root-node returned from SoDB::readAll() has initial zero
// ref-count, so reference it before we start using it to
// avoid premature destruction.
root->ref();
// [do your thing here -- attach the scene to a viewer or whatever]
// Bring ref-count of root-node back to zero to cause the
// destruction of the scene.
root->unref();
// (Upon self-destructing, the root-node will also de-reference
// it’s children nodes, so they also self-destruct, and so on
// recursively down the scenegraph hierarchy until the complete
// scenegraph has self-destructed and thereby returned all
// memory resources it was using.)
Returns NULL on any error.
Tip: a common operation to do after importing a scene graph is to pick
out the memory pointers to one or more of the imported nodes for
further handling. This can be accomplished by using either the
SoNode::getByName() function (which is the easier approach) or by using
an instance of the SoSearchAction class (which is the more complex but
also more flexible approach).
SoVRMLGroup * SoDB::readAllVRML (SoInput * in) [static] Same as
SoDB::readAll(), except it return an SoVRMLGroup instead of an
SoSeparator.
See also:
SoDB::readAll()
Since:
Coin 2.0
SbBool SoDB::isValidHeader (const char * teststring) [static] Check if
testString is a valid file format header identifier string.
See also:
getHeaderData(), registerHeader()
SbBool SoDB::registerHeader (const SbString & headerstring, SbBool
isbinary, float ivversion, SoDBHeaderCB * precallback, SoDBHeaderCB *
postcallback, void * userdata = NULL) [static] Register a header string
which should be recognized by SoInput upon file import. This is a
convenient way for library users to register their own VRML or Coin
derived file formats.
Set isbinary to TRUE if the file should be read as binary data, and set
ivversion to indicate which Coin library version is needed to read the
file.
Callbacks precallback and postcallback will be called before and after
importing the custom format.
If headerstring can not be accepted as a valid file format header for
Coin files, FALSE will be returned. A valid header must start with a
’#’ character, and not be more than 80 characters long.
See also:
getHeaderData()
SbBool SoDB::getHeaderData (const SbString & headerstring, SbBool &
isbinary, float & ivversion, SoDBHeaderCB *& precallback, SoDBHeaderCB
*& postcallback, void *& userdata, SbBool substringok = 0) [static]
Returns the settings for the given headerstring, if headerstring is a
valid header.
If substringok is TRUE, ignore trailing characters in headerstring when
checking for validity.
If no valid header string by this name is found, FALSE is returned,
otherwise TRUE will be returned, and the other input arguments will be
set to their respective values.
See also:
isValidHeader(), registerHeader()
int SoDB::getNumHeaders (void) [static] Returns number of registered file
headers.
See also:
getHeaderString()
SbString SoDB::getHeaderString (const int i) [static] Returns the
identifier header string of index i.
See also:
getNumHeaders(), getHeaderData()
SoField * SoDB::createGlobalField (const SbName & name, SoType type)
[static] Create a new global field by the given type, and identified in
subsequent accesses to getGlobalField() by name. If a global field by
the name and type already exists, returns a pointer to it. If a global
field with the same name but a different type exists, returns NULL.
A global field can be deallocated by calling SoDB::renameGlobalField(),
with the second argument set to an empty string.
See also:
getGlobalField(), renameGlobalField()
SoField * SoDB::getGlobalField (const SbName & name) [static] If there
exist a global field with the given name, return a pointer to it. If
there is no field with this name, return NULL.
Of particular interest is the realTime global field set up by the
library on initialization. This field is used as a source field to all
the autonomous animation objects within the library, like for instance
the SoTimeCounter engine or the SoRotor node.
If you want to control the speed of ’action’ of a scene with animating
/ moving components (for instance for doing fixed frame-time snapshots
for generating a movie), grab the global field named ’realTime’ and use
it in the manner depicted in the class documentation of the
SoOffscreenRenderer class.
See also:
createGlobalField(), renameGlobalField()
void SoDB::renameGlobalField (const SbName & from, const SbName & to)
[static] Rename a global field. If to is an empty name, the from field
gets deleted. If another global field already goes by the name to, that
field will get deleted before the rename operation.
See also:
getGlobalField(), createGlobalField()
void SoDB::setRealTimeInterval (const SbTime & interval) [static] Set the
time interval between updates for the realTime global field to
interval. Default value is 1/12 s.
The low update rate is due to historical reasons, to be compatible with
application code written for SGI Inventor.
Setting the interval to a zero time will disable automatic updates of
the realTime field.
See also:
getRealTimeInterval(), getGlobalField()
const SbTime & SoDB::getRealTimeInterval (void) [static] Returns the
current trigger interval for the global realTime SbTime field.
See also:
setRealTimeInterval(), getGlobalField()
void SoDB::enableRealTimeSensor (SbBool on) [static] Turn on or off the
realtime sensor.
The most common use for turning the realtime sensor off is to control
the realTime global field from the user application. This is for
instance handy when you want to take screen snapshots at fixed
intervals. See the class documentation of SoOffscreenRenderer for
further information.
See also:
setRealTimeInterval(), getGlobalField()
SoSensorManager * SoDB::getSensorManager (void) [static] Returns a pointer
to the global sensor manager. The sensor manager keeps track of the
sensor queues.
void SoDB::setDelaySensorTimeout (const SbTime & t) [static] This is just a
wrapper for the method in SoSensorManager by the same name.
See also:
getDelaySensorTimeout(), SoSensorManager
const SbTime & SoDB::getDelaySensorTimeout (void) [static] This is just a
wrapper for the method in SoSensorManager by the same name.
See also:
setDelaySensorTimeout(), SoSensorManager
int SoDB::doSelect (int nfds, void * readfds, void * writefds, void *
exceptfds, struct timeval * usertimeout) [static] NOTE: THIS METHOD IS
OBSOLETED. DON’T USE IT.
This is a wrapper around the POSIX select() call. It is provided so you
can do synchronous I/O while Coin continues to handle sensor events,
rendering, etc. The parameters are the same as for select(), so check
your system documentation on how to use them.
The void* arguments must be valid pointers to fd_set structures. We’ve
changed this from the original SGI Inventor API to avoid messing up the
header file with system-specific includes.
NOTE: THIS METHOD IS OBSOLETED. DON’T USE IT.
void SoDB::addConverter (SoType from, SoType to, SoType converter) [static]
Notify SoDB that there exists a way to convert data from the from
SoField type to the to SoField type, by connecting them with an
instance of the converter SoFieldConverter type.
By doing this, SoDB::getConverter() will later be able to automatically
return the type of the correct conversion class when requested.
Coin internally provides conversion between most field types, so
application programmers should usually not need to use this function.
The exception is if you are writing your own field type classes, and
want to be able to connect them to the internal field types (or other
extensions field types).
See also:
createConverter(), SoFieldConverter
SoType SoDB::getConverter (SoType from, SoType to) [static] Return the type
of an SoFieldConverter class which is able to convert data between
fields of type from to the data field(s) of field type to.
If no conversion between the given field types is possible, returns
SoType::badType().
See also:
addConverter()
SbBool SoDB::isInitialized (void) [static] Returns TRUE if init() has been
called.
See also:
init()
void SoDB::startNotify (void) [static] This API member is considered
internal to the library, as it is not likely to be of interest to the
application programmer.
SbBool SoDB::isNotifying (void) [static] This API member is considered
internal to the library, as it is not likely to be of interest to the
application programmer.
void SoDB::endNotify (void) [static] This API member is considered internal
to the library, as it is not likely to be of interest to the
application programmer.
void SoDB::addProgressCallback (ProgressCallbackType * func, void *
userdata) [static] The concept behind progress information in Coin is
that any internal process which may take a long time to complete (like
e.g. file import for huge scenes) can pass on progress information by
calling back to a progress callback set up by the code of the client
application.
The client’s progress callback’s function signature must match the
SoDB::ProgressCallbackType.
The mechanism works by enforcing that all progress notification from
within Coin must
1. Use a unique text id to identify the ’progress-informing’ process
(e.g. ’File import’ for SoDB::readAll() / SoInput file reading,
’File export’ for SoOutput / SoWriteAction, etc). This is the
itemid name passed on to the progress callback.
2. The first invocation of the user callback will be done with an
exact 0.0 fraction value.
3. The last invocation will be done with an exact 1.0 fraction value.
4. An exception to the last point is that if the process is aborted, a
final invocation with a -1.0 fraction value will be made.
One important thing to note about the mechanism is that processes with
progress callbacks can be running within other processes using the
progress callback functionality. Progress information will then have to
be considered to be ’stacked’, and client code must be aware of and
treat this properly.
This function is an extension for Coin, and it is not available in the
original SGI Open Inventor v2.1 API.
Since:
Coin 2.2
void SoDB::removeProgressCallback (ProgressCallbackType * func, void *
userdata) [static] Removes a progress callback function, which will no
longer be invoked.
SbBool SoDB::isMultiThread (void) [static] Returns TRUE if this is a thread
safe version of Coin (i.e. it was configured and built with --enable-
threadsafe).
void SoDB::readlock (void) [static] Places a read lock on the global SoDB
mutex. This can be used to synchronize between threads that are
reading/writing Coin scene graphs.
If you call this function, you must make sure that you also call
SoDB::readunlock(). If you fail to do this, you might experience that
your application locks up.
All Coin actions has a read-lock on the global SoDB mutex while
traversing the scene graph.
See also:
SoDB::readunlock(), SoDB::writelock()
Since:
Coin 2.3
TGS Inventor 3.0
void SoDB::readunlock (void) [static] Unlocks the read lock on the global
SoDB mutex.
See also:
SoDB::readlock()
Since:
Coin 2.3
TGS Inventor 3.0
void SoDB::writelock (void) [static] Places a write lock on the global SoDB
mutex. This can be used to prevent that the scene graph is read or
traversed while you modify the scene graph.
If you call this function, you must make sure that you also call
SoDB::writeunlock(). If you fail to do this, you might experience that
your application locks up.
See also:
SoDB::readlock()
Since:
Coin 2.3
TGS Inventor 3.0
void SoDB::writeunlock (void) [static] Unlocks the write lock on the global
SoDB mutex.
See also:
SoDB::writelock()
Since:
Coin 2.3
TGS Inventor 3.0
void SoDB::createRoute (SoNode * fromnode, const char * eventout, SoNode *
tonode, const char * eventin) [static] Create a connection from one
VRML97 node field to another.
(’Routes’ are what field-to-field connections are called for the VRML97
standard.)
Connections made in this manner will be persistent upon file export.
See also:
SoDB::removeRoute()
SoField::connectFrom(SoField*)
Since:
Coin 2.4
TGS Inventor 2.6
void SoDB::removeRoute (SoNode * fromnode, const char * eventout, SoNode *
tonode, const char * eventin) [static] Removes a field-to-field
connection.
See also:
SoDB::createRoute()
SoField::disconnect(SoField*)
Since:
Coin 2.4
TGS Inventor 2.6
Author
Generated automatically by Doxygen for Coin from the source code.