GraphicsTown Code Documentation

GraphicsTown is a set of example code written by Michael Gleicheras an example for the GraphicsTown project (CS559 Project 3). It isalso meant as a starting off point for students to do their ownprojects. Various TAs over the years have contributed as well.

A ZIP file containing the project can be downloaded. The most recent version is dated Nov18.

For your project, you should use GraphicsTown as astarting point. While figuring out how to extend GrTownwill take some work, it probably isn’t nearly as much work asrecreating the functionality from scratch. Plus, working with someoneelse’s (imperfect) code is good practice for the real world.

1.@ Building GraphicsTown

Graphics town requires FLTK. Because we didn’t know where you had FlTk installed, everything refers to an environment variable FLTKHOME. You should set the environment variable before running visual studio. (right click on “My Computer”, pick properties, and under the “Advanced” tab is an environment variables button).On a CSL computer, you should set FLTKHOME to be “S:\fltk\i386_winxp\vs9”. On your home machine, it will probably be something like “C:\fltk”.

There is one thing to be careful of: the user interface (the widgets and whatnot) are defined in the “GraphicsTownUI.fl” file. Fluid (the FlTk UI designer) turns this file into a .cxx and .H file. Do not edit those files as they will be overwritten.

2.@ Using GraphicsTown

To run GraphicsTown, the program must be able to find its texturefiles. It will search around a little for them.

There are sliders to control the time of day (which does not change byitself), the field of view of the camera, and the speedup factor (youcan set it to zero to stop time, or set it higher to speed things up).

The “Fly” button puts the system into flying mode (the default). The flying interface uses the following keys:

• Left mouse button = steer
• Right mouse button = fly (warning - if the flying gets “stuck” you will need to click the mouse again)
• Arrows = turn
• Space = go forward
• ‘x’ = reverse
• Arrow keys on the keypad = translate (strafe)
• NumPad5 = forward
• NumPad0 = reverse
• the ‘WASD’ keys do what you might expect if you play shooter games

The top chooser box (labeled “view”) allows you to pick an object to"ride.” When an object is chosen, you can turn on the “follow” buttonto follow behind the object instead. One special object to ride is the"map” camera that provides a birds-eye view of the town. When in mapmode, the arrow keys move things around. (improving this interface issomething you might want to do)

The lower chooser box (labeled “sights”) takes you to a view of somepre-defined interesting sights in the town. The default town doesn’thave too many (but then again, there isn’t too much that’sinteresting).

There isn’t too much more to do with the program other than fly aroundand look at things.

The default town is pretty boring - it is made of a small number ofsimple objects, and a few behaviors. Your job in the assignment is tocreate a better town.

3.@ Adding to Graphics Town

You can think of GraphicsTown as a simple game engine. In itsinitialization (in Main.cpp), it makes a world, a bunch of objects,and gives those objects behaviors. Then it lets things run. Each"step” of the world (between screen redraws), all of the behaviorshave an opportunity to change the objects that they effect.

The two key classes to figure out are “GrObject” (the graphicsobjects, the things that get drawn) and “Behavior” (the things thatmake GrObjects do things). There are many examples of GrObjects andBehaviors to look at and learn from.

The first place to start to understand how graphics town works is themain file (main.cpp). Here you will see where the world is built. Youwill replace this with something that creates your own town.

The main thing you will do for this assignment is create newsubclasses of GrObject and Behavior, and have main make instances ofthese to populate the world. Look in the Examples directory forsome simple things to get started with.

Note: there are many useful textures in the project for you touse. You need to find some of your own, but many of these will beuseful.

When you look at the graphics town code, be sure to note that thewidget layout was done in the FLTK interface editor (fluid). Visualstudio will automatically compile the “GraphicsTownUI.fl” file into aC++ source and header file. You should only edit the “.fl” file, andyou should use fluid to do it.

You can actually do most of the work of the assignment withoutchanging much of the existing code. You’ll need to change main.cpp,and you’ll need to add new files for new GrObjects andBehaviors. However, unless you want to do anything major, you probablywon’t need to change much else.

Note that Graphics Town uses the “GLEE” extension wrangler to provide for GL Extensions. There is an example object that loads in a shader program if you want to see how that works. Also, Graphics Town uses a TextureManager that can search paths for texture files and load in a variety of image file formats.

One thing that has thrown students off in the past: GrObjects keep a matrix for their own local coordinate system. In addition to be used for drawing, the matrix is also used as the camera matrix if the object is ever “ridden”. Therefore, if you animate the object, you should do it via the matrix (as appropriate), if you want the object to be rideable.

4.@ The Example Objects

There are a few simple objects (like cubes) and simple behaviors (likespinning around) to look at to get started.

I made some objects to make a suburban town - lawns, trees, houses,cars, … These objects are very simple - you will want to make nicerones.

You shouldn’t use my houses and my simple grids of houses. Do not use the “SimpleSubdivision” class in your code: do something more interesting!

The road system and driving behaviors are more complicated. The codeallows for an arbitrary network of pieces of roads, and for cars todrive around randomly. Cars do stay on the right hand side of theroad, but they don’t stop at stop signs, or avoid other cars, or… (see below for ideas on how to fix the road/driving model). Theroad/driving system is mainly there as an example of a more complexbehavior. You may want to extend it to be more interesting in yourtown – however, it will take a little effort to understand.In 2007, some students created a version where cars stop at the stop signs and not crash into each other.

5.@ Coding Style

The GraphicsTown program was originally written quickly in 2000 as asample solution. I wanted to try writing it as fast as possible to see what it was like for the students (the original version was done in a day or two).It was not necessarily designed to be the platformfor student projects. I had no intention of giving out the code.

Over time, I preferred to give out the code as a starting point so student could focus on the cool stuff (rather than re-creating my framework). So gradually, I improved the quality of the code so it is more useful as a framework.An overhaul in 2005 made it better, and morerecent updates have made it even better.

Working with someone else’s imperfect code is an intent of theproject: in the real world, you often get stuck finishing somethingthat someone else started. This will hopefully be useful practice.

One thing that you will notice is that the code is a mix ofstyles. In the “real world” you oftenrun into code that is a mix of styles because different people workedon it. (here its the same person, just over many years).

In general, I do not suggest you put too much effort into fixing thestyle of my code. It actually does work pretty well. You are betteroff investing your time and energy into defining new objects andbehaviors, and adding functionality.

GraphicsTown was “designed” to be easy (for me) to write, debug, andextend. It is not organized for efficiency. It performs well enough onmodern computers. (Even on the circa 2000 computers it was developed on itwas OK).

6.@ Things to fix

In addition to making your own town (with your own objects andbehaviors) there are many things that you might consider improving. Ifyou do make some major improvements, be sure to let us know (in yourREADME file and at the demo). If you do a good job, we mightincorporate your additions into the code we give to students next year(unless its something we want them to do themselves).

Some things that come to mind:

• You must make a more interesting town. Do not use SimpleSubdivision and SimpleLot.
• The example objects are ugly - you should do better!
• The user interface for the flying camera isn’t great. It would benice to have something easier to control.
• The map is really a hack. It should be orthographic, and it shouldhave a better interface, including being able to click to go toplaces.
• The flying camera remembers its last location. It would be nice ifyou switched to flying mode from a “sight” or following or drivingthat the flying camera started where the previous camera was.
• The camera that looks at “sights” doesn’t move. It would be nice tobe able to look around the interesting sight (maybe be able tocontrol an orbit around it while staying focused on the same point).
• The driving model doesn’t obey stop signs or have any support tostop at traffic lights or railroad crossings.
• Roads should have lines (lane markers)
• Curved roads should be added. (They are supported by the roadsystem, but right now there are just straight roads, and thecircular “track.")