===========================================================================
INSTALL for 3Dwm -- http://www.3dwm.org

Copyright (c) 2000, 2001 Niklas Elmqvist. All rights reserved.
Copyright (c) 2001 Steve Houston. All rights reserved.

File created 2000-08-11 by Niklas Elmqvist <elm@3dwm.org>.

File History:
2001-08-28	Added "Running the 3Dwm clock", updates for version 0.3.1.
2001-08-16	Updates for version 0.3.0.
2001-07-16	Updated in preparation for 3Dwm version 0.3.0.
2001-06-10	Updated for new build environment.
2001-06-09	Added "Configuring OmniORB" section. Added png and SDL deps.
2000-11-03	Updates for 3Dwm version 0.2.2.
2000-08-11	File created for 3Dwm version 0.2.

===========================================================================

General information
-------------------

Please see the README file in this directory for general information
on 3Dwm.


Quick start
-----------

Perform the following checklist and you should get 3Dwm running in a
matter of minutes (minus a certain amount of compilation time, of
course). Less experienced users will find in-depth instructions
further on in this file.

 1. Install dependencies.

 2. Untar 3Dwm, configure and compile it.
	$ configure
	$make

 3. (Optional) Install 3Dwm (not recommended at this time).
	$ make install

 4. Copy config file etc/tdwmrc to ~/.tdwmrc and edit it to suit your
    options (primarily the path to the etc/default.zorn file).
	$ cp etc/tdwmrc ~/.tdwmrc
	$vi ~/.tdwmrc

 5. Start the display server.
	$ cd server
	$ ./tdwm-server

 6. Run some 3Dwm clients. Install the 3dwm-data.tar.gz file for
    sample 3D models and textures.
	$ cd clients/geoclient
	$ ./geoclient office.3ds


Dependencies
------------

A project of 3Dwm's size naturally depends on a lot of other projects.
There is no point in reinventing the wheel over and over again.
Therefore, you will need to download and install a number of packages
on your system (if they are not already).

Here follows a list of required packages (including a minimum version 
number where applicable):

 - An OpenGL 1.1 implementation -- Mesa3D is a good alternative to
   commercial implementations.
	http://www.mesa3d.org
 
 - omniORB 3.0 -- A C++ ORB (Object Request Broker). Includes an
   IDL-to-C++ compiler, ORB libs, and a name service.
	http://www.uk.research.att.com/omniORB/

 - MeshIO 0.2 -- a 3D file I/O library. 
	http://www.3dwm.org/html/development_download.html

 - g++, the GNU C++ compiler, version 2.95 or later. Beware the "2.96"
   compiler that comes bundled with RedHat 7. 3Dwm *should* compile
   under gcc 3.0, but no work has been done on testing the system
   under that compiler (there are currently some issues with omniORB
   and gcc3.0).
	http://gcc.gnu.org

 - GNU Make, Autoconf, Automake, Libtool and bintools. Note that some
   people have experienced problems building 3Dwm using new versions
   of Automake/Autoconf/Libtool. Automake 1.4, Autoconf 2.13, and
   Libtool 1.3.5 are confirmed to work.
	http://www.gnu.org

 - A VNC server (if you want to use the 3Dwm 'vncclient'). Please note
   that this server doesn't have to be installed on the same host as
   3Dwm as long as the two computers are on the same network.
	http://www.uk.research.att.com/vnc/

 - libpng -- png image format decoding library.
	http://www.libpng.org/pub/png/libpng.html

 - SDL 1.2 -- cross platform multimedia library. Note the version
   number! 3Dwm will not work properly in the framebuffer console with
   pre-1.2 versions of SDL.
	http://www.libsdl.org

 - Expat -- an XML parser library used by the display server to load
   the 3Dwm XML configuration files. Expat is bundled with most
   Linux distributions.
       http://expat.sourceforge.net


Supported Platforms
-------------------

3Dwm has been confirmed to run on the following platforms:

 - Linux 2.x (x86)
 - SGI Irix 6.x (not recently tested)

The system should be _fairly_ easy to port to new platforms given
standard POSIX threads and a decent C++ compiler with template and
exception support. Anyone willing to do so is welcome to get in touch
with us.


Compiling
---------

If you have trouble getting 3Dwm to compile, subscribe to the 3Dwm
help mailing list and ask your question there (or mail us directly at
3dwm@3dwm.org).

If you downloaded the source from CVS, please refer to
README.build_from_cvs for directions on how to bootstrap your source
tree.

1. Download and install the 3Dwm dependencies as listed above. Make
   sure that the required libraries reside in places that can be found
   by the compiler and the run-time linker. The MeshIO lib file could
   for example be copied into the /usr/local/lib/ directory.

   Ensure that the omniORB name service (omniNames) is running and
   properly configured, refer to the section "Configuring OmniORB" in
   this file if necessary. Make sure that the omniORB examples in
   omni/src/examples (in the omniORB source tree, that is) work.

2. Ungzip and untar the source tarball into a suitable directory.
   This directory will be refered to as "srcdir" from here on.

3. Download the data tarball, 3dwm-data.tar.gz, unzip and untar into a
   suitable directory. This will be refered to "datadir" from here on.

4. We recommend that 3dwm be built into a seperate directory from the
   source. We use "objdir" to refer to the top-level build directory,
   and "srcdir" to refer to the top-level source directory. Create the
   objdir and run configure from the srcdir:

	$ mkdir objdir
	$ cd objdir
	$ srcdir/configure

5. Compile 3Dwm from the objdir.
	
	 $ make

   This will build the 3Dwm libraries and binaries. Compiling the
   system from scratch takes quite a long time, so this is a good time
   to grab a coffee.

   'make install' is an optional step. As 3Dwm is still under heavy
   development we recommend running it from objdir.


Configuring the server
----------------------

The display server needs to be configured before you can run it (it
will run without a configuration file, but it won't be very usable).
3Dwm configuration files are XML-based, but are quite easy to set up.
There is a sample configuration file in the etc/ directory called
tdwmrc. Your best bet is to use this file as a base and edit it to
suit your own preferences.

Configuration files are read by the display server on startup, and
must thus be located somewhere the server can find them. You may
either specify the path to the file (including the filename) using a
TDWMRC environment variable, or you may place your configuration file
in the root of your home directory and name it '.tdwmrc'.

For environment variables (sh-based shell):

	$ export TDWMRC=/path/to/3dwm/etc/tdwmrc

For configuration file in your home directory:

	$ cp /path/to/3dwm/etc/tdwmrc ~/.tdwmrc

Now it is time to edit the configuration file to suit your
preferences. Note that the configuration file is an XML document, so
make sure that it is well-formed at all times (this means that you
need to end all elements with end tags, all attribute values should be
quoted, etc).

Open the file in your favority text editor and have a look. You will
generally have to modify the path in the "eventRule" fields, but you
might also want to change the "screen" parameters.  Below is a short
description of each section (the tdwmrc file has additional
information).
		
'screen': Screen setup field. Modify the 'width', 'height' and 'depth'
		attributes to your desired values. Note that if you
		are running in the console framebuffer, 3Dwm may not
		be able to use just any old screen resolution that you
		desire, so make sure you use one that will work.

'eventRule': Specify how the server should translate input to system
             	commands. This is how you add support for different
             	input devices. Standard mouse and keyboard mappings
             	can be found in the etc/default.zorn file, and unless
             	you have an exotic setup, you should always include
             	this rule file. Make sure that the path to this file
             	is correct! Note that you may add as many rule files
             	as you want.

'logGroup': Subscribe to different log message groups. Used to
		configure the amount of verbosity of the display
		server.


Running the server
------------------

You may start the 3Dwm server by typing:

	$cd objdir/server
	$ ./tdwm-server

The server will start running and launch an OpenGL window for its
graphical output. Since 3Dwm is a client/server architecture,
*nothing* (but a black background) will be displayed in this window
until a client connects to the server and makes use of its display
services. Therefore, once booted, the server will wait indefinitely
for client connections.

If you are using the standard mouse and keyboard input mapping file
(default.zorn), you may now navigate and interact with the 3D scene of
the server using the following commands:

	Ctrl + LMB + mouse movement	- orbit around focal point.
	Ctrl + RMB + mouse movement	- zoom focal point in/out.
	Ctrl + CMB + mouse movement	- pan focal point.
	Ctrl + Shift + LMB + movement	- rotate left/right.
	Ctrl + Shift + RMB + movement	- modify field-of-view.

In the description above, LMB, RMB and CMB refers to the left, right
and center mouse buttons, respectively.

In addition to these commands, you may also use the following keys in
the server window:

	Esc				- terminate the server.


Running the geoclient
---------------------

While the server is running the geoclient can be started by
typing in another terminal (potentially on another machine):

	$ cd objdir/clients/geoclient
	$ ./geoclient datadir/office.3ds

The 'geoclient' is a very simple 3Dwm client that connects to the
exported GeometryKit in the server, creates a Geometry, loads a 3D
file from the local system (in this case a simple model of an office,
which also happens to be Rob's room), and passes it to the 3Dwm
server. The 3Dwm server will happily render any geometry that is
created, so running geoclient several times will add more geometries
to the graphical output. Please note that you may need to zoom out
(using the 'X' key) to see graphical output.

The geoclient is able to open native .raw files as well as standard
.3ds files (using MeshIO). In other words, you may experiment by
loading other files than the supplied office model to the 3Dwm server.
Have a look at the 3Dwm website for some more interesting models to
try.


Running the texclient
---------------------

The texclient is a simple client used for testing the 3Dwm texture
capabilities. While the server is running type in another terminal:

	$ cd objdir/clients/texclient
	$ ./texclient datadir/peng.png

This will load the peng.png image file (any .png file will do, not
just the supplied one) and send it to the server, where it will be
displayed on a small quad. Make sure you zoom out (using the 'X' key)
to see the texture.

This client will be updated in the future to allow for interactive
texture experimentation.


Running the vncclient
---------------------

To run the vncclient, you first need to start a VNC server on a
machine accessible to the local machine (yes, it's possible to run the
VNC server on the local machine--in fact, it's recommended for
performance reasons). In this example, we assume you are running an
X11 VNC server on the local machine:

	$ vncserver -geometry 512x512 -depth 8 &

This will start a VNC server with the dimensions 512x512 and an 8-bit
color depth. The awkward dimension is due to the fact that all OpenGL
textures must be multiples of two. For 3D hardware with a 256x256
texture limitation (notably 3dfx Voodoo 3's and earlier), you need to
update the -geometry option accordingly (3Dwm does have texture split
functionality, but it has been temporarily deactivated).

Given that the VNC server was started on the local machine, it can be
found on localhost:1. In the VNC world, displays map to port 5900 plus
the display number. In this case, the display number is 1, so Xvnc is
listening on port 5901. Remember that Windows VNC servers run on a
single desktop, which thus is numbered 0, so the port is 5900 in these
cases.

Now it's time to start the vncclient (yes, the 3Dwm server must of
course be running as well). To do this:

	$ cd objdir/clients/vncclient
	$ ./vncclient localhost 5901 <password>

In the above example, we're connecting to the aforementioned localhost
running on display :1. You will need to specify the correct VNC
password on the command line.

The vncclient will open a connection to the VNC server from the 3Dwm
server, and the graphical output will be displayed on a single quad in
the 3Dwm world (you may need to zoom out to see it). Currently,
vncclient supports no interaction with the VNC window (the bindings
and the actual communication code has been implemented, only the 3Dwm
side is missing). If you do want to manipulate the desktop, you can
use the vncviewer that is bundled with the AT&T VNC distribution.
Simply do the following:

	$ vncviewer -shared localhost:1 

Enter the session password, and voil! You can now manipulate the
desktop.


Running the 3Dwm clock
----------------------

The 3Dwm clock application (tdwm-clock) is the first real application
that is even remotely useful. It makes use of the 3Dwm Nobel API,
including the new solid modeling support, to create a
three-dimensional analog clock displaying the current time. At the
moment, this is all it does, but the application will be improved in
the future.

Running the clock is as simple as doing the following

	$ cd objdir/clients/clock
	$ ./tdwm-clock &

We add the ampersand ('&') to the command-line since tdwm-clock is a
real-time application and will run until terminated (or the server is
shut down), constantly updating the time (in five second intervals).


Configuring omniORB
-------------------

NOTE! The 3Dwm team does not give support for omniORB itself! You need
to refer to the omniORB website for additional help on how to build
and install omniORB.

Download from http://www.uk.research.att.com/omniORB/

(The pre-built x86 Linux 2.x/glibc2.1 tarball can be used on many
platforms, but if you run into problems, you need to build omni
yourself.)
	
Un-tar and cd into the omni directory.
Become root and create a directory to install omniORB in:
	mkdir /usr/local/omniORB
Copy the entire bin and lib directories there:
	cp -Rd bin /usr/local/omniORB
	cp -Rd lib /usr/local/omniORB
Install the include directory
	cd include
	cp -Rd * /usr/include
Create symbolic links to the libs:
	cd /usr/lib
	ln -s /usr/local/omniORB/lib/i586_linux_2.0_glibc2.1/libomniORB3.so libomniORB3.so
	ln -s /usr/local/omniORB/lib/i586_linux_2.0_glibc2.1/libomnithread.so libomnithread.so
	ln -s /usr/local/omniORB/lib/i586_linux_2.0_glibc2.1/libtcpwrapGK.so libtcpwrapGK.so
	ln -s /usr/local/omniORB/lib/i586_linux_2.0_glibc2.1/libomniDynamic3.so libomniDynamic3.so
Create the config file /usr/local/omniORB/omniORB.cfg, 
with the following content:
	ORBInitialHost localhost
	ORBInitialPort 8088
Create the directory /usr/local/omniORB/log and set it writable by all.
Edit /etc/profile adding the following:
	OMNINAMES_LOGDIR="/usr/local/omniORB/log"
	OMNIORB_CONFIG="/usr/local/omniORB/omniORB.cfg"
	LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/usr/local/omniORB/lib/i586_linux_2.0_glibc2.1"

	add /usr/local/omniORB/bin/i586_linux_2.0_glibc2.1 to the PATH
	export OMNINAMES_LOGDIR OMNIORB_CONFIG and LD_LIBRARY_PATH
Edit your ~/.bashrc adding:
	source /etc/profile
Launch a new console and execute omniNames -start 8088 &

