SoDB(3)

📦 version 2.5.0, in fedora 43, fedora 44

okay so this is the SoDB(3) page from the Library Functions Manual, and bestie you are gonna want to sit down for this one because it's giving global data central. 💖

✨ NAME ✨

SoDB — the SoDB class keeps track of internal global data. that's the whole job. no cap. 💅

💫 SYNOPSIS 💫

first things first, you gotta include the header:

#include <Inventor/SoDB.h>

🎀 Public Types 🎀

the one and only public type, a callback type:

typedef SbBool ProgressCallbackType(const SbName &itemid, float fraction, SbBool interruptible, void *userdata)

🌟 Static Public Member Functions 🌟

all of these are static, meaning they're basically the main character energy of the class. here's the full lineup, no skips:

static void init (void)
static void finish (void)
static void cleanup (void)
static const char * getVersion (void)
static SbBool read (SoInput *in, SoPath *&path)
static SbBool read (SoInput *in, SoBase *&base)
static SbBool read (SoInput *in, SoNode *&rootnode)
static SoSeparator * readAll (SoInput *in)
static SoVRMLGroup * readAllVRML (SoInput *in)
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. that's the whole vibe.

This class collects various methods for initializing, setting and accessing common global data from the Coin library. it's like the group chat admin for all the shared stuff. 👑

All methods on SoDB are static. every single one. periodt.

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. seriously, do it first or you're gonna have a bad time. 💀

📝 Member Typedef Documentation 📝

typedef SbBool SoDB::ProgressCallbackType(const SbName &itemid, float fraction, SbBool interruptible, void *userdata)

Client code progress callback function must be static functions of this type. no exceptions, bestie.

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. so if you see -1.0, that's the abort signal. 😭

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. so don't expect to cancel if it's not interruptible, okay?

See SoDB::addProgressCallback() for full documentation of how the progress notification mechanism works. go read that if you want the full tea. ☕

🛠️ 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. like, not even a cute crash, just a sad one. 💥

References: SoType::badType(), createGlobalField(), SoHardCopy::init(), SoInput::init(), SoType::init(), SoAction::initClass(), SoBase::initClass(), SoDetail::initClass(), SoElement::initClass(), SoEvent::initClass(), SoField::initClass(), SoSensor::initClass(), SoError::initClasses(), isInitialized(), SoDebugError::postWarning(), registerHeader(), and SoSensor::setFunction().

Referenced by: SoInteraction::init(), and SoNodeKit::init().

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. it's the final boss of cleanup. 🧹

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. so if you're just a regular app, you can skip it.

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. so plug-ins and weird hosts, listen up. 🫶

Since: Coin 2.4, TGS Inventor 5.0

Referenced by: cleanup().

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. it's giving deprecated, bestie. 💀

Since: Coin 2.0

References: finish().

const char * SoDB::getVersion (void ) [static]

Returns a text string containing the name of the library and version information. it's like a little ID card for the library. 🪪

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

Instantiates and reads an SoPath object from in and returns a pointer to it in path. it's literally making a path out of thin air. ✨

The reference count of the SoPath object will initially be zero. so don't forget to ref it if you keep it around.

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. so TRUE + NULL means EOF, not a problem. got it?

References: SoType::getName(), SbName::getString(), SoBase::getTypeId(), SoBase::isOfType(), SoReadError::post(), read(), SoBase::ref(), and SoBase::unref().

Referenced by: read(), read(), and SoFile::readNamedFile().

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. same energy as the other read, but for SoBase.

The reference count of the base object will initially be zero.

Returns FALSE on error.

References: SoBase::getClassTypeId(), SoInput::isValidFile(), and SoBase::read().

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 node edition.

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. EOF again, no drama.

References: SoType::getName(), SbName::getString(), SoBase::getTypeId(), SoBase::isOfType(), SoReadError::post(), read(), SoBase::ref(), and SoBase::unref().

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. so it's smart about not adding extra wrappers. 💅

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. so the usual ref-count rules apply.

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. so check for NULL, bestie.

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). so either the easy way or the flexible way, your choice. 🎀

Referenced by: SoInteractionKit::readDefaultParts().

SoVRMLGroup * SoDB::readAllVRML (SoInput * in) [static]

Same as SoDB::readAll(), except it return an SoVRMLGroup instead of an SoSeparator. note: "return" not "returns", that's what the original says, we don't fix typos here. 😭

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. note: argument is teststring but text says testString, keep both. lowercase vs camelCase, it's a whole thing. 🙈

See also: getHeaderData(), registerHeader()

References: getHeaderData(), and SoDebugError::postWarning().

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. so you can make your own format, fancy. 💅

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. so you get hooks before and after, slay.

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. so # and <= 80 chars, got it?

See also: getHeaderData()

References: SbString::getLength(), SbString::getString(), and SoDebugError::postWarning().

Referenced by: init().

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. it's like a little query for all the header config.

If substringok is TRUE, ignore trailing characters in headerstring when checking for validity. so you can be a little loose with the match.

If no valid header string by this name is found, FALSE gets returned 💔 — but if it is found, you get TRUE back, and all those other input arguments get filled in with their respective values. bestie got her answers ✨

See also: isValidHeader(), registerHeader()

References: SbString::getLength(), getNumHeaders(), SbString::getSubString()

Referenced by: isValidHeader()

🌸 int SoDB::getNumHeaders(void) — static

Returns the number of registered file headers. that's it, that's the whole vibe 💅

See also: getHeaderString()

Referenced by: getHeaderData()

🎀 SbString SoDB::getHeaderString(const int i) — static

Hands you the identifier header string of index i. gimme the i-th one and it's yours 👑

See also: getNumHeaders(), getHeaderData()

References: SoDebugError::post()

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

Makes a brand-new global field of the given type, and from now on it answers to name whenever somebody hits up getGlobalField() 🫶

  • If a global field with that same name and type already exists? no worries, you just get a pointer to the one that's already there 😌
  • If a global field with that same name but a different type exists? nope, you get NULL 🚫

And if you ever want to deallocate a global field, you do it by calling SoDB::renameGlobalField() with the second argument set to an empty string. poof, gone 💨

See also: getGlobalField(), renameGlobalField()

References: SoType::canCreateInstance(), SoType::createInstance(), getGlobalField(), SoType::getName(), SbName::getString(), SoField::getTypeId(), SoDebugError::postWarning()

Referenced by: init()

🦋 SoField * SoDB::getGlobalField(const SbName & name) — static

If a global field with the given name exists, you get a pointer to it. If there's no field with that name, you get NULL. simple as 🌈

Now here's the tea: the realTime global field, set up by the library on initialization, is the one to know about 🔥 It's used as a source field by all the autonomous animation objects inside the library — think the SoTimeCounter engine, or the SoRotor node, etc.

And if you want to control the speed of "action" in a scene that's got animating / moving components (say, for doing fixed frame-time snapshots so you can generate a movie 🎬), grab the global field named "realTime" and use it the exact way it's depicted in the class documentation of the SoOffscreenRenderer class.

See also: createGlobalField(), renameGlobalField()

Referenced by: createGlobalField(), SoField::notify(), SoSceneManager::render(), SoElapsedTime::SoElapsedTime(), SoOneShot::SoOneShot(), SoRotor::SoRotor(), SoTimeCounter::SoTimeCounter(), SoVRMLTimeSensor::SoVRMLTimeSensor(), SoVRMLTimeSensor::write(), SoElapsedTime::writeInstance(), SoTimeCounter::writeInstance()

💫 void SoDB::renameGlobalField(const SbName & from, const SbName & to) — static

Renames a global field, glow-up style ✨ If to is an empty name, then the from field gets deleted. And if some other global field is already going by the name to? that one gets deleted first before the rename happens. no duplicates allowed in this house 💅

See also: getGlobalField(), createGlobalField()

References: SbName::getString(), SoDebugError::postWarning()

⏰ void SoDB::setRealTimeInterval(const SbTime & interval) — static

Sets the time interval between updates for the realTime global field to interval. The default value is 1/12 s. yes bestie, that's the actual default, don't come for me 😭

The low update rate is due to historical reasons — it's there to stay compatible with application code written for SGI Inventor. old code, old habits 🫠

Setting the interval to a zero time will disable automatic updates of the realTime field entirely. 👀

See also: getRealTimeInterval(), getGlobalField()

References: SoDebugError::postWarning(), SbTime::zero()

🕰️ const SbTime & SoDB::getRealTimeInterval(void) — static

Returns the current trigger interval for the global realTime SbTime field. that's your number, right there 🎀

See also: setRealTimeInterval(), getGlobalField()

🔥 void SoDB::enableRealTimeSensor(SbBool on) — static

Turns the realtime sensor on or off with that on argument, like a lil lightswitch 💡

The most common reason to turn the realtime sensor off is so you — the user application — can control the realTime global field yourself. Super handy when you wanna take screen snapshots at fixed intervals 📸 See the class documentation of SoOffscreenRenderer for the further info.

See also: setRealTimeInterval(), getGlobalField()

References: isInitialized(), SoDebugError::postWarning(), SbTime::zero()

👑 SoSensorManager * SoDB::getSensorManager(void) — static

Returns a pointer to the global sensor manager. The sensor manager is the one keeping track of the sensor queues. it's giving middle management but make it iconic 🗂️

Referenced by: endNotify(), getDelaySensorTimeout(), SoDelayQueueSensor::schedule(), SoTimerQueueSensor::schedule(), SoTimerSensor::schedule(), setDelaySensorTimeout(), SoTimerQueueSensor::setTriggerTime(), SoDelayQueueSensor::unschedule(), SoTimerQueueSensor::unschedule(), SoTimerSensor::unschedule()

🌙 void SoDB::setDelaySensorTimeout(const SbTime & t) — static

This is literally just a wrapper for the method in SoSensorManager by the same name. it's a pass-through, bestie 🫶

See also: getDelaySensorTimeout(), SoSensorManager

References: getSensorManager(), SoSensorManager::setDelaySensorTimeout()

🌸 const SbTime & SoDB::getDelaySensorTimeout(void) — static

Also just a wrapper for the method in SoSensorManager by the same name. same energy, different direction ✨

See also: setDelaySensorTimeout(), SoSensorManager

References: SoSensorManager::getDelaySensorTimeout(), getSensorManager()

💀 int SoDB::doSelect(int nfds, void * readfds, void * writefds, void * exceptfds, struct timeval * usertimeout) — static

NOTE: THIS METHOD IS OBSOLETED. DON'T USE IT. 🚫🚫🚫 like fr fr, do not use it.

Okay so what was it? It's a wrapper around the POSIX select() call, provided so you could do synchronous I/O while Coin keeps on handling sensor events, rendering, etc. The parameters are the same as for select(), so go 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 so we don't mess up the header file with system-specific includes. tidier ✨

NOTE: THIS METHOD IS OBSOLETED. DON'T USE IT. (yes, they said it twice, and so am I, because it matters 😭)

🔄 void SoDB::addConverter(SoType from, SoType to, SoType converter) — static

Tells SoDB that there's a way to convert data from the from SoField type over to the to SoField type, by connecting them with an instance of the converter SoFieldConverter type 🔗

Once you've done that, SoDB::getConverter() will later be able to automatically return the type of the correct conversion class when it's asked. it just knows now 💅

Coin internally provides conversion between most field types, so application programmers usually do not need this function. The exception is when you're writing your own field type classes and you want to be able to connect them to the internal field types (or to other extension field types). then it's your moment, bestie 👑

See also: createConverter(), SoFieldConverter

References: SoType::getKey(), SoType::getName(), SbName::getString(), SoDebugError::postWarning()

🧚 SoType SoDB::getConverter(SoType from, SoType to) — static

Returns the type of an SoFieldConverter class that's able to convert data between fields of type from and the data field(s) of field type to 🎀

If no conversion between the given field types is possible at all, it returns SoType::badType(). that's the "nope, no vibe match" answer 🙈

See also: addConverter()

References: SoType::badType(), SoType::fromKey(), SoType::getKey()

Referenced by: createRoute()

✅ SbBool SoDB::isInitialized(void) — static

Returns TRUE if init() has been called. just checking in on whether we've started the party yet 🎉

See also: init()

Referenced by: enableRealTimeSensor(), SoType::fromName(), init(), SoInteraction::init(), SoNodeKit::init(), SoSceneManager::SoSceneManager()

📣 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. iykyk, it's not for you 💅

Referenced by: SoBase::startNotify(), SoField::startNotify()

🫧 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. same deal, hands off bestie 🙈

🌈 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. yep, another one, internal squad only ✨

References: getSensorManager(), SoSensorManager::isDelaySensorPending(), SoSensorManager::processImmediateQueue()

Referenced by: SoBase::startNotify(), SoField::startNotify()

💜 void SoDB::addProgressCallback(ProgressCallbackType * func, void * userdata) — static

Okay, storytime. The concept behind progress information in Coin is that any internal process which might take a long time to complete (like, say, file import for huge scenes 🐘) can pass on progress information by calling back to a progress callback that the client application's code set up.

Your client's progress callback function signature must match SoDB::ProgressCallbackType. no off-brand signatures allowed 🚫

The mechanism works by enforcing that all progress notification from within Coin must do these things:

  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 that gets passed on to the progress callback 🏷️
  2. The first invocation of the user callback will be done with an exact 0.0 fraction value. fresh start 🌱
  3. The last invocation will be done with an exact 1.0 fraction value. finished, periodt 💅
  4. An exception to that last point: if the process gets aborted, a final invocation with a -1.0 fraction value will be made. oh no 😭

One important thing to note about this whole mechanism: processes with progress callbacks can be running within other processes that are also using the progress callback functionality. That means progress information has to be considered "stacked" 📚, and client code must be aware of this and treat it properly. don't skip this part, it'll bite you 🫠

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. bye bestie, you're unsubscribed 💨

🧵 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. threads, but make it safe 🔒

🔐 void SoDB::readlock(void) — static

Places a read lock on the global SoDB mutex. You can use this 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. like, completely frozen, do not pass go 😭

Heads up: all Coin actions have a read-lock on the global SoDB mutex while they're traversing the scene graph. it's just how they roll 🌈

See also: SoDB::readunlock(), SoDB::writelock()

Since: Coin 2.3

TGS Inventor 3.0

References SbRWMutex::readLock().

Referenced by SoAction::apply(), SoAction::apply(), and SoAction::apply().

void SoDB::readunlock (void ) [static]

Bestie, this one unlocks the read lock on the global SoDB mutex. It’s giving “okay we’re done reading for now, release the girlypop lock.” 💅

See also: SoDB::readlock()

Since: Coin 2.3

TGS Inventor 3.0

References SbRWMutex::readUnlock().

Referenced by SoAction::apply(), SoAction::apply(), and SoAction::apply().

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. Main character energy: you’re editing, so nobody else gets to peek. 👑

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

References SbRWMutex::writeLock().

void SoDB::writeunlock (void ) [static]

Unlocks the write lock on the global SoDB mutex. The vibe: you’re done editing, release the lock, let the people read. 🦋

See also: SoDB::writelock()

Since: Coin 2.3

TGS Inventor 3.0

References SbRWMutex::writeUnlock().

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. So iconic. ✨

See also:

  • SoDB::removeRoute()
  • SoField::connectFrom(SoField*)

Since: Coin 2.4

TGS Inventor 2.6

References SoType::badType(), SoField::connectFrom(), SbPList::find(), SoEngineOutput::getConnectionType(), getConverter(), SoField::getFieldType(), SoEngineOutput::getForwardConnections(), SoField::getForwardConnections(), SoBase::getName(), SoType::getName(), SbName::getString(), SoField::getTypeId(), SoBase::isOfType(), and SoDebugError::postWarning().

Referenced by SoBase::connectRoute().

void SoDB::removeRoute (SoNode * fromnode, const char * eventout, SoNode * tonode, const char * eventin) [static]

Removes a field-to-field connection. Bye bye, route. 💀

See also:

  • SoDB::createRoute()
  • SoField::disconnect(SoField*)

Since: Coin 2.4

TGS Inventor 2.6

References SoField::disconnect(), SoBase::getName(), SbName::getString(), SoBase::isOfType(), and SoDebugError::postWarning().

✨ Author ✨

Generated automatically by Doxygen for Coin from the source code.

This page was brought to you by Coin, Version 2.5.0, SoDB(3) — periodt. 💅

📦 where this page comes from