The FreeWRL FAQ

Table of contents

1 Introduction

1.1 Conformance

FreeWRL is able to read and display most VRML2.0, VRML97, and X3D files encoded in "Classic" or "XML" encoded X3D files.

FreeWRL has passed the Web3D Consortium for testing to X3D "Interchange Profile" compliance - the first browser (commercial, or open source) to submit.

FreeWRL Will be compliant to most of the X3D Profiles - the main developers of FreeWRL are employed by the Canadian Government in a Federal Research Centre, and use FreeWRL in research. So our goal for FreeWRL is to have it become an implementation for X3D, not to develop FreeWRL for sale or as a tool for bundling within other products. We use FreeWRL for our research projects, and make it available for free, under the GPL License, for your use.

how can I help? Tell us what you use FreeWRL for! It helps us in our internal funding and planning cycle to know how FreeWRL is used- for certain kinds of research, for industrial design, or for whatever.

We are always looking for coding help, but realize that FreeWRL (and any project of this magnitude) is difficult for people to jump in to. Giving us a pat on the back helps; telling us what FreeWRL is used for helps; submitting bugs helps.

1.2 Maintainer

FreeWRL is written and maintained by a group of people headed by John Stewart of the Communications Research Centre in Ottawa, Canada.

John Stewart can be reached at: freewrl-06 -at- rogers.com.

1.3 Version

Current revision of this FAQ is 1.9, 30 June 2008.

1.4 Mailing list

There is a mailing list about FreeWRL. This is a closed list, so you must be on the list to send mail to it. (this is an anti-spam measure). The address is freewrl@crc.ca . To subscribe to this list, send an email to freewrl-join@crc.ca. The subject and contents of the message do not matter; you should get a reply to the request in a few minutes.

For more information on the mailing list interface, look at the GNU Mailman web page.

1.5 Contributions

Many people have contributed to FreeWRL over the years. Have a look through the code - we try to include submitters names in comments where possible.

We are always looking for coding help, but realize that FreeWRL (and any project of this magnitude) is difficult for people to jump in to. Giving us a pat on the back helps; telling us what FreeWRL is used for helps; submitting bugs helps. Contributors are always welcome. We can always do with people helping with all areas from documentation to in-depth coding.

John Stewart can be reached at: freewrl-06 -at- rogers.com.

2 Installing Freewrl On Linux and other Unix machines.

This section attempts to answer questions about installs on Linux and other computers.

First, get FreeWRL. The Download page has links to some binary distributions, and to the latest release version of the source code.

Choose one that fits your operating system, and download it.

If you are installing from the "tar" source, the general methodology is to:

• untar the source; (eg: gunzip freewrl-zz.tar.gz; tar -xf freewrl-zz.tar)
• go into the top level directory; (eg, cd freewrl-zz)
• type "perl Makefile.PL"
• type "make install"

and that should compile and install the source. There are some specific Linux distribution notes in section 2.1, below.

If the package is an RPM: rpm -Uvh after downloading.

If the package is for Gentoo, Debian, etc, you'll have to use the specific installer for your distro.

If you have FreeWRL running, and are experiencing problems only on a few worlds, please refer to the operating system independent section 6. FreeWRL Q and A (assumes FreeWRL installed)

2.1 Hints on installing from Source

1. What if I don't have root privileges? Have a look at the runme-standalone csh script file in the FreeWRL build directory. It may not be perfect; if you improve it, please send along the changes to help the next person.

2. What packages do I require? This depends on what you have on your system already. The build process will tell you when things go wrong, of course!

   Here are notes on installing on Ubuntu Dapper; Fedora Core 5; Suse 10.1; Suse 10.1 RC3 on X86_64;

   In general, people have reported that:

   • /usr/include/GL Check for this directory, and check that it is not empty. It should have at least "gl.h" in it. If this directory is empty, install "devel" packages; on Debian you might have to install "xlibmesa-gl" and "libgl1-mesa-glx".

   • javac - the Java Compiler You can build without javac, (look in vrml.conf or vrml.conf.x86_64 and comment out the "JAVA") but it may be best to keep the build as complete as possible. To see if javac is in your path, type the command "which javac" to see if it is installed. If not, go through your RPMS and look for "java devel" and/or "gcj-java" packages. Which package contains the java compiler seems to be release dependent.

   • Motif - libXm Motif is used by FreeWRL by default. Motif (or one of the equivalents) is recommended to enable to building and running FreeWRL. Anything that simulates the Motif widget set should do - FreeWRL does not do anything really complex with widgets. As root, "ldconfig -p | grep libXm" will show you which (if any) Motif libs are installed.

     If you do not have Motif you can edit the vrml.conf.linux (or vrml.conf.x86_64) and follow the comments for Motif in this file. (then, perl Makefile.PL; make install...). However, Motif does make the whole environment much nicer.

2.2 Hints on installing from a binary distribution

1. Can I use an rpm or debian file built for Linux release X on my Linux release Y box?

   yes, but you might have to install different versions of libraries - eg, different versions of the PNG library.

   if you install, and see errors like:

   Unpacking freewrl (from freewrl_1.19.8_amd64.deb) ...
   dpkg: dependency problems prevent configuration of freewrl:
     freewrl depends on libc6 (>= 2.5-0ubuntu1); however:
     Version of libc6 on system is 2.3.6.ds1-13etch2.
   

   it means that a library on your system is older than required. (2.5 > 2.3). You have a couple of choices:
   • go through the download section and try older binary distros;
   • compile from source;
   • and/or upgrade the required libraries on your system.

2.3 Problems running FreeWRL standalone

Running FreeWRL standalone is the best way to see what is happening with your world.

1. FreeWRL displays error messages, and crashes, or just flakes out

   Nothing is perfect. Can you tell from the error message what the problem is? Can you simplify your world to show the bug in a simple file?

   Possibly you have stumbled across a known bug, possibly a new one. Please check out the bugs database at http://sourceforge.net/projects/freewrl and feel free to submit a bug report.

2. I get the message "GLUT: Fatal Error in FreeWRL: OpenGL GLX extension not supported by display: :0.0"

   This is an OpenGL problem, not a FreeWRL problem. IIRC, you have to comment out the "Load dri" line of your X Configuration file, if you are running an NVidia accellerated graphics card and driver. But, please check the net via Google to find out for sure.

3. I have an Nvidia graphics card, and is FreeWRL ever slow!

   Make sure you are running in hardware accellerated mode. The "About FreeWRL" button will show you what the graphics driver is. Alternatively, typing "glxinfo | grep rendering" should result in a line saying "direct rendering: Yes". If not, then you need to work on your OpenGL driver install.

   We are always working on rendering speed improvements in FreeWRL; we (like you) require a fast VRML/X3D browser for our work.

2.4 Problems running FreeWRL in a Browser

NOTE: Browser Plugin code works in i386 machines so far...

1. Is the Plugin installed?

   After installing FreeWRL, restart your browser. The file "npfreewrl.so" is the FreeWRL Plugin; it should reside in a directory where your browser can find it.

   To verify if you have the plugin code in the correct place, type "about:plugins" in the Browser location box. It should show something very similar to:

   

   If you do not see FreeWRL in this list, you need to find out how to get your Browser to recognize the npfreewrl.so file - it can be as simple as clicking on a "search for plugins" button, or it can be to simply copy the npfreewrl.so file to a directory in the browser search path.

2. Can you run FreeWRL standalone?

   Try a simple test. Download the file (right-click on the following link) http://freewrl.sourceforge.net/test.wrl. to your local disc, and try running freewrl with it. For instance, if you download it to the file "test.wrl", open a terminal window, and type "freewrl test.wrl". You should see the FreeWRL Window appear.

   If you can not run FreeWRL standalone, please refer to section 2.3 Problems running FreeWRL standalone

3. Can you run this test?

   Click on this link: http://freewrl.sourceforge.net/test.wrl. and you should have a window like the following:

   

   If you can't, and the above two tests work, please contact the FreeWRL development team.

4. But your complex world still does not run...

   Then please try downloading it, and running standalone. There are more error messages printed than there are when running within a browser.

   If you have encountered a bug please contact the FreeWRL development team and tell us as much as you can about it.

3. Installing FreeWRL on Apple OS X

FreeWRL is a "Universal Binary" meaning that it runs natively on Intel and G4 processors.

I have broken down the install into quite a few steps; it is not as complicated as it may seem.

Find your Administrator password from wherever you wrote it when you first started your OSX computer, and:

• Download the "dmg" file from the OSX section of the Download page;
• Double click the "dmg" file from within the Finder - it should be on the Desktop;
• In the "dmg" window, double click on the brownish open box icon and follow the installer prompts.

Now, for using FreeWRL with Safari:

• Quit Safari, and restart it. When Safari is running, look at the "Help" -> "Installed Plugins", scroll down and you should see FreeWRL in there.
• Alternatively, click here and you should see a grey cone.
• Note: FreeWRL will try and "speak" errors (either with the input files, or with FreeWRL's interpretation of them), so listen to the sound output. The text of the messages can be found in the OSX "Console" (in the Finder, "Applications" -> "Utilities" ->"Console")

And, to use FreeWRL with the Finder (to double click a file):

• Down load the test file in Safari, by doing a holding down the control key, and clicking the mouse here. Choose "Saved Linked file to the Desktop".
• In the finder, go to the Desktop; single click the "test.wrl" file to highlight it.
• Then click on the apple key and the I key at the same time. A window titled "test.wrl Info" will appear.
• Go to the Open With: section, and find the "Applications" "FreeWRL" "FreeWRL Icon", select this, and then click "Add".
• click the "Change All" button.

To put FreeWRL in the dock:

• You will find the FreeWRL directory in the Applications folder; open the FreeWRL directory, and drag the FreeWRL icon to your Dock.

If you have FreeWRL running, and are experiencing problems only on a few worlds, please refer to the operating system independent section 6. FreeWRL Q and A

4. Installing FreeWRL on other Operating Systems

This section attempts to answer questions about installs on non-linux and non-OSX computers.

If you have FreeWRL running, and are experiencing problems only on a few worlds, please refer to the operating system independent section 6. FreeWRL Q and A

5. MIDI and Propellerheads Reason integration.

We are integrating FreeWRL with MIDI, and with Propellerheads' Reason software. Click here for our web pages describing this work.

6. FreeWRL Q and A.

99.9% of FreeWRL is common between Operating Systems; thus, if you have a problem or question on running a specific vrml/x3d file or on FreeWRL in general, you should be reading this section. We assume that you have successfully installed FreeWRL; if not, please refer to one of the Installing sections above.

But my complex world still does not run...

If it is a world on a web site, lease try downloading it, and running standalone. There are more error messages printed than there are when running within a browser.

If you have encountered a bug please contact the FreeWRL development team and tell us as much as you can about it.

Here is a list of common problems and some solutions:

1. Tailoring of FreeWRL

   large worlds can seriously affect the operations of your computer, especially ones with minimal memory or with graphics chips that do not support hardware transform and lighting. To this end, one can minimize texture size when running standalone by clicking on the pull down menu "texture size" for a smaller texture. alternatively, you can also use the environment variables shown in the next paragraph.

   If you are running from within an HTML browser (Netscape and equivalents on Linux, and Safari on OSX) you can change "shell environment variables" before starting either the HTML browser, or FreeWRL. There are different ways of doing this, but one way is to type "export xx=1" in a terminal window before starting the browser/FreeWRL, where "xx" is one of the following environment variables:

   1. FREEWRL_NO_GL_ARB_OCCLUSION_QUERY stops FreeWRL from trying to use the graphics processor for pruning geometry. This can speed up rendering under certain conditions, that are entirely dependent on your computers' hardware and OpenGL library implementation.

   2. FREEWRL_256x256_TEXTURES limits textures from the system texture size (generally 1024x1024 to 2048x2048) to increase loading and rendering of texture-rich worlds.

   3. FREEWRL_512x512_TEXTURES limits textures from the system texture size (generally 1024x1024 to 2048x2048) to increase loading and rendering of texture-rich worlds - like the one above, but not so drastic.

   4. BROWSER tells FreeWRL what browser to invoke when an Anchor is required to load an HTML page.

   5. FREEWRL_DO_PLUGIN_PRINT is a diagnostic tool that helps us see what is going on with FreeWRL-HTML browser interactions.

2. Why is the freewrl window completely black?

   Is lighting turned on? (try turning on the headlight, the "h" key toggles this)

   Are you trying to run a VRML 1.0 world? (check the first line of the file)

AUTHOR

This project is managed by John Stewart.

Please send bug reports to freewrl-06 --at-- rogers.com including the word ``freewrl'' on the subject line will make sure that I'll notice it. Also, see the FreeWRL home page at http://www.crc.ca/FreeWRL.

There is absolutely no warranty, express or implied for this software. For details on the conditions of use, see the FreeWRL distribution.

FreeWRL is Copyright (C) 1998, 1999...2005 Tuomas J. Lukka, John Stewart and others.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA