Open Inventor Release 2023.2.3
 
Loading...
Searching...
No Matches
SoDB Class Reference

Scene graph database class. More...

#include <Inventor/SoDB.h>

Public Types

enum  RenderCacheMode {
  COMPILE ,
  COMPILE_AND_EXECUTE ,
  AUTO_RENDER_CACHE
}
 Render cache modes. More...
 

Static Public Member Functions

static void init ()
 Initializes the database.
 
static void finish ()
 Frees Open Inventor's internal static memory allocations.
 
static void setSystemTimer (SoSystemTimer *timer)
 The system dependent timer allows Inventor to manage its sensor queue (for timers, animation) when creating custom viewers.
 
static SbBool read (SoInput *in, SoNode *&rootNode)
 Reads a graph from the file specified by the given SoInput, returning the resulting root node in rootNode.
 
static SbBool read (SoInput *in, SoPath *&path)
 Reads a graph from the file specified by the given SoInput, returning the resulting path in path.
 
static SoSeparatorreadAll (SoInput *in)
 Reads all graphs and paths from the file specified by the given SoInput.
 
static SbBool registerHeader (const SbString &headerString, SbBool isBinary, float ivVersion, SoDBHeaderCB *preCB, SoDBHeaderCB *postCB, void *userData=NULL)
 Registers the given string as a valid header for input files.
 
static SbBool getHeaderData (const SbString &string, 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.
 
static int getNumHeaders ()
 Returns the number of valid headers, including standard Open Inventor headers, and user-registered headers.
 
static SbString getHeaderString (int i)
 Returns the i'th header.
 
static SbBool isValidHeader (const char *testString)
 This returns TRUE if the given character string is one of the valid Open Inventor file headers, (e.g., "#Inventor V2.0 binary"), or if the string has been registered as a valid header through the registerHeader() method.
 
static SoFieldcreateGlobalField (const SbName &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.
 
static SoFieldgetGlobalField (const SbName &name)
 Returns the global field with the given name, or NULL if there is none.
 
static void renameGlobalField (const SbName &oldName, const SbName &newName)
 Renames the global field named oldName.
 
static void setRealTimeInterval (const SbTime &deltaT)
 The database automatically creates one global field when SoDB::init() is called.
 
static const SbTimegetRealTimeInterval ()
 Returns how often the database is updating the realTime global field.
 
static void setDelaySensorTimeout (const SbTime &t)
 This sets the timeout value for sensors that are delay queue sensors (one-shot sensors, data sensors).
 
static const SbTimegetDelaySensorTimeout ()
 Returns the current delay queue timeout value.
 
static void processEvents ()
 Process Open Inventor sensor queues (TimerQueue and DelayQueue).
 
static int doSelect (int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *userTimeOut)
  UNIX/Linux Only
In order to keep timer and idle sensors running as expected, it is necessary that an Open Inventor application not block while waiting for input.
 
static void writelock ()
 Acquire the global scene graph write-lock.
 
static void writeunlock ()
 Release the global scene graph write-lock.
 
static void readlock ()
 Acquire a non-exclusive global scene graph read-lock.
 
static void readunlock ()
 Release a non-exclusive global scene graph read-lock.
 
static SbTime getCurrentTime ()
 Returns the current time.
 
static bool addPlugin (const SbString &fileName)
 Loads a plugin library.
 
static bool removePlugin (const SbString &fileName)
 Unloads the specified plugin library.
 
static const std::vector< SbString > & getLoadedPlugins ()
 Returns the list of currently loaded plugins (file names).
 
static const std::vector< SbString > & getUnloadedPlugins ()
 Returns the list of plugins that failed to load (file names).
 
static bool addPluginsDirectory (const SbString &dirName)
 Adds a directory to search for libraries defining new Open Inventor plugins.
 
static bool removePluginsDirectory (const SbString &dirName)
 Remove directory from the list of search directories for plugin loading.
 
static const std::vector< SbString > & getPluginsDirectories ()
 Returns the list of search directories for plugin loading.
 
static void addConverter (SoType fromField, SoType toField, SoType converterEngine)
 Registers a field conversion engine that can be used to convert from one type of field to another.
 
static SoType getConverter (SoType fromField, SoType toField)
 Returns the field conversion engine registered for the two given field types.
 
static void removeConverter (SoType fromField, SoType toField)
 Remove a previously added converter.
 
static void setIvTuneAllowed (SbBool ivTuneAllowed)
 Specifies if launching IvTune interactively using the keyboard shortcut is allowed.
 
static SbBool getIvTuneAllowed ()
 Returns TRUE if IvTune can be launched interactively using the keyboard shortcut.
 

Friends

class SoGlobalField
 
class SoVRMLDB
 
class SoVRMLInline
 

Deprecated

static SoDEPRECATED void threadInit ()
 Initializes the database.
 
static SoDEPRECATED SbBool isMultiThread ()
 Returns whether multi-thread support is enabled in Open Inventor.
 
static SoDEPRECATED void setNumRenderCaches (int)
 Since Open Inventor 10.3, this method has no effect because render caches are automatically managed.
 
static SoDEPRECATED int getNumRenderCaches ()
 See method setNumRenderCaches().
 
static SoDEPRECATED void setRenderCacheMode (RenderCacheMode mode)
 Since Open Inventor 10.3, this method has no effect because render caches are automatically managed.
 
static SoDEPRECATED RenderCacheMode getRenderCacheMode ()
 See setRenderCacheMode().
 

Detailed Description

Scene graph database class.

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 SoDB::init() before calling any other database routines and before constructing any nodes, paths, functions, or actions. Note that SoDB::init() is called by SoInteraction::init(), SoNodeKit::init(), and SoWin::init(), so if you are calling any of these methods, you do not need to call SoDB::init() directly. All methods on this class are static.

Application programs should close and cleanup the database by calling SoDB::finish() after deleting all explicitly created Open Inventor objects. Note that in when using C++ API, "reference counted" objects like nodes and paths cannot be explicitly deleted.

All methods in this class are static.

Data Files:

SoDB also provides convenient methods for reading data files, for example:

SbString filename = "$OIVHOME/data/models/bird.iv";
SoSeparator* rootSep = NULL;
SoInput input;
if (input.openFile( filename )) {
rootSep = SoDB::readAll( &in );
input.closeFile();
}
Class for smart character strings.
Definition SbString.h:202
static SoSeparator * readAll(SoInput *in)
Reads all graphs and paths from the file specified by the given SoInput.
Used to read Open Inventor data files.
Definition SoInput.h:363
virtual SoNONUNICODE SbBool openFile(const char *fileName, SbBool okIfNotFound=FALSE, SbBool aSync=FALSE)
Opens named file, sets file pointer to result.
virtual void closeFile()
Closes all files on stack opened with openFile() or pushFile().
Group node that saves and restores traversal state.

Open Inventor has built-in support for reading the following file formats:

Open Inventor also supports many standard CAD file formats. See SoCADInputReader for the current list. Also see SoCADFileFormat.

Multithread Programming:

Since Open Inventor 10 in a multithreaded program, only the main thread has to call SoDB::init. Note that it is still valid to call init/finish in each threads.

SEE ALSO

SoBase, SoNode, SoEngine, SoField, SoInput, SoFile, SoPath, SoOneShotSensor, SoDataSensor, SoWin

Definition at line 219 of file SoDB.h.

Member Enumeration Documentation

◆ RenderCacheMode

Render cache modes.

Enumerator
COMPILE 

Display lists are created with COMPILE mode.

COMPILE_AND_EXECUTE 

Display lists are created with COMPILE_AND_EXECUTE mode.

AUTO_RENDER_CACHE 

Automatically choose mode depending on the hardware.

(Default).

Definition at line 225 of file SoDB.h.

Member Function Documentation

◆ addConverter()

static void SoDB::addConverter ( SoType  fromField,
SoType  toField,
SoType  converterEngine 
)
static

Registers a field conversion engine that can be used to convert from one type of field to another.

The type id's of the two fields are passed in, as is the type id of the field converter engine (derived from SoFieldConverter).

◆ addPlugin()

static bool SoDB::addPlugin ( const SbString fileName)
static

Loads a plugin library.

A plugin library may implement one or more classes extending Open Inventor classes. For example a custom node or a custom file reader derived from SoInputReader.

A plugin library must implement the initPlugin() and exitPlugin() C-formatted entry-points. The initPlugin() function is responsible for registering the new class (or classes) in the Open Inventor database through the standard SoType type creation mechanism. The exitPlugin() function is used to disable the use of the custom class(s) by removing the corresponding type(s) from the Open Inventor database.

By default, Open Inventor attempts to load all files that may be plugins (files with the extension .dll or .so depending on the platform) from the following locations:

  • Application specified directories,
    defined using the OIV_PLUGINS_DIRECTORY environment variable, or the SoDB::addPluginsDirectory() method.
  • The current application working directory.
  • The directory containing the Open Inventor libraries.

Specific plugin libraries can be loaded and unloaded by direct calls to the SoDB::addPlugin() and SoDB::removePlugin() methods.

Different plugins can be designed depending on their usage. Please refer to the Open Inventor plugin section in the documentation

◆ addPluginsDirectory()

static bool SoDB::addPluginsDirectory ( const SbString dirName)
static

Adds a directory to search for libraries defining new Open Inventor plugins.

See addPlugin(). Returns true if directory has been successfully added.

◆ createGlobalField()

static SoField * SoDB::createGlobalField ( const SbName name,
SoType  type 
)
static

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:

static SoField * createGlobalField(const SbName &name, SoType type)
The database maintains a namespace for global fields, making sure that there is at most one instance ...
Field containing a int32_t integer.
Definition SoSFInt32.h:80
static SoType getClassTypeId()
Returns the type identifier for this class.

◆ doSelect()

static int SoDB::doSelect ( int  nfds,
fd_set *  readfds,
fd_set *  writefds,
fd_set *  exceptfds,
struct timeval *  userTimeOut 
)
static

UNIX/Linux Only
In order to keep timer and idle sensors running as expected, it is necessary that an Open Inventor application not block while waiting for input.

If the Open Inventor application uses the SoXt component 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() that will handle Open Inventor tasks if necessary instead of blocking.

◆ finish()

static void SoDB::finish ( )
static

Frees Open Inventor's internal static memory allocations.

This avoids false positives from memory leak checking software. We recommend calling this method and it should be the last Open Inventor method called by the application.

Note : Open Inventor objects must be destroyed before you call this method. See SoXt::finish() method for additional info.

◆ getConverter()

static SoType SoDB::getConverter ( SoType  fromField,
SoType  toField 
)
static

Returns the field conversion engine registered for the two given field types.

If no such engine exists, SoType::badType() is returned. See addConverter().

◆ getCurrentTime()

static SbTime SoDB::getCurrentTime ( )
static

Returns the current time.

◆ getDelaySensorTimeout()

static const SbTime & SoDB::getDelaySensorTimeout ( )
static

Returns the current delay queue timeout value.

See setDelaySensorTimeout().

◆ getGlobalField()

static SoField * SoDB::getGlobalField ( const SbName name)
static

Returns the global field with the given name, or NULL if there is none.

See createGlobalField(). The type of the field may be checked using the SoField::isOfType(), SoField::getClassTypeId(), and SoField::getTypeId() methods.

◆ getHeaderData()

static SbBool SoDB::getHeaderData ( const SbString string,
SbBool isBinary,
float &  ivVersion,
SoDBHeaderCB *&  preCB,
SoDBHeaderCB *&  postCB,
void *&  userData,
SbBool  substringOK = FALSE 
)
static

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.

◆ getHeaderString()

static SbString SoDB::getHeaderString ( int  i)
static

Returns the i'th header.

See registerHeader().

◆ getIvTuneAllowed()

static SbBool SoDB::getIvTuneAllowed ( )
static

Returns TRUE if IvTune can be launched interactively using the keyboard shortcut.

See setIvTuneAllowed().

◆ getLoadedPlugins()

static const std::vector< SbString > & SoDB::getLoadedPlugins ( )
static

Returns the list of currently loaded plugins (file names).

See addPlugin().

◆ getNumHeaders()

static int SoDB::getNumHeaders ( )
static

Returns the number of valid headers, including standard Open Inventor headers, and user-registered headers.

See registerHeader().

◆ getNumRenderCaches()

static SoDEPRECATED int SoDB::getNumRenderCaches ( )
inlinestatic

See method setNumRenderCaches().

Definition at line 609 of file SoDB.h.

◆ getPluginsDirectories()

static const std::vector< SbString > & SoDB::getPluginsDirectories ( )
static

Returns the list of search directories for plugin loading.

See addPlugin().

◆ getRealTimeInterval()

static const SbTime & SoDB::getRealTimeInterval ( )
static

Returns how often the database is updating the realTime global field.

See also setRealTimeInterval(). The realTime global field can be accessed like this:

SoSFTime* realTimeField = (SoSFTime*)SoDB::getGlobalField( "realTime" );
static SoField * getGlobalField(const SbName &name)
Returns the global field with the given name, or NULL if there is none.
Field containing an SbTime.
Definition SoSFTime.h:82

◆ getRenderCacheMode()

static SoDEPRECATED RenderCacheMode SoDB::getRenderCacheMode ( )
static

◆ getUnloadedPlugins()

static const std::vector< SbString > & SoDB::getUnloadedPlugins ( )
static

Returns the list of plugins that failed to load (file names).

See addPlugin().

◆ init()

static void SoDB::init ( )
static

Initializes the database.

This must be called before calling any other database routines, including the construction of any nodes, paths, engines, or actions.

◆ isMultiThread()

static SoDEPRECATED SbBool SoDB::isMultiThread ( )
static

Returns whether multi-thread support is enabled in Open Inventor.

◆ isValidHeader()

static SbBool SoDB::isValidHeader ( const char *  testString)
static

This returns TRUE if the given character string is one of the valid Open Inventor file headers, (e.g., "#Inventor V2.0 binary"), or if the string has been registered as a valid header through the registerHeader() method.

◆ processEvents()

static void SoDB::processEvents ( )
static

Process Open Inventor sensor queues (TimerQueue and DelayQueue).

Normally this is handled automatically by the viewer.

◆ read() [1/2]

static SbBool SoDB::read ( SoInput in,
SoNode *&  rootNode 
)
static

Reads a graph from the file specified by the given SoInput, returning the resulting root node in rootNode.

There is an alternate read routine that returns the resulting 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.

◆ read() [2/2]

static SbBool SoDB::read ( SoInput in,
SoPath *&  path 
)
static

Reads a graph from the file specified by the given SoInput, returning the resulting path in path.

There is an alternate read routine that returns the resulting root node. 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.

◆ readAll()

static SoSeparator * SoDB::readAll ( SoInput in)
static

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, 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 it. This returns NULL on error. This processes directory paths in the same way as the other reading routines.

Reading a DXF file into Open Inventor is just like reading in an Open Inventor format file. Open Inventor will open the file and automatically detect that it is a DXF file. Optionally, you can tell Open Inventor explicitly that the file type is DXF. See SoInput for details about support of the DXF format.

◆ readlock()

static void SoDB::readlock ( )
static

Acquire a non-exclusive global scene graph read-lock.

The calling thread will block until a read-lock is available (no thread is holding the global write-lock). Multiple threads may hold global read-locks at the same time. While holding a read-lock it is safe to traverse the scene graph and to query values of fields, but not to modify the scene graph (see method SoDB::writelock). See readunlock().

◆ readunlock()

static void SoDB::readunlock ( )
static

Release a non-exclusive global scene graph read-lock.

See readunlock().

◆ registerHeader()

static SbBool SoDB::registerHeader ( const SbString headerString,
SbBool  isBinary,
float  ivVersion,
SoDBHeaderCB preCB,
SoDBHeaderCB postCB,
void *  userData = NULL 
)
static

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 Open Inventor file format. The ivVersion number indicates which Open Inventor file version this header corresponds to. The user-defined callback functions preCB and postCB are called before and after a file with 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.

◆ removeConverter()

static void SoDB::removeConverter ( SoType  fromField,
SoType  toField 
)
static

Remove a previously added converter.

See addConverter().

◆ removePlugin()

static bool SoDB::removePlugin ( const SbString fileName)
static

Unloads the specified plugin library.

See addPlugin(). Returns true if plugin was successfully unloaded.

◆ removePluginsDirectory()

static bool SoDB::removePluginsDirectory ( const SbString dirName)
static

Remove directory from the list of search directories for plugin loading.

See addPlugin(). Returns true if directory has been successfully removed.

◆ renameGlobalField()

static void SoDB::renameGlobalField ( const SbName oldName,
const SbName newName 
)
static

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 getGlobalField() method can be used to guard against this). See createGlobalField().

◆ setDelaySensorTimeout()

static void SoDB::setDelaySensorTimeout ( const SbTime t)
static

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.

The default timeout for delay queue sensors is 0.083 seconds. So if delay queue sensors are only triggered by the timeout, then by default the viewer animation can only run at about 12 frames per second. To trigger the delay queue sensors at, for example, 30 frames per second, make this call:

SoDB::setDelaySensorTimeout( 0.03f );

◆ setIvTuneAllowed()

static void SoDB::setIvTuneAllowed ( SbBool  ivTuneAllowed)
static

Specifies if launching IvTune interactively using the keyboard shortcut is allowed.

See SoIvTune to set the keyboard shortcut.

◆ setNumRenderCaches()

static SoDEPRECATED void SoDB::setNumRenderCaches ( int  )
inlinestatic

Since Open Inventor 10.3, this method has no effect because render caches are automatically managed.

Definition at line 600 of file SoDB.h.

◆ setRealTimeInterval()

static void SoDB::setRealTimeInterval ( const SbTime deltaT)
static

The database automatically creates one global field when SoDB::init() 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. 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. This method ensures that engines that do not continuously animate (such as SoTimeCounter) will eventually be scheduled. See also getRealTimeInterval(). The realTime global field can be accessed like this:

SoSFTime* realTimeField = (SoSFTime*)SoDB::getGlobalField( "realTime" );

◆ setRenderCacheMode()

static SoDEPRECATED void SoDB::setRenderCacheMode ( RenderCacheMode  mode)
static

Since Open Inventor 10.3, this method has no effect because render caches are automatically managed.

◆ setSystemTimer()

static void SoDB::setSystemTimer ( SoSystemTimer timer)
static

The system dependent timer allows Inventor to manage its sensor queue (for timers, animation) when creating custom viewers.

Typically, this method could be called in the constructor of the first interactive render area created. Calling this method more than once, does nothing. The SoSystemTimer instance is reference counted and will be deleted when its reference count reaches 0.

◆ threadInit()

static SoDEPRECATED void SoDB::threadInit ( )
static

Initializes the database.

This must be called before calling any other database routines, including the construction of any nodes, paths, engines, or actions. This method calls SoDB::init.

◆ writelock()

static void SoDB::writelock ( )
static

Acquire the global scene graph write-lock.

The calling thread will block until the write-lock is available (no threads hold a global read-lock). The global write-lock is exclusive. Only a single thread can hold this lock and while it is held, no thread can acquire a global read-lock. While holding the global write-lock it is safe to modify the scene graph including adding/removing nodes, modifying field values, etc. Do not hold the global write-lock longer than necessary. See writeunlock().

Note: Be sure the global write-lock is always released or there is a good chance the application will "dead lock" because all standard actions automatically attempt to acquire a global read-lock.

◆ writeunlock()

static void SoDB::writeunlock ( )
static

Release the global scene graph write-lock.

See writelock().

Friends And Related Symbol Documentation

◆ SoGlobalField

friend class SoGlobalField
friend

Definition at line 972 of file SoDB.h.

◆ SoVRMLDB

friend class SoVRMLDB
friend

Definition at line 973 of file SoDB.h.

◆ SoVRMLInline

friend class SoVRMLInline
friend

Definition at line 974 of file SoDB.h.


The documentation for this class was generated from the following file: