1SoDB(3IV)()                                                        SoDB(3IV)()
2
3
4

NAME

6       SoDB — scene graph database class
7

INHERITS FROM

9       SoDB
10

SYNOPSIS

12       #include <Inventor/SoDB.h>
13
14     typedef void        SoDBHeaderCB(void *userData, SoInput *in)
15
16          Methods from class SoDB:
17
18     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
46

DESCRIPTION

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
58       Typical program database initialization and scene reading  is  as  fol‐
59       lows:
60
61          #include <Inventor/SoDB.h>
62          #include <Inventor/SoInput.h>
63          #include <Inventor/nodes/SoSeparator.h>
64
65          SoSeparator  *rootSep;
66          SoInput      in;
67
68          SoDB::init();
69          rootSep = SoDB::readAll(&in);
70          if (rootSep == NULL)
71              printf("Error on read...\n");
72           ...
73
74

METHODS

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
81     static const char *    getVersion()
82          Returns  a  character string identifying the version of the Inventor
83          library in use.
84
85     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
94          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
101     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
110     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
116     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
133     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
147     static int             getNumHeaders()
148          Returns the number of valid  headers,  including  standard  Inventor
149          headers, and user-registered headers.
150
151     static SbString        getHeaderString(int i)
152          Returns the i'th header.
153
154     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
164          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
170
171     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
176     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
183     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
203     static const SbTime &  getRealTimeInterval()
204          Returns how often the database is updating realTime.
205
206     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
215     static const SbTime &  getDelaySensorTimeout()
216          Returns the current delay queue timeout value.
217
218     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
228

SEE ALSO

230       SoBase,  SoNode, SoEngine, SoField, SoInput, SoFile, SoPath, SoOneShot‐
231       Sensor, SoDataSensor, SoXt
232
233
234
235
236                                                                   SoDB(3IV)()
Impressum