OpenVRML library version 0.11.2, 18 October, 2001
Copyright (C) 1998, 1999, 2000 Chris Morley <cmorley@vermontel.net>
Copyright (C) 2000, 2001 Braden McDaniel <braden@endoframe.com>
Portions Copyright SGI and others

Available from <http://openvrml.org>

See the `NEWS' file for a list of changes in this release.


About
=====

   OpenVRML is a portable C++ class library for reading and displaying
VRML97 files.  This distribution includes Lookat, a sample viewer
program that uses GLUT.


License terms
=============

   This bulk of the code in OpenVRML is Free Software available under
the terms of the Lesser General Public License (LGPL), version 2.1.
Other code in OpenVRML is used under "LGPL-compatible" licenses, which
effectively means that OpenVRML is Free Software which may be used as
a whole according to the terms of the LGPL.  The full text of the LGPL
can be found in the file `COPYING.LIB'.  Code used (and available for
reuse) under other terms is as follows:

 * OpenVRML uses the ANTLR parser generator and C++ support library
   which are in the public domain.

 * OpenVRML includes GIF reading code by David Koblas:
 
     Copyright 1990, David Koblas.
     Permission to use, copy, modify, and distribute this software
     and its documentation for any purpose and without fee is hereby
     granted, provided that the above copyright notice appear in all
     copies and that both that copyright notice and this permission
     notice appear in supporting documentation.  This software is
     provided "as is" without express or implied warranty.

 * OpenVRML's OpenGL renderer includes code from Silicon Graphics, Inc.:
 
     (c) Copyright 1993, 1994, Silicon Graphics, Inc.
     ALL RIGHTS RESERVED
     Permission to use, copy, modify, and distribute this software for
     any purpose and without fee is hereby granted, provided that the
     above copyright notice appear in all copies and that both the
     copyright notice and this permission notice appear in supporting
     documentation, and that the name of Silicon Graphics, Inc. not be
     used in advertising or publicity pertaining to distribution of the
     software without specific, written prior permission.
     
     THE MATERIAL EMBODIED ON THIS SOFTWARE IS PROVIDED TO YOU "AS-IS"
     AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE,
     INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR
     FITNESS FOR A PARTICULAR PURPOSE.  IN NO EVENT SHALL SILICON
     GRAPHICS, INC.  BE LIABLE TO YOU OR ANYONE ELSE FOR ANY DIRECT,
     SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY
     KIND, OR ANY DAMAGES WHATSOEVER, INCLUDING WITHOUT LIMITATION,
     LOSS OF PROFIT, LOSS OF USE, SAVINGS OR REVENUE, OR THE CLAIMS OF
     THIRD PARTIES, WHETHER OR NOT SILICON GRAPHICS, INC.  HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH LOSS, HOWEVER CAUSED AND ON
     ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE
     POSSESSION, USE OR PERFORMANCE OF THIS SOFTWARE.
     
     US Government Users Restricted Rights
     Use, duplication, or disclosure by the Government is subject to
     restrictions set forth in FAR 52.227.19(c)(2) or subparagraph
     (c)(1)(ii) of the Rights in Technical Data and Computer Software
     clause at DFARS 252.227-7013 and/or in similar or successor
     clauses in the FAR or the DOD or NASA FAR Supplement.
     Unpublished-- rights reserved under the copyright laws of the
     United States.  Contractor/manufacturer is Silicon Graphics,
     Inc., 2011 N.  Shoreline Blvd., Mountain View, CA 94039-7311.
     
     OpenGL(TM) is a trademark of Silicon Graphics, Inc.


Required libraries
==================

   OpenVRML requires zlib, OpenGL/Mesa, and GLUT to build.  If any
of these are not already present on your system, first consult your
operating system vendor for packages tailored to your particular
operating system/distribution.

   Mac users can find the Apple OpenGL SDK here
     <http://developer.apple.com/opengl/>
and compiled versions of the remaining dependencies here:
     <http://openvrml.org/dist/macos_required_libs.sit>

   Compiled versions of the depenencies for Windows users are available
here:
     <http://openvrml.org/dist/win32_required_libs.zip>

Otherwise, consult the following URLs:
     zlib:  <http://www.info-zip.org/pub/infozip/zlib/>
     Mesa:  <http://www.mesa3d.org>
     GLUT:  <http://reality.sgi.com/mjk_asd/glut3/>


   OpenVRML also uses the ANTLR parser generator.  The generated sources
come with the distribution, and most users should never need to
recompile the ANTLR source.  For those who do, ANTLR can be found here:
    <http://www.antlr.org>


Optional features
=================

 * PNG image support
   
   libpng is required for PNG support in OpenVRML.  If libpng is not
   already installed on your system, you can find it at
   <http://www.libpng.org/pub/png/libpng.html>.  The GNU build includes
   configuration options to either allow the build to locate libpng on
   your system, or build without PNG support (if you don't have libpng
   or don't want PNG support).  These arguments can be passed to
   `configure':
   
   --with-libpng
   --with-libpng=yes
      Look in the default library and include paths for libpng.  This is
      the default.
   
   --with-libpng=PREFIX
      If libpng is not installed in the default library and include 
      paths on your system, pass the prefix under which it is installed
      as PREFIX.
   
   --without-libpng
   --with-libpng=no
      Build without PNG support.
   
   Other build systems should define HAVE_LIBPNG when building OpenVRML
   with PNG support.

 * JPEG image support
   
   libjpeg is required for JPEG support in OpenVRML.  If libpng is not
   already installed on your system, you can find it at
   <http://www.ijg.org>.  The GNU build includes configuration options
   to either allow the build to locate libjpeg on your system, or build
   without JPEG support (if you don't have libjpeg or don't want JPEG
   support).  These arguments can be passed to `configure':
   
   --with-libjpeg
   --with-libjpeg=yes
      Look in the default library and include paths for libjpeg.  This
      is the default.
   
   --with-libjpeg=PREFIX
      If libjpeg is not installed in the default library and include 
      paths on your system, pass the prefix under which it is installed
      as PREFIX.
   
   --without-libjpeg
   --with-libjpeg=no
      Build without JPEG support.
   
   Other build systems should define HAVE_LIBJPEG when building OpenVRML
   with JPEG support.

 * JavaScript support
   
   SpiderMonkey (libmozjs) is required for JavaScript support in
   OpenVRML.  If SpiderMonkey is not already installed on your system,
   you can find it at <http://www.mozilla.org/js/spidermonkey/>.  The
   GNU build includes configuration options to either allow the build to
   locate libmozjs on your system, or build without JavaScript support
   (if you don't have SpiderMonkey or don't want JavaScript support).
   These arguments can be passed to `configure':
   
   --with-mozjs
   --with-mozjs=yes
      Look in the default library and include paths for libmozjs.  This
      is the default.
   
   --with-mozjs=PREFIX
      If libmozjs is not installed in the default library and include 
      paths on your system, pass the prefix under which it is installed
      as PREFIX.
   
   --without-mozjs
   --with-mozjs=no
      Build without JavaScript support.
   
   Other build systems should define HAVE_MOZJS when building
   OpenVRML with JavaScript support.


Installation
============

   Refer to the file INSTALL for detailed installation instructions.


Conformance
===========

   OpenVRML aspires to full conformance to the VRML97 specification. It
isn't there yet, but much of the spec is supported, and OpenVRML will
continue to get better.

   Detailed results of testing Lookat against the NIST VRML97 Test Suite
can be found in the file `conformance.html'.


System-specific notes
=====================

 * X11 colormap flashing on 8-bit displays

   If you are having trouble with colormap flashing on an 8-bit display,
   try restarting your X server (e.g., log out and back in in an xdm
   environment) and running "xstdcmap -default" BEFORE running anything
   else.  In fact, you might put that command in your X startup script.
   But you should really get a graphics card with 24-bit color.  Tell
   your boss I said so.

 * Compiling on Irix
   
   OpenVRML cannot currently be compiled with the SGI C++ compiler.  It
   can be compiled with gcc 2.95, but to prevent a runtime error libGLU
   must also be compiled with gcc 2.95 since gcc and the MIPSPro
   compiler have different ABIs. The source code to the SGI OpenGL
   sample implementation (which includes the GLU library) can be found
   here:
     <ftp://oss.sgi.com/projects/ogl-sample/download/>

 * Using helper applications on the Macintosh
   
   A creator code should be supplied in
   `libvrml97core/macos/LibVRML97.prefix' to enable InternetConfig to
   pass non-VRML anchors to helper applications.  The supplied prefix
   files assumes that you are building MacLookat (code vrVW).

 * Initializing VrmlScene on the Macintosh
   
   VrmlScene should be initialised with either a URL or a Unix-style
   filepath starting with "///" (instead of "/").  This is consistent
   with Mac file URLs of the form "file:///".  This means that if you
   want to open local files using a Mac file dialog then you need to
   retrieve the full path of the selected file, prepend ///, and
   replace colons with slashes before passing it to VrmlScene.


Bug reports
===========

   Please report any bugs you encounter via the SourceForge bug tracking
system:

     <http://sf.net/bugs/?group_id=7151>

   Note that you will need to log into SourceForge before reporting a
bug.


Mailing lists
=============

   Two mailing lists are maintained:

 * <openvrml-announce@sourceforge.net> is a low-traffic list for
   announcments, typically regarding new releases.  Subscription
   instructions are at
     <http://lists.sf.net/mailman/listinfo/openvrml-announce>

 * <openvrml-develop@sourceforge.net> is a forum for developers using
   and working on the libraries.  User feedback is welcome in this
   channel.  Subscription instructions are at
     <http://lists.sf.net/mailman/listinfo/openvrml-develop>


Get involved
============

   We're always grateful for help in improving OpenVRML.  Consult the
SourceForge Task Manager for a list of planned improvements:

     <http://sf.net/pm/task.php?group_project_id=2579&group_id=7151&func=browse>

   Unassigned tasks are up for grabs, but please post to the
openvrml-develop mailing list to alert others of your intention to take
a task.  This helps avoid duplicated effort.  If you do not see the task
you'd like to pursue listed in the Task Manager, but you think the
library could benefit from your contribution, post a proposal to the
openvrml-develop mailing list.


Design
======

   The very brief architecture description:

 * VrmlScene is the top-level class; a scene corresponds to reading in a
   VRML file (and all its associated data).  A VrmlScene object will
   have data members for the node type definitions (built-in and PROTOs/
   EXTERNPROTOs) and the actual nodes of the scene graph.  The variables
   are d_namespace and d_nodes, respectively.  You can pretty much
   ignore everything else in VrmlScene.

 * A VrmlNamespace is just a list of node type definitions and a list of
   node name definitions.  So if you want to find a particular named node
   in a scene, you would use the findNode method of the relevant
   namespace.  Each PROTO gets its own namespace.

 * Each built in node type has a corresponding VrmlNode* class.  PROTO'd
   node instances are represented by the VrmlNodeProto class.  Vrml
   nodes are built from the primitive field types, represented by the
   VrmlSF* and VrmlMF* (single- and multi-valued) classes.  For each
   field of each node as defined by the VRML97 spec there is a data
   member in the corresponding node class.  For example, the Group node
   has a field called children of type MFNode.  The VrmlNodeGroup class
   has a data member VrmlMFNode d_children.  There is a lot of code,
   but it is pretty easy to find what you want once you understand the
   structure.
