Home Hierarchy Members Alphabetical Related Pages

The XdkWrl Library

1.1.0

The lightweight solution for loading/saving VRML files.
Author:
Xavier Décoret
Date:
31 august 2003

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.

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

Advanced concepts

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

Todo:
indent the header file correctly (check generator)

reference counting for SFImage type.

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

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).

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

Put parser classes in wrl namespace


Generated on 24 Feb 2005 with doxygen version 1.3.9.1. Valid HTML 4.0! Valid CSS!