XdkWrl: The XdkWrl Library

Home | Hierarchy | Members | Alphabetical | Related Pages

# The XdkWrl Library

### 1.2.0

The lightweight solution for loading/saving VRML files.

- Introduction
  - The things at stake
  - Minimalistic functionnality
- Installation
  - Installing and compiling ANTLR
  - Installing and compiling XdkWrl
  - The Documentation
- Tour by examples
- Advanced concepts

Author:
  Xavier Décoret

Date:
  18 october 2005

## Introduction

The XdkWrl library allows you to load a VRML97 file into a C++ structure that you can then traverse to do whatever you need to. So this library is not aimed at rendering a 3D scene described by a VRML file! If you search for this kind of facility, I suggest you have a look at the excellent OpenVRML library. Instead this library aims at allowing to add VRML support to your application, whatever it is, by providing you with the export/import facilities.

VRML97, the finalized version of the language formerly known as VRML2, is a useful language. It should pretty soon be replaced by X3D which in the long term will make the present library obsolete and unecessary, but for the moment, there are still several reasons you want to work with VRML.

It is a language to describe 3D scenes, which you probably know. The nice thing is that it is well described, and it is a standard defined by the Web3D consortium. Many popular modelling software such as Maya, 3DSudio or blender are able to export in this language. Therefore, it is a good choice to store and exchange your 3D models.

The bad thing is that it is quite a pain to use it in your own software as you are pretty soon faced with the problem of reading VRML files. Once again, when X3D will be largely used, this will no longer stand since X3D files will be valid XML files that can be parsed easily with many libraries such as tinyXML, libxml or even Qt. But for the moment, you might find this library quite useful to you and here is why.

### The things at stake

The key concept here is parsing. On one hand you have a VRML scene that contains the information you want: your 3D scene. On the other hand, you have your C++ program to manipulate this information. The problem is that in your C++ program, you only know how to manipulate objects, not text file, except for fetching character sequentially. So what you need is something that transform the information in the text file into C++ objects. This is called parsing the file and it is exactly what this library will do for you.

Another problem is the traversing of a 3D scene. For VRML it is quite complex because depending of what you want to do, you have to deal with all the different cases specified by the standard concerning the semantic of nodes. Moreover ome actions such as maintaining the transformation hierarchy while traversingthe tree structure can be quite painful. Though this library do not take care of this semantic, a minimalistic tool set it privided to help you with this traversal task.

### Minimalistic functionnality

This library won't do anything else than parsing the file for you. It will just transform the text file into a C++ structure so you can manipulate it in you program. If you are familiar with the XML concepts, it is somehow similar to the Document Object Model (DOM). There are several reasons why I chose to limit this library's functionnalities.

- Modularity. From my experience of the Unix word, I believe that is better to have small tools that do very well what they are designed for than big and heavy tools that try and fail to do everything. So in your work with VRML files, they may be many processes: loading, transforming, displaying,etc. This library provides the tool for only one part, that is loading/saving and traversing.
- Portability. The more functionnalities you add to a library, the more it is likely to use other libraries. For exemple, rendering a VRML file would require OpenGL. Then you run on many problems to make your library available because you also have to deal with portability issues. This library is almost standalone: you need antlr to compile it, but once it is compiled you don't have to link with anything else (you can remove anltr from your hard disk, although I definitely urge you to keep it!).
- Difficulty. Let's face it, rendering, that is implementing a fully compliant VRML browser, is quite difficult especially because of timers and scripts. Although it took me some time to figure out how to parse correctly a VRML file, it is far much easy, so....
- Usability. I realized from my work in Computer Graphics that we own use our own internal data format for 3D models. As I mentionned, VRML is a very good language for exchanging data, that is storing them externally but I am sure any of you would find many good reasons to use its own internal format in your application (I personnaly do) so what you would only need is reading a file and any other functionnality I might strive to implement will certainly always be insufficient for you to use it.

## Installation

Enough for the foreword, let's put the hands in. So you downloaded the tarball and from the README you have been redirected to that page. Here is how to compile and use the library.

### Installing and compiling ANTLR

You need ANTLR to build the XdkWrl library. You will not need it after anymore so you can just install it in a local directory. Moreover, the XdkWrl library only needs the ANTLR headers and static library (libantlr.a) so it is sufficient to get a copy of them. For convenience, I included in the distribution this files for gcc-3.2.3. If you are on another platform, check htpp://www.antlr.org for downloads and installation notes.

Remarks:
  Antlr is a tools in the style of lex and yavv (the acronym stands for another tool for langage recognition). It uses a .g file to produce .hpp and .cpp file that implements fully re-entrant C++ lexers and parsers. I don't bundle the .g file with the tarball because I do not want to make it public yet (it should come soon). Instead, I bundle the generated file, using antlr-2.7.2. So it means that you have to install this version on your machine and no other.

### Installing and compiling XdkWrl

The library is distributed as tarball using automake and autoconf. So it ressembles the package you usually install.

The process is simply:

    > tar zxf xdkwrl.tar.gz
     > cd xdkwrl/
     > ./configure
     > make
     > make install

This should place install the library headers in /usr/local/include/ (all grouped in subdirectory xdkwrl) and libraries in /usr/local/lib (both static and shared versions). If you want to install it somewhere else, do

    > configure --help

and tweak the `--prefix` and associated options. The configure help will also show you that you can use the `--with-antlr-` command lines options to indicate where antlr is installed. As I said, I included precompiled version for gcc-3.2.3 under linux. If you want to yse it, here is how to do:

    >./configure --with-antlr_incdir=`pwd`/antlr-2.7.2/gcc-3.2.3/include --with-antlr_libdir=`pwd`/antlr-2.7.2/gcc-3.2.3/lib

### The Documentation

This documentation contains all the information about the C++ classes of the library. I added the documentation of VRML nodes (the semantic ) that I copied from the official standard. Although I used Doxygen, you cannot completely regenerate the documentation from the tarball because I use some external files that I don't include in the tarball. Instead I distribute the complete doc as I intended to have it formatted. It might change in the future. You might also want to look the different tutorials to see how to use the library. You can also find the complete official specification of VRML2 here

## Tour by examples

- Overview of organisation
- Loading a VRML file
- Traversing a VRML2 tree
- Using the Transformator class
- Generating VRML files and the pretty printer

## Advanced concepts

Now that you are familiar with the concepts of the library, you can look at more complex parts of the

- A complex example: X3D converter
- Using protos: the Plane proto example
- Extending the node class using the generaor.

Todo:
  indent the header file correctly (check generator)

Todo:
  reference counting for SFImage type.

Todo:
  Checking the fact that some nodes may have only certain other nodes as children (see ISO standard doc 4.6.5).

Todo:
  Signal two errors in the ISO standard to web3d: examples 13.3 and a reference not good in spec (for a texture field of a node).

Todo:
  Parse extern proto urls and inline urls (use web access?)

Todo:
  Put parser classes in wrl namespace

Generated on 5 Jan 2007 with version 1.5.1. |