TKSM v0.9b Copyright (c) 1995 Irving Hsu Introduction ============ TKSM is a Mesa/OpenGL widget 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. 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. Two types of viewports are available: viewport widgets, and canvas viewport items. Viewport widgets offer better performance for animation-oriented applications, especially with hardware graphics support. While canvas viewport items may be slower 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. TKSM provides no direct access to OpenGL routines; to render a scene a user will have to create 3D models, specify the model attributes (vertices, surfaces, colors, material properties, etc.), and set up a viewport with the right position, size, and angle. If you are looking for an OpenGL widget with binding for each OpenGL routine, TKSM is not for you (check out EGR TIGER and the Generic 3D Graphics Kernel, ftp://metallica.prakinf.tu-ilmenau.de/pub/ PROJECTS/GENERIC/generic1.3.tar.gz). However, if you are interested in doing some elementary 3D modeling in your Tcl/Tk application, you may find TKSM to be of use. Please send all bug reports to: ihsu@eng.umd.edu Status ====== model types: polyhedra with simple convex polygon faces spheres (gluSphere) cylinders (gluCylinder) disks (gluDisk) model attributes: material properties for both front and back faces all culling modes smooth/flat shading point, line and fill mode for polygons (no stippling) model hierarchy vertex normals viewport attributes: up to 8 light sources in RGBA mode two-sided lighting hidden surface removal depthcueing (fog) parallel/perspective projections In the works are (in order of priority): point and line models texture mapping models with nurb surfaces Supported platforms =================== TKSM has been tested on SunOS 4.1.4 and Solaris 2.4 with Mesa (version 1.2.3), and on Irix 5.3 with OpenGL. There is hardly any platform-dependent code in TKSM, and since Mesa is available on just about all Unix platform (Mac and PC too), porting TKSM to other systems should be a breeze. Installation ============ Compiling TKSM is straightforward. Look through the Makefile and edit the include and library paths as are appropriate for your site, and 'make'. Naturally, you will need either OpenGL or the publicly available Mesa graphics library by Brian Paul. I've included the README file from the Mesa-1.2.3 distribution. It contains instruction on obtaining Mesa. Known Problems ============== 1. Selecting visuals. TKSM is quite brain dead in the way it chooses the viewport visual type. It will only ask for a RGBA (and in the case of a viewport widget, DOUBLEBUFFER) visual from glXChooseVisual. If the visual chosen differs from that of the viewport's parent window, TKSM will blow up. It is therefore critical that you specify the right visual type for the toplevel window or frame that contains the viewport widget/canvas. On a 24 bit display, glXChooseVisual typically returns {truecolor 24} for canvas viewport items and {truecolor 12} for the double-buffered viewport widgets, so if you want to place a viewport widget in a toplevel window you will need to request a {truecolor 12} visual for the toplevel window. 2. 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 SHM support. Another solution is to remove the XSetErrorHandler calls from Mesa (in xmesa.c). 3. Model hierarchy isn't checked for cycles. This will be fixed shortly.