@c -*-texinfo-*-
@node CEGUI, Making Own Projects, AWS2, Using Crystal Space
@section @sc{cegui} Introduction
@noindent
@emph{Written by Seth Yastrov, @email{syastrov@@users.sourceforge.net} and
Dan H@"ardfeldt, @email{swedishcoder@@users.sourceforge.net}.}

@subheading The @sc{cegui} Plugin

The @sc{cegui} plugin is a wrapper around @sc{cegui}, an embeddable widget
library, so it can be easily used from within Crystal Space applications. The
plugin provides a renderer, a @sc{vfs} resource provider, and an event handler
for @sc{cegui}. You will need version 0.4.1 or 0.5.0 of @sc{cegui}.

@noindent
@uref{http://www.cegui.org.uk/}

@subheading Initialization

All components of the @sc{cegui} plugin are set up when the application calls
@code{iCEGUI::Initialize()}. This function will initialize @sc{cegui} and tell
it to use the @sc{cegui} plugin renderer and event handler. It is not necessary
to create a new @code{CEGUI::System()} in your application as this is
performed automatically by the Crystal Space @sc{cegui} plugin.

@subheading Renderer

To render the graphical user interface (@sc{gui}), use convenience function,
@code{iCEGUI::Render()}.  This function may be called from anywhere in the
application to allow the ability to render to an alternate render target (like
procedural textures).  In applications based upon @samp{csBaseEventHandler}, it
is called typically in @code{ProcessFrame()}, sandwiched somewhere between
@code{BeginDraw()} and @samp{FinishDraw()} calls.

@subheading Singletons

It is important that applications using @sc{cegui} from Crystal Space do not
use any of the @sc{cegui} @code{getSingleton()} or @code{getSingletonPtr()}
calls, such as @code{CEGUI::Singleton<T>::getSingleton()} or
@code{CEGUI::System::getSingleton()}.  The reason for this is that global and
static variables (declared in methods, classes, namespaces, or globally) are
not normally shared between modules.  Calling @code{getSingleton()} from the
Crystal Space application will not necessarily return the same instance as
calling @code{getSingleton()} from the @sc{cegui} plugin.

To remedy this, there are @samp{Get*} functions in the @samp{iCEGUI} interface
that return a reference or pointer to the @sc{cegui} singletons so that they
may be used safely from a Crystal Space application. @code{iCEGUI::GetSystem()}
and @code{GetSystemPtr()} are the most commonly used.

@subheading Resource Provider

The @sc{cegui} plugin provides a @sc{vfs} implementation of the @sc{cegui}
resource provider.  This means that all paths passed to @sc{cegui} functions
should be @sc{vfs} paths.  Textures, scheme files, layout files, etc, will all
be loaded through the @sc{vfs}.  Paths within these files should be @sc{vfs}
paths as well.

@subheading Event Handler

Keyboard and mouse input is automatically injected into the @sc{cegui} event
system by the @sc{cegui} plugin event handler. The @sc{cegui} display area is
automatically resized when the Crystal Space canvas is resized.
