OpenVRML library version 0.17.5
Copyright 1998, 1999, 2000 Chris Morley <cmorley@vermontel.net>
Copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
   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 toolkit including a C++ library for reading
and displaying VRML and X3D files, an OpenGL renderer, and a Mozilla
Web browser plug-in for viewing VRML and X3D content on the Internet.


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

   The OpenVRML libraries comprising the VRML/X3D runtime ("libopenvrml")
and the OpenGL renderer ("libopenvrml-gl") are available under the terms
of the GNU Lesser General Public License (LGPL), version 3.  These
libraries incorporate some code that is available under "LGPL-
compatible" licenses, which effectively means that the OpenVRML
libraries are Free Software which may be used collectively according to
the terms of the LGPL.  The full text of the LGPL can be found in the
file "COPYING.LESSER".  Code used in these libraries under other terms
(and available for reuse under the same terms) is as follows:

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

   The XEmbed control, OpenVRML Player, and the Mozilla plug-in as
well as the included example programs are available under the terms of
the GNU General Public License (GPL), version 3.  The full text of the
GPL can be found in the file "COPYING".


Package directory layout
========================
   /doc
     /manual            :  API documentation.
   /examples            :  Example programs.
   /ide-projects
     /Windows
       /VisualC9_0      :  Microsoft Visual C++ 9.0 project files.
   /java                :  Java sources.
   /lib                 :  3rd party library sources.
   /m4                  :  m4 macros used by the GNU build system.
   /models              :  Sample VRML models.
   /mozilla-plugin      :  Mozilla plug-in sources.
   /src
     /libopenvrml       :  Runtime library sources.
     /libopenvrml-gl    :  OpenGL renderer library sources.
     /openvrml-xembed   :  XEmbed control application sources.
     /openvrml-player   :  OpenVRML Player application sources.
   /tests               :  Test programs.


Prerequisites
=============

   OpenVRML requires the Boost C++ libraries to build.  Boost is
packaged for many systems; so you should consult your operating system
vendor if Boost is not already installed on your system.  Otherwise, you
can obtain Boost from <http://boost.org>.

   Note that Boost binaries built from the boost.org distribution, as
well as some other distributions, apply a suffix to the library
name that depends on the particular build configuration.  When
building OpenVRML with such binaries it will be necessary to set the
variable BOOST_LIB_SUFFIX to match the suffix applied to the Boost
binaries; refer to the output of "configure --help".

   Building OpenVRML is fairly demanding of system resources;
especially, it seems, with modern versions of the GNU C++ compiler.  It
is recommended that 32-bit build hosts have at least 1.5 GB of system
memory; the recommended minimum for 64-bit build hosts is 3 GB.


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

   OpenVRML has several optional dependencies.  If your system is
missing any of these dependencies, first check to see if they are
provided by your operating system vendor.  If not, consult the URIs
below.

     libpng                 <http://www.libpng.org/pub/png/libpng.html>
     libjpeg                <http://www.ijg.org>
     FreeType               <http://freetype.org>
     Fontconfig             <http://fontconfig.org>
     Mozilla                <http://mozilla.org>
     Java Development Kit   <http://java.sun.com/j2se/>
     OpenGL/Mesa            <http://mesa3d.org>
     GTK+                   <http://gtk.org>
     SDL                    <http://libsdl.org>
     Doxygen                <http://doxygen.org>

   OpenVRML can be built with reduced functionality which can avoid
these dependencies.  See the following section, "'configure' options",
for details.


"configure" options
===================

   OpenVRML's build configuration script accepts a number of arguments
that modify what features are built and/or what packages OpenVRML
depends on.

 --disable-exception-specs
     Disable use of C++ exception specifications.  This is likely to
     improve performance.  Note that this changes the library ABI.

 --enable-gecko-rpath
     Enable use of the Gecko runtime library directory -rpath flag.  On
     many systems, the directory where libmozjs.so and other Gecko
     runtime libraries reside is not a path known to the dynamic linker.
     In such cases, applying an -rpath to executables is frequently a
     desirable alternative to setting LD_RUN_PATH before running them.

 --disable-png-textures
     Disable support for rendering PNG images as textures.  OpenVRML
     uses libpng to read PNG images.

 --disable-jpeg-textures
     Disable support for rendering JPEG images as textures.  OpenVRML
     uses libjpeg to read JPEG images.

 --disable-render-text-node
     Disable support for rendering Text nodes.  The node is still
     parsed, and events to and from it are processed; but no text is
     rendered.  By default OpenVRML uses Fontconfig for font discovery
     and FreeType to get font data.

 --disable-script-node-javascript
     Disable support for JavaScript in the Script node.  By default,
     OpenVRML uses the Mozilla JavaScript library to execute JavaScript.

 --enable-script-node-java
     Enable support for Java in the Script node.  "configure" searches
     for a Java Native Interface (JNI) implementation, which may be
     provided either by a Java Development Kit or the GNU Compiler for
     Java (gcj).  If using a Java Development Kit, you will probably
     need to supply the include and library directories using CPPFLAGS
     and LDFLAGS, respectively.  See the file INSTALL for general
     information on using these variables.

     NOTE: This option is not supported in this release of OpenVRML.
     (Don't even bother trying; the code simply does not build.) Java
     scripting support will reappear in a future release of OpenVRML.

 --disable-gl-renderer
     Do not build the GL renderer.  OpenVRML's GL renderer depends on
     OpenGL/Mesa.

 --disable-xembed
     Do not build the XEmbed control.  This is an out-of-process
     component that provides a VRML/X3D browser that can be used in an
     XEmbed container.  This depends on GTK+.  It also requires that
     the GL renderer be built.

 --disable-player
     Do not build openvrml-player.  This is a GNOME application that
     hosts the XEmbed control.  It depends on GNOME (libgnomeui) and
     libcurl.

 --disable-mozilla-plugin
     Do not build the Mozilla plug-in.  The Mozilla plug-in depends on
     GTK+ and, of course, a Mozilla-based browser.  It also requires
     that the XEmbed control be built.

 --disable-examples
     Do not build the example programs.  The example programs depend on
     SDL.

 --with-x
     Passing the argument "--without-x" to "configure" will allow
     OpenVRML to be built without depending on the X Windowing System.
     This option is really only useful when building OpenVRML on
     platforms where X is available alongside another windowing system
     (e.g., Cygwin or Mac OS X with X installed).

 --with-libjs
     Use the stand-alone SpiderMonkey distribution.  By default,
     "configure" looks for SpiderMonkey as it is distributed with a
     Mozilla Gecko-based Web browser (i.e., libmozjs).  Passing the
     argument "--with-libjs" causes "configure" to look instead for the
     stand-alone distribution of SpiderMonkey (i.e., libjs).


Significant preprocessor symbols
================================

   Certain code in OpenVRML is compiled conditionally depending on what
symbols have been defined for the preprocessor.  The "configure" script
will add the appropriate compiler and preprocessor flags for you; in
general you should use the options to "configure" documented in the
previous section rather than define these symbols in CPPFLAGS.  These
symbols are documented here primarily for the benefit of persons trying
to compile OpenVRML without the GNU build tools.

 OPENVRML_ENABLE_PNG_TEXTURES
     Include support for rendering PNG images as textures.  Requires
     libpng.

 OPENVRML_ENABLE_JPEG_TEXTURES
     Include support for rendering JPEG images as textures.  Requires
     libjpeg.

 OPENVRML_ENABLE_RENDER_TEXT_NODE
     Include support for rendering text using the Text node.  Requires
     fontconfig and FreeType.

 OPENVRML_ENABLE_SCRIPT_NODE_JAVASCRIPT
     Include support for JavaScript scripts in the Script node.
     Requires Mozilla SpiderMonkey.

 OPENVRML_ENABLE_SCRIPT_NODE_JAVA
     Include support for Java scripts in the Script node.  Requires the
     Sun Java Development Kit.


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

   Refer to the file "INSTALL" for detailed installation instructions.


Usage
=====

   To write programs that use the OpenVRML libraries, refer to the API
documentation in the "doc/manual" subdirectory of the distribution and
the example programs in the "examples" subdirectory.

   If OpenVRML is configured to be installed to the same prefix as a
Mozilla-based browser is installed on the system, "make install" will
install the Mozilla plug-in to the browser's plug-in directory.  This
should be sufficient to enable support for the "model/vrml" media type
in the browser.  Entering "about:plugins" in the URL entry bar of a
Mozilla-based browser will show a listing of successfully installed
plug-ins.

   It is possible, for testing or other convenience, to run the
plug-in from the build directories.  A symbolic link to the plug-in
module "openvrml.so" must be made in the Mozilla plug-in directory and
the environment variable "OPENVRML_XEMBED" must be set to the full
path name of the "openvrml-xembed" executable.


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.


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@lists.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@lists.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>

      In order to curb unsolicited commercial e-mail, openvrml-develop
   permits posting only by subscribers.

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.