CS559
Fall 2005

News
Calendar
Assignments

Lectures/Notes
Tutorials
Sample Code

Project 1
Project 2
Project 3

Basic Info
Policies

C++ hints


GraphicsTown Documentation

GraphicsTown2005 is a set of example code written by Michael Gleicher as an example for the GraphicsTown project (CS559 Project 3). It is also meant as a starting off point for students to do their own projects.

Note: this project is not great. Its meant as an example, and a starting point. Some comments on things you might want to fix are at the end.

A ZIP file containing the project can be found here.

Using GraphicsTown

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

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.

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). In this mode, you can use the arrow keys to turn, the spacebar to fly forward, and the 'x' key to reverse. (improving this interface is something you might want to do)

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.

Adding to Graphics Town

When you look at the graphics town code, be sure to note that the widget layout was done in the FLTK interface editor (fluid). 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.

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.

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.

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 problem! 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.

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.

The Example Objects

There are a few simple objects (like cubes) and simple behaviors (like spinning 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 may want to make nicer ones.

The road system and driving behaviors are more 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 ... (see below for ideas on how to fix the road/driving model). 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.

There is an older road/driving system (from the 2000 version of the code) that is far more complex and harder to understand. It has a few more features (the cars stop at the stop signs), but is not as general (and the code is much harder to understand/debug).

Coding Style

The GraphicsTown program was originally written quickly in 2000 as a sample solution. It was not necessarily designed to be the platform for student projects. An overhaul in 2005 made it better, but its still not super-high-quality code, and it is not well documented.

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

One thing that you will notice is that the code is a mix of styles. For example, some parts use linked lists, while others use the STL. In practice this comes from the history of the program (in 2000, I didn't feel the STL was appropriate). 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 at a different time).

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.

Things to fix

In addition to making your own town (with your own objects and behaviors) there are many things that you might consider improving. If you do make some major improvements, be sure to let us know (in your README file and at the demo). If you do a good job, we might incorporate 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:

  • Most of the standard objects are really ugly - you should do better!
  • The user interface for the flying camera isn't great. It would be nice to have something easier to control, and maybe something that used the mouse.
  • 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 has really simple turns at intersections (just linear interpolation). It looks stupid and should be fixed.
  • The driving model doesn't obey stop signs or have any support to stop at traffic lights or railroad crossings.
  • The driving model pauses briefly at the end of a road segment.
  • Roads should have lines (lane markers)
  • Curved roads should be added.