				  TkSM

		     Copyright (c) 1995-1996 Irving Hsu
		            <ihsu@eng.umd.edu>

Introduction
============
TkSM is an OpenGL based 3D modeling extension for Tcl/Tk.  My goal in writing
TkSM is to provide a simple and relatively light-weight tool for displaying
polygon-based 3D models from within Tcl/Tk applications.  TkSM allows a user
to define hierarchical models, place groups of models into individual cells,
and associate each cell with one or more independent viewports through which
the models may be viewed and manipulated.

Two types of viewports are available: viewport widgets, and canvas viewport
items.  While canvas viewport items are generally slower in terms of rendering
speed (due to their use of off-screen pixmaps), they give the user the ability
to super-impose text and other canvas elements on top of rendered images, and
offer faster screen refreshes of static scenes.  On the other hand, viewport
widgets draw directly into OpenGL windows and will therefore render much faster
on systems with hardware OpenGL acceleration.

TkSM provides no direct access to OpenGL routines; if you are looking for an
OpenGL widget with binding for each OpenGL routine, or a 3D graphics widget
with control over the low level rendering details, TkSM may not be for you.
However, if you are interested in adding elementary 3D viewing/modeling
capabilities to your Tcl/Tk application, you may find TkSM to be of use.

Currently TkSM has native support for VRML only; a 3DMF parser is in the plans,
but probably won't materialize anytime soon.

Please send all questions, comments, and bug reports to: ihsu@eng.umd.edu


Status
======
TkSM is compatible with Tcl7.4/Tk4.0 (pl3) as well as Tcl7.5/Tk4.1. The
latest released version of TkSM is 1.3.


Features now supported include:

	model type:
		- polyhedra with simple convex polygon faces
		- line segments
		- points
		- spheres (gluSphere)
		- cylinders (gluCylinder)
		- disks (gluDisk)

	model attributes:
		- material properties for
		  - front and back faces (for polygonal models)
		  - individual vertices (for point, line and polygonal models)
		  - individual line segments (for line models)
		- material properties include
		  - color
		  - emissive coefficients
		  - ambient reflectance coefficients
		  - diffuse reflectance coefficients
		  - specular reflectance coefficients
		  - shininess
		- line stipples for line models
		- culling modes
		  - none
		  - front
		  - back
		  - both
		- single level texture mapping for point, line and polygonal
		  models
		- flat and smooth shading models
		- point, line, and fill modes for polygonal models
		- hierarchical models
		- per-face and per-vertex normals

	viewport attributes:
		- up to 8 light sources for each viewport
		- light source properties
		  - ambient color
		  - diffuse color
		  - specular color
		  - directional light
		  - positional light
		  - spot light
		  - attenuation for positional and spot light sources
		- two-sided lighting
		- hidden surface removal
		- depth-cueing (fog)
		- parallel and perpective projection
	
	file formats:
		- VRML (import only)


Supported Platforms
===================
TkSM has been tested on SunOS 4.1.4, Solaris 2.4, OSF1 V3.2, HP-UX 9.05 and
MachTen 4.0.2 with Mesa-1.2.7, and on Irix 5.3 with OpenGL.  There is hardly
any platform independent code in TkSM, and since Mesa is available on just
about all Unix platforms, porting TkSM to other Unix systems should be a
breeze.

I'd love to port TkSM to both MacOS and Windows (95 and NT), now that Tcl/TK
support for these OS's has more or less stabilized.  Chances are however, that
I won't have the time to.  If you are interested I would appreciate it if you
could drop me a note.


Known Problems
==============

-Minor Mesa incompatibility with Tcl/Tk:

If Mesa is configured to use shared memory (MIT-SHM) for the backbuffer in a
double-buffered visual, under certain situations destroying a window will cause
Tcl/Tk to die.  For example, if you have a button and a viewport widget in a
toplevel window created with its own colormap, destroying the toplevel window
from the button's command procedure will generate an X protocol error and bring
your program to a halt.

In attempting to allocate shared memory for a double buffered viewport, Mesa
calls XSetErrorHandler directly.  This messes up Tcl/Tk's error capturing
mechanism, causing it to fail to catch X errors generated during the
destruction of the toplevel window. The X errors occur because when the
toplevel window is destroyed, its colormap is freed; however, the colors used
by the button widget are not freed til after the command invocation is
complete. By then the colormap from which the colors were allocated no longer
exists, and freeing these colors will lead to a Bad Colormap error.

The easiest way to get around this problem is to compile Mesa without MIT-SHM
support. Another solution is to remove the XSetErrorHandler calls from Mesa
(in xmesa1.c).

