Copyright (c) 1993-1996 Ken Martin, Will Schroeder, Bill Lorensen.

This software is copyrighted by Ken Martin, Will Schroeder and Bill Lorensen.
The following terms apply to all files associated with the software unless
explicitly disclaimed in individual files. This copyright specifically does
not apply to the related textbook "The Visualization Toolkit" ISBN
013199837-4 published by Prentice Hall which is covered by its own copyright.

The authors hereby grant permission to use, copy, and distribute this
software and its documentation for any purpose, provided that existing
copyright notices are retained in all copies and that this notice is included
verbatim in any distributions. Additionally, the authors grant permission to
modify this software and its documentation for any purpose, provided that
such modifications are not distributed without the explicit consent of the
authors and that existing copyright notices are retained in all copies. Some
of the algorithms implemented by this software are patented, observe all
applicable patent law.

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR
DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF,
EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN
"AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

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


1. Introduction
---------------

Welcome to the Visualization Toolkit. 

"The Visualization Toolkit, an Object-Oriented Approach to 3D Graphics" is
the title of a new book published by Prentice Hall (ISBN 013199837-4).  

This README file contains information regarding the educational software
associated with the book. The two big pieces (120 and 80 KLOC) are a C++
library for visualization, and a Tcl binding to that C++ library so that it
can be used as a Tcl based interpreted language.

This is version 1.2. In this release there have been many bugs fixed and a
number of new classes. Depending on when you get this, there may be more
recent versions out. For more information and a FAQ see our web page at
http://www.cs.rpi.edu/~martink/


2. Documentation
----------------

This software does come with automatically generated man pages for all of the
C++ objects. The ideal way to learn about the software is from the book it is
designed to support.  You should be able to get the book from any local
bookstore or from our web page.

  The Visualization Toolkit, An Object-Oriented Approach to 3D Graphics
  by Will Schroeder, Ken Martin and Bill Lorensen.
  Prentice Hall, ISBN 013199837-4


3. Installation
---------------

The following instructions only apply to UNIX systems.  
The windows source distribution will be released in a different file.

First we will give you the quick and dirty way to build vtk.
If you have OpenGL, GL, XGL (with header files), or Starbase
do the following:

If you will be using C++ as your development language:

  1) untar the src files
  2) untar the data files
  3) cd vtk1.2
  4) read and edit Config.mk (possibly set your CC and CXX variables)
  5) ./configure
  6) make

If you will be using tcl in addition to C++:

  1) untar the src files
  2) untar the data files
  3) cd vtk1.2
  4) obtain and build Tcl/Tk if you don't already have it
  5) read and edit Config.mk (possibly set your CC and CXX variables)
  6) ./configure --with-tcl 
  7) make

If you do not have OpenGL, GL, Starbase or XGL the you will need to get and
compile Mesa, a wonderful free version of OpenGL. You will need to add
--with-mesa to your configure line. If you want to try building shared
libraries you can use the --with-shared option also.


Now here is the slightly more detailed version.

This software uses scripts generated by GNU autoconfigure to build itself.
There are a couple of options in building the software that you need to
decide on. First you need to decide if you are going to use the Mesa
rendering library developed by Brian Paul.  This is a software renderer that
vtk can use on Xwindows based workstations.  If your workstation doesn't
support Starbase, XGL, OpenGL or GL then you will need Mesa because you have
no other choice :-) If you want to build the vtk interpreter then you will
need to have Tcl7.4 and Tk4.0 or greater. 

Look to http://www.sunlabs.com:80/research/tcl/ for information about getting
Tcl and Tk. To obtain a copy of Mesa, written by Brian Paul, you can
visit http://www.ssec.wisc.edu/~brianp/Mesa.html.

To build vtk in the distribution directory just type ./configure
You can specify  --with-tcl  and/or  --with-mesa  on the command line
if you would like to use those packages as well. Building vtk for multiple 
architectures will be discussed later.

To build the vtk library and the tcl bindings and use mesa you would specify

./configure --with-tcl --with-mesa

The command:

./configure --help    

gives some brief help for the command line arguments. If you are using gmake 
then you might want to consider the --srcdir option.

The next step is to modify the Config.mk file.  If you are using tcl/tk you
must specify the full path to find the include files and libraries.  If you
are using mesa you must do the same. You might also want to specify the
compiler flags.  We recommend compiling without debug information and with
optimizations. The debug information can quadruple the executable size.  If
you are going to be working with the C++ library you might want to look into
using shared libraries. We use them in our development I just didn't figure
out a good way to use them with the GNU autoconfigure stuff. So you might
want to look into modifying the generated Makefiles and Config.mk to generate
shared libraries. On most machines these days it's not too difficult.

Once this is done you can type make (or gmake if you have it) and it should
compile :-)  

<< modify this >>
In the src directory it will build libvtk.a.  In the examples/cc
directory it will build one example, VisQuad. In the tclsrc directory it will
build libvtktcl.a and the vtk executable. 

If you are planning to build vtk for multiple architectures then you can
either make a copy of the entire vtk tree for each architecture and then
follow the instructions above. Or if you have gmake, you can have one copy of
the vtk tree and compile it in a different manner. Instead of running
configure from the vtk directory, create a new directory where you have some
free disk space (not in the vtk tree), a possible name would be
vtk-solaris. cd into this directory and then run configure similar to the
following example:

cd vtk-solaris
/home/joe_user/vtk/configure --with-tcl 

This will create makefiles in the vtk-solaris directory.  Then you can run
gmake in vtk-solaris to compile vtk.  Repeate this process for each
architecture you wish to build.

There isn't an install target yet for vtk.  Once you have tried some of the
examples discussed below you might want to do a hand installation.  Basically
copy tclsrc/vtk into /usr/local/bin or some other place where you keep
executables. Copy src/libvtk.a into /usr/local/lib or something similar.
Then copy all the include files in the include directory into
/usr/local/include or a similar directory. You might want to create a vtk
subdirectory to put all the include files in since there are quite a few.
Finally copy the man pages in man/man3 into /usr/local/man/man3 or an
equivalent place.


4. Execution
------------

Many of the examples require the data found in vtk1.2data.tar.gz. This should
be uncompressed and un-tarred so that there is a data directory in the vtk1.2
directory. The examples that require data look for it in ../../data.
If you compiled with the --srcdir option you may need to create a symbolic 
link to the data directory. 

To run the cc examples just type their name.  To run the tcl examples,
(assuming that you built the tcl stuff) type 

../../tclsrc/vtk mace.tcl


5. Common Problems
------------------
I got a "warning: no configuration information is in tcl" from configure.
This is correct and is supposed to happen. 

cpp_parse fails to compile - this is usually due to running an old version
of yacc or bison. I know that old versions of bison do not work. My
suggestion would be to make sure you are using yacc or a recent version of
bison (available at prep.ai.mit.edu in /pub/gnu)


6. Adding a new class to vtk
----------------------------
1) create the .cxx and .h file for the new class in one of the existing 
   directories. 
2) edit Makefile.in for that directory and follow the instructions in
   there. You will need to add the class in three or four places. 
   If the class is concrete (you can instantiate it) then you will
   add it in four places and the cpp_parse command line will have
   an argument of 1. (follow common/vtkObject as an example) 
   If it is an abstract class then you will add it in three places
   and the argument to cpp_parse will be 0. (follow common/vtkDataSet
   as an example)
3) you will need to rerun configure
4) then make (or gmake)


7. Adding a new toolkit to vtk (UNIX version)
---------------------------------------------
If you are not using cvs revision control then you can ignore steps
2 and 4. You can get autoconf from prep.ai.mit.edu in the /pub/gnu
directory. 

1) create a directory for it
2) cvs add that directory
3) cd into that directory and create a tcl subdirectory
4) cvs add the tcl subdirectory
5) edit configure.in at the top level and follow the example of graphics
   to add your directory. You might want to make it excluded by default.
6) edit Makefile.in at the top level, again follow the example of graphics
7) run autoconf on the configure.in to generate a new configure
8) using one of the other kits as an example, create a
     configure.in and Makefile.in in your toolkit directory
9) run autoconf to create the new configure for your configure.in
10) in the top level tcl directory edit configure.in 
11) generate a new configure file
12) edit Makefile.in and tkAppInit.c as done for graphics

