                            === Tcl-SIPP 3.0b ===

    Tcl-SIPP provides a 3D image specification and rendering toolkit for use
with Tcl and Tk.  It is based on SIPP, the SImple Polygon Processor, a library
for creating 3-dimensional scenes and rendering them using a scan-line
z-buffer algorithm.  Tcl is an easy to use, powerful, interpretive programming
language, that is designed to be imbeddable in applications.  Tk is a X11
toolkit programmed in Tcl.

    Tcl-SIPP is a set of Tcl commands used to programmed SIPP without having to
write and compile C code.  Commands are used to specify surfaces, objects,
scenes and rendering options.  Scenes may be rendered to files in the PPM
format or in Utah Raster Toolkit RLE format.

   Tk interactive applications may also be developed that do rendering to the
Tk photo widget.

   This interface greatly speeds the development of scenes because no compile
and link phase is required.  Data is represented in a simple ASCII form.
This is particularly useful when for producing 3D scenes from ASCII data
generated by other programs.  Since most of the work in creating a scene is
still done in libsipp, the is only a small performance penalty in programming
in Tcl.

NEW FEATURES
============
The following new features have been added in this release.  See CHANGES for
a full list of changes and incompatibilities.

  o Added Tk X11 toolkit support with rendering to the Photo widget with
    handling of X events during the rendering process.
  o Added ability to partially or fully reset the state of SIPP, including
    releasing all objects, surfaces, cameras, or lights.
  o Created a single rendering command that can render to one or more output
    targets at the same time.
  o Added ability to render to an in-memory image (pixel or bitmap). This
    can later be written to a file or displayed in the photo widget.
  o Added ability to read RLE files.
  o Added Tcl library procedures, including procs to create an
    Evans & Sutherland VW object.
  o Better error checking.
  o All known bugs fixed, including memory leaks.

Since this is only the second release, there are a fair number of
incompatibilities were introduced fixing the conceptual and usability problems
with the first release.  Conversion should be fairly straight forward, as most
changes are command name or argument changes.  No external data representation
were changed.

REQUIREMENTS
============
The following software packages are required to build and use Tcl-SIPP:

   o Tcl 6.5 - The Tcl command language
        sprite.berkeley.edu:/pub/tcl/tcl6.5.tar.Z
     or
        ftp.uu.net:/languages/tcl/tcl6.5.tar.Z

   o TclX6.5c - Extended Tcl, an add on package for Tcl.
        sprite.berkeley.edu:/pub/tcl/tclX6.5c.tar.Z
     or
        barkley.berkeley.edu:/tcl/extensions/tclX6.5c.tar.Z
     or
        ftp.uu.net:/languages/tcl/tclX6.5c.tar.Z

   o Utah Raster Toolkit (optional) - This tool kit is great, check it out.
        cs.utah.edu:/pub/urt/urt-3.0.tar.Z
        cs.utah.edu:/pub/urt/urt-3.0.patch1
        cs.utah.edu:/pub/urt/urt-3.0.patch2.Z
     or
        wuarchive.wustl.edu:/graphics/graphics/packages/urt/urt-3.0.tar.Z
        wuarchive.wustl.edu:/graphics/graphics/packages/urt/urt-3.0.patch1
        wuarchive.wustl.edu:/graphics/graphics/packages/urt/urt-3.0.patch2.Z

   o Tk 3.0 (optional) - A Tcl-based X11 toolkit.
        sprite.berkeley.edu:/pub/tcl/tk3.0.tar.Z (includes Tcl 6.5)
     or
        ftp.uu.net:/languages/tcl/tk3.0.tar.Z (includes Tcl 6.5)

The SIPP 3.0 sources required to build Tcl-SIPP are included.  If you
wish to get the entire SIPP distribution, it is available from:

        wuarchive.wustl.edu:/graphics/graphics/packages/sipp/sipp-3.0.tar.Z
     or
        isy.liu.se:/pub/sipp/sipp-3.0.tar.Z (note: this site is in Sweden)

The photo widget is included in this release.  It has been adapted for use
with Tk 3.0.  The full photo widget distribution is available from:

        barkley.berkeley.edu:/tcl/extensions/photo.tar.Z



The latest version of Tcl-SIPP should be available in the Tcl contributed
archives:

        barkley.berkeley.edu:/tcl/extensions/tsipp*.tar.Z


VERSION NUMBERING
=================
    The Tcl-SIPP version number is a concatenation of the SIPP library version
number that it works with and a single letter indicating the Tcl interface
version.  The version may also include a patch level if Tcl-SIPP has been
patched.  This is Tcl-SIPP 3.0b.


DIRECTORY STRUCTURE
===================
    The following is the directory structure of the Tcl-SIPP code:
  

                                  tsipp3.0b
          src   libsipp   photo   tclsrc  man   tests   demos   help

o src - The source directory containing the Tcl interface to SIPP.

o libsipp - The complete SIPP 3.0 libsipp sources.  A few modifications were
  made in libsipp for Tcl-SIPP.  The entire libsipp sources are included for
  convenience. See libsipp/README for a description of the changes made for
  Tcl-SIPP support.

o photo - Contains the amazing Tk photo widget by Paul Mackerras
  (paulus@cs.anu.edu.au).

o tclsrc - Contains Tcl source that is built into an demand loadable .tlib.

o man - Contains the Tcl-SIPP manual page.

o tests - Contains basic tests that validate the individual commands.

o demos - A port of the demo programs from SIPP.  These also server to test
  Tcl-SIPP functionality not checked by the basic tests.

o help - This directory is not actually included with the distribution, but
  is built.  It contains help files that can read via the Extended Tcl help
  system.


BUILDING
========
    Sipp 3.0, Tcl 6.5 and Extended Tcl 6.5c should all have been built before
building Tcl-SIPP.  Extended Tcl should also be installed in its configured
location, if not you will need to set the TCLDEFAULT environment variable
to point to the TCLDEFAULT file in the Extended Tcl build directory before
running Tcl-SIPP.  If you are going to be building a Tk version to Tcl-SIPP,
Tk 3.0 should be built as well.  If you are including URT RLE, then it should
be built as well.  I highly recommend this toolkit

    Edit "Config.mk" to set the compilation options and to point to the
other packages required by Tcl-SIPP.  Follow the instructions in Config.mk
carefully.

    Enter the command:

        make

to compile and link Tcl-SIPP.  This should result in an interactive Tcl
interpreter being created in top-level directory called "tsipp".  This program
is the Extended Tcl shell with the Tcl-SIPP commands built-in.  A very minimal
test is to run tsipp to see if you get an interactive prompt (tsipp>).  Use
the exit command or enter an EOF to exit tsipp.  If specified in the Config.mk
file, a Tk shell based on extended wish will be build called "tksipp".


TESTING
=======
    A basic set of tests to validate Tcl-SIPP is run with the command:

        make test

This will do some basic validation of the commands.  If the RLE libraries are
linked into Tcl-SIPP, then the URT program `rlehdr' should be in a directory in
the PATH, or some tests will fail.


DEMOS
=====
    The demonstration pictures are built by entering the command:

        make demo

If you built Tcl-SIPP with the RLE library, the RLE format files will be
built by default.  IF RLE is not available, PPM format files will be build.
The can be overridden in the Config.mk file.  Other options controlling the
creation of the demo images may be set in Config.mk.

    The programs to create these images are ports of the C programs provided
with SIPP.  They are good example on how to use Tcl-SIPP.  If your generate
RLE images, use the Utah Raster Toolkit program getx11 (or what ever get
command is appropriate for your environment). to display them.  If you have
a 256 color display instead of full color, try the following:

        cat demos/*.rle | rlequant | getx11

    A RLE comment is added to the image to specify a correct image gamma for
these images.  See Utah Raster Toolkit Documentation for more details.

    If you create PPM images, use your favorite view capable of handling them,
or use the PBMPlus toolkit to convert them to a format that you can view.


    A simple tksipp demo application is included.  Enter

        make tkdemo

to run it.

BUILDING HELP FILES
===================
    Extended Tcl help files may be extracted from the man page with the
command:

        make buildhelp

Note that this requires nroff to be installed on your system.

INSTALLING
==========
    No install script currently exists for Tcl-SIPP.  The following files
should be installed:

   o tsipp - To a bin directory.

   o tksipp - To a bin directory if you built it.

   o tclsrc/tsipp.tlib, tclsrc/tsipp.tndx - Install in the directory specified
     by TCL_TCLDIR in your Extended Tcl Config.mk.

   o help - Install all files under this directory in $(TCL_TCLDIR)/help

   o man/tsipp.man, man/photo.man - To a man directory, probably where you
     installed your Tk & Tcl manual pages.


Tcl-SIPP AUTHOR
===============
   Mark Diekhans - markd@grizzly.com

Please send all bugs, questions or comments to this address.

AUTHORS OF OTHER SOFTWARE IN THIS DISTRIBUTION
==============================================

The SIPP 3D rendering package was developed by:

   Jonas Yngvesson -  jonas-y@isy.liu.se
   Inge Wallin -      ingwa@isy.liu.se

of Linkoping Institute of Technology, Sweden

The photo widget was developed by:

    Paul Mackerras (paulus@cs.anu.edu.au)

of The Australian National University.

Thanks for the great software!!!

