The Beginner Guide to Getting CEGUI Rendering

In order to get CEGUI to render, no matter what your target engine is, there are basically three steps that must be done.

1. Create an instance of a CEGUI::Renderer based object.
2. Create the CEGUI::System object.
3. Call the method to render the GUI.

Obviously you also need to load some data and perform very basic initialisation, which is covered in The Imbeciles Guide to Loading Data Files and Initialisation, and also you need to get your inputs into the system which is covered in The Beginner Guide to Injecting Inputs.

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, also remember that for Ogre3D the renderer module now comes with Ogre and not CEGUI.

The basic renderer creation code is:

Direct3D 8.1

CEGUI::DirectX81Renderer* myRenderer =
	new CEGUI::DirectX81Renderer(myD3D8Device);

Direct3D 9

CEGUI::DirectX9Renderer* myRenderer =
	new CEGUI::DirectX9Renderer(myD3D9Device);

OpenGL

CEGUI::OpenGLRenderer* myRenderer = 
	new CEGUI::OpenGLRenderer(0);

Ogre3D

CEGUI::OgreCEGUIRenderer* myRenderer = 
	new CEGUI::OgreCEGUIRenderer(myRenderWindow);

Irrlicht Engine

CEGUI::IrrlichtRenderer* myRenderer = 
	new CEGUI::IrrlichtRenderer(myIrrlichtDevice, true);

Create the CEGUI::System object

Another extremely simple step. Just 'new' the CEGUI::System object, passing in a pointer to the renderer created in the previous step.

new CEGUI::System(myRenderer);

Call the method 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 method at the end of your rendering loop. For lucky users of the Ogre3D engine, this step is taken care of automatically. For everybody else, some simple example code can be seen below

Direct3D 8.1 / 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);

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();

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.

--CrazyEddie 11:14, 11 Apr 2005 (BST)