A tutorial on CEGUI and Qt/QGLViewer

• Introduction
  • The QGLViewer library
  • The CEGUI library
• Preparation
  • Overview of the tutorial
  • Installation
  • Compiling tutorials steps
  • What we need to know about QGLViewer
• Introducing CEGUI
  • First elements: system and renderer
  • Next elements: Look, imagesets and fonts
    • Resources, CEGUI and XML
    • Loading imagesets and fonts with managers
    • Benefits of imagesets and fonts
  • My first interface
  • The size problem
• Better resource loading: simplicity and flexibility
  • Simplified look loading with schemes
  • Dynamic interface setup with layouts
  • My second interface
• Managing input: injections
  • Time pulse injections
  • Mouse injections
  • Keyboard injections
  • Conclusion and problems
• Encapsulating: the QGLCEGUIViewer
  • Using QGLViewer::preDraw() and QGLViewer::postDraw()
  • Managing events
  • Adding some helpers
  • The result
• Interacting with interface: listeners, callbacks and slots
  • The callback mechanism of CEGUI
  • The signal/slot mechanism of Qt
  • Mixing CEGUI and Qt message passing

Introduction

The QGLViewer library

The work by Gilles Debunne on the QGLViewer provides a wonderful base for developping 3D applications. It encapsulates :

• creation of a window with an OpenGL context;
• interaction with keyboard and mouse through a really nice trackball and fly metaphor;
• useful features such as memorizable camera path, easy snapshots, etc..

Since it is developped with Qt, it is very easy to have a 3D interface. You build your interface as a widget, using for example the Qt designer, and you let this interface interact with you viewer through signal and slots. However, doing so, you end up with two windows: one for the viewer and one for the interface. You cannot have you interface "overlayed" on you 3D rendering. Theoretically, with Qt4, it should be possible as Qt's widgets can now be rendered using an OpenGL renderer. However, I cannot make it work (and it seems other people are trying and it is difficult). For that reason, I investigated a purely OpenGL based widget/interface library. This tutorial summarizes my investigations.

The CEGUI library

Crazy Eddy's GUI is a quite powerful Open Source and LGPL library that allows overlayed interface. From what I can tell, it is the only one that can integrates with a 3D rendering system by being "rendered" directly in that system. Ogre and Irrlicht typically make use of them. It has a bunch of nice features that we will discover soon. However, it suffers from a number of (classical) drawbacks that I list first so we can get rid of that ;-) :

• No standard/easy distribution. Well, it is not a problem for Linux as I packaged it as a rpm so you can now easily deploy it. For Windows, there should be an installer soon and I'll try to describe integration to an Eclipse/CDT based development environment.
• Almost unusable documentation. It typically suffers from the syndrom "we are documented because we use Doxygen": the produced API reference is a big pack and you have no idea on how to enter it. Moreover, most of the documentation brings no information: typically, the doc for the setDisplaySize reads "sets the display size" Hum...
• Annoying bugs. Either I have missed some points (documentation is to blame gain) or some functions are not behaving the way they should. Thus you have to try and add workarounds where the could should theoretically be straightforward. Good thing is that it is Open Source so you can propose patch to fix them.
• Multiple ways of doing one thing. Well, it is a big debate amongst designers wether their should be one, ideally clean, way (as in the Python language) to do one thing or multiple ways (as in the Perl language). Personnaly, I don't mind multiple ways if the documentation helps me understand what are the pros and cons of each. Moreover, I want to be sure I understand everything that happens (consequences and implications) of the code I write. Either it is obvious from the API or it must be well documented.
• Sparse tutorials. Well, it *does* take time to write them so I understand.

This said, CEGUI is really cool and quite powerful and as Sinbad (the maniac behind Ogre) adequately puts it, when invited to a free lunch, you should not complain about the quality of the caviar. So thanks Eddie, here is my contribution to the project.

Preparation

Overview of the tutorial

There is a bunch of things to discover in CEGUI and another bunch of things to master in Qt/QGLViewer. There is the way things should theoretically work, and the way we have to do it in practice. There are fundamental issues that are not related to CEGUI in particular. Wow! That's a bunch of things! So we need to walk slowly and progress step by step. The goal of this tutorial is twofold :

• understand the principles behind CEGUI;
• encapsulate CEGUI within the QGLViewer.

The first goal will be achieved through the step-by-step construction of a simple viewer that displays a cube and has an overlayed interface to select color, rendering mode, etc.

The second step will be a complete refactoring of this simple viewer that will allow for very easy sub-classing, enforcing reusability and ease of use.

Finally, if there is some time left, we will try to go into advanced features of CEGUI such as scripting. It will be quite a journey so send your girlfriend to the movie, order a pizza and fasten you seatbelt.

Installation

You must first check that you have DevIL and QGLViewer installed. For that, type in a shell >rpm -q DevIL libQGLViewer libQGLViewer-devel If it returns at leas one "packaged not installed", you have to install it before installing CEGUI. The libQGLViewer install is well detailled. For DevIL, I did a src.rpm that you can download below. Apply the same instructions that the one for installing the CEGUI rpms. To install CEGUI, you have download the source RPMs for CEGUI (and DevIL if you need it). You will have to rebuild and install the binary result. Here is the sequence for CEGUI, to be done as root: >cd /usr/src/redhat/SRPMS >wget http://artis.inrialpes.fr/Membres/Xavier.Decoret/resources/CEGUI/downloads/CEGUI-0.4.1-2.src.rpm >rpmbuild --rebuild CEGUI-0.4.1-2.src.rpm >cd /usr/src/redhat/RPMS/i386 >rpm -Uvh CEGUI-0.4.1-2.i386.rpm CEGUI-devel-0.4.1-2.i386.rpm It's done! Now you can download and compile the examples.