15-462 course software

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
GLUT, the OpenGL Utility Toolkit, is a UI library for OpenGL. It is portable to UNIX, Linux, and Windows. GLUT provides facilities for window management, input handling, and event-driven callbacks. Full documentation is available at the OpenGL website. GLUT is installed on all of the graphics cluster machines.
GD2 is a C library which supports reading and writing several common image file formats. GD also provides support for simple drawing operations (lines, polygons, text annotations) which can be applied to image buffers. Full documentation at Boutell's website. GD2 is installed on all of the graphics cluster machines.

Commands

For previewing animation:

The animate command allows for previewing image sequence animations.
The convert command can create movies (as well as do many other kinds of conversions of image files).
mpeg2encode can be used to generate mpeg versions of your animation; mplayer or gmplayer can then display them.
If you have Adobe Premiere or some other video editing software, then you can convert your animation into a digital video format and go to town.

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.
gimp is a nice image processing system for UNIX, and is installed on the cluster machines. gimp's Video menu options can be used to preview and save animations (see the VCR Navigator option in particular).
Adobe Photoshop (PC or Mac) can do almost anything.

UNIX Compilation

The include files for GL,GLUT, and GD2 are in /usr/include, which is in the default include path on most systems. You can thus use

#include <GL/gl.h>  /* for OpenGL */
#include <GL/glu.h>  
#include <GL/glut.h>  /* for GLUT */
#include "gd.h"  /* for GD2 */

to include some of the more important include files.

UNIX Linking

The Makefiles we provide will link the starter code correctly on cluster Linux machines, so hopefully you won't need to muck with the following much. A link sequence, if you're using GLUT and GD, is:

-lgd -lpng -lz -ljpeg -lfreetype -lm -lglut -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.

If you experience errors from missing .so files, you'll need the command

setenv LD_LIBRARY_PATH /usr/lib:/usr/local/lib

It's a good idea to put this command in your .login. You can, of course, check this variable with

echo $LD_LIBRARY_PATH

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 ensure that OpenGL, GLUT, and GD2 (both headers and libraries) are installed on your machine. See your distro's package manager for details.

If your machine is running OSX, you'll need to install Fink or DarwinPorts, install GD2, and add /opt/local/bin to your path. OSX uses a different header namespace than Linux, you you'll need to replace the includes mentioned above with

#include <OpenGL/gl.h>  /* for OpenGL */
#include <OpenGL/glu.h>  
#include <GLUT/glut.h>  /* for GLUT */
#include "/opt/local/include/gd.h"  /* for GD2 */

and use the following link sequence (split into two lines for readability only):

 
-L/opt/local/lib -lgd -lpng -lz -ljpeg -lfreetype -lm -L/System/Library/Frameworks/OpenGL.framework/Libraries
 -L/System/Library/Frameworks/GLUT.framework/ -lGLU -lGL -framework GLUT

You'll then be able to compile the app, and run it via the X11 server found at /Applications/Utilities/X11.app