A research oriented introduction to Ogre

This site is dedicated to those who wants to use Ogre to develop new 3D rendering techniques or algorithms. That is people who want to write rendering code (e.g. OpenGL commands) but are bored of writing small demos where objects are not animated, where you struggle with 3D file formats, bref where you have to code by yourself all the things that makes a cool demo although they are not relevant to your research. That was my case. It got me crazy. So I decided to use Ogre to have all these stuff already there and still be able to add new stuff. This takes some time to learn and to save this time to others, here is a digest of my understanding of Ogre and how it can help me.

As a consequence, these pages are not for those who use Ogre to develop a game and just want tutorials on how to use the already existing cool things in Ogre.

This site has been updated for Dagon (release 1.2.1 of Ogre) on June, 13th, 2006. If you experience some problems around that date, this might be because I am still fixing the updates ;-).

Preliminaries

I make it short, just a few guidelines to be sure you have Ogre and you can compile the examples. I assume you know C++ and you are familiar with 3D rendering. I also assume you are developping under Linux since (it is my case) but everyting should work under Windows since Ogre is multi-platform. No flame please, it is just that I rarely use Windows for my research and I cannot provide feedback for it.

Installation of Ogre

Ogre can be compiled from the tarball available at Ogre's website. It requires some work as Ogre depends on some mandatory libraries (DevIL and zziplib for example) and some optional library (CEGUI). Some of these libraries are not necessarily available on your linux distribution. It was my case on a Fedora Core 4 so you must get them and compile them beforehand.

That sound complicated, huh? That's what I think too. Moreover, Linux has a quite handy tool for installing programs, called rpm, so why don't use it? The answer is because the package dos not exist on some linux distribution. Damn it! So what to do? The answer is: spend some time packaging what's needed and release it on the web as you contribution to the community. Guess what? I did it and the rpms are available below.

Filename Size Last modified
DevIL-1.6.8-0.8.rc1.i386.rpm 626 Kb June 13th 2006
DevIL-devel-1.6.8-0.8.rc1.i386.rpm 15 Kb June 13th 2006
zziplib-0.13.38-1.i386.rpm 77 Kb July 6th 2005
zziplib-devel-0.13.38-1.i386.rpm 123 Kb July 6th 2005
CEGUI-0.4.1-2.i386.rpm 9.4 Mb June 1st 2006
CEGUI-devel-0.4.1-2.i386.rpm 247 Kb June 1st 2006
Ogre-1.2.1-1.i386.rpm 18 Mb June 13th 2006
Ogre-devel-1.2.1-1.i386.rpm 549 Kb June 13th 2006
Ogre-samples-1.2.1-1.i386.rpm 15 Mb June 13th 2006

Get all files in a single click by selecting the commands below and pasting them in a shell.

wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/RPMS/i386/DevIL-1.6.8-0.8.rc1.i386.rpm
wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/RPMS/i386/DevIL-devel-1.6.8-0.8.rc1.i386.rpm
wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/RPMS/i386/zziplib-0.13.38-1.i386.rpm
wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/RPMS/i386/zziplib-devel-0.13.38-1.i386.rpm
wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/RPMS/i386/CEGUI-0.4.1-2.i386.rpm
wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/RPMS/i386/CEGUI-devel-0.4.1-2.i386.rpm
wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/RPMS/i386/Ogre-1.2.1-1.i386.rpm
wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/RPMS/i386/Ogre-devel-1.2.1-1.i386.rpm
wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/RPMS/i386/Ogre-samples-1.2.1-1.i386.rpm

There is quite a bunch of them and you must install them in the order they are listed. You can skip those that might be already installed on your linux distribution (always prefer the one packaged by the distribution maintainers to my packages~: although I tried to do package properly, I have'nt set the dependencies to strictly.). If you have problem with the packages (binary incompatibilities due to the fact that I compiled them on a Fedora Core 2), you can download the source packages below and recompile the packages.

Filename Size Last modified
DevIL-1.6.8-0.8.rc1.src.rpm 2.9 Mb June 13th 2006
zziplib-0.13.38-1.src.rpm 496 Kb July 6th 2005
CEGUI-0.4.1-2.src.rpm 7.1 Mb June 13th 2006
Ogre-1.2.1-1.src.rpm 21 Mb June 13th 2006

Get all files in a single click by selecting the commands below and pasting them in a shell.

wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/SRPMS/DevIL-1.6.8-0.8.rc1.src.rpm
wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/SRPMS/zziplib-0.13.38-1.src.rpm
wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/SRPMS/CEGUI-0.4.1-2.src.rpm
wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/SRPMS/Ogre-1.2.1-1.src.rpm

The procedure to recompile is roughly (as root on your machine) :

>rpmbuild --rebuild thepackage.src.rpm
>cd /usr/src/redhat/RPMS/i386
>rpm -Uvh thepackage*.rpm

Note: I provide a customized rpm for DevIL because the one I found on the web does not package the .la files, so the Ogre package can not be re-compiled.

Installation of code snippets for the tutorials

The snippets are organized in the following way. There is a directory per step of a tutorial. This directory contains a working example corresponding to the step of the tutorial and that you can compile. To manage compilation, I use qmake coming with Trolltech's Qt. It is installed on every linux distribution that I know. Qmake is a great tool and work like this. Each directory contains a .pro file that lists what is needed. These files include a common config.pri that lists machine dependent information such as where ogre is installed, etc. The tarball below contains a default-config.pri that you should rename to config.pri and edit to match your system (the syntax is obivous). To compile an example, just go in the directory and type qmake and then make. To get the snippets, download the tarball below :

Filename Size Last modified
snippets.tar.gz 35 Kb June 13th 2006

Get all files in a single click by selecting the commands below and pasting them in a shell.

wget http://artis.imag.fr/Membres/Xavier.Decoret/resources/ogre/ogre/downloads/snippets.tar.gz

Untar it somewehere, go in the directory and compile all snippets. On linux, the sequence of commands will be :

>tar zxvf snippets.tar.gz
>cd ogre
>cp default-config.pri config.pri
>vi config.pri (or any editor you like)
>qmake
>make

Fow windows user, I do not yet provide project files for all steps in tutorials. However, the final step usually contains a .vcproj file that you can use. It is for Visual Net 2003 (7.1).

Running

As you will see in tutorials, Ogre uses some configuration file it loads at runtime. Those are located at the root of the tutorials directory. They are named plugins.cfg and resources.cfg. I distribute two version of these files, one for Linux (Ogre installed with above RPMs) and one for Windows (Ogre installed with the SDK installer in C:\OgreSDK). Choose the one you want and rename the files to plugins.cfg and resources.cfg.

Troubleshooting

If you have installed Ogre with my packages, you should not have any problem. If you did a custom install in a non standard way, you must edit the file config.pri to change the three lines of both the ogre and cegui "modules". To find out what you must feed in there, simply run :

>pkg-config --cflags --libs OGRE

Then copy the directory without the -I part in the INCLUDEPATH variable, the defines without the -D part in the DEFINES variable and everything else in the LIBS variable. Then do the same with :

>pkg-config --cflags --libs CEGUI

You must also edit the resources.cfg files to indicate where are the media (meshes, textures,etc.) coming with Ogre.

List of tutorials

Tutorial 1 Displaying and manipulating a scene
Tutorial 2 Using Ogre's facilities for debugging
Tutorial 3 Assembling a nice scene
Tutorial 4 Rendering your own stuff