Course Software
Subroutine
Libraries
- OpenGL is a programming
interface for interactive 3D graphics. OpenGL implementations exist
for various platforms. To learn more OpenGL we recommend the book OpenGL
Programming Guide, 3rd Edition: The Official Guide to Learning OpenGL
- Mesa is a free
implementation of OpenGL that runs on Sun with UNIX, Linux PCs, and
other machines, with a variety of graphics boards. For some boards and
drivers, OpenGL is supported mostly in hardware; for others it is
implemented almost entirely in software. On UNIX and Linux, OpenGL is
almost always layered on top of XWindows. The Mesa README file is also
useful, especially for tips on how to manage X-Windows color maps.
Mesa can emulate a 24 bit display on an 8 bit one, and that's the way
we recommend using Mesa on the Suns. Setting up the colormap so this
works right is a bit tricky. If you want the full story, see the user guide,
and do a find for "glXChooseVisual". The code we're providing for the
assignments should set things up so that you don't need to worry about
this, however.
Mesa version 3.2.1 is installed as libGL.so. You can link it with
-lGL . See below for linking tips and for a gotcha regarding -lGL on
Suns.
- FLTK is a nice graphical user interface package, a variant
of Xforms (below) that doesn't rely on X Windows. It is portable to
UNIX, Linux, and Windows. You can go to the FLTK web site for information regarding
this graphical user interface package. We have a copy of the FLTK documentation
for your reference as well. FLTK comes with an interactive interface
design and layout program called fluid. If you prefer to use some
other user interface library, feel free. We are currently using
version 1.0.7 with the patches as of 1/26/2000. After assignment 1,
we plan to support FLTK in favor of Xforms.
Commands
For previewing
animation:
- The xplay program can read PPM and TIFF picture files and
display them at various speeds or single framed. Paul Heckbert wrote
it. Try, e.g. xplay *.tif . Sometimes it uses so much memory that the
X server bogs down and thrashes or crashes. To use less memory / run
faster:
- xplay ??0.tif --- display every tenth frame (frame numbers
ending in 0).
- xplay ??[05].tif --- display every fifth frame
- xplay -zoom .5 *.tif --- display pictures half size
- xplay -depth 8 -grid ??[05].tiff - will display using 8
bits per pixel (not 24), thereby saving X server memory, showing
every 5th frame.
- xplay `cat frame.list` - will display the frames
listed, one per line, in the file frame.list
This program is in the class bin directory; its source is in
src/xplay.
(Bug: as of 2/1/00, on linux, if your tiffs are 8 bit pseudocolor,
not 24 bit (check that with tiffinfo), xplay probably won't work right.
If you create your tiffs with the pic_write or tiff_write routine,
they will be 24 bit.)
- The animate program in /usr/contributed/bin is also good.
Try it also.
- If you have Adobe Premiere or some other video
editing software, then you can convert your animation into MPEG
or other digital video format and go to town.
- mpeg_encode can be used to generate mpeg versions of your
animation; mpeg_play can then display them. This is a pretty fast
process and will allow you to preview your animation even on machines
with small memory. If the cluster machines don't have this, you could
find the source on the web.
For viewing
stills and image processing:
- display can display many picture file formats. It does
a good job displaying 24 bit pictures.
- convert is good for file format conversion from the
command-line.
- xv reads most format and permits interactive cropping,
file format conversion, and many other functions. The user
interface is a bit clumsy, but it works.
- On the Andrew cluster, the installed version of xv is quite
old (1992) and will not display a 24 bit picture file using a 24 bit
window; it always converts to 8 bits per pixel. I therefore do not
recommend its use if you're concerned about image quality. Use display
or xplay some other program instead.
- (Bug: As of 2/2/00, it appears that xv won't display many
TIFF files properly (it displays them as ASCII files). Perhaps xv
wasn't compiled correctly? Computing Services says this should be
fixed in a few days.)
- gimp is a nice image processing system for UNIX, if you
can find it
- Adobe Photoshop (PC or Mac) is the best image processing
software; it can do almost anything.
fluid is the
user interface design program for FLTK, and fdesign is the
corresponding program for Xforms, as mentioned previously. They are in
the class bin directory.
I suggest you set
your path automatically by putting something like
set path=($path /afs/cs/academic/class/15462/bin)
in your .cshrc
to get these programs with minimum hassle.
UNIX Compilation
The include
files for Mesa, FLTK, Xforms, libpicio, and libtiff are in
/afs/cs/academic/class/15462/include, so if you compile with gcc
-I/afs/cs/academic/class/15462/include, your source code can use, for
example
#include <GL/gl.h> /* for OpenGL */
#include <pic.h> /* for libpicio */
#include <FL/Fl.H> /* for FLTK */
to include some
of the more important include files.
UNIX Linking
The Makefiles we
provide will link the starter code correctly on cluster Sun and Linux
machines, so hopefully you won't need to muck with the following much.
Typical link sequences, if you're using FLTK, are:
on Linux: -lfltk -lGLU -lGL -lX11 -lXext -lm
on Sun: -lfltk -lGLU -lGL -lX11 -lXext -lsocket -lm
on SGI: -lfltk -lGLU -lGL -lX11 -lm
If you're using
Xforms as the user interface library instead of FLTK, then replace
-lfltk with -lforms. If you're linking with the pic_ and tiff_
routines, then you'll need -lpicio -ltiff as well. If for some reason
you want the old, soon-to-disappear version of Mesa mentioned above,
use -lMesaGLU -lMesaGL instead of -lGLU -lGL.
A quick tutorial on
UNIX libraries: Subroutine libraries come in two forms, .a files and
.so files. When you make an executable, subroutines are ``linked'' to
the main program. If you compile with -lfoo, the compiler by default
looks for the archive file libfoo.a, and if it doesn't find it, it
looks for the shared object file libfoo.so. These files are searched
for in the list of directories given in -L options to the C/C++
compiler, then in the directories listed in the shell variable
$LD_LIBRARY_PATH, then in the default directory /usr/lib. See "man ld"
for more details. When an archive file (.a) is linked, the appropriate
subroutines from the object files (.o) are copied, making your
executable larger, but ensuring that it will always run (on the right
architecture). When a shared object file (.so) is linked, the
subroutines are not copied and compile/link time. Instead, at run time,
the system uses LD_LIBRARY_PATH to find the .so file and the
appropriate subroutines are dynamically linked into your executable in
memory. This results in much smaller executable files, but it means
that if you copy your executable to another machine without copying all
of the .so's it references, your program won't run. The upshot of this
is that LD_LIBRARY_PATH must be set correctly or something is likely to
fail.
You'll need the
command
setenv LD_LIBRARY_PATH /afs/cs/academic/class/15462/lib:/usr/lib:/usr/local/lib
It's a good idea
to put this command in your .login . On the Suns, if you're using -lGLU
-lGL, it's critical that you list the class lib directory before
/usr/lib and /usr/local/lib, or you'll get Sun's version of OpenGL
(from /usr/lib), rather than Mesa's. Our experience is that Sun's
OpenGL doesn't work well on Suns having only 8 bits per pixel (the
colormap is wrong). You can, of course, check this variable with
echo $LD_LIBRARY_PATH
On an SGI, you'll
probably also need
setenv LD_LIBRARYN32_PATH /usr/local/lib32
for shared
object files such as libforms.so and libGL.so to be resolved correctly.
You can get a list
of shared object files that a given executable needs with ldd
<PROGRAM>.
Working on a
Non-Cluster UNIX/Linux Machine
If you want to
set up so you can program the assignments directly on a non-cluster
machine, without remote login to a cluster machine, you'll need to do
some extra work, namely copy the include files and libraries. In order
to compile code, you'll need the include files. Copy the include
directory hierarchy to your machine. (We currently have different
versions for each architecture, but I think the differences are
insignificant, so copy any of them.) Then you'll need the libraries for
linking. Figure out what architecture your remote (e.g. home) machine
is. If it's an Intel processor running Linux, then copy the directory
hierarchy in arch/i386_linux2/include. If it's a Sun Sparc, copy
arch/sun4_55/include. To copy a hierarchy, the easy way to do it is
cp -r source-dir
dest-dir
Another way to
do it is:
mkdir dest-dir
cd dest-dir
(cd source-dir; tar cfL - .) | tar xvf -
The L option to
tar tells it to follow symbolic links. You'll probably want option this
to help grab files that come from outside the 462 hierarchy such as the
header files for libpicio and libtiff.
If your machine is
not a Sun or a Linux machine (an Alpha, say) then the first thing to do
is check the web pages for the libraries above (Mesa, FLTK, etc) to see
if a compiled library is available for your architecture already. If
not, you'll need to get the source and recompile. If it was written by
someone at CMU and it's used in this course, you should find the source
code in the class src directory.
Documentation
To get
documentation via the "man" program, put this
setenv MANPATH /usr/share/catman:/usr/share/man:/usr/catman:/usr/man:/usr/local/man:/afs/cs/academic/class/15462/man
in your .login
or equivalent shell initialization file.
15-462, Computer Graphics 1