Using CEGUI with Axiom

From Axiom

NOTE: This page was ported over from the old Axiom wiki, but we haven't had a chance to update it yet. It's woefully out of date. Once the dust from the recent CEGUI# and Axiom changes settles, this will be brought up to date, and this notice removed. -- 04/02/06

Contents 1 Introduction 2 Setting up CEGUI for Axiom 2.1 Required files 2.2 Initialization code 3 Basic usage 3.1 Creating Windows 3.2 CEGUI Events 4 Advanced Usage 4.1 Changing the look of widgets 4.2 Creating window layouts using xml 4.2.1 schema example 4.2.2 loading an xml layout 4.3 3D objects rendered on CEGUI windows 4.4 creating your own window scripts. 5 Examples

Introduction

CEGUI is an advanced GUI library that has been ported to c# for Axiom and other managed applications. As a library it is completely independent, the link to the application is done through a renderer implementation

Setting up CEGUI for Axiom

Required files

CEGUI expects a few files to work:

• Naturally you need to have the two assemblies, CrayzEdsGui.Base.dll and CrayzEdsGui.Renderers.Axiom.dll and have them referenced in the projects where you use them.

• the XSD schemas, used for imageset and layout loading, in the run directory

• an imageset.xml file, that defines the image areas and bitmap used for widgets, in the run directory

• a widget images bitmap, in the axiom assets textures folder

• the widget scripts, which are compiled at runtime.

• optional xml layout files

You change where those files are expected to be. Notice the name of the assemblies too: CrayzEdsGui. Be sure to write it right for using declarations.

Initialization code

CEGUI renders it's windows on quads, that are created and streamed to the hardware independent of axiom, through its renderer implementation. Thus we need to tell CEGUI which renderer to use when we create the GuiSystem. Notice there are a few overloads for the renderer constructor, for when you use a different axiom SceneManager then the default.

Then we set what widget's to use. these are c# classes compiled at runtime, implementing a certain look and feel of the CEGUI widget's.

We set what the main imageset to use is. This XML file contains the name of the bitmap and the rectangle area's and names of images defined in it, so the widgets can find it. Be sure to use the corresponding one as defined in the widget scripts.

Then we set the default mouse cursor, which is visible when no specific Gui event overrides it.

Last but not least we create a font bitmap trough code and set it as the default.

First it's a good idea to use imports/using statements:

'VB:
Imports CrayzEdsGui.Base
Imports CrayzEdsGui.Base.Widgets
Imports CrayzEdsGui.Renderers.AxiomEngine

// C#
using CrayzEdsGui.Base;
using CrayzEdsGui.Base.Widgets;
using CrayzEdsGui.Renderers.AxiomEngine;

Now for the code:

// Create Axiom Renderer
// AxiomRenderer is a member of of CrayzEdsGui.Renderers.AxiomEngine
// "window" is a reference to the axiom rendering window (Axiom.Graphics.RenderWindow)
// such as the "window" object used in the techdemo.
guiRenderer = new AxiomRenderer(window, RenderQueueGroupID.Overlay, false);
        
// Init the subsystem singleton
// GuiSystem is a member of CrayzEdsGui.Base
new GuiSystem(guiRenderer);

// Set the logging level
CrayzEdsGui.Base.Logger.Instance.LoggingLevel = CrayzEdsGui.Base.LoggingLevel.Insane;

// compile the TaharezLook widgets
if(!WindowManager.Instance.CompileScripts("TaharezLookWidgets", @"path-to-widgets", true))
{
    window.DebugText = "Script compilation failed, see log for details.";
    return;
}

// Init the imageset
ImagesetManager.Instance.CreateImageset("path-to-imageset\\imageset-name");

// Configure the default mouse cursor
GuiSystem.Instance.SetDefaultMouseCursor("TaharezImagery", "MouseTarget");

// Create a default font bitmap
CrayzEdsGui.Base.Font defaultFont = FontManager.Instance.CreateFont("Tahoma-12", "Tahoma", 12, FontFlags.None);

// Configure the default font
GuiSystem.Instance.SetDefaultFont(defaultFont);

Basic usage

Creating Windows

CEGUI expects one Window as root, all others are children. Usually you use a window of type GuiSheet for this, which you can set fullscreen and as a frameless window. You can have references to other window hierarchys though, so you can create a few main guiSheets and switch them as needed.

When creating a window, you need to cast it to the expected type, and set the widgetlook it uses, which are strings you can define using constants.

The window created needs to be added to another or the root to be visible

CEGUI Events

Advanced Usage

Changing the look of widgets

To change the visual look of windows you can just change the bitmap it uses, if you change position and bounds of individual parts you will have to edit your imageset.xml to reflect that. This only allows some basic tweaking like color or visuals, for more control you need to create your own widget script implementation. At some point a more general data driven widget set will be created.

[1] has information on a project that was making it easier to create these

Creating window layouts using xml

To ease the chore of defining windows and their hierarchy trough code, you can create them using xml.

schema example

Just like in code, the xml layout schema expects one root window, as child of the xmlroot. The element names follow the name and casing of the classes. the third kind of element are property name value pairs, and then there are the events, this window has to emit.

loading an xml layout

If I would get it to work I'd say :) ...

3D objects rendered on CEGUI windows

using RenderToTexture and an imageset we can display an axiom scene on Gui elements, like for an overhead map, character or weapon selection menu, etc

creating your own window scripts.

this is more CEGUI specific but might be required at some point...

Examples