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

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

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

File History:
2001-08-16	Updates for version 0.3.0.
2001-07-16	Added reference to the French translation. 
2001-06-08	Minor revision.
2000-11-09	Documentation translation information added.
2000-11-03	Updates for version 0.2.2.
2000-08-11	Major revision for version 0.2.
2000-03-28	Updates for version 0.1.1.
2000-02-11	File created for 3Dwm version 0.1.

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

NOTE!	Translations of the 3Dwm documentation can be found in the doc/
	subdirectory! We currently have translations in the following
	languages:

	French:		doc/README.french
			doc/INSTALL.french

	Italian:	doc/README.italian

	Russian:	doc/README.russian
			doc/INSTALL.russian

	Spanish:	doc/README.spanish
			doc/INSTALL.spanish

What is it?
-----------

3Dwm is the Three-Dimensional Workspace Manager. It is *not* an X11
window manager; rather, 3Dwm is an attempt at defining a full user
environment with support for fully three-dimensional user interfaces
built using a 3D widget kit. Still, 3Dwm does provide a measure of
backwards-compatibility with all the major exisiting windowing system
(using VNC).

The official 3Dwm website resides at the following URL:

	http://www.3dwm.org

3Dwm is Free Software released under the Lesser GNU Public License
(LGPL). See the COPYING file for the complete software license text.
The project is always in need of more developers willing to help us
improve the system, so feel free to join in on the effort!


Technical highlights
--------------------

 - Distributed 3D scene graph (abstract logical description of the
	scene to render).
 - VNC client support (for displaying remote graphical desktops (like
	Windows, MacOS, or X11)).
 - Location-transparent (fully distributed).
 - Platform-independent.
 - Language-independent (need CORBA language bindings).
 - Distributed geometry and textures.
 - Texture splitting functionality (for 3D-hardware with the 256x256
	texture limitation, e.g. 3dfx Voodoo 3).
 - Retargettable renderer abstraction (OpenGL currently supported).
 - Hardware platform abstraction layer to allow 3Dwm to be retargeted
	to most rendering platforms.
 - Solid geometry functionality (Constructive Solid Geometry).


Mailing lists
-------------

There are three distinct mailing lists for the 3Dwm project (if we get
enough interest and developers, this number will rise), the
announcement, the help list, and the development list. The 3Dwm
development mailing list is the primary means of communication for all
3Dwm developers, so anyone planning to work on the 3Dwm core should
subscribe. The announce list, on the other hand, is a very low-traffic
mailing list for people who only want to be notified of new releases
and important 3Dwm events.

If you're having problems with 3Dwm and need some assistance,
subscribe to the 3Dwm help mailing list and ask your question there.
There are always people willing to help budding 3Dwm users find their
way.

To subscribe to the 3Dwm announcement, help or development lists, send
mail to

	3dwm-announce-request@oss.medialab.chalmers.se 
	3dwm-help-request@oss.medialab.chalmers.se
	3dwm-dev-request@oss.medialab.chalmers.se 

with the word "subscribe" in the message body or subject line.

In addition to these three mailing lists, there is also a CVS mailing
list which receives all information about CVS commits. Developers are
recommended to monitor this list to keep track of what is going on in
the 3Dwm source tree. Subscribing is done as per the above
instructions, the mailing list request address is

	3dwm-cvs-request@oss.medialab.chalmers.se

In addition, subscriptions to all of the 3Dwm mailing lists can be
managed through a friendly web interface by pointing your browser to

	http://www.3dwm.org/html/mailing_list.php


Getting 3Dwm
------------

3Dwm is experimental software and is under constant development. While
we certainly do release new versions on a regular basis, your best bet
for the most up-to-date work is the 3Dwm development CVS (see below
for instructions).

3Dwm stable releases can be downloaded from the following locations:

	HTTP:	http://www.3dwm.org/html/development_download.php
	FTP:	ftp://oss.medialab.chalmers.se/pub/3dwm/

If you would like to mirror 3Dwm releases, please contact the
development team at 3dwm@3dwm.org.

The 3Dwm website and the CVS documentation shows how to download a
copy of the 3Dwm source repository from the development CVS; below is
a quick guide:

  $ export CVSROOT=:pserver:anonymous@oss.medialab.chalmers.se:/home/cvsroot
  $ cvs login

The CVS password is "cvs".

  $cvs checkout 3Dwm

Keep your source tree updated by performing a CVS update in the root
source directory from time to time:

  $ cvs update

Note that the development CVS is truly "bleeding-edge", and there is
no guarantuee that the source contained therein will work or even
compile. If it is relative stability you are looking for, the 3Dwm
stable release is what you should use (see above).


Installation
------------

See the INSTALL file for notes on compiling, installing, and running
3Dwm. There are some example clients in the clients/ subdirectory.


Things to do
------------

There are some things that will have to be done on 3Dwm in order to
bring it nearer to completion (far, far away). We really need your
help! Take a look at the TODO file for some pointers on things that
need your attention, if you don't have a good idea of what you want to
do yourself. If you want to work on any of these areas, be sure to get
in touch with us (preferably by subscribing to the development mailing
list) so that you do not unknowingly stumble into the work of another
developer.


Joining 3Dwm
------------

We are always grateful for any contributions to the project, and not
necessarily in the form of source code. Software developers are always
welcome, but so are graphical artists, writers, bughunters, reviewers,
and so on. In other words, we would be just as happy to receive new
media such as sound, graphics and/or 3D models to use in the system as
we are to receive code. In addition, you can never have enough
documentation, so that is another area you might focus on if you are
willing to contribute but don't know where to start.

So, how do you join the 3Dwm project? Here are a few simple steps
(note that this is pretty much aimed towards programmers, but the
procedure should be similar for other contributors):

1. Download the source, preferably using CVS to get the newest version
   (see above for directions on how to do this, or check the 3Dwm
   website). There are also source tarballs available on the 3Dwm
   website. (If you're reading this, you probably got past this
   stage.)

2. Compile the source. (See the INSTALL file in this directory.)

3. Try to run it. If you encounter any problems, please submit a bug
   report. Or, better yet, try to fix the problem and then send us a
   patch. Feel free to comment on any problems you had when compiling
   and installing the system as well (we are very grateful to receive
   any portability tips).

4. Join the 3Dwm development mailing list. The devlist is the primary
   means of communication between the developers of 3Dwm, so if you
   want to contribute, you should be on it as well.

5. Start playing around with any part of the source that interests
   you. Try to get a feel for what it does. If you come up with
   anything nice, make a patch and send it to us at 3dwm@3dwm.org.
   Alternatively, if you think you will be doing lots of work, you can
   try to convince us to set you up with CVS write access.


Documentation
-------------

There is currently very little in terms of real documentation
describing 3Dwm. There exists a tentative 3Dwm client progammer's
manual in doc/manual of the source tree (it's written using the
DocBook SGML DTD, so you need Jade to compile it). However, the code
is quite clear and understandable, and is heavily commented, so it
should certainly be possible to learn the system by browsing the
source. 

Any contributions to the documentation of 3Dwm, including this README,
will be gratefully accepted. We are especially looking for technical
writers with the time and inclination to help us write some good
tutorials and user guides.


3Dwm in a CAVE
--------------

The main target for 3Dwm is an immersive environment like a CAVE
(Computer Animated Virtual Environment). 3Dwm was written to make use
of the CAVELib using OpenGL, but it should be possible (and is highly
desirable) to add support for other CAVE and HMD APIs. Unfortunately,
the CAVE support in 3Dwm is currently broken; this will be remedied as
soon as possible.

UPDATE: The new CAVELib version that is based on multithreading (as
opposed to multiprocessing) is currently in beta, and the 3Dwm
development team should receive it soon. Alternatively, there is a
number of Open Source VR libs like VR Juggler
(http://www.vrjuggler.org) that might be used for the same purpose.
