Importing, rendering and exporting a scene graph:

Typical usage:

1) Include header file
 
#include "world.H"

2) Create a world object:
 
  xrml::world* wrl = new xrml::world;

3a) Importing (parsing) a scene graph from a VRML'97 (or other) file:
 
  if (!wrl->parse(filename)) /* error */

"filename" can be the name of a regular file, a URL or a pipe (e.g. "< gunzip myfile.wrl.gz"). When the file name extensions is .Z, .gz, .bz or .bz2, the appropriate uncompress program is called. If filename is null, or if it is omitted, VRML will be read from standard input. In order to find out whether parsing was succesful, you can also inspect whether the world object got a scene graph:
 
  wrl->parse(filename);
  if (!wrl->sceneGraph) /* error */

The default time at parsing is 0. You can optionally set another start time as the second argument:
 
  wrl->parse(filename, start_time);

xrml::world::parse() also accepts a third argument: a so called importer.  The default importer imports VRML'97. By explicitly specifying a different importer, you can also read in other file formats. For instance:
 
  #include "ply/importer.H"
  ...
  ply::importer* ply_importer = new ply::importer;
  wrl->parse(filename, start_time, ply_importer);

ply::importer is a subclass of xrml::importer (see importer.H).

List of available import filters.

4) Specify a renderer: used to render frames of the world:
 
  #include "myrenderer.H"

  xrml::renderer* old_renderer = wrl->set_renderer(new myrenderer);

myrenderer is a subclass of xrml::renderer (see renderer.H), in which the default handlers for the nodes we are interested in are overriden. A simple renderer to study, in case you would like to design your own, is in FILTERS/nff.

5a) Rendering only the initial frame:
 
  wrl->newframe(); /* Important. Don't forget it! */
  wrl->render();

OR

5b) Rendering an animation:
 
 loop
    wrl->set_time(get_time());
    wrl->newframe();
    wrl->render();

OR equivalently:
 
 loop
    wrl->new_frame(get_time());
    wrl->render();

OR equivalently:
 
 loop
    wrl->rendernewframe(get_time());

During rendering, initial events for the next frame shall be generated. The events will be dispatched (routed and processed) next time wrl->newframe() is executed.

6) Exporting (saving) a scene graph

You can export the scene graph for the current frame to a VRML'97-like file on standard output as follows:
 
  wrl->save();

xrml::world::save can take up to two arguments, the first argument being the name of a file or a pipe to sent the output to (e.g. "| gzip -9 > filename.gz"):
 
 wrl->save(filename)

The second argument xrml::world::save() takes is a pointer to an export filter to be used, e.g.
 
  #include "nff/exporter.H"

  xrml::exporter* nff_exporter = new nff::exporter;
  wrl->save(filename, nff_exporter);

The export filters are objects inheriting from the xrml::exporter base class (see exporter.H).

List of available export filters.

INOTES:

1) Getting the time on a UNIX system:
 
#include <sys/time.h>
#include <unistd.h>

// returns number of seconds since Januari, 1st, 1970.
double get_time(void)
{
  struct timeval t;
  struct timezone tz = {0, DST_NONE}; // adapt if necessary.
  gettimeofday(&t, &tz);
  return (double)t.tv_sec + (double)t.tv_usec * 1e-6;
}

This file is maintained by Philippe.Bekaert@mpi-sb.mpg.de
Last update: February 22, 2001