MPIglut Documentation

An MPI-based, Powerwall-friendly GLUT
Main/Download Page

Here are the steps for setting up MPIglut on your own powerwall.

Setting up DMX on your Powerwall

MPIglut currently pulls the screen sizes and locations from "DMX", Distributed Multiheaded X, an open-source X server built on the x.org server code. So step 1 in using MPIglut is setting up DMX on your cluster.

DMX pulls the list of screens to use, and their locations, from a configuration file. Here's the configuration file for the powerwall (in /home/shared/dmx/):

virtual bigwall {
        display powerwall0:0 1680x1050+0+0 @0x0;
        display powerwall0:0 1680x1050+0+1050 @0x1200;
        display powerwall1:0 1680x1050+0+0 @0x2400;
...
        display powerwall8:0 1680x1050+0+1050 @7320x1200;
        display powerwall9:0 1680x1050+0+0 @7320x2400;
        display powerwall9:0 1680x1050+0+1050 @7320x3600;
}

This makes one big virtual server out of the 20 powerwall screens. 1680x1050 is the resolution of each individual screen. The "+0+1050" specifies the corner of the "sublocal" DMX display on the local screen. The "@XxY" specifies the corner of the sublocal DMX display on the global overall screen.

To fire up the DMX virtual server using your config file, run:

	/usr/X11R6/bin/Xdmx :1 +xinerama -configfile ./mydmxconfigfile

The ":1" says to start the DMX server on DISPLAY=localhost:1. "-configfile" loads your config file. You need not run the Xdmx server as root.

Once this has started, you should be able to

	export DISPLAY=localhost:1
	xclock

And you should see a clock on the powerwall! Once DMX is running, you can actually already use OpenGL applications on the powerwall--DMX is smart enough to take one running program, and broadcast all the geometry data across the wall. But MPIglut is more efficient, because it broadcasts user input events instead of geometry.

Building MPIglut

You can build MPIglut on a Linux machine like so:

	wget http://www.cs.uaf.edu/sw/mpiglut/MPIglut_latest.tgz
	tar xzvf MPIglut_latest.tgz
 	cd MPIglut
	make
	sudo make install

This will create a "libmpiglut.a", which contains the MPIglut code, the DMX client library MPIglut needs, and a slightly modified version of freeglut. Currently MPIglut is set up to download, patch, and build freeglut 2.4.0. On non-x86 machines, you may need to replace MPIglut's "libdmx.a" with your version from /usr/lib/libdmx.a.

Converting a Program to use MPIglut

In your code, replace #include <GL/glut.h> with include <GL/mpiglut.h>, or else just rename your copy of mpiglut.h as glut.h

Make sure you call glLoad* (e.g., glLoadIdentity) for the GL_PROJECTION matrix every time the window size or viewport changes. mpiglut intercepts this call, and inserts the global-to-local display transformation matrix. You can also get and apply the subwindow matrix manually with mpiglutGetSubwindowMatrix, which may be needed when using programmable shaders that do not access glProjectionMatrix.
If your code is geometry-rate limited, or would run better if it knew about the local backend's display size, call mpiglutGetRect(MPIGLUT_RECT_VIEWPORT,r) to get the pixel bounding box you'll actually be rendering. Alternatively, pull your clipping planes out of the projection matrix--glGet for GL_PROJECTION will return the MPIglut-modified projection matrix.

Compile your code with "mpiCC" or "mpicc" (or else you'll get an error message about "Can't find header 'mpi.h'")
Link your code with the MPIglut library "-lmpiglut" (or else you'll get link errors about missing "mpiglut..." routines)
Make sure the MPI machine file (/etc/mpich/machines.LINUX) and DMX configuration file (dmx.conf) list the same machines in the same order. Otherwise you'll get OpenGL remote-rendering errors at startup and/or really bad performance, because the backends aren't rendering locally.

It's almost always possible to write code so it transparently works with either plain glut or MPIglut. You can also use #ifdef MPIGLUT_H in the source code to protect MPIglut-specific parts.

Be careful when printing to the console with an mpiglut program--each node in the cluster will print the information! At the very least prefix each line with the node it's coming from.

Running an MPIglut program on Powerwall

An MPIglut program should just run. You may need to set the appropriate DISPLAY variable, like:

	export DISPLAY=powerwall0:1
	./myprog

The main program you run becomes the "frontend", which opens a big empty window to the DMX screen. The frontend does nothing but forward events--it doesn't run your code. Internally, at startup the MPIglut frontend calls mpirun to spawn off a set of "backends", one per DMX screen, which separately run your code.

MPIglut Command-Line Arguments

MPIglut's glutInit intercepts some command-line arguments, so all programs compiled with MPIglut accept these arguments:

-mpiglut_version
    Print out the version of MPIglut linked into the application.

-mpiglut_nosync
    Disable glutSwapBuffers-time synchronization. Performance
    may be slightly better, but animation will be jerkier,
    and slower backends may fall far behind.

-mpiglut_benchmark
    Cause the application window to be fullscreen, and
    repeatedly call glutPostRedisplay at idle time.
    This is useful for MPIglut or application benchmarking.

-mpiglut_verbose=10
    Set MPIglut's internal tracing verbosity level to 10.
    Traced events are written to files named "mpiglut_backend#.trc".
    This is unlikely to be useful except in debugging MPIglut itself.

Please email Dr. Lawlor with bugs, fixes, or suggestions about MPIglut!

Dr. Lawlor, Dr. Genetti
CS, UAF