1SoDB(3IV)() SoDB(3IV)()
2
6 SoDB — scene graph database class
7
9 SoDB
10
12 #include <Inventor/SoDB.h>
13 typedef void SoDBHeaderCB(void *userData, SoInput *in)
15 Methods from class SoDB:
17 static void init()
19 static const char * getVersion()
20 static SbBool read(SoInput *in, SoNode *&rootNode)
21 static SbBool read(SoInput *in, SoPath *&path)
22 static SoSeparator * readAll(SoInput *in)
23 static SbBool isValidHeader(const char *testString)
24 static SbBool registerHeader(const SbString &headerString,
25 SbBool isBinary, float ivVersion, SoDBHead‐
26 erCB *preCB, SoDBHeaderCB *postCB, void
27 *userData)
28 static SbBool getHeaderData(const SbString &headerString, SbBool
29 &isBinary, float &ivVersion, SoDBHeaderCB
30 *&preCB, SoDBHeaderCB *&postCB, void *&user‐
31 Data, SbBool substringOK = FALSE)
32 static int getNumHeaders()
33 static SbString getHeaderString(int i)
34 static SoField * createGlobalField(const SbName &name, SoType type)
35 static SoField * getGlobalField(const SbName &name)
36 static void renameGlobalField(const SbName &oldName, const
37 SbName &newName)
38 static void setRealTimeInterval(const SbTime &deltaT)
39 static const SbTime & getRealTimeInterval()
40 static void setDelaySensorTimeout(const SbTime &t)
41 static const SbTime & getDelaySensorTimeout()
42 static int doSelect(int nfds, fd_set *readfds, fd_set
43 *writefds, fd_set *exceptfds, struct timeval
44 *userTimeOut)
45
48 The SoDB class holds all scene graphs, each representing a 3D scene
49 used by an application. A scene graph is a collection of SoNode objects
50 which come in several varieties (see SoNode). Application programs must
51 initialize the database by calling SoDB::init() before calling any
52 other database routines and before constructing any nodes, paths, func‐
53 tions, or actions. Note that SoDB::init() is called by SoInterac‐
54 tion::init(), SoNodeKit::init(), and SoXt::init(), so if you are call‐
55 ing any of these methods, you do not need to call SoDB::init()
56 directly. All methods on this class are static.
57 Typical program database initialization and scene reading is as fol‐
59 lows:
60 #include <Inventor/SoDB.h>
62 #include <Inventor/SoInput.h>
63 #include <Inventor/nodes/SoSeparator.h>
64 SoSeparator *rootSep;
66 SoInput in;
67 SoDB::init();
69 rootSep = SoDB::readAll(&in);
70 if (rootSep == NULL)
71 printf("Error on read...\n");
72 ...
73
76 static void init()
77 Initializes the database. This must be called before calling any
78 other database routines, including the construction of any nodes,
79 paths, engines, or actions.
80 static const char * getVersion()
82 Returns a character string identifying the version of the Inventor
83 library in use.
84 static SbBool read(SoInput *in, SoNode *&rootNode)
86 static SbBool read(SoInput *in, SoPath *&path)
87 Reads a graph from the file specified by the given SoInput, return‐
88 ing a pointer to the resulting root node in rootNode, or a pointer
89 to the resulting path in path. The programmer is responsible for
90 determining which routine to use, based on the contents of the
91 input. These routines return FALSE if any error occurred during
92 reading.
93 If the passed SoInput was used to open a file and the name of the
95 file contains a directory, SoDB automatically adds the directory to
96 the end of the current directory search path in the SoInput. This
97 means that nested files named in SoFile nodes may be found relative
98 to that directory. The directory is removed from the search path
99 when reading is complete.
100 static SoSeparator * readAll(SoInput *in)
102 Reads all graphs and paths from the file specified by the given
103 SoInput. If there is only one graph in the file and its root is an
104 SoSeparator, a pointer to the root is returned. In all other cases,
105 this creates an SoSeparator, adds the root nodes of all graphs read
106 as children of it, and returns a pointer to it. This returns NULL on
107 error. This processes directory paths in the same way as the other
108 reading routines.
109 static SbBool isValidHeader(const char *testString)
111 This returns TRUE if the given character string is one of the valid
112 Inventor file headers, (e.g. "#Inventor V2.0 binary"), or if the
113 string has been registered as a valid header through the register‐
114 Header method.
115 static SbBool registerHeader(const SbString &headerString,
117 SbBool isBinary, float ivVersion, SoDBHead‐
118 erCB *preCB, SoDBHeaderCB *postCB, void
119 *userData)
120 Registers the given string as a valid header for input files. The
121 string must be 80 characters or less, and start with the comment
122 character '#'. If the passed isBinary flag is true, any file with
123 this header will be read as a binary file. Usually, a user-defined
124 header represents a file format that is a superset of the Inventor
125 file format. The ivVersion number indicates which Inventor file ver‐
126 sion this header corresponds to. The user-defined callback functions
127 preCB and postCB are called before and after a file with this header
128 is read. The userData is passed to both callback functions. The
129 method returns TRUE if the header is successfully registered. Note,
130 nothing prevents you from registering the same string multiple
131 times.
132 static SbBool getHeaderData(const SbString &headerString, SbBool
134 &isBinary, float &ivVersion, SoDBHeaderCB
135 *&preCB, SoDBHeaderCB *&postCB, void *&user‐
136 Data, SbBool substringOK = FALSE)
137 Passes back the data registered with the given header string,
138 including the flag specifying whether the string is for a binary
139 file, pointers to the callback functions invoked before and after
140 reading the file, and a pointer to the user data passed to the call‐
141 back functions. If the given header string does not match any of the
142 registered headers, and the substringOK flag is TRUE, then the
143 method will search for a registered header that is a substring of
144 the given string. The method returns TRUE if a matching registered
145 header, or subheader, was found.
146 static int getNumHeaders()
148 Returns the number of valid headers, including standard Inventor
149 headers, and user-registered headers.
150 static SbString getHeaderString(int i)
152 Returns the i'th header.
153 static SoField * createGlobalField(const SbName &name, SoType type)
155 The database maintains a namespace for global fields, making sure
156 that there is at most one instance of a global field with any given
157 name in the database. This routine is used to create new global
158 fields. If there is no global field with the given name, it will
159 create a new global field with the given name and type. If there is
160 already a global field with the given name and type, it will return
161 it. If there is already a global field with the given name but a
162 different type, this returns NULL.
163 All global fields must be derived from SoField; typically the result
165 of this routine is cast into the appropriate type; for example:
166 SoSFInt32 *longField =
167 (SoSFInt32 *) SoDB::createGlobalField("Frame",
168 SoSFInt32::getClassTypeId());
169 static SoField * getGlobalField(const SbName &name)
172 Returns the global field with the given name, or NULL if there is
173 none. The type of the field may be checked using the SoField::isOfT‐
174 ype(), SoField::getClassTypeId(), and SoField::getTypeId() methods.
175 static void renameGlobalField(const SbName &oldName, const
177 SbName &newName)
178 Renames the global field named oldName. Renaming a global field to
179 an empty name ("") deletes it. If there is already a global field
180 with the new name, that field will be deleted (the getGlobalField
181 method can be used to guard against this).
182 static void setRealTimeInterval(const SbTime &deltaT)
184 The database automatically creates one global field when
185 SoDB::init() is called. The realTime global field, which is of type
186 SoSFTime, can be connected to engines and nodes for real-time anima‐
187 tion. The database will automatically update the realTime global
188 field 12 times per second, using a timer sensor. Typically, there
189 will be a node sensor on the root of the scene graph which schedules
190 a redraw whenever the scene graph changes; by updating the realTime
191 global field periodically, scene graphs that are connected to real‐
192 Time (and are therefore animating) will be redrawn. The rate at
193 which the database updates realTime can be controlled with this rou‐
194 tine. Passing in a zero time will disable automatic update of real‐
195 Time. If there are no enabled connections from the realTime field to
196 any other field, the sensor is automatically disabled. .p Note that
197 the SoSceneManager class automatically updates realTime immediately
198 after redrawing, which will result in as high a frame rate as possi‐
199 ble if the scene is continuously animating. The SoDB::setRealTimeIn‐
200 terval method ensures that engines that do not continuously animate
201 (such as SoTimeCounter) will eventually be scheduled.
202 static const SbTime & getRealTimeInterval()
204 Returns how often the database is updating realTime.
205 static void setDelaySensorTimeout(const SbTime &t)
207 This sets the timeout value for sensors that are delay queue sensors
208 (one-shot sensors, data sensors). Delay queue sensors are triggered
209 whenever there is idle time. If a long period of time elapses with‐
210 out any idle time (as when there are continuous events to process),
211 these sensors may not be triggered. Setting this timeout value
212 ensures that if the specified length of time elapses without any
213 idle time, the delay queue sensors will be processed anyway.
214 static const SbTime & getDelaySensorTimeout()
216 Returns the current delay queue timeout value.
217 static int doSelect(int nfds, fd_set *readfds, fd_set
219 *writefds, fd_set *exceptfds, struct timeval
220 *userTimeOut)
221 In order to keep timer and idle sensors running as expected, it is
222 necessary that an Inventor application not block waiting for input.
223 If the Inventor application uses the Xt utility library, this can be
224 handled automatically. However, if the application is using its own
225 event loop, this function is provided as a wrapper around select(2)
226 that will handle Inventor tasks if necessary instead of blocking.
227
230 SoBase, SoNode, SoEngine, SoField, SoInput, SoFile, SoPath, SoOneShot‐
231 Sensor, SoDataSensor, SoXt
232 SoDB(3IV)()