15-859 course software

15-859 Course Software

Libraries

Xforms is a Graphical User Interface (GUI) toolkit layered on top of Xwindows. There's an online manual. Xforms comes with an interactive interface design and layout program called fdesign. If you prefer some other user interface toolkit, such as tk, feel free to use it. Xforms source code isn't available, but compiled libraries for many systems, including Linux, are available at the link above. I have Xforms installed in the class directories.
fltk, the Fast, Light Toolkit, is an alternative to Xforms that does not require Xwindows or UNIX. It is portable to Windows 95/98/NT and UNIX. Otherwise, it is quite similar to Xforms. It's written in C++. I haven't installed it, and haven't tried it, but it comes highly recommended.
OpenGL is a programming library for interactive 3D and 2D graphics. The man pages are online. The library was invented by Silicon Graphics (SGI), but it runs on other machines also. On SGI machines and on some PC graphics boards, most low-level OpenGL operations (draw line, draw polygon, ...) are implemented in hardware, so it runs very fast. To learn more OpenGL I recommend the book OpenGL Programming Guide, 2nd Edition: The Official Guide to Learning OpenGL, Version 1.1 by Mason Woo, Jackie Neider, and Tom Davis, Addison Wesley, 1997. (The first edition of this book is fine, too). You can read the OpenGL Programming Guide online using the Insight electronic documentation package on the SGI's. Type "insight &" into an SGI, wait a minute for the program to start, then find "OpenGL_PG" in the top subwindow and double-click on it. Otherwise, use the documentation at the first link above.
Mesa is a free OpenGL implementation in software which runs on almost anything, albeit more slowly. Mesa allows you to use OpenGL programs on Suns, and on PC's running Linux. Mesa is installed on cluster machines in /usr/local. You can get code for Mesa from the above link. On an SGI or a machine with native support for OpenGL, there's no need for Mesa.
Xlib is the low level library for Xwindows. We'll use it for mouse and keyboard input. Some information on Xwindows at: opengroup.org and ohio state. Xlib is available on all UNIX (and Linux) machines.
SVL, the Simple Vector Library, written by Andrew Willmott here at CMU, is a C++ library for vector and matrix arithmetic. It is very useful for operations with 2-D and 3-D vectors, colors, and transformations. I have SVL installed in the class directory, compiled to use doubles. If you want matrices and vectors of floats, instead, recompile the SVL source code with -DVL_FLOAT.
VL, the Vector Library, is a more sophisticated version of SVL (above) that has very efficient data structures for sparse matrices, capabilities for manipulating submatrices (handy for wavelet and finite difference computations), and code for solving linear systems using the conjugate gradient method and other techniques.
arg_parse is a command line argument parser I wrote that is handy for non-interactive programs. It's easy to use and makes it easy to add run-time options so that you don't need to recompile so often. Source code and a man page (Postscript , text) are available. You might find it helpful.

I'll be supporting two platforms primarily, the cluster Sparcs and SGI's, both running UNIX. You may use other hardware and operating systems, but in that case you're more on your own. Porting to Linux PC's will be relatively easy. Porting/rewriting software for Windows 95, 98, or NT will be quite a bit more work. To avoid porting and installing a lot of software by yourself, I recommend that you use one of the two supported platforms.

Commands

Commands and systems that could be useful include Matlab, Maple, Mathematica, and gnuplot. The first three are listed in Computing Services' tables of cluster software for Andrew, PC, and Mac machines. All four are available on cluster machines.
NETPBM is a collection of programs for manipulating pictures. PBM stands for Portable BitMap. It's installed in /usr/contributed on CMU cluster machines. Two of its picture file formats, PGM for grayscale and PPM for color, will be useful to us. Some documentation on netpbm is available via manual pages, or here. Alternatives to NETPBM include the "convert", "xv" and "photoshop" programs.
"xv" and "display" can display pictures in various file formats. Note: if you use "xv" to view small pictures of 16x16 pixels, say, put the cursor in the window and hit the "a" key to fix the aspect ratio; otherwise the picture is displayed very stretched.

Web Browsers

.mailcap file -- see this if your web browser (netscape, explorer) doesn't display Postscript or PDF or Quicktime or MPEG files properly.

Setup

Put the class bin directory in your path so that you'll have easy access to the programs we'll need in this class, such as fdesign.

    setenv pubdir /afs/cs/project/classes-ph/859E/pub
    set path = ($path $pubdir/bin)

It's probably a good idea to put these commands in your .login file.

Linking

The libraries to link OpenGL programs differ between SGI's and Suns. Typical link sequences are:

on SGI: -lforms -lGLU -lGL -lX11 -lm 
on Sun: -lforms -lMesaGLU -lMesaGL -lX11 -lXext -lsocket -lm

Makefiles will be provided that take care of most of these details.

You'll need to type the command

setenv LD_LIBRARY_PATH /usr/lib:/usr/local/lib:$pubdir/lib

If you don't set these environment variables correctly, you'll get error messages when you go to run a program that uses a shared object file such as the Xforms library (libforms.so). The error message might look like:

rld: Fatal Error: Cannot Successfully Map soname 'libforms.so.0.86'

It's probably a good idea to put these setenv commands in your .login .

For hackers: If you have access to an SGI Octane or other SGI machine with a MIPS R8000 or better, you might get some performance advantages by compiling with the cc or CC option "-n32" or "-64" instead of "-o32", which is the default on Indy's. To set up for this, you'll probably want

setenv LD_LIBRARYN32_PATH /usr/local/lib32:$pubdir/lib32

If you compile with the -n32 option (as opposed to -o32) then you'll need to use lib32 directories, not lib's, and use the LD_LIBRARYN32_PATH variable. If you're not using an SGI or (not using -n32 compilation and not running executables compiled with -n32), then you won't need that latter environment variable. For more info on this gripping topic, see "man cc" or run "insight" on an SGI, and look in the SGI Developer collection for the "MIPSpro 64-Bit Porting and Transition Guide".

For hackers: You can get a list of shared object files that a given executable looks for, by running elfdump -Dl <PROGRAM> on an SGI or ldd <PROGRAM> on a Sun. If you're really curious about which versions of shared object files are getting linked in, you can set the following environment variables and this will affect the runtime linker, rld (on SGI's):

setenv _RLD_ARGS "-quickstart_info -v"
setenv _RLD_PATH /usr/lib/rld.debug

so that every time you run a program it will print gobs of info. To turn off the linker debugging info, do

unsetenv _RLD_ARGS
unsetenv _RLD_PATH

Documentation

For documentation, use the "rtfm" command or "man" command, e.g. "rtfm pgm" prints info on the PGM file format, "rtfm tifftopnm" prints info on the tifftopnm command. If "man" doesn't find manuals for all the programs you're able to run, you might need to change your MANPATH (probably defined in your .cshrc or .login). I have mine set to

setenv MANPATH /usr/share/man:/usr/man:/usr/contributed/man:/usr/local/man

Many interesting programs are in /usr/contributed, so don't forget that dir.

15-859E, Hierarchical Methods for Simulation
Paul Heckbert, Sept. 1998