OpenVRML library version 0.12.3
Copyright (C) 1998, 1999, 2000 Chris Morley <cmorley@vermontel.net>
Copyright (C) 2000, 2001, 2002 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.


Optional dependencies
=====================

Most of OpenVRML's dependencies are optional; OpenVRML can be built
without these dependencies with reduced functionality.  Note that if
you have installed any of these libraries to a non-standard location on
your system, you may need to add arguments to the CPPFLAGS and LDFLAGS
variables when running `configure'. See INSTALL for details.

Most of OpenVRML's dependencies are either commonplace or easy to obtain
for POSIX systems.  Windows and Macintosh users may encounter additional
difficulty compiling some of these dependencies, so compiled versions
are provided for convenience:
     <http://openvrml.org/dist/macos_required_libs.sit>
     <http://openvrml.org/dist/win32_required_libs.zip>

 * ANTLR

   OpenVRML's parser uses the ANTLR parser generator.  The OpenVRML
   distribution includes libantlr, the runtime library for ANTLR
   parsers, along with the ANTLR-generated sources.  Most users will not
   need to install ANTLR in order to compile and use OpenVRML; however,
   ANTLR is required to regenerate the parser sources if you wish to
   modify the parser.  ANTLR can be obtained from <http://antlr.org>.

 * zlib

   OpenVRML uses zlib for reading gzipped VRML worlds.  If your system
   does not include zlib, you can obtain it from
   <http://www.gzip.org/zlib/index.html>.  The GNU build includes
   configuration options to allow the build either to locate zlib on
   your system, or to build OpenVRML without support for gzipped worlds.
   These arguments can be passed to "configure":
   
   --with-zlib
   --with-zlib=yes
      Attempt to locate and build using zlib.  This is the default.
   
   --without-zlib
   --with-zlib=no
      Build without zlib.  OpenVRML will not be able to read gzipped
      worlds.
   
   Other build systems should define OPENVRML_HAVE_ZLIB when building
   OpenVRML with zlib.

 * OpenGL/Mesa

   In addition to the core runtime, OpenVRML includes an OpenGL
   renderer.  If your system does not include OpenGL or an OpenGL-
   compatible implementation, you can find such an implementation at
   <http://mesa3d.org>.  The GNU build includes configuration options to
   allow the build either to locate an OpenGL implementation on your
   system, or to build only the core runtime without the GL renderer and
   LookAt.  These arguments can be passed to "configure":
   
   --with-gl
   --with-gl=yes
      Attempt to locate and build using OpenGL/Mesa.  This is the default.
   
   --without-gl
   --with-gl=no
      Build without OpenGL/Mesa.  Only the core runtime will be built.
   
   Other build systems should define OPENVRML_HAVE_GL when building
   OpenVRML with OpenGL/Mesa.

 * GLUT

   OpenVRML uses GLUT to render Text nodes, and in LookAt.  If GLUT is
   not present on your system, it can be found at
   <http://opengl.org/developers/documentation/glut/index.html>.  The
   GNU build includes configuration options to allow the build either to
   locate GLUT on your system, or to build OpenVRML without Text node
   support and without building LookAt.  These arguments can be passed
   to "configure":
   
   --with-glut
   --with-glut=yes
      Attempt to locate and build using GLUT.  This is the default.
   
   --without-glut
   --with-glut=no
      Build without GLUT.  OpenVRML will not include Text node support,
      and LookAt will not be built.
   
   Other build systems should define OPENVRML_HAVE_GLUT when building
   OpenVRML with GLUT.

 * libpng
   
   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 allow the build either to locate libpng on
   your system, or to 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
      Attempt to locate and build using libpng.  This is the default.
   
   --without-libpng
   --with-libpng=no
      Build without PNG support.
   
   Other build systems should define OPENVRML_HAVE_LIBPNG when building
   OpenVRML with libpng.

 * libjpeg
   
   libjpeg is required for JPEG support in OpenVRML.  If libjpeg 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
      Attempt to locate and build using libjpeg.  This is the default.
   
   --without-libjpeg
   --with-libjpeg=no
      Build without JPEG support.
   
   Other build systems should define OPENVRML_HAVE_LIBJPEG when building
   OpenVRML with libjpeg.

 * SpiderMonkey
   
   SpiderMonkey (the Mozilla JavaScript engine) 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 allow the build either to locate
   SpiderMonkey 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-spidermonkey
   --with-spidermonkey=yes
      Attempt to locate and build using SpiderMonkey.  This is the
      default.
   
   --without-spidermonkey
   --with-spidermonkey=no
      Build without JavaScript support.
   
   Other build systems should define OPENVRML_HAVE_SPIDERMONKEY when
   building OpenVRML with SpiderMonkey.

 * Sun Java Development Kit
   
   OpenVRML uses the Java Development Kit to provide Java support.
   These libraries and headers are provided by the Java Development Kit.
   If the JDK is not already installed on your system, you can find it
   at <http://java.sun.com/j2se/>.  The GNU build includes configuration
   options to allow the build either to locate the JDK on your system,
   or build without Java support (if you don't have the JDK or don't
   want Java support). These arguments can be passed to "configure":
   
   --with-jdk
   --with-jdk=yes
      Attempt to locate and build using the Java Development Kit.  This
      is the default.
   
   --without-jdk
   --with-jdk=no
      Build without Java support.
   
   configure will use the JAVA_HOME variable to attempt to locate the
   JDK.  If this variable is not set, you may need to add arguments to
   the CPPFLAGS and LDFLAGS variables.  Other build systems should
   define OPENVRML_HAVE_JNI when building OpenVRML with the JDK.

 * Doxygen

   OpenVRML uses Doxygen to build API documentation.  If Doxygen is not
   already installed on your system, you can find it at
   <http://doxygen.org>.  These arguments can be passed to "configure":
   
   --with-doxygen
   --with-doxygen=yes
      Attempt to locate and build using Doxygen. This is the default.
   
   --without-doxygen
   --with-doxygen=no
      Do not build API documentation.


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.


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.

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