Crazy Eddie's GUI System  0.8.5
Overview of system components

The following is intended as a high level overview of the CEGUI system; the core components are described as are the general relationships between the components. Once you have finished reading this section you should have a basic understanding of the way CEGUI operates.


Much of the functionality of CEGUI is exposed - in one way or another - via abstracted interfaces that allow the user of the library to customise the precise way that various functionality is implemented. Whether it's rendering imagery, loading image data, parsing XML files, or any number of other aspects, there usually exists a mechanism for the library user to select - or create - a solution tailored to the needs of their individual project.

Low Level Interface Objects

For the most part, the entire CEGUI system is initialised in one step when the CEGUI::System object is created. The user can pass the System::create function their choice of Renderer object as well as other options like a ResourceProvider, an XMLParser and an ImageCodec (if any of three latter objects are not provided default options are used instead). These four objects - that is the Renderer, XMLParser, ImageCodec and ResourceProvider - essentially form a bridge from the CEGUI world to the world outside; these objects are key, so each will be briefly described here so you know the role they play.

The Renderer object is the top level implementation of a set of interfaces that perform rendering - and other video system related services - for CEGUI.
The ResourceProvider object basically loads data indicated by a resource group and a resource name into memory buffers. The exact mechanism employed to do this is not specified - so while for the most part this will likely involve loading file based data from disk, it's possible for a ResourceProvider implementation to use any other mechanism instead (or as well).
The XMLParser abstracts access to lower level XML parsing libraries, such as Expat or Xerces-C++. The XMLParser is then used by various components within the CEGUI system when they require XML data - obtained via the ResourceProvider - to be parsed.
The ImageCodec abstracts access to lower level image reading libraries, such as FreeImage or DevIL. The ImageCodec is then used by other CEGUI system components to parse image file data - obtained via the ResouceProvider - into source imagery used by CEGUI::Texture objects - as created by the Renderer object.

System and Manager Objects

The System object provides system wide options, settings and functions, as well as access to other non-singleton objects (such as the previously described Renderer, ResourceProvider, XMLParser and ImageCodec objects).

When the core CEGUI::System object is created the system also creates a set of manager objects that are subsequently used to interact with various parts of CEGUI. The main group of managers - as used in the majority of applications - are the ImageManager, the FontManager, the SchemeManager and the WindowManager. The remaining manager objects, the AnimationManager, the RenderEffectManager the WindowRendererManager, the WindowFactoryManager and the WidgetLookManager are generally only needed by library users when they come to extend or customise the windows and widgets available to the system or to do things via code that are more normally accomplished via XML data files.

The key to understanding CEGUI is in these managers. Generally you do not directly create and destroy objects in CEGUI (meaning you do not use the C++ new and delete keywords), but rather you use an appropriate manager object to create the object for you. The managers keep track of all the objects created and - because each created object has a name - you can use the managers to get access to created objects at a later time. This arrangement also aids in cleaning up the system when you're done; CEGUI will destroy any remaining objects automatically when it is closed down (via the System::destroy function).

The ImageManager manages CEGUI::Image based objects. Image is an interface that defines needed operations for CEGUI to handle imagery and is typically the lowest level abstraction of imagery used by CEGUI; when you - or the system itself - wants to draw something, this typically entails an Image object submitting geometry to a GeometryBuffer provided via the Renderer. Each Image must have a name that is unique within the system, allowing the Image instances to be retrieved via the ImageManager by specifying the name of the Image. At least initially, it is likely that all the Image instances you use will be of the type CEGUI::BasicImage. BasicImage is an Image subclass that represents a rectangular region on a texture. In this way, it is possible for a single texture to contain multiple sub-images that can then be used by CEGUI - this is a highly efficient approach to texture management and is usually referred to as a texture atlas. When using CEGUI, the general way you define the set of images provided by a texture atlas is to provide an Imageset definition file - this is an XML file that specifies the name of the texture or image file and definitions for the sub-images that are part of the atlas.
The FontManager manages CEGUI::Font objects. In CEGUI a Font is - unsurprisingly - an abstraction of a typeface of some kind and is used to render textual information. You should be aware that - beneath the surface - the entire font system is actually built on top of the Imageset system; when a font is used to draw text it accesses one or more Imageset objects holding the imagery for the text glyphs to be drawn.
The SchemeManager manages CEGUI::Scheme objects. A CEGUI Scheme is essentially a collection of references to other resources and so provides a means to group resources and definitions that are to be loaded together; essentially a Scheme represents a top-level means to form a GUI 'skin'.
The WindowManager manages CEGUI::Window based objects and is the means by which you will create and manage the windows and widgets of your GUIs.
The AnimationManager offers functions to manage animation definitions and create instances of those animations within the system. Generally, animations are defined via XML - either in their own animation XML file or as part of the WidgetLook definitions in the Falagard "look n feel" skin definition XML.
The RenderEffectManager is where RenderEffect types are registered with the system. Note that CEGUI does not come with any 'stock' RenderEffects although some examples are provided within the CEGUI samples. RenderEffects are registered with a name and this name is then used in mappings to associate the effect with a window type that you later create via the WindowManager.
Every type of Window based object is required to have a WindowFactory based object that creates and destroys instances of that specific window type. WindowFactoryManager is where these WindowFactory objects are registered with the system. Unless you are registering new concrete Window based classes with the system (or are doing some other advanced operation), you will not need to directly interact with the WindowFactoryManager.
The core Window based objects generally do not perform any specific drawing operations; rather they are only concerned with the logic of the window's implementation. The visual aspects of window objects are delegated to an associated WindowRenderer object. The WindowRendererManager keeps track of the WindowRenderer objects registered with the system. Again, except when creating new window or widget types, you will not usually need to interact with the WindowRendererManager.
The WidgetLookManager is the last manager object, it is part of the Falagard skinning system for CEGUI and manages WidgetLookFeel objects as loaded from XML LookNFeel files (actually it's possible to define such objects in code alone, but this is rarely - if ever - done). Again, unless you're accessing WidgetLookFeel objects from a custom Window or WindowRenderer implementation, you will not usually need to use the WidgetLookManager directly.

Falagard Mappings

The Window, WindowRenderer and WidgetLookFeel objects are the CEGUI system's 'holy trinity'. They each provide part of the functionality required to represent a fully working, interactive window or widget, and are combined via what is known as a "Falagard Mapping" (typically defined in scheme XML files, though of course can also be made in code by accessing the WindowFactoryManager). A falagard mapping is a means to provide a type name to a grouped concrete window or widget type providing the core logic of the widget, a window renderer providing high-level rendering instructions, a WidgetLookFeel providing the lower-level definitions to be used by the window and window renderer and, optionally, a RenderEffect to handle any special rendering effects required. It is these mapped type names that are typically used when creating windows within the system and frees you from the complexity of needing to create and manage instances of these objects manually.