Assignment One

Ball in Room

Assignment 1: Ball in Room

Assigned: Tuesday, Jan 24, 2012
Due: Tuesday, February 7, 2012 (before 11:59pm)

Project Description

You are to familiarize yourself with using Ogre in C++ by making a small demonstration. There will be only two objects in this, a spherical ball inside a cubic room. The ball will start off in a random direction and with a randomly chosen speed within some reasonable range of your choice that will allow a nice interactive demo. At each frame, you will move the ball in the current direction an amount determined by its speed, which can remain constant for the entire time the program is running. You will check to see if the ball has hit any wall. If it does hit a wall, you will adjust its direction to make it bounce off the wall as in a perfect elastic collision with no loss of energy. This is therefore just a geometric computation to change direction, no real physics simulation is required. You can color and light the environment in simple ways, nothing needs to be texture mapped, but the lighting cannot just be ambient, you should at the very least have diffuse lighting from at least one light source that is placed so that the observer can see the shape of the ball and the discontinuities where the walls of the room meet. The objects are presumed opaque and three dimensional.

Getting Started

You should first take the opportunity to download and build the Ogre platform to the machine you plan to use for most of your development work. The source code can be found here. I have had good luck building this according to the instructions provided for both the lab Linux machines and for Windows 7 using Visual Studio 2010. I have had less luck with OSX on either Lion of Snow Leopard, so I would advise you to avoid those platforms until I've had time to figure out how to get the build to work. Follow the instructions to build Ogre and the Ogre docs if you want a local copy of the documentation. Alternatively, you can find documentation here. You should pay particular attention to the Ogre Wiki, and within that to the Tutorials to help you get started.

Update

I have prepared more complete descriptions of how to build your own Ogre application from source code on the lab machines and on Windows using Visual Studio 10.

Lab Machines

Building and Installing OGRE

First download the source distribution for Linux as described above and unzip/untar it into a source directory tree. This is big, you can put it in your own account, or you can use /tmp, although that will only stay around temporarily, but you will eventually install the results into a directory in your own account that will use no more than about 100 megs or so and the rest can be deleted. Even that will no longer be required after this assignment is turned in, so you won't be taking a permanent big hit to your disk quota.

At first, you'll basically follow the instructions for all this in BuildingOgre.txt in the source tree you just created, let's call it sourcedirectory and the full path to it sourcepath. First you create a build directory as the target for the Ogre build. Then you cd to that directory (we'll call it builddirectory) and run cmake. The instructions assume that cmake-gui is installed on your machine, but it doesn't appear to be on the lab machines, so you'll have to use the command line version of cmake. Once you are in the builddirectory, you issue the command cmake -G "Unix Makefiles" sourcepath and wait for it to complete. If things go well you'll have a bunch of new files in builddirectory, one of which is called Makefile. You now issue the command make and watch everything compile and link. When that completes successfully you'll have a version of the Ogre system and a bunch of example programs to demo it in builddirectory. You can run these by cd'ing to the bin directory in builddirectory and executing ./SampleBrowser. Check that everything is okay by running that and playing with the cool Ogre demos. The actual demos are in the lib subdirectory of builddirectory, the SampleBrowser executable just sets up the window and a bunch of Ogre parameters and then runs the shared library in the lib directory for each demo you choose to run.

Up to this point, you've just been following the directions distributed with the source and checking that they worked. If that's all good, here's where you diverge from those instructions. The next thing they tell you to do is make install, but that will try to put the Ogre stuff in /usr/local, and you need root permission to write to that directory, which you don't have and aren't going to get. So you need to modify things to install into a directory in your own account. This one you shouldn't put in /tmp but rather in a more permanent spot. You'll be able to delete everything else you've made up to now once you get things installed successfully. I'll refer to this directory as installdirectory and the full path to is installpath from now on.

Before you do make install, you have to tell the system where to put things instead of /usr/local. To do this, you'll edit two files that have been created in the builddirectory, cmake_install.cmake and CPackConfig.cmake. In each of these files, find all instances of the string /usr/local (there should only be one in each file), and replace them with installpath. Once that's done, you can run make install and when you're done you should see three subdirectories, bin, lib and include in installdirectory. These should have the Ogre executables, the Ogre libraries, and the Ogre header files in them, respectively. If that's the case, you're nearly done.

To make it possible to use all this stuff with the GNU build system, you still have one more step. Go to the lib/pkgconfig subdirectory of installdirectory. There should be six files with .pc extensions in them there. Edit each one of them to replace /usr/local in the first line with installpath. That's it, you should now have an Ogre installation that you can use to build your application.

Building your Application with your Ogre Installation

Start by making yourself a directory, we'll call it appdirectory, in which to put all your stuff. It's better not to put this in installdirectory, otherwise put it where you like. Now go here and download and extract the four files (BaseApplication.cpp, BaseApplication.h, TutorialApplication.cpp, TutorialApplication.h)in "Tutorial Framework (Linux Line-endings)" into appdirectory. Then extract these tools into appdirectory. This should add four more files, buildit, makeit, configure.ac, and Makefile.am to appdirectory. Finally, extract these resources into appdirectory. This should add two .cfg files and a media directory. Edit the second lines of both buildit and makeit to change "${HOME}/Ogre/sdk" to "${HOME}/installdirectory" (assuming your installdirectory is in your home directory)*. Edit plugins.cfg to change PluginFolder to point to installpath/lib/OGRE. Make sure that you set the protections such that both buildit and makeit are executable (if they aren't already). You can do this using the command chmod u+x buildit makeit. Then just give the command ./buildit and you should see a whole bunch of new files in appdirectory, one of which is called called OgreApp. Execute ./OgreApp and if everything worked right you'll get an empty Ogre window that you can use as the start of your own application development.

Windows with Visual Studio

For this platform, you can just follow the instructions here and things should work as described. I've used both the Ogre SDK and built Ogre from source, and I've built the application project manually with Visual Studio 10, not with the Ogre Application Wizard, and it worked fine. Note that when you want to run your executable, there will be a copy in the directory where the Ogre libraries have been built. Run that one so it can find the dll's it needs.

Notes

You might prefer to use the MinimalOgre starting code instead of the Tutorial Framework as your initial application. It does the same work, but all in one class instead of two. Read the pros and cons in the tutorial about the two different starting points, the suggestion there is that MinimalOgre is a better starting point for your project, but not as good as the Framework for tutorial purposes. If you do this, you'll have to modify the OgreApp_SOURCES definition in Makefile.am so that it has the correct list of your source files in it before you build.

You can make the code smaller by using TinyOgre instead, this is a pretty minimal starting point, for instance it drops the use of the OIS library for input. And you can get rid of the need to use .cfg files as shown in LowLevelOgre by hard coding these definitions. Look at all of this as discussed in the Ogre Tutorial to understand more about options for starting a project with Ogre.

Don't forget to look in the media subdirectory of installdirectory for some resources (meshes, textures, shader codes, etc.) that you might find useful for this starting project. Or you can get these here as a gzipped tar file. There are other tutorials in the wiki that show you how to load and use these resources in Ogre.

If you change the code in any of the tutorial files and you want to recompile, you can do this just by giving the ./makeit command without redoing ./buildit. If you want to add more files, put them in your directory and add the .cpp files to the list in Makefile.am, then rebuild using ./buildit at least once before dropping back to ./makeit.

*Thanks to Anant Rathi for catching my error in the original instructions.

What to turn in

Whatever machine you develop your application on, you will need to turn it in on the lab machines, so if you didn't develop it there, you will need to port it and build a runnable version there. By lab machines, we mean the 64-bit linux machines with names from Kingdom of Loathing (run cshosts kol64 to see the names of these machines) in the ENS basement lab. Make sure you leave some time for this in your planning. You will turn in the following:
  1. An executable file that can be run out of the box by us on the linux lab machines. This should be built against the standard linux installation of Ogre as described below.
  2. A README text file that tells us both what exactly are the steps involved in building the program from what you've turned in.
  3. A project description text file that tells us what functionality you've implemented, any other interesting features of the program (e.g. it's really fast because I did this clever thing), what software it relies on that you didn't write, issues you've encountered if you have unresolved problems, and how to use the program once it's built (trivial for the base version of this assignment, but critical as we go forward or if you've done extra credit work).
  4. A source tree of your project, including any resources needed that are not already installed on the linux lab machines. To turn in the main project, first clean your development area so that all intermediate files and object files are removed. Do not remove the executable of your project. Make sure that the necessary .cfg files are there, along with all the media you're using in a subdirectory. Put the README and project description files here too. Then, go to the parent directory (we'll call it sourcetreedir) and use the following command to submit your entire project tree: 
      turnin --submit theshark assignment1 sourcetreedir
    Note that this command turns in everything you need to submit if you followed these instructions.

Porting your Application to the Standard Ogre Lab Installation

Regardless of whether you built you application on Windows or on your own installation of Ogre on the lab machines, you'll need to configure it to build on the standard Ogre installation in the lab before you turn it in. To do this, either start with the appdirectory you created earlier, or make one if you're porting from Windows. Make sure you have all your source code (.cpp and .h files) in this directory. Make sure you have any media you are using in a subdirectory. Also make sure you have plugins.cfg and resources.cfg files in this directory if you are using those (as is done in the tutorial startup code). Finally, download the maketools.tar.gz file linked above in the section on building your application on linux and extract these files into this directory. Then do the following.

  1. Remove the second and third lines (those starting with export) from both buildit and makeit.
  2. Edit Makefile.am so that the noinst_HEADERS line has a list of your .h files, the bin_PROGRAMS line has the name you want to use for your executable after the "=" sign, and the four lines following that one have OgreApp at the beginning of each line replaced by this same executable name. Finally, make sure the fourth line starting with executablename_SOURCES has a list of your .cpp files after the "=" sign.
  3. Edit plugins.cfg so that PluginFolder=/usr/local/lib/OGRE. Make sure the only plugins you define are: RenderSystem_GL, Plugin_ParticleFX, Plugin_BSPSceneManager, Plugin_PCZScenenMnager, Plugin_OctreeZone, and Plugin_OctreeSceneManager. Unless you are doing something very fancy in your code, all but the first of these are optional.
  4. Edit resources.cfg so that the all the references are to the media directory you've created, presumably as a subdirectory of your appdirectory. You will certainly not need all of the ones that are distributed for the Ogre samples, and resources.cfg only needs to refer to those that you are actually going to use. If you're using the tutorial code, that probably does include SdkTrays.zip but not thumbnails (even though it lists that as essential). The only other ones you are likely to be using are the materials directories (okay, maybe not the nvidia one) if you got fancy and started using textures and stuff on your objects, and the models directory (if you got the sphere mesh from there). You don't need to reference the others.

After doing this, just run ./buildit and you should get a build that runs using the installed version of Ogre. Now you're ready to turn things in.

How to use turnin

Instructions for using turnin are here and by doing "man turnin" on the linux lab machines. Note that to use this or do any of the other work on the linux lab machines, you'll need a UTCS department account. If you're in our program, you should already have one. If you're in this class and don't have one, you're qualified to get one. To do so, go here. Make sure to do this well before the assignment deadline.

Extra credit

Here is a list of suggestions for extending the program. Note that since the assignments will build on each other, many of these things will constitute head starts on what you'll have to do later. We're giving you some extra credit for being ahead of schedule. How much depends on how much you've done. Don't expect the extra credit make up for not doing the basic requirements, though. If those aren't done, no extra credit will be given. And if you do all of this, you've already made a simple game. No, we don't expect that, concentrate on doing the required stuff first.
Last modified: 02/07/12 by Don Fussell fussell@cs.utexas.edu