========================================================================
README for Vrui version 1.0, build 068
Copyright (c) 1998-2010 Oliver Kreylos
========================================================================

Overview
========

Vrui is a C++ software development toolkit for highly interactive
virtual reality applications, with a focus on portability between vastly
different virtual reality environments, from laptop or desktop computers
to CAVEs and other fully immersive systems. More information about Vrui
can be found at http://idav.ucdavis.edu/~okreylos/ResDev/Vrui or
http://www.keckcaves.org.

Vrui's development was supported by the University of California, Davis,
by the UC Davis W.M. Keck Center for Active Visualization in the Earth
Sciences (KeckCAVES, http://www.keckcaves.org), the W.M Keck Foundation,
and the National Science Foundation.

Quick Installation Guide for the Impatient
==========================================

(Replace <build> by the current Vrui build number.)

0. (On MacOS X: Install required packages.)

1. Create src directory in home directory:
   > mkdir ~/src

2. Change into ~/src directory and unpack the Vrui tarball:
   > cd ~/src
   > tar xfz <download path>/Vrui-1.0-<build>.tar.gz
   - or -
   > tar xf <download path>/Vrui-1.0-<build>.tar

3. Change into Vrui base directory:
   > cd Vrui-1.0-<build>

4. Build Vrui and install it in Vrui-1.0 in home directory:
   > make install

5. If there are error messages during the build, read below.

Building and Running Vrui Example Applications
----------------------------------------------

1. Change into example application directory:
   > cd ~/src/Vrui-1.0-<build>/ExamplePrograms

2. Build example applications:
   > make

3. (On MacOS X: Start X11.)

4. Run Earth renderer:
   > ./ShowEarthModel

5. Read about Vrui's default user interface in HTML documentation in
   ~/src/Vrui-1.0/Documentation.

Detailed Installation notes
===========================

Installation is performed via the central makefile in the Vrui-1.0 base
directory. The only settings that probably need to be changed are the
installation path (where the Vrui include, library, executable, and
configuration files will be copied), the path to the C++ compiler, and
whether to build-in support for PNG and JPEG images using libpng and
libjpeg, respectively, and for spatial audio using the OpenAL API.

NOTE: It is important *not* to install Vrui into the same directory it
is built in. A typical installation would download the source tarball
into a special "source" directory, say ~/src, and extract it from there,
resulting in the sources being in ~/src/Vrui-1.0-<build>. Then Vrui can
be installed in ~/Vrui-1.0 (the default) without any problems. After
installation, the source tarball and the ~/src/Vrui-1.0-<build>
directory can in principle be deleted. Here is a diagram of the
directory structure described above:

~ (home directory)
	|
	+- src (unpack Vrui tarball from in here)
	|	|
	|	+- Vrui-1.0-<build> (package root directory, run "make" in here)
	|		|
	|		+- BuildRoot (additional make settings)
	|		|
	|		+- ExamplePrograms (Vrui example program source
	|		:  codes)
	|		:
	|		:
	|		+- d (dependency files, created by "make")
	|		|
	|		+- o (object files, created by "make")
	|		|
	|		+- lib / lib64 (library files and plug-ins,
	|		|  created by "make")
	|		|
	|		+- exe (executable files, created by "make")
	|
	+- Vrui-1.0 (created by "make install")
		|
		+- include (Vrui development header files)
		|
		+- lib / lib64 (library files and plug-ins)
		|
		+- bin (Vrui programs)
		|
		+- etc (Vrui configuration files)
		|
		+- share (font definitions, texture images, etc.)

Root Installation Directory
---------------------------

The root installation directory is set by changing the value of
INSTALLDIR at the top of the makefile. Vrui installs itself in the usual
subdirectories under the root installation directory:

- include: Contains header files for Vrui development
- lib or lib64: Contains shared libraries and Vrui plug-ins
- bin: Contains executables
- etc: Contains configuration files
- share: Contains additional files (texture fonts etc.)

If the root installation directory is set to /usr or /usr/local, Vrui
will drop right into an existing Linux installation. However, to
simplify removing a Vrui installation (there is no make uninstall yet),
it is recommended to install Vrui in its private root directory, such
as /usr/local/Vrui-1.0. If installed this way, it can be cleanly
uninstalled by simply removing the root installation directory.

During installation, Vrui creates a makefile fragment (Vrui.makeinclude)
in $(INSTALLDIR)/etc. This fragment should be included by the makefiles
of all Vrui-based projects to simplify compiling and linking. The
makefiles provided with the Vrui example applications show how this
should be done, and how it results in simple makefiles that build on any
environment with a properly installed version of Vrui.

Path to the C++ Compiler
------------------------

The compiler is selected in the file BuildRoot/SystemDefinitions. The
compiler suite's base directory is set by changing the GNUC_BASEDIR
variable. The default C++ compiler is /usr/bin/g++.

Note about g++ version 4.1.0 and greater
----------------------------------------

Starting with version 4.1.0, g++ no longer injects friend functions
defined inside a class declaration into the surrounding namespace. The
build system (BuildRoot/SystemDefinitions and BuildRoot/BasicMakefile)
contains code to detect the compiler version and add the
-ffriend-injection flag to the compiler's command line if the version
number is greater or equal 4.1.0. However, if compiling the example
programs in ExamplePrograms generates error messages about undeclared
functions, the flag -ffriend-injection needs to be manually added to the
compiler command line when building Vrui and Vrui-based applications.
The best place to add the flag is to the end of CSYSFLAGS at the
beginning of BuildRoot/SystemDefinitions before building. Alternatively,
the flag can be added to CFLAGS inside the example programs' build
directories after Vrui has been built/installed.

Machine Endianness
------------------

Vrui contains support for reading/writing binary files with automatic
endianness conversion, and sending/receiving data over TCP pipes with
automatic network endianness detection and endianness conversion. For
this to work, the OS must offer an include file that sets the #define
macros __LITTLE_ENDIAN, __BIG_ENDIAN, and __BYTE_ORDER. __BYTE_ORDER
must be equal to __LITTLE_ENDIAN on little-endian machines, and equal to
__BIG_ENDIAN on big-endian machines. The Misc/Endianness.h header file
includes the appropriate system header files for Linux and Mac OS X, but
might need to be adapted for other operating systems.

Support for PNG, JPEG, and TIFF
-------------------------------

The image handling library that is part of the Vrui toolkit supports
reading and writing image files in PNG, JPEG, and TIFF formats. These
features are based on the libpng, libjpeg, and libtiff libraries,
respectively. If the host computer does not contain either of these
libraries, support for PNG, JPEG, or TIFF images can be disabled
separately in the makefile by setting IMAGES_USE_PNG, IMAGES_USE_JPEG,
or IMAGES_USE_TIFF to 0, respectively. The Vrui makefile now contains
code to automatically detect whether libpng, libjpeg, and/or libtiff are
installed, and sets these three variables accordingly. More precisely,
the makefile looks for png.h, jpeglib.h, and tiffio.h in /usr/include
and /usr/local/include. If either library is installed in a different
directory on the host system, the makefile variables need to be set
manually, and the paths to the libraries need to be adjusted in
BuildRoot/Packages.

Vrui uses the PNG (Portable Network Graphics) image file format to save
screenshots taken from a Vrui application window using the image
handling library. If that library is not configured to support PNG
images (see above), Vrui can alternatively save screenshots in binary
PPM format. This feature is selected by setting VRUI_USE_PNG to 0 in the
makefile. At this point, the makefile is set up to use PNG files inside
Vrui if IMAGES_USE_PNG is set to 1.

Support for OpenAL
------------------

Vrui contains experimental support for spatial audio using the OpenAL
sound API. Since OpenAL is not yet widely used, this support can be
disabled in the makefile, removing dependency on the OpenAL header files
and libraries. To disable OpenAL support, the value of the
VRUI_USE_OPENAL variable is set to 0. The Vrui makefile now contains
code to automatically detect whether OpenAL is installed on the host
system by looking for AL/al.h in /usr/include and /usr/local/include. If
OpenAL is installed elsewhere, the VRUI_USE_OPENAL makefile variable
needs to be set manually, and the paths to OpenAL need to be adjusted in
BuildRoot/Packages.

Support for shared-memory multi-pipe rendering systems
------------------------------------------------------

As of version 1.0-035, Vrui contains an (experimental) mechanism to
optimally run on shared-memory multi-pipe rendering systems such as
SGI Onyx or Prism, or newer multi-CPU computers with multiple graphics
cards. Support for multithreaded rendering is enabled by setting
GLSUPPORT_USE_TLS to 1 in the makefile. Since this somewhat impacts
rendering performance, it is recommended to only enable multithreaded
support if (one of) the target VR environments requires it.

If the host compiler and run-time environment do not support a __thread
storage class for thread-local storage, SYSTEM_HAVE_TLS in
BuildRoot/SystemDefinitions must be set to 0 to fall back to POSIX
thread-local storage.

Building and Installing Vrui
============================

The easiest way to install Vrui is to cd to the Vrui-1.0-<build> root
directory, and type make install. If the root installation directory
(see above) is a system directory, make install has to be run as root.
In that case, it is safer to first run make (which will build in the
current directory) as a non-root user, and afterwards become root and
run make install.

Source-specific settings
------------------------

Vrui contains a few settings that might need to be adapted due to
different operating system or OpenGL versions. The settings that
typically cause trouble can be changed from within the main makefile
(they are listed in a section towards the beginning). If Vrui fails to
build with compiler errors, that is the first place to look. The
makefile lists which sources cause trouble, and how to address them.

Building debug version
----------------------

The Vrui libraries and executables are by default built without
debugging information and with full optimization (-O3). It is possible
to build Vrui with full debugging information and without optimization
by defining the DEBUG variable in the makefile. The easiest way to
achieve this is to pass DEBUG=1 on the make command line, i.e., to type
"make DEBUG=1 install" or "make DEBUG=1" followed by
"make DEBUG=1 install". Vrui is set up such that debug and non-debug
versions can coexist in the same installation directory. To build
applications with either version, the appropriate Vrui makefile fragment
has to be included in the makefile.
- For non-debug Vrui:
  include $(VRUIDIR)/etc/Vrui.makeinclude
- For debug Vrui:
  include $(VRUIDIR)/etc/Vrui.debug.makeinclude

To make full use of the debugger, the Vrui application itself needs to
be compiled/linked with debugging information as usual. The easiest way
to achieve this is to add the appropriate flags to VRUI_CFLAGS, as in
VRUI_CFLAGS += -g2 -O0, or to use makefiles similar to the ones used by
the example applications (see below).

Building Example Vrui Applications
==================================

The ExamplePrograms directory in the Vrui-1.0-<build> base directory
contains several small example programs, and two larger applications in
their own directories (MeshEditor and VRMLViewer).

ExamplePrograms contains several very simple Vrui applications to show
the basic development approach, and ShowEarthModel, one "realistic"
application to visualize global earthquake distributions.
MeshEditor contains a prototypical and fairly complex VR surface editing
application, and VRMLViewer contains a stand-alone viewer for simple
VRML files (it does not support VRML's full specification) that mostly
serves as an example of how higher-level scene graph functionality can
be layered on top of the Vrui API.

All applications can be built by running make in their respective
directories. If Vrui was not installed in its default location
(~/Vrui-1.0), the VRUIDIR variable at the top of each makefile needs to
be changed.

The example application makefiles show how to create debug/release
versions without changing the makefile by respecting the DEBUG make
command line argument ("make DEBUG=1") in the same way as the toolkit
build itself. The application makefiles do not allow coexisting targets;
changing between debug and release mode requires a "make clean".

Running Vrui Applications
=========================

Vrui applications are started in the usual fashion, by typing the
executable name from the directory containing the executable, and
providing any required command line parameters. Vrui applications will
configure themselves to the machine they are running on by reading an
appropriate root section in the Vrui.cfg configuration file in the
installation's etc directory. The root section is determined by the
following cascade:

1. By default, Vrui reads the section that has the same name as the
   local machine (as reported by hostname).

2. If an environment variable VRUI_ROOTSECTION exists, Vrui will use its
   value as the root section

3. If an application's command line contains the arguments
   -rootSection <section name>, Vrui will use <section name> as the root
   section.

4. If the root section selected by the above cascade does not exist in
   the configuration file, Vrui will fall back to the root section
   compiled into the library (defaults to Simulator).

The HTML pages in the Documentation directory contain additional
information about configuring, running, and using Vrui applications.