Project 2: Graphics Town Framework Code

by Mike Gleicher on November 7, 2014

Note: this may not make sense until you see the main Project 2 page.

There is a ZIP file of the most current version of the code HERE. The base project should be ready to build on a lab machine.

History

The GraphicsTown Assignment was first given in 2000. And you’ll probably recognize it, although its evolved a lot. Understanding the history of the code may help you get a sense of why it is the way that it is.

When I first gave the assignment, I wanted to make sure I could do it myself, and to provide students with an idea of what I was expecting. I wrote the original graphics town in a very short amount of time (if students get 4 weeks, I should be able to do it much more quickly). This is where a lot of the code comes from.

In 2001, I gave students my code. I allowed people to use it. But it was such a mess I couldn’t recommend that people use it. Many did anyway. Which made me realize, that my code did the “un-fun” aspects (creating a system framework), and let students focus on the fun parts (doing graphics programming to try to make new and cool objects and behaviors).

So, in 2003, I began to encourage students to use my code. It wasn’t great, but the experience of working with someone else’s bad code is good practice for the real world. And it was good enough that students could focus on the graphics programming. And we got even cooler projects (since students spent their energy on coolness, rather than getting basic functionality). Students did very cool stuff (see the Gallery and remember they had 3 weeks, not 4, and circa 2000 era computers which had limited graphics hardware).

In 2005 (I didn’t teach the class in 2002 or 2004), I decided to clean up the core of the code and more actively encourage students to use it. (the Gallery has both 2003 and 2005 examples in it). By 2006, we actively discouraged students from not using it. In 2007, I said “This year, we’ve improved it to the point where you’ll probably want to use it.” In 2008 and 2009 , the project started to have its modern form (see the 2009 Gallery).

I taught the class in 2010 and used this project. Remember back then, computers were slower, and students had 3 weeks (since we did 4 projects in the class). But there were very very cool projects.

The trick to this is that there is framework code so you can focus on making cool stuff in your town (since that’s what the project is about), not worrying about getting basic stuff to work (like making a window and being able to fly around).

For 2014, we haven’t modernized the code much. We got it to compile with VisualStudio 2013. We switched to a current GL extension wrangler (GLEW). We updated to use the most current FlTk. Most of the code is just the evolved, cleaned up stuff that is over a decade old.

When you look at the code, it’s lineage will become clear. The basic coding style is pretty 2001 (very sparing use of C++ features), it uses Old-Style OpenGL. I wrote my own Matrix “class” (rather than using GLM). We could keep going.

What this Code Is

The GraphicsTown code can be thought of as two different pieces:

An “engine” that keeps a collection of objects, provides a user interface, and asks those objects to move themselves and draw themselves from time to time.

A collection of example objects.

The engine is the piece you need to figure out. The objects, you should replace. Most of them has a circa-2000 blocky graphics look.

One part of the example objects is a road system. It’s actually pretty complicated. The code allows for an arbitrary network of pieces of roads, and for cars to drive around randomly. Cars do stay on the right hand side of the road, but they don’t stop at stop signs, or avoid other cars, or … The road/driving system is mainly there as an example of a more complex behavior. You may want to extend it to be more interesting in your town — however, it will take a little effort to understand. In 2007, some students created a version where cars stop at the stop signs and didn’t crash into each other.

Building Graphics Town

We provide a Visual Studio 2013 solution file that has the paths to GLEW and FLTK hard coded in. If you want to use GLM, you will need to change the Visual Studio settings appropriately.

One important thing: the user interface panel (the buttons and sliders and things) are created using FlTk’s interactive UI builder (fluid). The C++ source code (GraphicsTownUI.cxx, GraphicsTownUI.H) are built automatically by fluid as part of the build process.

The program should be able to poke around and find the textures and shaders it needs.

Using GraphicsTown

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

There are sliders to control the time of day (which does not change by itself), the field of view of the camera, and the speedup factor (you can 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” button to 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 map mode, the arrow keys move things around. (improving this interface is something you might want to do)

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

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

The default town is pretty boring – it is made of a small number of simple objects, and a few behaviors. Your job in the assignment is to create a better town.

Adding to Graphics Town

You can think of GraphicsTown as a simple game engine. In its initialization (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 behaviors have an opportunity to change the objects that they effect.

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

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

Note: GraphicsTown is really bad in terms of managing memory. It creates objects and never destroys them, relying on the fact that all memory is released when the program stops. While this is tolerable because all memory/object allocation happens at the beginning of the program, it is not good programming practice.

You do not need to fix GraphicsTown’s memory problems! Just make sure that you only allocate memory during the initialization, or if you allocate memory while the world is running, that you do release it when you’re done with it.

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

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

When you look at the graphics town code, be sure to note that the widget layout was done in the FLTK interface editor (fluid). Fluid is located in /FLTK 1.3.2/bin/. Visual studio will automatically compile the “GraphicsTownUI.fl” file into a C++ source and header file. You should only edit the “.fl” file, and you should use fluid to do it.

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

Note that Graphics Town uses the “GLEW” 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. The TextureManager and ShaderManager are admittedly a bit clunky, but they are good enough for the class project, and will probably save you a bunch of time.

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.

Adding to the UI

If you find yourself wanting to change the control panel (buttons, sliders, …) you will have to learn about fluid, the FlTk UI designer. Do not edit the .cxx and .H file. These get re-created based on the fluid file.

It should be pretty obvious that the .cxx file was generated by a program, and is not for human consumption.

Coding Style

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

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

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

Things to fix

Rather than fixing the basic framework, we suggest that you focus on making new and cool stuff. We discourage you from making changes that don’t improve functionality (cleaning up the code, updating the coding style). However, there are some things that could stand some improving:

Note: that you have to make better objects. Avoid using the ugly old cars and houses.

  • The user interface for the flying camera isn’t great. It would be nice to have something easier to control. It’s also currently possible to fly through the ground.
  • The map is really a hack. It should be orthographic, and it should have a better interface, including being able to click to go to places.
  • The flying camera remembers its last location. It would be nice if you switched to flying mode from a “sight” or following or driving that the flying camera started where the previous camera was.
  • The camera that looks at “sights” doesn’t move. It would be nice to be able to look around the interesting sight (maybe be able to control an orbit around it while staying focused on the same point).
  • The driving model doesn’t obey stop signs or have any support to stop at traffic lights or railroad crossings.
  • Roads should have lines (lane markers)
  • Curved roads should be added. (They are supported by the road system, but right now there are just straight roads, and the circular “track.”)
  • There are no trains in this project.

Previous post:

Next post: