CEGUI Wiki - Crazy Eddie's GUI System (Open Source) - User contributions [en]

Using CEGUI with Producer and OpenGL

2005-09-24T07:13:21Z

Granx:

[http://www.andesengineering.com/Producer/ Producer] is a cross platform toolkit, best explained on its website. I use it for many things, but creating a window, or Render Surface, is the most fundamental task. CEGUI requires knowledge of the window, mouse, and keyboard interaction. I will show how you can do that with some example code.

=== Defining a Producer Viewer ===
The first step is to create some sort of "viewer" with Producer, basically make a Producer::RenderSurface and a Producer::KeyboardMouse. Both of these classes are necessary for using CEGUI correctly. Your job is just to create these so they can be used later. There is no CEGUI code involved at this point. So, here is some example viewer code:

#include "Viewer.h"
Viewer::Viewer() : _camera(new Producer::Camera()), _rs(0), _kbm(0)
{
_rs = _camera->getRenderSurface(); // a Camera creates a RenderSurface, grab it
_kbm = new Producer::KeyboardMouse(_rs.get()); // make a new KeyboardMouse
}

=== Initializing the Viewer in an Application ===
And an application might use this viewer, doing some important initializations:

Application::Application(const std::string& fontfile):
_status(RUNNING), _viewer(new Viewer()), _sim(new TeapotSim()),
_scheme_loader("MouseArrow"), _layout_loader(), _script_module(new ApplicationEventHandler())
{
// OpenGL context specific initializations
Producer::ref_ptr<Producer::RenderSurface> rs = _viewer->GetRenderSurface();
rs->addRealizeCallback(new InitGL() );
rs->addRealizeCallback(new InitCEGUI(fontfile,_script_module) );
rs->setWindowName( "Producer and CEGUI example" );
rs->setWindowRectangle(20,50,800,600);

// rendering stuff
_viewer->GetCamera()->setSceneHandler( _sim.get() ); // draw the simulation graphics
_viewer->GetCamera()->addPostDrawCallback(new RenderCEGUI() ); // renders the GUI over scene

// device input stuff
Producer::ref_ptr<Producer::KeyboardMouse> kbm = _viewer->GetKeyboardMouse();
prce::Injector* injector = new prce::Injector( kbm.get() );
kbm->setCallback( injector );
kbm->startThread();
}

The InitGL and InitCEGUI functors are both specific to using CEGUI with Producer, and are quite important steps. Much of these initializations are OpenGL specific, and therefore must occur within a thread with the right OpenGL context. The Producer::RenderSurface can execute one-time initializations if you add them to be called upon window realization, with the Producer::RenderSurface::addRealizeCallback function which takes an instance to a class that derives from Producer::RenderSurface::Callback. Both InitGL and InitCEGUI are classes which derive from this Callback. I'll show what they need to do later in the tutorial.

Actually, a lot (more) is happening in the Application's constructor. Much of this is specific to using Producer. I recommend reading the examples in Producer's distribution, but this example might sumarize some things for those of you new to using it. The Producer::Camera class needs a 'SceneHandler' to perform draw calls. This is the heart of the application's rendering. I am showing an application that is named 'TeapotSim'. It is just an example showing OpenGL's famous teapot spinning. The SceneHandler instance must be set, and that is passed as a pointer to the Producer::Camera::addSceneHandler function. The Camera instance will call the SceneHandler::draw function as part of the render loop.

Another point in the render loop is the post-draw stage. I used this stage to do more drawing, just like what my simulation would be doing, but in this stage I will be drawing the CEGUI, so that it will always be drawn last, and on top of the other graphics.

=== Initializing CEGUI for Producer ===
Now, I want to show an example of initializing CEGUI:

#include <CEGUISystem.h>
#include <renderers/OpenGLGUIRenderer/openglrenderer.h>
#include <CEGUIScriptModule.h>
#include <CEGUIFontManager.h>

#include "InitCEGUI.h"

InitCEGUI::InitCEGUI(const std::string& font, CEGUI::ScriptModule* s): _sm(s), _font(font)
{
}

InitCEGUI::~InitCEGUI()
{
}

void InitCEGUI::operator ()(const Producer::RenderSurface& rs)
{
if( _sm )
new CEGUI::System( new CEGUI::OpenGLRenderer(0), _sm );
else
new CEGUI::System( new CEGUI::OpenGLRenderer(0) );

CEGUI::FontManager* fm = CEGUI::FontManager::getSingletonPtr();
CEGUI::Font* f = fm->createFont( _font );
}

Producer uses OpenGL for rendering, so that is the renderer we must choose. Luckily, CEGUI provides this. If you want your application to use a CEGUI::ScriptModule, you will need to provide a when initializing the CEGUI::System, but that is for another lesson. A default font needs to be provided to the System, and during initialization is a good time to provide that, so my functor has required it.

=== Rendering CEGUI with Producer ===
The application code showed a post draw callback being set. Producer will execute this little callback at the right time, within the correct OpenGL context for OpenGL calls. Here is what needs to happen for CEGUI to appear on your screen each frame:

void RenderCEGUI::operator ()(const Producer::Camera& c)
{
CEGUI::System::getSingleton().renderGUI();
}

=== Injecting Input to CEGUI via Producer ===
This is where the real magic happens. You must inject inputs into CEGUI because it does not poll the operating system for you. That is the job of a tool like Producer. For the most part, the following code works. There is a small bug that is only seen when resizing the Producer::RenderSurface (window). However, I think it provides insight into how injections need to be done for CEGUI to react to user input:

/** \author John K. Grant
* \date July, 14 2005.
* This code is public domain, free for use, with the author having no responsibility or liability.
*/
#include <CEGUISystem.h>
#include "SpecialKeyMapFunctor.h"
#include "Injector.h"

using namespace prce;

Injector::Injector(Producer::KeyboardMouse* kbm): _kbm(kbm)
{
prce::SpecialKeyMapFunctor specials;
_keys = specials();
}

Injector::~Injector()
{
}

/** changes from producer coordinates to normalized CE coordinates */
void Injector::_producer_to_cegui(float& mx, float& my)
{
// --- horizontal math
// ph = 1.0 - -1.0 = 2.0 // total horizontal distance in producer
// ch = 1.0 - 0.0 = 1.0 // total horizontal distance in ce

// --- vertical math
// pv = 1.0 - -1.0 = 2.0 // total vertical distance in producer
// cv = 0.0 - 1.0 = -1.0 // total vertical distance in ce

// cex = cx + px * (ch/2 / ph/2) = 0.5 + px * ( 0.5/1.0) = 0.5 + px*0.5
// cey = cy + py * (cv/2 / pv/2) = 0.5 + py * (-0.5/1.0) = 0.5 - py*0.5
// where cx is the "center" x value in ce
// and cy is the "center" y value in ce
float cex(0.5 + mx*0.5);
float cey(0.5 - my*0.5);
mx = cex;
my = cey;
}

/** takes normalized CEGUI coordinates and converts
* into pixel values for the screen.
*/
void Injector::_convert_to_screen(float& mx, float& my)
{
unsigned int width( _kbm->getRenderSurface()->getWindowWidth() );
unsigned int height( _kbm->getRenderSurface()->getWindowHeight() );

// the above yields the same results as the code below
//int wx(0), wy(0);
//unsigned int width(0), height(0);
//_kbm->getRenderSurface()->getWindowRectangle(wx,wy,width,height);

float pixel_x = (float)width * mx;
float pixel_y = (float)height * my;
mx = pixel_x;
my = pixel_y;
}

void Injector::mouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::passiveMouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::buttonPress(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
}

void Injector::buttonRelease(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::doubleButtonPress(float px,float py,unsigned int button)
{
/** currently is implemented to only inject a single press.
* CEGUI handles its own detection of the double click via
* the "time pulse", which controls other things as well.
*/
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px,py);
if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::mouseScroll(enum Producer::KeyboardMouseCallback::ScrollingMotion motion)
{
switch( motion )
{
case Producer::KeyboardMouseCallback::ScrollDown:
{
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
} break;

case Producer::KeyboardMouseCallback::ScrollUp:
{
CEGUI::System::getSingleton().injectMouseWheelChange( 1 );
} break;

default: // Producer::KeyboardMouseCallback::ScrollNone
break;
};
}

void Injector::keyPress(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(key) );
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( key ) );
}

void Injector::keyRelease(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(key) );
}

void Injector::specialKeyPress(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(cekey) );
}
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( prkey ) );
}

void Injector::specialKeyRelease(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(cekey) );
}
}

=== Using it all together ===
Here is what a simple main() will look like:

int main(unsigned int argc, char* argv[])
{
if( argc < 4 )
{
PrintUsage();
return 1;
}

Producer::ref_ptr<example::Application> app = new example::Application(argv[1]);
app->GetViewer()->GetRenderSurface()->realize();

app->LoadCEGUIScheme( argv[2] );
app->LoadCEGUILayout( argv[3] );

while( !app->IsFinished() )
{
app->GetViewer()->GetCamera()->frame();
}

return 0;
}

Using CEGUI with Producer and OpenGL

2005-09-24T07:06:09Z

Granx: /* Initializing the Viewer in an Application */

[http://www.andesengineering.com/Producer/ Producer] is a cross platform toolkit, best explained on its website. I use it for many things, but creating a window, or Render Surface, is the most fundamental task. CEGUI requires knowledge of the window, mouse, and keyboard interaction. I will show how you can do that with some example code.

=== Defining a Producer Viewer ===
The first step is to create some sort of "viewer" with Producer, basically make a Producer::RenderSurface and a Producer::KeyboardMouse. Both of these classes are necessary for using CEGUI correctly. Your job is just to create these so they can be used later. There is no CEGUI code involved at this point. So, here is some example viewer code:

#include "Viewer.h"
Viewer::Viewer() : _camera(new Producer::Camera()), _rs(0), _kbm(0)
{
_rs = _camera->getRenderSurface(); // a Camera creates a RenderSurface, grab it
_kbm = new Producer::KeyboardMouse(_rs.get()); // make a new KeyboardMouse
}

=== Initializing the Viewer in an Application ===
And an application might use this viewer, doing some important initializations:

Application::Application(const std::string& fontfile):
_status(RUNNING), _viewer(new Viewer()), _sim(new TeapotSim()),
_scheme_loader("MouseArrow"), _layout_loader(), _script_module(new ApplicationEventHandler())
{
// OpenGL context specific initializations
Producer::ref_ptr<Producer::RenderSurface> rs = _viewer->GetRenderSurface();
rs->addRealizeCallback(new InitGL() );
rs->addRealizeCallback(new InitCEGUI(fontfile,_script_module) );
rs->setWindowName( "Producer and CEGUI example" );
rs->setWindowRectangle(20,50,800,600);

// rendering stuff
_viewer->GetCamera()->setSceneHandler( _sim.get() ); // draw the simulation graphics
_viewer->GetCamera()->addPostDrawCallback(new RenderCEGUI() ); // renders the GUI over scene

// device input stuff
Producer::ref_ptr<Producer::KeyboardMouse> kbm = _viewer->GetKeyboardMouse();
prce::Injector* injector = new prce::Injector( kbm.get() );
kbm->setCallback( injector );
kbm->startThread();
}

The InitGL and InitCEGUI functors are both specific to using CEGUI with Producer, and are quite important steps. Much of these initializations are OpenGL specific, and therefore must occur within a thread with the right OpenGL context. The Producer::RenderSurface can execute one-time initializations if you add them to be called upon window realization, with the Producer::RenderSurface::addRealizeCallback function which takes an instance to a class that derives from Producer::RenderSurface::Callback. Both InitGL and InitCEGUI are classes which derive from this Callback. I'll show what they need to do later in the tutorial.

Actually, a lot (more) is happening in the Application's constructor. Much of this is specific to using Producer. I recommend reading the examples in Producer's distribution, but this example might sumarize some things for those of you new to using it. The Producer::Camera class needs a 'SceneHandler' to perform draw calls. This is the heart of the application's rendering. I am showing an application that is named 'TeapotSim'. It is just an example showing OpenGL's famous teapot spinning. The SceneHandler instance must be set, and that is passed as a pointer to the Producer::Camera::addSceneHandler function. The Camera instance will call the SceneHandler::draw function as part of the render loop.

Another point in the render loop is the post-draw stage. I used this stage to do more drawing, just like what my simulation would be doing, but in this stage I will be drawing the CEGUI, so that it will always be drawn last, and on top of the other graphics.

The Camera's draw callbacks are very important, but first I want to show an example of initializing CEGUI:

#include <CEGUISystem.h>
#include <renderers/OpenGLGUIRenderer/openglrenderer.h>
#include <CEGUIScriptModule.h>
#include <CEGUIFontManager.h>

#include "InitCEGUI.h"

InitCEGUI::InitCEGUI(const std::string& font, CEGUI::ScriptModule* s): _sm(s), _font(font)
{
}

InitCEGUI::~InitCEGUI()
{
}

void InitCEGUI::operator ()(const Producer::RenderSurface& rs)
{
if( _sm )
new CEGUI::System( new CEGUI::OpenGLRenderer(0), _sm );
else
new CEGUI::System( new CEGUI::OpenGLRenderer(0) );

CEGUI::FontManager* fm = CEGUI::FontManager::getSingletonPtr();
CEGUI::Font* f = fm->createFont( _font );
}

Producer uses OpenGL for rendering, so that is the renderer we must choose. Luckily, CEGUI provides this. You will need to provide a CEGUI::ScriptModule when initializing the System, but that is for another lesson. A default font needs to be provided to the System, and during initialization is a good time to provide that, so my functor has required it.

=== Rendering CEGUI with Producer ===
The application code showed a post draw callback being set. Producer will execute this little callback at the right time, within the correct OpenGL context for OpenGL calls. Here is what needs to happen for CEGUI to appear on your screen each frame:

void RenderCEGUI::operator ()(const Producer::Camera& c)
{
CEGUI::System::getSingleton().renderGUI();
}

=== Injecting Input to CEGUI via Producer ===
This is where the real magic happens. You must inject inputs into CEGUI because it does not poll the operating system for you. That is the job of a tool like Producer. For the most part, the following code works. There is a small bug that is only seen when resizing the Producer::RenderSurface (window). However, I think it provides insight into how injections need to be done for CEGUI to react to user input:

/** \author John K. Grant
* \date July, 14 2005.
* This code is public domain, free for use, with the author having no responsibility or liability.
*/
#include <CEGUISystem.h>
#include "SpecialKeyMapFunctor.h"
#include "Injector.h"

using namespace prce;

Injector::Injector(Producer::KeyboardMouse* kbm): _kbm(kbm)
{
prce::SpecialKeyMapFunctor specials;
_keys = specials();
}

Injector::~Injector()
{
}

/** changes from producer coordinates to normalized CE coordinates */
void Injector::_producer_to_cegui(float& mx, float& my)
{
// --- horizontal math
// ph = 1.0 - -1.0 = 2.0 // total horizontal distance in producer
// ch = 1.0 - 0.0 = 1.0 // total horizontal distance in ce

// --- vertical math
// pv = 1.0 - -1.0 = 2.0 // total vertical distance in producer
// cv = 0.0 - 1.0 = -1.0 // total vertical distance in ce

// cex = cx + px * (ch/2 / ph/2) = 0.5 + px * ( 0.5/1.0) = 0.5 + px*0.5
// cey = cy + py * (cv/2 / pv/2) = 0.5 + py * (-0.5/1.0) = 0.5 - py*0.5
// where cx is the "center" x value in ce
// and cy is the "center" y value in ce
float cex(0.5 + mx*0.5);
float cey(0.5 - my*0.5);
mx = cex;
my = cey;
}

/** takes normalized CEGUI coordinates and converts
* into pixel values for the screen.
*/
void Injector::_convert_to_screen(float& mx, float& my)
{
unsigned int width( _kbm->getRenderSurface()->getWindowWidth() );
unsigned int height( _kbm->getRenderSurface()->getWindowHeight() );

// the above yields the same results as the code below
//int wx(0), wy(0);
//unsigned int width(0), height(0);
//_kbm->getRenderSurface()->getWindowRectangle(wx,wy,width,height);

float pixel_x = (float)width * mx;
float pixel_y = (float)height * my;
mx = pixel_x;
my = pixel_y;
}

void Injector::mouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::passiveMouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::buttonPress(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
}

void Injector::buttonRelease(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::doubleButtonPress(float px,float py,unsigned int button)
{
/** currently is implemented to only inject a single press.
* CEGUI handles its own detection of the double click via
* the "time pulse", which controls other things as well.
*/
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px,py);
if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::mouseScroll(enum Producer::KeyboardMouseCallback::ScrollingMotion motion)
{
switch( motion )
{
case Producer::KeyboardMouseCallback::ScrollDown:
{
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
} break;

case Producer::KeyboardMouseCallback::ScrollUp:
{
CEGUI::System::getSingleton().injectMouseWheelChange( 1 );
} break;

default: // Producer::KeyboardMouseCallback::ScrollNone
break;
};
}

void Injector::keyPress(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(key) );
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( key ) );
}

void Injector::keyRelease(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(key) );
}

void Injector::specialKeyPress(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(cekey) );
}
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( prkey ) );
}

void Injector::specialKeyRelease(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(cekey) );
}
}

=== Using it all together ===
Here is what a simple main() will look like:

int main(unsigned int argc, char* argv[])
{
if( argc < 4 )
{
PrintUsage();
return 1;
}

Producer::ref_ptr<example::Application> app = new example::Application(argv[1]);
app->GetViewer()->GetRenderSurface()->realize();

app->LoadCEGUIScheme( argv[2] );
app->LoadCEGUILayout( argv[3] );

while( !app->IsFinished() )
{
app->GetViewer()->GetCamera()->frame();
}

return 0;
}

Using CEGUI with Producer and OpenGL

2005-09-24T06:46:29Z

Granx: /* Defining a Producer Viewer */

[http://www.andesengineering.com/Producer/ Producer] is a cross platform toolkit, best explained on its website. I use it for many things, but creating a window, or Render Surface, is the most fundamental task. CEGUI requires knowledge of the window, mouse, and keyboard interaction. I will show how you can do that with some example code.

=== Defining a Producer Viewer ===
The first step is to create some sort of "viewer" with Producer, basically make a Producer::RenderSurface and a Producer::KeyboardMouse. Both of these classes are necessary for using CEGUI correctly. Your job is just to create these so they can be used later. There is no CEGUI code involved at this point. So, here is some example viewer code:

#include "Viewer.h"
Viewer::Viewer() : _camera(new Producer::Camera()), _rs(0), _kbm(0)
{
_rs = _camera->getRenderSurface(); // a Camera creates a RenderSurface, grab it
_kbm = new Producer::KeyboardMouse(_rs.get()); // make a new KeyboardMouse
}

=== Using the viewer in an Application ===
And an application might use this viewer, doing some important initializations:

Application::Application(const std::string& fontfile):
_status(RUNNING), _viewer(new general::Viewer()), _sim(new example::TeapotSim()),
_scheme_loader_policy("MouseArrow"), _layout_loader_policy(), _script_module(new ApplicationEventHandler())
{
// OpenGL context specific initializations
Producer::ref_ptr<Producer::RenderSurface> rs = _viewer->GetRenderSurface();
rs->addRealizeCallback(new general::InitGL());
rs->addRealizeCallback(new prce::InitCEGUI(fontfile,_script_module));
rs->setWindowName("Producer and CEGUI example");
rs->setWindowRectangle(20,50,800,600);

// rendering stuff
_viewer->GetCamera()->setSceneHandler( _sim.get() );
_viewer->GetCamera()->addPreDrawCallback( new SimulationDrawContext(_sim.get()) );
_viewer->GetCamera()->addPostDrawCallback(new prce::RenderCEGUI() ); // renders the GUI over scene

// device input stuff
Producer::ref_ptr<Producer::KeyboardMouse> kbm = _viewer->GetKeyboardMouse();
prce::Injector* injector = new prce::Injector( kbm.get() );
kbm->setCallback( injector );
kbm->startThread();
}

The general::InitGL functor and prce::InitCEGUI functor are quite important. These initializations are OpenGL specific, and must occur within a thread with the right OpenGL context. The Producer::RenderSurface can execute one-time initializations if you add them to be called upon window realization. Actually, a lot is happening here in the Application's constructor. You might be able to imagine how OpenGL is initialized, so I'll skip that for now. The Camera's draw callbacks are very important, but first I want to show an example of initializing CEGUI:

#include <CEGUISystem.h>
#include <renderers/OpenGLGUIRenderer/openglrenderer.h>
#include <CEGUIScriptModule.h>
#include <CEGUIFontManager.h>

#include "InitCEGUI.h"

using namespace prce;

InitCEGUI::InitCEGUI(const std::string& font, CEGUI::ScriptModule* s): _sm(s), _font(font)
{
}

InitCEGUI::~InitCEGUI()
{
}

void InitCEGUI::operator ()(const Producer::RenderSurface& rs)
{
if( _sm )
new CEGUI::System( new CEGUI::OpenGLRenderer(0), _sm );
else
new CEGUI::System( new CEGUI::OpenGLRenderer(0) );

CEGUI::FontManager* fm = CEGUI::FontManager::getSingletonPtr();
CEGUI::Font* f = fm->createFont( _font );
}

Producer uses OpenGL for rendering, so that is the renderer we must choose. Luckily, CEGUI provides this. You will need to provide a CEGUI::ScriptModule when initializing the System, but that is for another lesson. A default font needs to be provided to the System, and during initialization is a good time to provide that, so my functor has required it.

=== Rendering CEGUI with Producer ===
The application code showed a post draw callback being set. Producer will execute this little callback at the right time, within the correct OpenGL context for OpenGL calls. Here is what needs to happen for CEGUI to appear on your screen each frame:

void RenderCEGUI::operator ()(const Producer::Camera& c)
{
CEGUI::System::getSingleton().renderGUI();
}

=== Injecting Input to CEGUI via Producer ===
This is where the real magic happens. You must inject inputs into CEGUI because it does not poll the operating system for you. That is the job of a tool like Producer. For the most part, the following code works. There is a small bug that is only seen when resizing the Producer::RenderSurface (window). However, I think it provides insight into how injections need to be done for CEGUI to react to user input:

/** \author John K. Grant
* \date July, 14 2005.
* This code is public domain, free for use, with the author having no responsibility or liability.
*/
#include <CEGUISystem.h>
#include "SpecialKeyMapFunctor.h"
#include "Injector.h"

using namespace prce;

Injector::Injector(Producer::KeyboardMouse* kbm): _kbm(kbm)
{
prce::SpecialKeyMapFunctor specials;
_keys = specials();
}

Injector::~Injector()
{
}

/** changes from producer coordinates to normalized CE coordinates */
void Injector::_producer_to_cegui(float& mx, float& my)
{
// --- horizontal math
// ph = 1.0 - -1.0 = 2.0 // total horizontal distance in producer
// ch = 1.0 - 0.0 = 1.0 // total horizontal distance in ce

// --- vertical math
// pv = 1.0 - -1.0 = 2.0 // total vertical distance in producer
// cv = 0.0 - 1.0 = -1.0 // total vertical distance in ce

// cex = cx + px * (ch/2 / ph/2) = 0.5 + px * ( 0.5/1.0) = 0.5 + px*0.5
// cey = cy + py * (cv/2 / pv/2) = 0.5 + py * (-0.5/1.0) = 0.5 - py*0.5
// where cx is the "center" x value in ce
// and cy is the "center" y value in ce
float cex(0.5 + mx*0.5);
float cey(0.5 - my*0.5);
mx = cex;
my = cey;
}

/** takes normalized CEGUI coordinates and converts
* into pixel values for the screen.
*/
void Injector::_convert_to_screen(float& mx, float& my)
{
unsigned int width( _kbm->getRenderSurface()->getWindowWidth() );
unsigned int height( _kbm->getRenderSurface()->getWindowHeight() );

// the above yields the same results as the code below
//int wx(0), wy(0);
//unsigned int width(0), height(0);
//_kbm->getRenderSurface()->getWindowRectangle(wx,wy,width,height);

float pixel_x = (float)width * mx;
float pixel_y = (float)height * my;
mx = pixel_x;
my = pixel_y;
}

void Injector::mouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::passiveMouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::buttonPress(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
}

void Injector::buttonRelease(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::doubleButtonPress(float px,float py,unsigned int button)
{
/** currently is implemented to only inject a single press.
* CEGUI handles its own detection of the double click via
* the "time pulse", which controls other things as well.
*/
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px,py);
if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::mouseScroll(enum Producer::KeyboardMouseCallback::ScrollingMotion motion)
{
switch( motion )
{
case Producer::KeyboardMouseCallback::ScrollDown:
{
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
} break;

case Producer::KeyboardMouseCallback::ScrollUp:
{
CEGUI::System::getSingleton().injectMouseWheelChange( 1 );
} break;

default: // Producer::KeyboardMouseCallback::ScrollNone
break;
};
}

void Injector::keyPress(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(key) );
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( key ) );
}

void Injector::keyRelease(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(key) );
}

void Injector::specialKeyPress(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(cekey) );
}
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( prkey ) );
}

void Injector::specialKeyRelease(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(cekey) );
}
}

=== Using it all together ===
Here is what a simple main() will look like:

int main(unsigned int argc, char* argv[])
{
if( argc < 4 )
{
PrintUsage();
return 1;
}

Producer::ref_ptr<example::Application> app = new example::Application(argv[1]);
app->GetViewer()->GetRenderSurface()->realize();

app->LoadCEGUIScheme( argv[2] );
app->LoadCEGUILayout( argv[3] );

while( !app->IsFinished() )
{
app->GetViewer()->GetCamera()->frame();
}

return 0;
}

Using CEGUI with Producer and OpenGL

2005-09-24T06:44:25Z

Granx: /* Defining a Producer Viewer */

[http://www.andesengineering.com/Producer/ Producer] is a cross platform toolkit, best explained on its website. I use it for many things, but creating a window, or Render Surface, is the most fundamental task. CEGUI requires knowledge of the window, mouse, and keyboard interaction. I will show how you can do that with some example code.

=== Defining a Producer Viewer ===
The first step is to create some sort of "viewer" with Producer, basically make a Producer::RenderSurface and a Producer::KeyboardMouse. Both of these classes are necessary for using CEGUI correctly. Your just is just to create these so they can be used later. There is no CEGUI code involved at this point. So, here is some example viewer code:

#include "Viewer.h"
Viewer::Viewer() : _camera(new Producer::Camera()), _rs(0), _kbm(0)
{
_rs = _camera->getRenderSurface();
_kbm = new Producer::KeyboardMouse(_rs.get());
}

Viewer::~Viewer() {}

=== Using the viewer in an Application ===
And an application might use this viewer, doing some important initializations:

Application::Application(const std::string& fontfile):
_status(RUNNING), _viewer(new general::Viewer()), _sim(new example::TeapotSim()),
_scheme_loader_policy("MouseArrow"), _layout_loader_policy(), _script_module(new ApplicationEventHandler())
{
// OpenGL context specific initializations
Producer::ref_ptr<Producer::RenderSurface> rs = _viewer->GetRenderSurface();
rs->addRealizeCallback(new general::InitGL());
rs->addRealizeCallback(new prce::InitCEGUI(fontfile,_script_module));
rs->setWindowName("Producer and CEGUI example");
rs->setWindowRectangle(20,50,800,600);

// rendering stuff
_viewer->GetCamera()->setSceneHandler( _sim.get() );
_viewer->GetCamera()->addPreDrawCallback( new SimulationDrawContext(_sim.get()) );
_viewer->GetCamera()->addPostDrawCallback(new prce::RenderCEGUI() ); // renders the GUI over scene

// device input stuff
Producer::ref_ptr<Producer::KeyboardMouse> kbm = _viewer->GetKeyboardMouse();
prce::Injector* injector = new prce::Injector( kbm.get() );
kbm->setCallback( injector );
kbm->startThread();
}

The general::InitGL functor and prce::InitCEGUI functor are quite important. These initializations are OpenGL specific, and must occur within a thread with the right OpenGL context. The Producer::RenderSurface can execute one-time initializations if you add them to be called upon window realization. Actually, a lot is happening here in the Application's constructor. You might be able to imagine how OpenGL is initialized, so I'll skip that for now. The Camera's draw callbacks are very important, but first I want to show an example of initializing CEGUI:

#include <CEGUISystem.h>
#include <renderers/OpenGLGUIRenderer/openglrenderer.h>
#include <CEGUIScriptModule.h>
#include <CEGUIFontManager.h>

#include "InitCEGUI.h"

using namespace prce;

InitCEGUI::InitCEGUI(const std::string& font, CEGUI::ScriptModule* s): _sm(s), _font(font)
{
}

InitCEGUI::~InitCEGUI()
{
}

void InitCEGUI::operator ()(const Producer::RenderSurface& rs)
{
if( _sm )
new CEGUI::System( new CEGUI::OpenGLRenderer(0), _sm );
else
new CEGUI::System( new CEGUI::OpenGLRenderer(0) );

CEGUI::FontManager* fm = CEGUI::FontManager::getSingletonPtr();
CEGUI::Font* f = fm->createFont( _font );
}

Producer uses OpenGL for rendering, so that is the renderer we must choose. Luckily, CEGUI provides this. You will need to provide a CEGUI::ScriptModule when initializing the System, but that is for another lesson. A default font needs to be provided to the System, and during initialization is a good time to provide that, so my functor has required it.

=== Rendering CEGUI with Producer ===
The application code showed a post draw callback being set. Producer will execute this little callback at the right time, within the correct OpenGL context for OpenGL calls. Here is what needs to happen for CEGUI to appear on your screen each frame:

void RenderCEGUI::operator ()(const Producer::Camera& c)
{
CEGUI::System::getSingleton().renderGUI();
}

=== Injecting Input to CEGUI via Producer ===
This is where the real magic happens. You must inject inputs into CEGUI because it does not poll the operating system for you. That is the job of a tool like Producer. For the most part, the following code works. There is a small bug that is only seen when resizing the Producer::RenderSurface (window). However, I think it provides insight into how injections need to be done for CEGUI to react to user input:

/** \author John K. Grant
* \date July, 14 2005.
* This code is public domain, free for use, with the author having no responsibility or liability.
*/
#include <CEGUISystem.h>
#include "SpecialKeyMapFunctor.h"
#include "Injector.h"

using namespace prce;

Injector::Injector(Producer::KeyboardMouse* kbm): _kbm(kbm)
{
prce::SpecialKeyMapFunctor specials;
_keys = specials();
}

Injector::~Injector()
{
}

/** changes from producer coordinates to normalized CE coordinates */
void Injector::_producer_to_cegui(float& mx, float& my)
{
// --- horizontal math
// ph = 1.0 - -1.0 = 2.0 // total horizontal distance in producer
// ch = 1.0 - 0.0 = 1.0 // total horizontal distance in ce

// --- vertical math
// pv = 1.0 - -1.0 = 2.0 // total vertical distance in producer
// cv = 0.0 - 1.0 = -1.0 // total vertical distance in ce

// cex = cx + px * (ch/2 / ph/2) = 0.5 + px * ( 0.5/1.0) = 0.5 + px*0.5
// cey = cy + py * (cv/2 / pv/2) = 0.5 + py * (-0.5/1.0) = 0.5 - py*0.5
// where cx is the "center" x value in ce
// and cy is the "center" y value in ce
float cex(0.5 + mx*0.5);
float cey(0.5 - my*0.5);
mx = cex;
my = cey;
}

/** takes normalized CEGUI coordinates and converts
* into pixel values for the screen.
*/
void Injector::_convert_to_screen(float& mx, float& my)
{
unsigned int width( _kbm->getRenderSurface()->getWindowWidth() );
unsigned int height( _kbm->getRenderSurface()->getWindowHeight() );

// the above yields the same results as the code below
//int wx(0), wy(0);
//unsigned int width(0), height(0);
//_kbm->getRenderSurface()->getWindowRectangle(wx,wy,width,height);

float pixel_x = (float)width * mx;
float pixel_y = (float)height * my;
mx = pixel_x;
my = pixel_y;
}

void Injector::mouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::passiveMouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::buttonPress(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
}

void Injector::buttonRelease(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::doubleButtonPress(float px,float py,unsigned int button)
{
/** currently is implemented to only inject a single press.
* CEGUI handles its own detection of the double click via
* the "time pulse", which controls other things as well.
*/
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px,py);
if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::mouseScroll(enum Producer::KeyboardMouseCallback::ScrollingMotion motion)
{
switch( motion )
{
case Producer::KeyboardMouseCallback::ScrollDown:
{
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
} break;

case Producer::KeyboardMouseCallback::ScrollUp:
{
CEGUI::System::getSingleton().injectMouseWheelChange( 1 );
} break;

default: // Producer::KeyboardMouseCallback::ScrollNone
break;
};
}

void Injector::keyPress(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(key) );
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( key ) );
}

void Injector::keyRelease(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(key) );
}

void Injector::specialKeyPress(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(cekey) );
}
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( prkey ) );
}

void Injector::specialKeyRelease(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(cekey) );
}
}

=== Using it all together ===
Here is what a simple main() will look like:

int main(unsigned int argc, char* argv[])
{
if( argc < 4 )
{
PrintUsage();
return 1;
}

Producer::ref_ptr<example::Application> app = new example::Application(argv[1]);
app->GetViewer()->GetRenderSurface()->realize();

app->LoadCEGUIScheme( argv[2] );
app->LoadCEGUILayout( argv[3] );

while( !app->IsFinished() )
{
app->GetViewer()->GetCamera()->frame();
}

return 0;
}

FAQ

2005-09-09T21:08:29Z

Granx: /* Build Questions */

== General Questions ==
=== What is CEGUI? ===
CEGUI is ''Crazy Eddie's Gui System''; a cross platform Gui/widget library for use in games and other multi-media projects where use of standard operating system Gui libraries is either not possible, or is very difficult.

=== How is CEGUI licensed? ===
CEGUI is licensed under the LGPL (Lesser/Library General Public License). For details of this license, please visit the following web-site: http://www.gnu.org/copyleft/lesser.html.

=== How much does CEGUI cost? ===
Nothing. The use of CEGUI is totally free within the bounds of the LGPL license as described above.

=== I am developing a commercial, closed-source product. Since CEGUI is licensed under LGPL, this means that can't I use the library, right? ===
No, that's not right. So long as you link dynamically to CEGUI and associated libraries, then you do not have to release any of your own source or .o/.obj files, though do carefully check the LGPL, and the licenses for the third party libraries for full details of what is and is not permissible.

=== I am not happy with the LGPL license, do you offer alternative licensing? ===
No. Alternative licensing is not available, nor is it planned.

=== Does CEGUI rely upon any third party libraries? If so what are they? ===
CEGUI currently depends upon the following external libraries:

* FreeType2
* Xerces-C++ (optional, built-in TinyXML parser is provided)

You will also require a supported rendering system, and some form of input library.
=== Where can I get these third party libraries? ===

* FreeType2: http://www.freetype.org/
* Xerces-C++: http://xml.apache.org/xerces-c/

=== Do I have to compile the third part libraries myself? ===
It depends. Under Linux and similar systems, you will need to perform your own compilation. For Microsoft® Windows® users, we have supplied packages containing binary versions of the libraries for a selection of popular compiler configurations.

=== You mentioned something about "supported rendering systems", what's that all about and which systems are supported? ===
CEGUI can be used with various rendering systems. There are currently CEGUI renderer modules for Microsoft® DirectX® 8.1 and 9, OpenGL, the Ogre engine, and the Irrlicht engine.

=== There is no renderer module for my rendering engine or API of choice, will other rendering system be supported? ===
It is likely that, over time, CEGUI will add support for other APIs and engines. Having said this, it is fairly simple to write your own renderer module for CEGUI, so you might consider taking that option if you do not want to wait.

=== And what about input libraries? ===
CEGUI requires you to ''inject'' inputs into it, these inputs can come from any source that you choose. All you need to do is pass mouse movements, mouse button up and down events, and keyboard inputs to CEGUI.

=== Why doesn't CEGUI collect its own inputs? Why do I need to inject the inputs myself? ===
CEGUI does not collect its own input so that the system can remain as flexible as possible. We didn't want to tie people down to one system or input library.

=== I have seen mention of a Lua scripting module, how can I get this? ===
'''TODO'''

=== I can't find many of the things you talk about in my crayzedsgui code, what's wrong? ===
You probably have one of the older Mk-1 alpha releases. Get the newer Mk-2 releases instead, the archive files for these generally have names with cegui_mk2 in them.

=== Why are there two versions of the system? ===
The Mk-1 version was a Windows®/DirectX® only library and was really a dry run for what became the Mk-2 system. There was only ever 'alpha' versions of the Mk-1 code, so it was never anywhere near finished.

=== Are the Mk-1 and Mk-2 systems interface compatible? ===
No. The interfaces of the two systems are totally different, although many of the general concepts have remained the same.

=== The Mk-1 system is so much more lightweight than the Mk-2 system. Can I still use the Mk-1 code? Is the Mk-1 code still being developed and supported? ===
Short Answer: Not really.

Long Answer: There were too many weak areas within the Mk-1 system and development on this version has ceased completely. There is no longer any support for the Mk-1 version; in general it would be better for everyone if they migrated to the Mk-2 version of the system.

=== I am having major troubles integrating CEGUI with my project, will you do it for me? ===
No. The CEGUI developers have enough to do without writing users projects for them.

=== I have (or think I have) found a bug. How should I proceed? ===
If you are certain that it's a bug and not, for example, a misunderstanding of what is happening, then the bug should be reported via the project bug tracking system. However, before submitting a bug to the tracker, it is asked that you first do a quick search to see if the bug has already been reported. If you are unsure whether something is a bug or not, then it may be discussed on the web site forums prior to submitting a bug report to the project bug tracker.

=== I notice that feature/widget 'X' is missing. Will this be added to CEGUI? ===
Requests for new features and/or widgets are welcomed. You can discuss such things on the web site forums and then submit a feature request to the project feature request tracking system. Although it is asked that you first search to ensure that the feature has not already been requested; if the feature has already been requested feel free to add a note to the tracker item stating your support for the feature request. Note that no promises are made with regards to which features will and will not be added, or how long such things will take, but all requests will be seriously considered.

=== How can I get involved with CEGUI development? ===
The best way to become involved is to visit the web site forums, state what your intentions are (to help in avoiding duplicated effort), and then start submitting some patches to the project patch tracking system.

=== Is there managed code / Microsoft .Net support for the CEGUI library? ===
Yes, there is ''ceguisharp'' at http://realmforgewiki.castlegobs.nl/index.php/CEGUI This is a C# port of the library which uses the excellent Axiom rendering engine.

=== This FAQ doesn't answer my question, what should I do now? ===
Feel free to post your question on the web site forums, somebody will gladly answer your question and/or offer further advice.

== Build Questions ==
(A work in Progress)
CEGUI Build
# General Requirements
# Dependency installs

# Building from CVS (unix systems)
# Configuring
Run cegui_mk2/bootstrap
# The build
Type 'make'

CEGUI Layout Editor Build
# Dependency installs (for versions > 0.4.0)
Install wxWidgets
# Building

== Usage Questions ==
=== What is the correct way to subscribe for an event? ===
Event notification is a vital aspect of GUI programming. CEGUI handles those using subscribers.
In order to subscribe a window for an event, you have to call the method 'Window::subscribeEvent', passing the function
to be called when the specified event occurs, and the instance on which the method is called.

class MyButtonHandler
{
private:
PushButton* mButton;

public:
MyButtonHandler::MyButtonHandler(PushButton* btn) : mButton(btn)
{
btn->subscribeEvent(PushButton::EventClicked, Event::Subscriber(MyButtonHandler::ButtonClicked,this));
}

MyButtonHandler::ButtonClicked()
{
//This function gets called when the button is clicked
std::cout << "Button clicked" << std::endl;
}

The 'subscribeEvent' method returns an Event::Connection, which can be used later to unsubscribe for a registered event with
the 'disconnect' method.

Event::Connection myCon = btn->subscribeEvent(...);

...

myCon->disconnect();

In order to totally remove the event itself, you have to call the 'removeEvent' function:
all the connections to the specified event will be disconnected.
There's also an Event::ScopedConnection, which can be used to auto-unsubscribe when the event goes out of scope.

Similar way for the scripted events, which can be subscribed with the 'subscribeScriptedEvent' method.
In addition, you can do it in XML, using this syntax:

<Event Name="Clicked" Function="luabtn_clicked" />

=== How can I make the ListBox highlight the selected item? ===
In order to highlight selected items you need to set selection brush image and the selection colours of that item. The selection image is modulated by the colours you set. Note, that the alpha component needs to be smaller than 1.0, for the content of the selected item to be seen.
// set selection highlight to a half transparent blue to red gradient.
colour blue(0.0, 0.0, 1.0, 0.5);
colour red(1.0, 0.0, 0.0, 0.5);
myListBoxItem->setSelectionColours(blue, blue, red, red);
// this default image is a simple white rectangle
myListBoxItem->setSelectionBrushImage("TaharezLook", "ListboxSelectionBrush");

=== How can I remove the border of a StaticImage? ===
Either put the following property into the window definition:
<Property Name="FrameEnabled" Value="false" />
Or set it by code:
myStaticImage->setFrameEnabled(false);

=== How can I set the background of a StaticImage? ===
The first thing you need in order to do this is an Imageset that defines the Image that you wish to use. When wanting to use an image file for this as you suggest, you basically have an imageset defined like this:
<?xml version="1.0" ?>
<Imageset Name="BackdropImageset" Imagefile="backdrop.tga" NativeHorzRes="1024" NativeVertRes="768" AutoScaled="true">
<Image Name="Backdrop" XPos="0" YPos="0" Width="1024" Height="768" />
</Imageset>

What this does is define an Imageset using the backdrop.tga. A single image "Backdrop" is defined that starts at location (0,0) and is 1024 x 768 in size. You should be careful in that the source image file should have dimensions that are powers of two - this is because the image is loaded as a texture, and may be stretched if the powers-of-two requirement is not observed.<br>
Once you have your imageset defined, you can load it either by adding a reference to it in whichever scheme you are loading, or manually using the ImagesetManager:
CEGUI::ImagesetManager::getSingleton().createImageset("myImageset.imagset");
Once the thing is loaded, you set the image into the StaticImage like so:
myStaticImage->setImage("BackdropImageset", "Backdrop");
Notice that the names we specify here are the ones that were originally specified in the imageset XML file.<br>

=== What properties are available for use in XML layouts, and what format do I use for the value strings? ===
Each widget has its properties placed within an appropriately named C++ namespace, so all you need to do is look up the appropriate namespace within the [http://www.cegui.org.uk/api_reference/namespaces.html namespaces section of the API reference].

Also, remember that properties are inherited. So for example, when looking up properties for a PushButton, also check the properties for ButtonBase and Window too - since these properties are also available to you.

=== I can't see the items I've added to my Combobox, how do I get the list to show when I press the button? ===

The height you specify for the combobox widget includes the height of the drop down list; it's not just for the 'Editbox' portion of the widget (the height of which is usually automatically determined based upon the font). Ensure that when specifying the height for your combobox, you have provided sufficient space for the list to appear.

FAQ

2005-09-09T21:03:41Z

Granx: /* Build Questions */

== General Questions ==
=== What is CEGUI? ===
CEGUI is ''Crazy Eddie's Gui System''; a cross platform Gui/widget library for use in games and other multi-media projects where use of standard operating system Gui libraries is either not possible, or is very difficult.

=== How is CEGUI licensed? ===
CEGUI is licensed under the LGPL (Lesser/Library General Public License). For details of this license, please visit the following web-site: http://www.gnu.org/copyleft/lesser.html.

=== How much does CEGUI cost? ===
Nothing. The use of CEGUI is totally free within the bounds of the LGPL license as described above.

=== I am developing a commercial, closed-source product. Since CEGUI is licensed under LGPL, this means that can't I use the library, right? ===
No, that's not right. So long as you link dynamically to CEGUI and associated libraries, then you do not have to release any of your own source or .o/.obj files, though do carefully check the LGPL, and the licenses for the third party libraries for full details of what is and is not permissible.

=== I am not happy with the LGPL license, do you offer alternative licensing? ===
No. Alternative licensing is not available, nor is it planned.

=== Does CEGUI rely upon any third party libraries? If so what are they? ===
CEGUI currently depends upon the following external libraries:

* FreeType2
* Xerces-C++ (optional, built-in TinyXML parser is provided)

You will also require a supported rendering system, and some form of input library.
=== Where can I get these third party libraries? ===

* FreeType2: http://www.freetype.org/
* Xerces-C++: http://xml.apache.org/xerces-c/

=== Do I have to compile the third part libraries myself? ===
It depends. Under Linux and similar systems, you will need to perform your own compilation. For Microsoft® Windows® users, we have supplied packages containing binary versions of the libraries for a selection of popular compiler configurations.

=== You mentioned something about "supported rendering systems", what's that all about and which systems are supported? ===
CEGUI can be used with various rendering systems. There are currently CEGUI renderer modules for Microsoft® DirectX® 8.1 and 9, OpenGL, the Ogre engine, and the Irrlicht engine.

=== There is no renderer module for my rendering engine or API of choice, will other rendering system be supported? ===
It is likely that, over time, CEGUI will add support for other APIs and engines. Having said this, it is fairly simple to write your own renderer module for CEGUI, so you might consider taking that option if you do not want to wait.

=== And what about input libraries? ===
CEGUI requires you to ''inject'' inputs into it, these inputs can come from any source that you choose. All you need to do is pass mouse movements, mouse button up and down events, and keyboard inputs to CEGUI.

=== Why doesn't CEGUI collect its own inputs? Why do I need to inject the inputs myself? ===
CEGUI does not collect its own input so that the system can remain as flexible as possible. We didn't want to tie people down to one system or input library.

=== I have seen mention of a Lua scripting module, how can I get this? ===
'''TODO'''

=== I can't find many of the things you talk about in my crayzedsgui code, what's wrong? ===
You probably have one of the older Mk-1 alpha releases. Get the newer Mk-2 releases instead, the archive files for these generally have names with cegui_mk2 in them.

=== Why are there two versions of the system? ===
The Mk-1 version was a Windows®/DirectX® only library and was really a dry run for what became the Mk-2 system. There was only ever 'alpha' versions of the Mk-1 code, so it was never anywhere near finished.

=== Are the Mk-1 and Mk-2 systems interface compatible? ===
No. The interfaces of the two systems are totally different, although many of the general concepts have remained the same.

=== The Mk-1 system is so much more lightweight than the Mk-2 system. Can I still use the Mk-1 code? Is the Mk-1 code still being developed and supported? ===
Short Answer: Not really.

Long Answer: There were too many weak areas within the Mk-1 system and development on this version has ceased completely. There is no longer any support for the Mk-1 version; in general it would be better for everyone if they migrated to the Mk-2 version of the system.

=== I am having major troubles integrating CEGUI with my project, will you do it for me? ===
No. The CEGUI developers have enough to do without writing users projects for them.

=== I have (or think I have) found a bug. How should I proceed? ===
If you are certain that it's a bug and not, for example, a misunderstanding of what is happening, then the bug should be reported via the project bug tracking system. However, before submitting a bug to the tracker, it is asked that you first do a quick search to see if the bug has already been reported. If you are unsure whether something is a bug or not, then it may be discussed on the web site forums prior to submitting a bug report to the project bug tracker.

=== I notice that feature/widget 'X' is missing. Will this be added to CEGUI? ===
Requests for new features and/or widgets are welcomed. You can discuss such things on the web site forums and then submit a feature request to the project feature request tracking system. Although it is asked that you first search to ensure that the feature has not already been requested; if the feature has already been requested feel free to add a note to the tracker item stating your support for the feature request. Note that no promises are made with regards to which features will and will not be added, or how long such things will take, but all requests will be seriously considered.

=== How can I get involved with CEGUI development? ===
The best way to become involved is to visit the web site forums, state what your intentions are (to help in avoiding duplicated effort), and then start submitting some patches to the project patch tracking system.

=== Is there managed code / Microsoft .Net support for the CEGUI library? ===
Yes, there is ''ceguisharp'' at http://realmforgewiki.castlegobs.nl/index.php/CEGUI This is a C# port of the library which uses the excellent Axiom rendering engine.

=== This FAQ doesn't answer my question, what should I do now? ===
Feel free to post your question on the web site forums, somebody will gladly answer your question and/or offer further advice.

== Build Questions ==
CEGUI Build
# General Requirements
# Dependency installs

# Building from CVS (unix systems)
# Configuring
Run cegui_mk2/bootstrap
# The build
Type 'make'

CEGUI Layout Editor Build
# Dependency installs (for versions > 0.4.0)
Install wxWidgets
# Building

== Usage Questions ==
=== What is the correct way to subscribe for an event? ===
Event notification is a vital aspect of GUI programming. CEGUI handles those using subscribers.
In order to subscribe a window for an event, you have to call the method 'Window::subscribeEvent', passing the function
to be called when the specified event occurs, and the instance on which the method is called.

class MyButtonHandler
{
private:
PushButton* mButton;

public:
MyButtonHandler::MyButtonHandler(PushButton* btn) : mButton(btn)
{
btn->subscribeEvent(PushButton::EventClicked, Event::Subscriber(MyButtonHandler::ButtonClicked,this));
}

MyButtonHandler::ButtonClicked()
{
//This function gets called when the button is clicked
std::cout << "Button clicked" << std::endl;
}

The 'subscribeEvent' method returns an Event::Connection, which can be used later to unsubscribe for a registered event with
the 'disconnect' method.

Event::Connection myCon = btn->subscribeEvent(...);

...

myCon->disconnect();

In order to totally remove the event itself, you have to call the 'removeEvent' function:
all the connections to the specified event will be disconnected.
There's also an Event::ScopedConnection, which can be used to auto-unsubscribe when the event goes out of scope.

Similar way for the scripted events, which can be subscribed with the 'subscribeScriptedEvent' method.
In addition, you can do it in XML, using this syntax:

<Event Name="Clicked" Function="luabtn_clicked" />

=== How can I make the ListBox highlight the selected item? ===
In order to highlight selected items you need to set selection brush image and the selection colours of that item. The selection image is modulated by the colours you set. Note, that the alpha component needs to be smaller than 1.0, for the content of the selected item to be seen.
// set selection highlight to a half transparent blue to red gradient.
colour blue(0.0, 0.0, 1.0, 0.5);
colour red(1.0, 0.0, 0.0, 0.5);
myListBoxItem->setSelectionColours(blue, blue, red, red);
// this default image is a simple white rectangle
myListBoxItem->setSelectionBrushImage("TaharezLook", "ListboxSelectionBrush");

=== How can I remove the border of a StaticImage? ===
Either put the following property into the window definition:
<Property Name="FrameEnabled" Value="false" />
Or set it by code:
myStaticImage->setFrameEnabled(false);

=== How can I set the background of a StaticImage? ===
The first thing you need in order to do this is an Imageset that defines the Image that you wish to use. When wanting to use an image file for this as you suggest, you basically have an imageset defined like this:
<?xml version="1.0" ?>
<Imageset Name="BackdropImageset" Imagefile="backdrop.tga" NativeHorzRes="1024" NativeVertRes="768" AutoScaled="true">
<Image Name="Backdrop" XPos="0" YPos="0" Width="1024" Height="768" />
</Imageset>

What this does is define an Imageset using the backdrop.tga. A single image "Backdrop" is defined that starts at location (0,0) and is 1024 x 768 in size. You should be careful in that the source image file should have dimensions that are powers of two - this is because the image is loaded as a texture, and may be stretched if the powers-of-two requirement is not observed.<br>
Once you have your imageset defined, you can load it either by adding a reference to it in whichever scheme you are loading, or manually using the ImagesetManager:
CEGUI::ImagesetManager::getSingleton().createImageset("myImageset.imagset");
Once the thing is loaded, you set the image into the StaticImage like so:
myStaticImage->setImage("BackdropImageset", "Backdrop");
Notice that the names we specify here are the ones that were originally specified in the imageset XML file.<br>

=== What properties are available for use in XML layouts, and what format do I use for the value strings? ===
Each widget has its properties placed within an appropriately named C++ namespace, so all you need to do is look up the appropriate namespace within the [http://www.cegui.org.uk/api_reference/namespaces.html namespaces section of the API reference].

Also, remember that properties are inherited. So for example, when looking up properties for a PushButton, also check the properties for ButtonBase and Window too - since these properties are also available to you.

=== I can't see the items I've added to my Combobox, how do I get the list to show when I press the button? ===

The height you specify for the combobox widget includes the height of the drop down list; it's not just for the 'Editbox' portion of the widget (the height of which is usually automatically determined based upon the font). Ensure that when specifying the height for your combobox, you have provided sufficient space for the list to appear.

Using CEGUI with Producer and OpenGL

2005-08-20T23:35:43Z

Granx: /* Using it all together */

[http://www.andesengineering.com/Producer/ Producer] is a cross platform toolkit, best explained on its website. I use it for many things, but creating a window, or Render Surface, is the most fundamental task. CEGUI requires knowledge of the window, mouse, and keyboard interaction. I will show how you can do that with some example code.

=== Defining a Producer Viewer ===
The first step is to create some sort of "viewer" with Producer, basically make a Producer::RenderSurface and a Producer::KeyboardMouse. Both of these classes are necessary for using CEGUI correctly. So, here is some example viewer code:

#include "Viewer.h"
Viewer::Viewer() : _camera(new Producer::Camera()), _rs(0), _kbm(0)
{
_rs = _camera->getRenderSurface();
_kbm = new Producer::KeyboardMouse(_rs.get());
}

Viewer::~Viewer() {}

=== Using the viewer in an Application ===
And an application might use this viewer, doing some important initializations:

Application::Application(const std::string& fontfile):
_status(RUNNING), _viewer(new general::Viewer()), _sim(new example::TeapotSim()),
_scheme_loader_policy("MouseArrow"), _layout_loader_policy(), _script_module(new ApplicationEventHandler())
{
// OpenGL context specific initializations
Producer::ref_ptr<Producer::RenderSurface> rs = _viewer->GetRenderSurface();
rs->addRealizeCallback(new general::InitGL());
rs->addRealizeCallback(new prce::InitCEGUI(fontfile,_script_module));
rs->setWindowName("Producer and CEGUI example");
rs->setWindowRectangle(20,50,800,600);

// rendering stuff
_viewer->GetCamera()->setSceneHandler( _sim.get() );
_viewer->GetCamera()->addPreDrawCallback( new SimulationDrawContext(_sim.get()) );
_viewer->GetCamera()->addPostDrawCallback(new prce::RenderCEGUI() ); // renders the GUI over scene

// device input stuff
Producer::ref_ptr<Producer::KeyboardMouse> kbm = _viewer->GetKeyboardMouse();
prce::Injector* injector = new prce::Injector( kbm.get() );
kbm->setCallback( injector );
kbm->startThread();
}

The general::InitGL functor and prce::InitCEGUI functor are quite important. These initializations are OpenGL specific, and must occur within a thread with the right OpenGL context. The Producer::RenderSurface can execute one-time initializations if you add them to be called upon window realization. Actually, a lot is happening here in the Application's constructor. You might be able to imagine how OpenGL is initialized, so I'll skip that for now. The Camera's draw callbacks are very important, but first I want to show an example of initializing CEGUI:

#include <CEGUISystem.h>
#include <renderers/OpenGLGUIRenderer/openglrenderer.h>
#include <CEGUIScriptModule.h>
#include <CEGUIFontManager.h>

#include "InitCEGUI.h"

using namespace prce;

InitCEGUI::InitCEGUI(const std::string& font, CEGUI::ScriptModule* s): _sm(s), _font(font)
{
}

InitCEGUI::~InitCEGUI()
{
}

void InitCEGUI::operator ()(const Producer::RenderSurface& rs)
{
if( _sm )
new CEGUI::System( new CEGUI::OpenGLRenderer(0), _sm );
else
new CEGUI::System( new CEGUI::OpenGLRenderer(0) );

CEGUI::FontManager* fm = CEGUI::FontManager::getSingletonPtr();
CEGUI::Font* f = fm->createFont( _font );
}

Producer uses OpenGL for rendering, so that is the renderer we must choose. Luckily, CEGUI provides this. You will need to provide a CEGUI::ScriptModule when initializing the System, but that is for another lesson. A default font needs to be provided to the System, and during initialization is a good time to provide that, so my functor has required it.

=== Rendering CEGUI with Producer ===
The application code showed a post draw callback being set. Producer will execute this little callback at the right time, within the correct OpenGL context for OpenGL calls. Here is what needs to happen for CEGUI to appear on your screen each frame:

void RenderCEGUI::operator ()(const Producer::Camera& c)
{
CEGUI::System::getSingleton().renderGUI();
}

=== Injecting Input to CEGUI via Producer ===
This is where the real magic happens. You must inject inputs into CEGUI because it does not poll the operating system for you. That is the job of a tool like Producer. For the most part, the following code works. There is a small bug that is only seen when resizing the Producer::RenderSurface (window). However, I think it provides insight into how injections need to be done for CEGUI to react to user input:

/** \author John K. Grant
* \date July, 14 2005.
* This code is public domain, free for use, with the author having no responsibility or liability.
*/
#include <CEGUISystem.h>
#include "SpecialKeyMapFunctor.h"
#include "Injector.h"

using namespace prce;

Injector::Injector(Producer::KeyboardMouse* kbm): _kbm(kbm)
{
prce::SpecialKeyMapFunctor specials;
_keys = specials();
}

Injector::~Injector()
{
}

/** changes from producer coordinates to normalized CE coordinates */
void Injector::_producer_to_cegui(float& mx, float& my)
{
// --- horizontal math
// ph = 1.0 - -1.0 = 2.0 // total horizontal distance in producer
// ch = 1.0 - 0.0 = 1.0 // total horizontal distance in ce

// --- vertical math
// pv = 1.0 - -1.0 = 2.0 // total vertical distance in producer
// cv = 0.0 - 1.0 = -1.0 // total vertical distance in ce

// cex = cx + px * (ch/2 / ph/2) = 0.5 + px * ( 0.5/1.0) = 0.5 + px*0.5
// cey = cy + py * (cv/2 / pv/2) = 0.5 + py * (-0.5/1.0) = 0.5 - py*0.5
// where cx is the "center" x value in ce
// and cy is the "center" y value in ce
float cex(0.5 + mx*0.5);
float cey(0.5 - my*0.5);
mx = cex;
my = cey;
}

/** takes normalized CEGUI coordinates and converts
* into pixel values for the screen.
*/
void Injector::_convert_to_screen(float& mx, float& my)
{
unsigned int width( _kbm->getRenderSurface()->getWindowWidth() );
unsigned int height( _kbm->getRenderSurface()->getWindowHeight() );

// the above yields the same results as the code below
//int wx(0), wy(0);
//unsigned int width(0), height(0);
//_kbm->getRenderSurface()->getWindowRectangle(wx,wy,width,height);

float pixel_x = (float)width * mx;
float pixel_y = (float)height * my;
mx = pixel_x;
my = pixel_y;
}

void Injector::mouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::passiveMouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::buttonPress(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
}

void Injector::buttonRelease(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::doubleButtonPress(float px,float py,unsigned int button)
{
/** currently is implemented to only inject a single press.
* CEGUI handles its own detection of the double click via
* the "time pulse", which controls other things as well.
*/
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px,py);
if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::mouseScroll(enum Producer::KeyboardMouseCallback::ScrollingMotion motion)
{
switch( motion )
{
case Producer::KeyboardMouseCallback::ScrollDown:
{
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
} break;

case Producer::KeyboardMouseCallback::ScrollUp:
{
CEGUI::System::getSingleton().injectMouseWheelChange( 1 );
} break;

default: // Producer::KeyboardMouseCallback::ScrollNone
break;
};
}

void Injector::keyPress(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(key) );
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( key ) );
}

void Injector::keyRelease(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(key) );
}

void Injector::specialKeyPress(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(cekey) );
}
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( prkey ) );
}

void Injector::specialKeyRelease(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(cekey) );
}
}

=== Using it all together ===
Here is what a simple main() will look like:

int main(unsigned int argc, char* argv[])
{
if( argc < 4 )
{
PrintUsage();
return 1;
}

Producer::ref_ptr<example::Application> app = new example::Application(argv[1]);
app->GetViewer()->GetRenderSurface()->realize();

app->LoadCEGUIScheme( argv[2] );
app->LoadCEGUILayout( argv[3] );

while( !app->IsFinished() )
{
app->GetViewer()->GetCamera()->frame();
}

return 0;
}

Using CEGUI with Producer and OpenGL

2005-08-20T23:35:10Z

Granx:

[http://www.andesengineering.com/Producer/ Producer] is a cross platform toolkit, best explained on its website. I use it for many things, but creating a window, or Render Surface, is the most fundamental task. CEGUI requires knowledge of the window, mouse, and keyboard interaction. I will show how you can do that with some example code.

=== Defining a Producer Viewer ===
The first step is to create some sort of "viewer" with Producer, basically make a Producer::RenderSurface and a Producer::KeyboardMouse. Both of these classes are necessary for using CEGUI correctly. So, here is some example viewer code:

#include "Viewer.h"
Viewer::Viewer() : _camera(new Producer::Camera()), _rs(0), _kbm(0)
{
_rs = _camera->getRenderSurface();
_kbm = new Producer::KeyboardMouse(_rs.get());
}

Viewer::~Viewer() {}

=== Using the viewer in an Application ===
And an application might use this viewer, doing some important initializations:

Application::Application(const std::string& fontfile):
_status(RUNNING), _viewer(new general::Viewer()), _sim(new example::TeapotSim()),
_scheme_loader_policy("MouseArrow"), _layout_loader_policy(), _script_module(new ApplicationEventHandler())
{
// OpenGL context specific initializations
Producer::ref_ptr<Producer::RenderSurface> rs = _viewer->GetRenderSurface();
rs->addRealizeCallback(new general::InitGL());
rs->addRealizeCallback(new prce::InitCEGUI(fontfile,_script_module));
rs->setWindowName("Producer and CEGUI example");
rs->setWindowRectangle(20,50,800,600);

// rendering stuff
_viewer->GetCamera()->setSceneHandler( _sim.get() );
_viewer->GetCamera()->addPreDrawCallback( new SimulationDrawContext(_sim.get()) );
_viewer->GetCamera()->addPostDrawCallback(new prce::RenderCEGUI() ); // renders the GUI over scene

// device input stuff
Producer::ref_ptr<Producer::KeyboardMouse> kbm = _viewer->GetKeyboardMouse();
prce::Injector* injector = new prce::Injector( kbm.get() );
kbm->setCallback( injector );
kbm->startThread();
}

The general::InitGL functor and prce::InitCEGUI functor are quite important. These initializations are OpenGL specific, and must occur within a thread with the right OpenGL context. The Producer::RenderSurface can execute one-time initializations if you add them to be called upon window realization. Actually, a lot is happening here in the Application's constructor. You might be able to imagine how OpenGL is initialized, so I'll skip that for now. The Camera's draw callbacks are very important, but first I want to show an example of initializing CEGUI:

#include <CEGUISystem.h>
#include <renderers/OpenGLGUIRenderer/openglrenderer.h>
#include <CEGUIScriptModule.h>
#include <CEGUIFontManager.h>

#include "InitCEGUI.h"

using namespace prce;

InitCEGUI::InitCEGUI(const std::string& font, CEGUI::ScriptModule* s): _sm(s), _font(font)
{
}

InitCEGUI::~InitCEGUI()
{
}

void InitCEGUI::operator ()(const Producer::RenderSurface& rs)
{
if( _sm )
new CEGUI::System( new CEGUI::OpenGLRenderer(0), _sm );
else
new CEGUI::System( new CEGUI::OpenGLRenderer(0) );

CEGUI::FontManager* fm = CEGUI::FontManager::getSingletonPtr();
CEGUI::Font* f = fm->createFont( _font );
}

Producer uses OpenGL for rendering, so that is the renderer we must choose. Luckily, CEGUI provides this. You will need to provide a CEGUI::ScriptModule when initializing the System, but that is for another lesson. A default font needs to be provided to the System, and during initialization is a good time to provide that, so my functor has required it.

=== Rendering CEGUI with Producer ===
The application code showed a post draw callback being set. Producer will execute this little callback at the right time, within the correct OpenGL context for OpenGL calls. Here is what needs to happen for CEGUI to appear on your screen each frame:

void RenderCEGUI::operator ()(const Producer::Camera& c)
{
CEGUI::System::getSingleton().renderGUI();
}

=== Injecting Input to CEGUI via Producer ===
This is where the real magic happens. You must inject inputs into CEGUI because it does not poll the operating system for you. That is the job of a tool like Producer. For the most part, the following code works. There is a small bug that is only seen when resizing the Producer::RenderSurface (window). However, I think it provides insight into how injections need to be done for CEGUI to react to user input:

/** \author John K. Grant
* \date July, 14 2005.
* This code is public domain, free for use, with the author having no responsibility or liability.
*/
#include <CEGUISystem.h>
#include "SpecialKeyMapFunctor.h"
#include "Injector.h"

using namespace prce;

Injector::Injector(Producer::KeyboardMouse* kbm): _kbm(kbm)
{
prce::SpecialKeyMapFunctor specials;
_keys = specials();
}

Injector::~Injector()
{
}

/** changes from producer coordinates to normalized CE coordinates */
void Injector::_producer_to_cegui(float& mx, float& my)
{
// --- horizontal math
// ph = 1.0 - -1.0 = 2.0 // total horizontal distance in producer
// ch = 1.0 - 0.0 = 1.0 // total horizontal distance in ce

// --- vertical math
// pv = 1.0 - -1.0 = 2.0 // total vertical distance in producer
// cv = 0.0 - 1.0 = -1.0 // total vertical distance in ce

// cex = cx + px * (ch/2 / ph/2) = 0.5 + px * ( 0.5/1.0) = 0.5 + px*0.5
// cey = cy + py * (cv/2 / pv/2) = 0.5 + py * (-0.5/1.0) = 0.5 - py*0.5
// where cx is the "center" x value in ce
// and cy is the "center" y value in ce
float cex(0.5 + mx*0.5);
float cey(0.5 - my*0.5);
mx = cex;
my = cey;
}

/** takes normalized CEGUI coordinates and converts
* into pixel values for the screen.
*/
void Injector::_convert_to_screen(float& mx, float& my)
{
unsigned int width( _kbm->getRenderSurface()->getWindowWidth() );
unsigned int height( _kbm->getRenderSurface()->getWindowHeight() );

// the above yields the same results as the code below
//int wx(0), wy(0);
//unsigned int width(0), height(0);
//_kbm->getRenderSurface()->getWindowRectangle(wx,wy,width,height);

float pixel_x = (float)width * mx;
float pixel_y = (float)height * my;
mx = pixel_x;
my = pixel_y;
}

void Injector::mouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::passiveMouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::buttonPress(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
}

void Injector::buttonRelease(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::doubleButtonPress(float px,float py,unsigned int button)
{
/** currently is implemented to only inject a single press.
* CEGUI handles its own detection of the double click via
* the "time pulse", which controls other things as well.
*/
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px,py);
if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::mouseScroll(enum Producer::KeyboardMouseCallback::ScrollingMotion motion)
{
switch( motion )
{
case Producer::KeyboardMouseCallback::ScrollDown:
{
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
} break;

case Producer::KeyboardMouseCallback::ScrollUp:
{
CEGUI::System::getSingleton().injectMouseWheelChange( 1 );
} break;

default: // Producer::KeyboardMouseCallback::ScrollNone
break;
};
}

void Injector::keyPress(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(key) );
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( key ) );
}

void Injector::keyRelease(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(key) );
}

void Injector::specialKeyPress(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(cekey) );
}
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( prkey ) );
}

void Injector::specialKeyRelease(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(cekey) );
}
}

=== Using it all together ===
Here is what a simple main() will look like:
int main(unsigned int argc, char* argv[])
{
if( argc < 4 )
{
PrintUsage();
return 1;
}

Producer::ref_ptr<example::Application> app = new example::Application(argv[1]);
app->GetViewer()->GetRenderSurface()->realize();

app->LoadCEGUIScheme( argv[2] );
app->LoadCEGUILayout( argv[3] );

while( !app->IsFinished() )
{
app->GetViewer()->GetCamera()->frame();
}

return 0;
}

Using CEGUI with Producer and OpenGL

2005-08-20T23:32:46Z

Granx: Using CEGUI via Producer

[http://www.andesengineering.com/Producer/ Producer] is a cross platform toolkit, best explained on its website. I use it for many things, but creating a window, or Render Surface, is the most fundamental task. CEGUI requires knowledge of the window, mouse, and keyboard interaction. I will show how you can do that with some example code.

=== Defining a Producer Viewer ===
The first step is to create some sort of "viewer" with Producer, basically make a Producer::RenderSurface and a Producer::KeyboardMouse. Both of these classes are necessary for using CEGUI correctly. So, here is some example viewer code:

#include "Viewer.h"
Viewer::Viewer() : _camera(new Producer::Camera()), _rs(0), _kbm(0)
{
_rs = _camera->getRenderSurface();
_kbm = new Producer::KeyboardMouse(_rs.get());
}

Viewer::~Viewer() {}

=== Using the viewer in an Application ===
And an application might use this viewer, doing some important initializations:

Application::Application(const std::string& fontfile):
_status(RUNNING), _viewer(new general::Viewer()), _sim(new example::TeapotSim()),
_scheme_loader_policy("MouseArrow"), _layout_loader_policy(), _script_module(new ApplicationEventHandler())
{
// OpenGL context specific initializations
Producer::ref_ptr<Producer::RenderSurface> rs = _viewer->GetRenderSurface();
rs->addRealizeCallback(new general::InitGL());
rs->addRealizeCallback(new prce::InitCEGUI(fontfile,_script_module));
rs->setWindowName("Producer and CEGUI example");
rs->setWindowRectangle(20,50,800,600);

// rendering stuff
_viewer->GetCamera()->setSceneHandler( _sim.get() );
_viewer->GetCamera()->addPreDrawCallback( new SimulationDrawContext(_sim.get()) );
_viewer->GetCamera()->addPostDrawCallback(new prce::RenderCEGUI() ); // renders the GUI over scene

// device input stuff
Producer::ref_ptr<Producer::KeyboardMouse> kbm = _viewer->GetKeyboardMouse();
prce::Injector* injector = new prce::Injector( kbm.get() );
kbm->setCallback( injector );
kbm->startThread();
}

The general::InitGL functor and prce::InitCEGUI functor are quite important. These initializations are OpenGL specific, and must occur within a thread with the right OpenGL context. The Producer::RenderSurface can execute one-time initializations if you add them to be called upon window realization. Actually, a lot is happening here in the Application's constructor. You might be able to imagine how OpenGL is initialized, so I'll skip that for now. The Camera's draw callbacks are very important, but first I want to show an example of initializing CEGUI:

#include <CEGUISystem.h>
#include <renderers/OpenGLGUIRenderer/openglrenderer.h>
#include <CEGUIScriptModule.h>
#include <CEGUIFontManager.h>

#include "InitCEGUI.h"

using namespace prce;

InitCEGUI::InitCEGUI(const std::string& font, CEGUI::ScriptModule* s): _sm(s), _font(font)
{
}

InitCEGUI::~InitCEGUI()
{
}

void InitCEGUI::operator ()(const Producer::RenderSurface& rs)
{
if( _sm )
new CEGUI::System( new CEGUI::OpenGLRenderer(0), _sm );
else
new CEGUI::System( new CEGUI::OpenGLRenderer(0) );

CEGUI::FontManager* fm = CEGUI::FontManager::getSingletonPtr();
CEGUI::Font* f = fm->createFont( _font );
}

Producer uses OpenGL for rendering, so that is the renderer we must choose. Luckily, CEGUI provides this. You will need to provide a CEGUI::ScriptModule when initializing the System, but that is for another lesson. A default font needs to be provided to the System, and during initialization is a good time to provide that, so my functor has required it.

=== Rendering CEGUI with Producer ===
The application code showed a post draw callback being set. Producer will execute this little callback at the right time, within the correct OpenGL context for OpenGL calls. Here is what needs to happen for CEGUI to appear on your screen each frame:

void RenderCEGUI::operator ()(const Producer::Camera& c)
{
CEGUI::System::getSingleton().renderGUI();
}

=== Injecting Input to CEGUI via Producer ===
This is where the real magic happens. You must inject inputs into CEGUI because it does not poll the operating system for you. That is the job of a tool like Producer. For the most part, the following code works. There is a small bug that is only seen when resizing the Producer::RenderSurface (window). However, I think it provides insight into how injections need to be done for CEGUI to react to user input:

/** \author John K. Grant
* \date July, 14 2005.
* This code is public domain, free for use, with the author having no responsibility or liability.
*/
#include <CEGUISystem.h>
#include "SpecialKeyMapFunctor.h"
#include "Injector.h"

using namespace prce;

Injector::Injector(Producer::KeyboardMouse* kbm): _kbm(kbm)
{
prce::SpecialKeyMapFunctor specials;
_keys = specials();
}

Injector::~Injector()
{
}

/** changes from producer coordinates to normalized CE coordinates */
void Injector::_producer_to_cegui(float& mx, float& my)
{
// --- horizontal math
// ph = 1.0 - -1.0 = 2.0 // total horizontal distance in producer
// ch = 1.0 - 0.0 = 1.0 // total horizontal distance in ce

// --- vertical math
// pv = 1.0 - -1.0 = 2.0 // total vertical distance in producer
// cv = 0.0 - 1.0 = -1.0 // total vertical distance in ce

// cex = cx + px * (ch/2 / ph/2) = 0.5 + px * ( 0.5/1.0) = 0.5 + px*0.5
// cey = cy + py * (cv/2 / pv/2) = 0.5 + py * (-0.5/1.0) = 0.5 - py*0.5
// where cx is the "center" x value in ce
// and cy is the "center" y value in ce
float cex(0.5 + mx*0.5);
float cey(0.5 - my*0.5);
mx = cex;
my = cey;
}

/** takes normalized CEGUI coordinates and converts
* into pixel values for the screen.
*/
void Injector::_convert_to_screen(float& mx, float& my)
{
unsigned int width( _kbm->getRenderSurface()->getWindowWidth() );
unsigned int height( _kbm->getRenderSurface()->getWindowHeight() );

// the above yields the same results as the code below
//int wx(0), wy(0);
//unsigned int width(0), height(0);
//_kbm->getRenderSurface()->getWindowRectangle(wx,wy,width,height);

float pixel_x = (float)width * mx;
float pixel_y = (float)height * my;
mx = pixel_x;
my = pixel_y;
}

void Injector::mouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::passiveMouseMotion(float px,float py)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);
}

void Injector::buttonPress(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
}

void Injector::buttonRelease(float px,float py,unsigned int button)
{
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px, py);

if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::doubleButtonPress(float px,float py,unsigned int button)
{
/** currently is implemented to only inject a single press.
* CEGUI handles its own detection of the double click via
* the "time pulse", which controls other things as well.
*/
_producer_to_cegui(px,py);
_convert_to_screen(px,py);
CEGUI::System::getSingleton().injectMousePosition(px,py);
if( button == 1 ) // left
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);

else if( button == 2 ) // middle
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);

else if( button == 3 ) // right
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
}

void Injector::mouseScroll(enum Producer::KeyboardMouseCallback::ScrollingMotion motion)
{
switch( motion )
{
case Producer::KeyboardMouseCallback::ScrollDown:
{
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
} break;

case Producer::KeyboardMouseCallback::ScrollUp:
{
CEGUI::System::getSingleton().injectMouseWheelChange( 1 );
} break;

default: // Producer::KeyboardMouseCallback::ScrollNone
break;
};
}

void Injector::keyPress(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(key) );
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( key ) );
}

void Injector::keyRelease(Producer::KeyCharacter key)
{
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(key) );
}

void Injector::specialKeyPress(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyDown( static_cast<CEGUI::uint>(cekey) );
}
CEGUI::System::getSingleton().injectChar( static_cast<CEGUI::utf32>( prkey ) );
}

void Injector::specialKeyRelease(Producer::KeyCharacter prkey)
{
KeyMap::iterator iter = _keys.find( prkey );
if( iter != _keys.end() )
{
CEGUI::Key::Scan cekey = (*iter).second;
CEGUI::System::getSingleton().injectKeyUp( static_cast<CEGUI::uint>(cekey) );
}
}

Using CEGUI with Producer and OpenGL

2005-08-20T23:06:38Z

Granx:

Using CEGUI with Producer and OpenGL

2005-08-20T23:05:31Z

Granx:

Using CEGUI with Producer and OpenGL

2005-08-20T23:00:59Z

Granx: Using CEGUI via Producer

Using CEGUI with Producer and OpenGL

2005-08-20T22:33:24Z

Granx:

Tutorials

2005-08-20T22:25:52Z

Granx: /* Window System Examples */

=== CrazyEddie's Beginner Guides ===
* [[The Beginner Guide to Getting CEGUI Rendering]] - How to initialise CEGUI to render properly.
* [[The Beginner Guide to Loading Data Files and Initialisation]] - How to load some data files and perform basic system initialisation.
* [[The Beginner Guide to Creating a CEGUI Window]] - How to create a simple window and get it on screen.
* [[The Beginner Guide to Injecting Inputs]] - How to inject inputs into CEGUI and get interactive.

=== Lua Scripting with CEGUI ===
* [[Getting Started with Lua and CEGUI]] - How to initialise CEGUI with a Lua script module and configuration file.
* [[Handling Events from Lua]] - How to load Lua script files and bind CEGUI events to Lua functions.
* [[Writing CEGUI scripts]] - Code snippets
* [[Adding LuaScriptModile to Sample_FirstWindow]] - Experience adding scripting to an existing sample.

=== Window System Examples ===
* [[Using CEGUI with SDL and OpenGL]] - Guidelines on how to get SDL, OpenGL and CEGUI running together.
* [[Using CEGUI with Producer and OpenGL]] - Guidelines on how to render and inject input to CEGUI from the Producer API.