The Beginners Guide to Getting CEGUI Rendering

Author

Paul D Turner

Introduction

In order to get CEGUI to render - regardless of your target API or engine - there are basically three steps that need to be performed:

• Create an instance of a CEGUI::Renderer based object.
• Create the CEGUI::System object (passing in the renderer created above).
• Each frame, call the CEGUI::System::renderGUI function to perform the rendering.

Obviously you also need to load some data and perform other basic initialisation, which is covered in The Beginners Guide to resource loading with ResourceProviders and The Beginners Guide to Data Files and Defaults Initialisation. You'll also need to get your inputs into the system so that you can interact with the GUI elements, this is covered in The Beginners Guide to Injecting Inputs.

For Ogre3D and Irrlicht users, there are helper 'bootstrap' functions to create the renderer, system and other related objects in one go. These functions exist because those engines have additional supporting objects (engine specific ResourceProvider and ImageCodec implementations) that will be desired by most users, most of the time, so these helpers offer a simplified interface for getting the system up and running on those engines. As such Ogre3D and Irrlicht users can skip to Ogre3D and Irrlicht 'bootstrapSystem' functions.

Create an instance of a CEGUI::Renderer based object

This is fairly straight forward and should pose no major obstacles for any of the supported renderers. You must of course remember to include the header file for the renderer that you will be using.

The basic renderer creation code is:

Direct3D 9

CEGUI::Direct3D9Renderer& myRenderer =
    CEGUI::Direct3D9Renderer::create( myD3D9Device );

Direct3D 10

CEGUI::Direct3D10Renderer& myRenderer =
    CEGUI::Direct3D10Renderer::create( myD3D10Device );

OpenGL

// Create an OpenGLRenderer object that uses the current GL viewport as
// the default output surface.
CEGUI::OpenGLRenderer& myRenderer =
    CEGUI::OpenGLRenderer::create();

Ogre3D

// Create an OgreRenderer object that uses the default Ogre rendering
// window as the default output surface.
CEGUI::OgreRenderer& myRenderer =
    CEGUI::OgreRenderer::create();

Irrlicht Engine

CEGUI::IrrlichtRenderer& myRenderer =
    CEGUI::IrrlichtRenderer::create( myIrrlichtDevice );

DirectFB

// Create DirectFBRenderer that draws to the given DirectFB surface using
// the given IDirectFB instance.
CEGUI::DirectFBRenderer& myRenderer =
    CEGUI::DirectFBRenderer::create( *myDirectFB, *myDirectFBSurface );

Create the CEGUI::System object to initialise the system

Another extremely simple step. Just instantiate the CEGUI::System object by using the System::create function, passing in the reference to the CEGUI::Renderer that you created in the previous step. This will cause the core CEGUI system to initialise itself.

CEGUI::System::create( myRenderer );

Call the function to render the GUI

This is the only step that, depending upon your target engine, can be done differently. Basically what you need to do call the CEGUI::System::renderGUI function at the end of your rendering loop. For users of the Ogre3D engine, this step is taken care of automatically. For everybody else, some simple example code can be seen below:

Direct3D 9

// Start the scene
myD3DDevice->BeginScene();
// clear display
myD3DDevice->Clear(0, 0, D3DCLEAR_TARGET, D3DCOLOR_XRGB(0, 0, 0), 1.0f, 0);
// user function to draw 3D scene
draw3DScene();

    // draw GUI
    CEGUI::System::getSingleton().renderGUI();

// end the scene
myD3DDevice->EndScene();
// finally present the frame.
myD3DDevice->Present(0, 0, 0, 0);

Direct3D 10

// define colour view will be cleared to
float clear_colour[4] = { 0.0f, 0.0f, 0.0f, 1.0f };

// clear display
myD3DDevice->ClearRenderTargetView(myRenderTargetView, clear_colour);

// user function to draw 3D scene
draw3DScene();

    // draw GUI
    CEGUI::System::getSingleton().renderGUI();

// present the newly drawn frame.
mySwapChain->Present(0, 0);

OpenGL

// user function to draw 3D scene
draw3DScene();

    // draw GUI (should not be between glBegin/glEnd pair)
    CEGUI::System::getSingleton().renderGUI();

Irrlicht

// start the scene
myIrrlichtDriver->beginScene(true, true, irr::video::SColor(150,50,50,50));
// draw main scene
myIrrlichtSceneManager->drawAll();

    // draw gui
    CEGUI::System::getSingleton().renderGUI();

// end the scene
myIrrlichtDriver->endScene();

DirectFB

// clear display
myDirectFBSurface->Clear( myDirectFBSurface, 0x0, 0x0, 0x0, 0xFF );

// TODO: Do other drawing here.

    // draw the GUI
    CEGUI::System::getSingleton().renderGUI();

// flip the surface we just rendered
myDirectFBSurface->Flip(myDirectFBSurface, 0, (DFBSurfaceFlipFlags)0);

Ogre3D and Irrlicht 'bootstrapSystem' functions

This section describes the Ogre3D and Irrlicht specific 'bootstrap' helper functions. Unless you're using one of these engines, you can probably skip to Conclusion.

The Ogre3D and Irrlicht engines each have their own intergrated file loading and image parsing functionality which CEGUI can seamlessly make use of via custom implementations of the CEGUI::ResourceProvider and CEGUI::ImageCodec interfaces. In order to make use of these implementations, the user would typically be required to create instances of these objects and pass them, along with the CEGUI::Renderer, to the System::create function. Since this over-complicates system construction for even the most simplest of uses, the renderer for each of these engines provides one or more bootstrapSystem functions that creates all those supporting objects automatically (there are also destroySystem functions for cleaning up afterwards).

When using the boostrapSystem functions, starting up CEGUI is as simple as a single function call:

Ogre3D

// Bootstrap CEGUI::System with an OgreRenderer object that uses the
// default Ogre rendering window as the default output surface, an Ogre based
// ResourceProvider, and an Ogre based ImageCodec.
CEGUI::OgreRenderer& myRenderer =
    CEGUI::OgreRenderer::bootstrapSystem();

Irrlicht

// Bootstrap CEGUI::System with an IrrlichtRenderer object, an Irrlicht based
// ResourceProvider, and an Irrlicht based ImageCodec.
CEGUI::IrrlichtRenderer& myRenderer =
    CEGUI::IrrlichtRenderer::bootstrapSystem( myIrrlichtDevice );

Conclusion

This is the most basic introduction to setting up CEGUI to render. There are things not covered here, such as using different scene managers in Ogre and advanced options such as user specified resource providers, and so on.