Information Visualisation utilising
3D Computer Game Engines

Case Study: A source code comprehension tool

By Blazej Kot; Project supervised by: Burkhard Wuensche, John Hosking, John Grundy

Tool usage

Example of Multi-user Code Walkthrough

This example will show how a multi-user walkthrough of some source code can be carried out using the implemented too. The example code used for this walkthrough is that of the gzip[32] Unix command line compression and uncompresison utility. This was chosen because its source code consists of twenty files, which seemed like a good amount for a simple example. The demo map is based on the q3dm1 map which comes with Quake 3, shown below. It was chosen because it is simple, and its source (uncompiled form of the map) is provided by id Software. This map consists of two main areas: an outdoor courtyard and an indoor room, connected by corridors:



Two source files are shown below. On the left is crypt.c, only a few lines long, while gzip.c, which is over 100KB long is on the right. (The text labels may be difficult to read due to the reduced size of the image.)



Below is an overview of the courtyard and the files placed in it. On the left pedestal are gzip.h and gzip.c, the two main files in the project. Notice the header files are displayed in red. Nearer the camera are util.c, getopt.c and getopt.h. Together, these five file contain most of the argument parsing and file access functions.



On the right side are crypt.h, crypt.h, lzw.h, lzw.c, revision.h and tailor.h. All of these are very small files, which perform very little work in the program. Therefore, they were all put in the same part of the map.



In the room there are nine files which contain implementations of the various compression and uncompession algorithms. On the right, near the camera is unpack.c, unlzw.c and unlzh.c. Further away on the right side are zip.c and unzip.c. On the left hand side are deflate.c, inflate.c, trees.c and bits.c.

Let us introduce two players to demonstrate the multi-user features: Claus (left) and Tim (right):

Screenshots taken from Claus’s perspective will be shown on the left, those seen by Tim will be on the right. Tim will first demonstrate how to move a file. Tim looks at the sourcefile he wants to move:

And then shoots:

The file disappears, but a ‘T’ icon appears on Tim’s display.

Tim moves to the place where he wants the file to go to (this could be anywhere on the map):

And then presses the use key (typically e) to drop the file:

The file appears at the new location.

Tim will now guide Claus through part of the source code of gzip. Both users go up to gzip.c:

They can now both see the beginning of the file. At the bottom of the screen, next to "Lock View With:" Claus can see Tim’s portrait and vice versa. Claus clicks on Tim’s portrait to lock his view with Tim’s.

The green background of Tim’s portrait starts flashing (difficult to show on paper). Claus’ view will now always follows the scroll position of Tim. Claus cannot scroll using the keyboard or mouse. Tim now scrolls to what he wants to show to Claus. Tim circles a part of the source file by dragging the mouse with the right mouse button held down. This leaves a trail of green squares on both player’s screens. Since both screens are practically identical, only Claus’ view is shown below (click for higher resolution):


Click for higher resolution. 

It can be seen that Tim is underlining the unzip hyperlink (the trail looks a lot better and cleaner when viewed for real.) Tim did this as he wants to show Claus he is about to click on it. When he does do so, both players will be slid to the file where unzip is defined. A few frames from this animation is shown below, in sequence left to right, top to bottom. Again, both players’ views are identical, so only one is shown:

Upon reaching the destination, both players see the same view, of the definition of unzip(). This is shown below, this time from Tim’s screen:


Click for higher resolution.

Tim could now click on the inflate() link to go and look at the implementation of the unzip algorithm. He then could click on BACK to come back to the view above. Or, he could scroll up or down to see other methods in the file. He could also press Esc, to close the file view, and then walk to some other file in the world. In that case, Claus’ view would be unlocked, and Claus would be able to scroll normally again.

The players can currently chat in two ways: if a file is not being displayed, either player can press the talk key (usually t), and type their message. This will appear on the other players’ screens, with an audible alert. Otherwise, if a file is being displayed, the players will need to drop down the console to chat by pressing ~. They can type messages to each other, as long as they don’t start with \ (since these will be interpreted as commands). This chatting-via-console is not optimal, since other players are not notified when a messages arrives for them. Improving the chat system in the file view is a planned as a future improvement.

This demo only had two players. Quake 3 supports up to 64 players, but some limitations in the implemented tool (using 32 bit for the users field) mean only 32 players maximum can use the source files.

Installation

A working Quake 3 Arena install is needed to use this tool. To set up the tool and the demo, unzip the file SRCVIS.zip into the Quake 3 Arena directory. This should unzip several files and directories into a new directory called SRCVIS. This directory should be in the same place as quake3.exe and the baseq3 directory. Running srcvis.bat from within the SRCVIS directory should start Quake 3, load the tool, and start the demo.

The player’s name and model can be changed by pressing Esc, selecting SETUP and then PLAYER.

To set up the tool with several users, firstly run the srcvis.bat file as described above on all the computers. Choose one of the computers to be the server this preferably should be the fastest computer available. There are then two ways to proceed: if the IP address of the LAN (or internet) network interface of the server is known, then on all the other computers, press ~ and type \connect 192.168.0.13 without the quotes, replacing the address by the address of the server. If the IP address is not known, then on all the other computers go to the menu, press Esc and choose LEAVE ARENA. This will halt the servers running on these computers. Then, go to MULTIPLAYER. Hopefully, the one computer still running a quake server will be shown there. If not, try pressing REFRESH. Once the server is shown, click on it to highlight it and then click on FIGHT to connect. If one method doesn’t work, try the other one. If both fail, try using a different computer as the server Quake 3, and network games in general, often don’t seem to run well on certain machines.

Setting up the Tool to Visualise a Different Source Project

The process of setting up the tool to visualise a source project is rather complicated, so it is outlined here, using the same example, gzip, as above.

Download and install doxygen[30]. Start the ‘doxywizard’ program. Choose the ‘Wizard’ button. Type in gzip for the Project name. Select the source directory containing the gzip source code, and create a new directory and set it as the destination directory. On the ‘Mode’ tab select ‘All entities’ and ‘Include cross-referenced source code in output’. Then select ‘Optimize for C output’. On the ‘Output’ tab select only HTML output, and make sure ‘plain HTML’ is selected. On the ‘Diagrams’ tabs select ‘No Diagrams.’ Click the OK button

In the main window, under Step 2, click on ‘Save’ and save the configuration file somewhere. Under Step 3, specify the working directory; the directory containing the source files seems to work well. Click on the start button. After a few minutes, doxygen should finish.

Now copy the dox2html executable into the directory which was the destination directory for doxygen. Run it from there (dox2html needs the doxygen output to be in the same directory as itself.) A console will pop up, and lots of messages will scroll past these indicate links not processed due to some features not being implemented in dox2html yet. After a few minutes (dox2html is not particularly fast) the tool should finish. If all went well, a new directory out should have been created, containing all the source files and a filenames file. Move or copy these into the SRCVIS directory under the Quake 3 directory.

At this point, the map may need to be edited to alter the number or location of sourcefile entities in it this can not be done using the implemented tool at this stage, so Q3Radiant will need to be used. This is quite a complex tool, so refer to its documentation to learn how to use it. The file to load is testmap2.map from the SRCVIS\maps directory. Add or remove sourcefiles like you would any other entity. To assign itemids to sourcefiles, select the sourcefile, press n to bring up the entity window, and type in itemid in the key field and a number in the value field. Press enter to store the new value. The map needs to run through the normal Quake 3 bsp, vis and light toolchain to generate testmap2.bsp, which is the file which Quake 3 loads.

Alternately, a different map altogether may be used, or a new one created. The map should be such that the player cannot die or become stuck in any part: for example, by falling into lava, drowning, or falling off the map (like in some of the Quake 3 "spacey" maps). The srcvis.bat file will need to be altered to specify the new map to be loaded.

Lastly, the filenames file may be edited to change the mapping of real source files to in-game sourcefiles. The filename at line n of the filenames file will by displayed by the sourcefile with itemid of n. (The minimum valid itemid is 1.)

This whole process is rather user unfriendly, but should be improved in the future, perhaps even incorporating an automatic layout of the source files, depending on the relationships between them.