- Author
- Paul D Turner
Introduction
In order to get CEGUI initialised and rendering – regardless of your target API or engine – there are basically three steps that need to be performed:
Obviously you also need to load some data and perform other basic initialisation, which is covered in 2 - The Beginners Guide to resource loading with ResourceProviders and 3 - 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 5 - The Beginners Guide to Injecting Inputs.
The Easy Way: Renderer 'bootstrapSystem' functions
This section describes the quickest and easiest way to get CEGUI up and running, and that is to use the static 'bootstrap' helper functions that are available on the Renderer class for your chosen API or engine. Unless you're doing something advanced or otherwise unusual, these are the fuctions you'll want to use, since they enable the creation of all the initial CEGUI objects in a single call.
Note that the Renderers also have destroySystem functions for cleaning up afterwards.
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 the majority of cases, the bootstrapSystem functions for those Renderers will create all the engine specific supporting objects automatically.
As stated above, when using the boostrapSystem functions, initialising CEGUI is as simple as a single function call:
Old desktop OpenGL 1.2 (Fixed Function)
- Header: <CEGUI/RendererModules/OpenGL/GLRenderer.h>
- Library: CEGUIOpenGLRenderer-0
Renderer class to interface with desktop OpenGL.
Definition: GLRenderer.h:40
static OpenGLRenderer & bootstrapSystem(const TextureTargetType tt_type=TTT_AUTO, const int abi=CEGUI_VERSION_ABI)
Convenience function that creates the required objects to initialise the CEGUI system.
Desktop OpenGL 3.2 or OpenGL ES 2.0
- Header: <CEGUI/RendererModules/OpenGL/GL3Renderer.h>
- Library: CEGUIOpenGLRenderer-0
- Note: to use this renderer with OpenGL ES 2.0, the Epoxy OpenGL loading library (https://github.com/yaronct/libepoxy, major version 1) must first be installed, and CEGUI must be configured with "-DCEGUI_BUILD_RENDERER_OPENGL=OFF -DCEGUI_BUILD_RENDERER_OPENGL3=ON
-DCEGUI_USE_EPOXY=ON -DCEGUI_USE_GLEW=OFF".
Renderer class to interface with desktop OpenGL version >= 3.2 or OpenGL ES version >= 2.
Definition: GL3Renderer.h:55
static OpenGL3Renderer & bootstrapSystem(const int abi=CEGUI_VERSION_ABI)
Convenience function that creates the required objects to initialise the CEGUI system.
Direct3D
- Header: <CEGUI/RendererModules/Direct3D9/Renderer.h>
- Library: CEGUIDirect3D9Renderer-0
Renderer class to interface with Direct3D 9.
Definition: RendererModules/Direct3D9/Renderer.h:65
static Direct3D9Renderer & bootstrapSystem(LPDIRECT3DDEVICE9 device, const int abi=CEGUI_VERSION_ABI)
Convenience function that creates the required objects to initialise the CEGUI system.
- Note
- This example shows the D3D9 renderer, but the D3D10 and D3D11 renderers are largely the same.
Ogre3D
- Header: <CEGUI/RendererModules/Ogre/Renderer.h>
- Library: CEGUIOgreRenderer-0
CEGUI::Renderer implementation for the Ogre engine.
Definition: RendererModules/Ogre/Renderer.h:92
static OgreRenderer & bootstrapSystem(const int abi=CEGUI_VERSION_ABI)
Convenience function that creates all the Ogre specific objects and then initialises the CEGUI system...
Irrlicht
- Header: <CEGUI/RendererModules/Irrlicht/Renderer.h>
- Library: CEGUIIrrlichtRenderer-0
CEGUI::Renderer implementation for the Irrlicht engine.
Definition: RendererModules/Irrlicht/Renderer.h:72
static IrrlichtRenderer & bootstrapSystem(irr::IrrlichtDevice &device, const int abi=CEGUI_VERSION_ABI)
Convenience function that creates all the Irrlicht specific objects and then initialises the CEGUI sy...
The Hard Way: Manual object creation.
If for some reason you don't want to use the bootstrapSystem functions, you can still, of course, create all the required objects manually. The following describes the creation of the Renderer and System objects via separate calls. Note that if you have already used the boostrapSystem function, you do not need to perform the following steps, and can instead skip to Call the function to render the GUI
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
- Header: <CEGUI/RendererModules/Direct3D9/Renderer.h>
- Library: CEGUIDirect3D9Renderer-0
static Direct3D9Renderer & create(LPDIRECT3DDEVICE9 device, const int abi=CEGUI_VERSION_ABI)
Create an Direct3D9Renderer object.
Direct3D 10
- Header: <CEGUI/RendererModules/Direct3D10/Renderer.h>
- Library: CEGUIDirect3D10Renderer-0
Renderer implementation using Direct3D 10.
Definition: RendererModules/Direct3D10/Renderer.h:69
static Direct3D10Renderer & create(ID3D10Device *device, const int abi=CEGUI_VERSION_ABI)
Create an Direct3D10Renderer object.
old Desktop OpenGL 1.2 (Fixed Function)
- Header: <CEGUI/RendererModules/OpenGL/GLRenderer.h>
- Library: CEGUIOpenGLRenderer-0
static OpenGLRenderer & create(const TextureTargetType tt_type=TTT_AUTO, const int abi=CEGUI_VERSION_ABI)
Create an OpenGLRenderer object.
Desktop OpenGL 3.2 or OpenGL ES 2.0
Ogre3D
- Header: <CEGUI/RendererModules/Ogre/Renderer.h>
- Library: CEGUIOgreRenderer-0
static OgreRenderer & create(const int abi=CEGUI_VERSION_ABI)
Create an OgreRenderer object that uses the default Ogre rendering window as the default output surfa...
Irrlicht Engine
- Header: <CEGUI/RendererModules/Irrlicht/Renderer.h>
- Library: CEGUIIrrlichtRenderer-0
static IrrlichtRenderer & create(irr::IrrlichtDevice &device, const int abi=CEGUI_VERSION_ABI)
Function to create and return IrrlichtRenderer objects.
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.
static System & create(Renderer &renderer, ResourceProvider *resourceProvider=0, XMLParser *xmlParser=0, ImageCodec *imageCodec=0, ScriptModule *scriptModule=0, const String &configFile="", const String &logFile="CEGUI.log", const int abi=CEGUI_VERSION_ABI)
Create the System object and return a reference to it.
Deinitialisation
Don't forget to deinitialise your CEGUI System and your CEGUI Renderer. This must be done in the following order:
- Call
static void destroy()
Destroy the System object.
to destroy the CEGUI System.
- Then destroy your CEGUI renderer (which you should store in a pointer, such as d_renderer) , e.g.:
static void destroy(OpenGL3Renderer &renderer)
Destroy an OpenGL3Renderer object.
The above expression inside the call casts the pointer, which is of type Renderer*, to the specific subtype Renderer class - in this case OpenGL3Renderer. You can of course store the reference to the Renderer using the correct subtype (here: OpenGL3Renderer) from the beginning.
In order to prevent leaks you will also need to destroy any GUIContexts, Textures and GeometryBuffers that you manually created. Windows, Images and other regularly created parts of CEGUI will be destroyed following the above two destruction calls automatically. In case you dynamically create a large amount of CEGUI windows or other objects in your application during run-time, you are advised to destroy them to reduce memory usage.
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::renderAllGUIContexts 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
myD3DDevice->BeginScene();
myD3DDevice->Clear(0, 0, D3DCLEAR_TARGET, D3DCOLOR_XRGB(0, 0, 0), 1.0f, 0);
draw3DScene();
myD3DDevice->EndScene();
myD3DDevice->Present(0, 0, 0, 0);
static System & getSingleton(void)
Return singleton System object.
void renderAllGUIContexts()
Depending upon the internal state, for each GUIContext this may either re-use cached rendering from l...
Direct3D 10
float clear_colour[4] = { 0.0f, 0.0f, 0.0f, 1.0f };
myD3DDevice->ClearRenderTargetView(myRenderTargetView, clear_colour);
draw3DScene();
mySwapChain->Present(0, 0);
OpenGL (desktop or ES)
Irrlicht
myIrrlichtDriver->beginScene(true, true, irr::video::SColor(150,50,50,50));
myIrrlichtSceneManager->drawAll();
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 rendering targets in Ogre and advanced options such as user specified resource providers, and so on.