OpenVRML library version 0.18.99 Copyright 1998, 1999, 2000 Chris Morley cmorley@vermontel.net Copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 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.
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.
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".
/data /component : XML component definitions. /doc /manual : API documentation. /examples : Example programs. /ide-projects /Windows /VisualC9_0 : Microsoft Visual C++ 9.0 project files. /m4 : m4 macros used by the GNU build system. /models : Sample VRML models. /src /libopenvrml : Runtime library sources. /libopenvrml-gl : OpenGL renderer library sources. /mozilla-plugin : Mozilla plug-in sources. /node /vrml97 : VRML97 node implementation sources. /x3d-cad-geometry : X3D CAD Geometry component node implementation sources. /x3d-core : X3D Core component node implementation sources. /x3d-dis : X3D DIS component node implementation sources. /x3d-environmental-effects : X3D Environmental Effects component node implementation sources. /x3d-event-utilities : X3D Event Utilities component node implementation sources. /x3d-geometry2d : X3D Geometry2D component node implementation sources. /x3d-geospatial : X3D Geospatial component node implementation sources. /x3d-grouping : X3D Grouping component node implementation sources. /x3d-h-anim : X3D H-Anim component node implementation sources. /x3d-interpolation : X3D Interpolation component node implementation sources. /x3d-key-device-sensor : X3D Key Device Sensor component node implementation sources. /x3d-networking : X3D Networking component node implementation sources. /x3d-nurbs : X3D NURBS component node implementation sources. /x3d-rendering : X3D Rendering component node implementation sources. /x3d-shape : X3D Shape component node implementation sources. /x3d-texturing : X3D Texturing component node implementation sources. /openvrml-xembed : XEmbed control application sources. /openvrml-player : OpenVRML Player application sources. /script : Scripting engine module sources. /java : Script node Java API sources. /tests : Test programs.
At a minimum, OpenVRML requires these libraries to build:
Boost (at least 1.44) <http://boost.org>
libltdl (non-Windows only) <http://www.gnu.org/software/libtool/>
libxml (non-Windows only) <http://xmlsoft.org>These libraries are packaged for many systems; so you should consult your operating system vendor if any of them is not already installed on your system. Otherwise, you can obtain them at the above URIs.
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 may 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".
libltdl and libxml are not required on Microsoft Windows platforms. On Windows, OpenVRML uses the Win32 API for module loading and the XmlLite library for XML parsing. XmlLite is included with recent versions of the Microsoft Windows SDK.
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 GB of system memory; the recommended minimum for 64-bit build hosts is 2 GB.
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>
XULRunner <https://developer.mozilla.org/En/XULRunner>
Java Development Kit <http://java.sun.com/j2se/>
OpenGL/Mesa <http://mesa3d.org>
GTK+ <http://gtk.org>
GtkGLExt <http://gtkglext.sourceforge.net>
libcurl <http://curl.haxx.se/libcurl/>
D-Bus <http://www.freedesktop.org/wiki/Software/dbus>
GNOME <http://gnome.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.
OpenVRML's build configuration script accepts a number of arguments that modify what features are built and/or what packages OpenVRML depends on.
--enable-exception-specs[=yes,no,nothrow] Modulate use of C++ exception specifications. By default, OpenVRML uses exception specifications wherever the set of exceptions thrown from a function can be constrained. This can aid in debugging; but in general it is likely to degrade performance. Exception specifications can be disabled altogether (using an argument of "no" or the option "--disable-exception-specs"); or, only empty (i.e., nonthrowing) exception specifications can be enabled (using an argument of "nothrow"). Some compilers may be able to use the nonthrowing exception specification as an optimization hint. Note that changing what exception specifications are applied 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.
--disable-script-node-java Disable 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.
--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).
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_JNI_CONST Define to "const" if "const" should be used in JNI function signatures; define to empty otherwise.
Refer to the file "INSTALL" for detailed installation instructions.
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.
libopenvrml loads data files and plug-ins from known locations once it is installed. If they are defined, libopenvrml will prefer the locations specified by these environment variables:
OPENVRML_DATADIR Directory where libopenvrml looks for architecture-independent data.
OPENVRML_NODE_PATH A search path where libopenvrml looks for node implementations.
OPENVRML_SCRIPT_PATH A search path where libopenvrml looks for scripting engine implementations.
The most common use case for setting these environment variables is running sdl-viewer or openvrml-xembed from the build directories. For example, if running a Bash shell and building in a subdirectory "build" where the current directory is the root of the OpenVRML distribution:
$ OPENVRML_DATADIR=$(pwd)/data \ OPENVRML_NODE_PATH=$(pwd)/build/src/node \ OPENVRML_SCRIPT_PATH=$(pwd)/build/src/script \ ./build/examples/sdl-viewer models/rotation_toy.wrl
openvrml-xembed is installed as a D-Bus service, meaning that it can be activated on-demand by applications that need it (like openvrml-player and the Mozilla plug-in). In order for this to work, OpenVRML must be installed to the same prefix as the system's D-Bus installation.
Similarly, 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" and "model/x3d-vrml" media types 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.
To run openvrml-player or the Mozilla plug-in from the build directories, you must first start an openvrml-xembed process. Once openvrml-xembed has been installed, D-Bus will start it automatically as needed. Additionally, 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.
When running openvrml-player from the build directories, you must specify the location of the GTK+ UI XML files using the environment variable OPENVRML_PLAYER_UIDIR; e.g.:
$ OPENVRML_PLAYER_UIDIR=$(pwd)/src/openvrml-player \ ./build/src/openvrml-player/openvrml-player
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.
Please report any bugs you encounter using OpenVRML's bug tracking system:
<https://sourceforge.net/apps/trac/openvrml/newticket>Note that you will need to log into SourceForge before reporting a bug.
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 https://lists.sourceforge.net/lists/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 https://lists.sourceforge.net/lists/listinfo/openvrml-develop
In order to curb unsolicited commercial e-mail, openvrml-develop permits posting only by subscribers.
We're always grateful for help in improving OpenVRML. Consult the list of active tickets:
<https://sourceforge.net/apps/trac/openvrml/report/1>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, but you think the library could benefit from your contribution, post a proposal to the openvrml-develop mailing list.