VTK:How I mangled Mesa
Abstract
This document describes the steps I took to build VTK (Visualization toolkit) with support the mangled Mesa libraries.
Introduction
If you use VTK and you're like me, you sometimes like to do your rendering offscreen in the software, right? Offscreen rendering is useful for a number of things, such as batch processing, parallel processing, and remote processing. VTK has functionality to perform these sorts of operations through the Mesa 3D library. Unfortunately, documentation on how to build VTK and enable support for offscreen rendering is sparse and incomplete. I will attempt to provide a clear explanation from start to finish how to setup VTK with support for Mesa for offscreen rendering.
Get the software
First move to the directory in which you plan to do the installing. I like using /usr/local/src and installing as the root user.
su - cd /usr/local/src
Download VTK and Mesa from their respective sources. You can get these libraries from the commandline using wget:
wget http://www.vtk.org/files/release/4.2/moved_to_sourceforge/VTK-4.2-LatestRelease.tar.gz wget http://internap.dl.sourceforge.net/sourceforge/mesa3d/MesaLib-5.0.2.tar.gz
Keep in mind that these files are from January 2005. You may have to look somewhere else to get them in the future. The next step is to extract the archives. I rename VTK to vtk-4.2.3 to keep it separate from my other vtk source installations.
tar xzvf MesaLib-5.0.2.tar.gz tar xzvf VTK-4.2-LatestRelease.tar.gz && mv VTK vtk-4.2.3
Mangling and Building Mesa
First I build Mesa. At this point, it's crucial that you understand what you're really doing and this is the part that's not really explained anywhere. Mesa will conflict with whatever rendering library you're using, so you can't install it on your system. More specifically, you can't make a dynamic (shared) library out of it. Confusion would result when linking a library or executable program that depends on OpenGL; The linker would be unclear whether to use Mesa or whatever is already installed on the system since Mesa symbols look like OpenGL.
Therefore, Mesa must be complied and linked into our VTK libraries staticly. Once VTK is built you can toss the Mesa stuff because all the code is included in the VTK library itself instead of residing in its own separate, linkable library. To avoiding Mesa having the same symbols as OpenGL I set a flag that will prepend each function name with an 'm'.
cd Mesa-5.0.2
With your favorite text editing program open Make-config and find the section labeled "linux-static" (or with Mesa > 6.2.1 take file configs/linux-static) and make the following changes:
GL_LIB = MGL OSMESA_LIB = MOSMesa CFLAGS = -DUSE_MGL_NAMESPACE ... CXXFLAGS = -DUSE_MGL_NAMESPACE ...
The file contains key = value mappings for the Mesa build. I just rename libGL.a to libMGL.a and libOSMesa.a to libMOSMesa.a and insert the -DUSE_MGL_NAMESPACE into CFLAGS and CXXFLAGS before the rest of the flags. Next I build Mesa:
make -f Makefile.X11 realclean make -f Makefile.X11 linux-static
Once you are done building Mesa, you can confirm the files were actually built by checking the lib directory
ls lib
You should see four files in this directory: libGLU.a libGLw.a libMGL.a libMOSMesa.a . If you see these four files then congratulations, you've succeeded and you're finished with Mesa. Configuring and Building VTK Now that Mesa is done, move on to VTK. I like to build vtk in a separate directory from where I extracted the source.
cd ../ mkdir vtk-bin cd vtk-bin
Configure VTK using CMake. Recall that I renamed my VTK source directory at the beginning. Just use whatever name your VTK source directory is set to.
ccmake ../vtk-4.2.3
You should now be in the CMake ncurses interface. Go ahead and toggle the advanced options to on and turn on the following options:
VTK_WRAP_TCL : ON VTK_USE_MANGLED_MESA : ON
Run configure and you will see four new options appear related to mangling mesa. They are unset, so you will need to set them to the Mesa you just built.
MANGLED_MESA_INCLUDE_DIR : /usr/local/src/Mesa-5.0.2/include MANGLED_MESA_LIB : /usr/local/src/Mesa-5.0.2/lib/libMGL.a MANGLED_OSMESA_INCLUDE_DIR : /usr/local/src/Mesa-5.0.2/include MANGLED_OSMESA_LIB : /usr/local/src/Mesa-5.0.2/lib/libMOSMesa.a
Now run generate to write out the VTK Makefiles. Now it's time to compile and link VTK:
make clean && make && make install
VTK will do its thing. Go get some ice cream and take a break -- this part takes a while.
Testing Offscreen Rendering
Now that you've installed your new mangled mesa powered VTK, you should probably test to see if it worked. Ironically, Kitware wrote their test program in Tcl which means that you have to run it with wish or vtk , which in turn means that you have to be running the X Window System, in which you really wouldn't have to use offscreen rendering in anyway. Got it? Too bad. Try the following:
vtk /usr/local/src/vtk-4.2.3/Examples/MangledMesa/Tcl/OffscreenCone.tcl
This program should run without crashing and it should NOT draw anything on the screen. Once it quietly finishes, look for a file in the current working directory called MangledMesaTest.png . Take a look at it. If you have ImageMagick, just type:
display MangledMesaTest.png
If it's a picture of a sideways cone, congratulations you're now a member of the VTK Builder elite!
