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

Building from source

2015-11-05T07:55:51Z

Mmixlinus: /* Documentation */

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

==Official documentation==
PLEASE use the documentation of your CEGUI version as your main source of information, e.g.: [http://static.cegui.org.uk/docs/current/compiling.html Latest API docs for building/compiling]

==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at bitbucket.org. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone https://bitbucket.org/cegui/cegui cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [https://bitbucket.org/cegui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [https://bitbucket.org/cegui/cegui/src cegui]
hg clone https://bitbucket.org/cegui/cegui cegui-source
* CEED unified editor - [https://bitbucket.org/cegui/ceed/src CEED]
hg clone https://bitbucket.org/cegui/ceed

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is the appended ''/src'' on the web URLs}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you have some 2.8.X version installed because CMake 3.x.x will break with our scripts at the moment.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable sortable" border="1" style="text-align: center;"
|+ External libraries supported by CEGUI
|-
! scope="col" | Type
! scope="col" | Name
! scope="col" halign="left" | Additional information

|- style="background: #eaffe8;"
| rowspan="5" | Rendering Module
| OpenGL 3.2+ Core Profile
| style="text-align: left;" | Uses the programmable rendering pipeline and only non-deprecated functionality and is therefore compatible with OpenGL Core Profile contexts (available since OpenGL 3.2). It can also be used with older OpenGL versions and/or Compatibility Profile, as long as the required functionalities are available.
|- style="background: #eaffe8;"
| OpenGL
| style="text-align: left;" | Uses the fixed-function rendering pipeline. It is designed to be compatible with very early OpenGL versions, as early as OpenGL 1.2, using some OpenGL extensions.
|- style="background: #eaffe8;"
| Microsoft Direct3D
| style="text-align: left;" | Microsoft Direct3D 9, 10, and 11 are supported using seperate modules.
|- style="background: #eaffe8;"
| OGRE
| style="text-align: left;" | The latest stable Ogre version is supported in the releases.
|- style="background: #eaffe8;"
| Irrlicht
| style="text-align: left;" | The latest stable Irrlicht version is supported in the releases.

|- style="background: #edfcfb;"
| rowspan="4" | Image Codec Module
| SILLY
| style="text-align: left;" | Default image codec, which is based on the SILLY library. Supports many formats, see [[SILLY]]
|- style="background: #edfcfb;"
| DevIL
| style="text-align: left;" | Image codec based on the DevIL library.
|- style="background: #edfcfb;"
| FreeImage
| style="text-align: left;" | Image codec based on the FreeImage library.
|- style="background: #edfcfb;"
| OGRE
| style="text-align: left;" | Image codec that loads data via image loading facilities of OGRE.

|- style="background: #dfeff1;"
| rowspan="3" | Resource Provider Module
| Default
| style="text-align: left;" | The default resource provider of CEGUI uses standard cross-platform file-access.
|- style="background: #dfeff1;"
| OGRE
| style="text-align: left;" | Ogre users can use CEGUI's Ogre ResourceManager. This way the resource locations of CEGUI can be specified in the same way as it is done for the Ogre resources already.
|- style="background: #dfeff1;"
| minizip
| style="text-align: left;" | CEGUI's MinizipResourceProvider allows users to provides the ability to load the resource files from locations within .zip files.

|- style="background: #e9ebfc;"
| rowspan="5" | XML Parser Module
| Expat
| style="text-align: left;" | Ddefault XML parser of CEGUI. Uses the Expat library for XML parsing.
|- style="background: #e9ebfc;"
| LibXML2
| style="text-align: left;" | Uses the LibXML2 library for XML parsing.
|- style="background: #e9ebfc;"
| RapidXml
| style="text-align: left;" | Uses the RapidXml library for XML parsing.
|- style="background: #e9ebfc;"
| TinyXML
| style="text-align: left;" | Uses the TinyXML library for XML parsing.
|- style="background: #e9ebfc;"
| Xerces-C++
| style="text-align: left;" | Uses the Xerces library for XML parsing. It can do schema validation using the .xsd files provided in CEGUI's resources.
|-

|- style="background: #fae9fc;"
| rowspan="1" | Font Module
| FreeType
| style="text-align: left;" | FreeType is the default font library of CEGUI and currently the only officially supported one.

|- style="background: #f4e0e7;"
| rowspan="1" | Regular Expression Module
| Perl Compatible Regular Expressions (PCRE)
| style="text-align: left;" | Default regular expression library and currently the only officially supported one. Uses the PCRE library.

|- style="background: #fcf3e9;"
| rowspan="2" | Scripting Module
| Lua
| style="text-align: left;" | Provides lua bindings using tolua++.
|- style="background: #fcf3e9;"
| Python
| style="text-align: left;" | Official Python bindings are available using [[PyCEGUI]]

|- style="background: #f2eeca;"
| rowspan="2" | Memory Management
| OGRE
| style="text-align: left;" | Ogre's memory allocator can optionally be used for CEGUI's memory management.
|- style="background: #f2eeca;"
| nedmalloc
| style="text-align: left;" | nedmalloc can optionally be used as memory allocator.

|- style="background: #f6fce9;"
| rowspan="2" | Bi-Directional Language Module
| MiniBIDI
| style="text-align: left;" | MiniBIDI based implementation of CEGUI's Bidi visual mapping.
|- style="background: #f6fce9;"
| FriBIDI
| style="text-align: left;" | FriBIDI based implementation of CEGUI's Bidi visual mapping.

|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone https://bitbucket.org/cegui/cegui cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabber>
GNU Make=
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
|-|
MSVC=
{{Todo|MSVC notes}}
|-|
Xcode=
{{Todo|Xcode notes}}
</tabber>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabber>
Linux=
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
|-|
Windows=
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tabber>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://static.cegui.org.uk/docs/ here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' with plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see [[CEED]] for a detailed description.

CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.

{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}

===Dependencies===
CEED requires a Python 2 interpreter, version 2.6 or higher.
Apart from [[PyCEGUI]] (the CEGUI Python bindings), it depends on the following libraries:
* PyOpenGL
* Qt4, PySide (+ PySide Tools)
* Boost.Python

<tabber>
Windows=
{{Todo|Windows dependencies notes}}
|-|
Mac=
{{Todo|Mac dependencies notes}}
|-|
Arch Linux=
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
|-|
Debian=
;Wheezy

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:

{{CLI||sudo apt-get update}}
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}
|-|
Fedora=
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
|-|
Gentoo=
You can use these supplied ebuilds:[https://bitbucket.org/ChrisTrenkamp/gentoo-ogre3d-tools]. Copy these ebuilds to your local overlay[http://en.gentoo-wiki.com/wiki/Overlay#Local_Overlays], add the necessary options to your package.keywords and package.use files, and run '''''emerge -av dev-util/ceed'''''
</tabber>

===Running===
{{Todo|Update this section when CEED/CEGUI 0.8 is released}}
If you're following the directory structure outlined in [[#Building|Building]], you should have something like:
cegui (root working directory)
cegui/CEED (CEED repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

Running the main ''ceed-gui'' application could be as simple as:
{{CLI|~/cegui/CEED|2=PYTHONPATH=.:$PYTHONPATH python2 bin/ceed-gui}}

If you don't have PyCEGUI installed system-wide but built it in ''cegui/cegui_mk2/build'', you can run ''ceed-gui'' like this:
{{CLI|~/cegui/CEED|2=PYTHONPATH=../cegui_mk2/build/lib:.:$PYTHONPATH python2 bin/ceed-gui}}

====Running from Mercurial====
If you've cloned the CEED mercurial repository, you will most likely get the following error when you try to run ''ceed-gui'':
ImportError: No module named mainwindow
This is because the compiled .ui files are not part of the repository. Edit the file ''ceed/version.py'' with your favorite text editor and change the value of '''CEED_developerMode''' from '''False''' to '''True'''.

=Troubleshooting=
If you encounter a problem that's not listed here, please make a post on the appropriate forum: [http://www.cegui.org.uk/phpBB2/viewforum.php?f=10 CEGUI], [http://www.cegui.org.uk/phpBB2/viewforum.php?f=15 CEED].

For comments about this article, you may use it's discussion page.

=Related articles=
* [[Eclipse and CEGUI]]
* [[Contribution|Contributing to the development of CEGUI]]

[[Category:HowTo]]

Rendering to texture (RTT) in CEGUI

2014-03-04T22:32:49Z

Mmixlinus:

{{VersionBadge|0.8}}

Since version 0.8 the new GUIContext class allows it to render your CEGUI interface into a texture instead of rendering it normally into your main buffer.

<source lang="cpp">
CEGUI::System& ceguiSystem = CEGUI::System::getSingleton();

//Taking some random values as example for a GUIContext size.
int width = 1024;
int height = 800;
CEGUI::Sizef size(static_cast<float>(width), static_cast<float>(height));

// We create a CEGUI texture target and create a GUIContext that will use it.
CEGUI::TextureTarget* renderTextureTarget = ceguiSystem.getRenderer()->createTextureTarget();
CEGUI::GUIContext& renderGuiContext = ceguiSystem.createGUIContext(static_cast<CEGUI::RenderTarget&>(*renderTextureTarget) );
renderTextureTarget->declareRenderSize(size);
</source>

The following section is only necessary if you want to use the rendered texture as a CEGUI Image again. Basically to render a CEGUI layout inside CEGUI. This won't be the case if you just want to render CEGUI into a texture and use it somewhere in your 3D application.
<source lang="cpp">
// We create a BasicImage and set the Texture
CEGUI::BasicImage* textureTargetImage = static_cast<CEGUI::BasicImage*>(&CEGUI::ImageManager::getSingleton().create("BasicImage", "MyTextureGroup/MyTextureName"));
textureTargetImage->setTexture(&renderTextureTarget->getTexture());

//Flipping is necessary due to differences between renderers regarding top or bottom being the origin
bool isTextureTargetVerticallyFlipped = renderTextureTarget->isRenderingInverted();
CEGUI::Rectf renderArea;

if (isTextureTargetVerticallyFlipped)
renderArea = CEGUI::Rectf(0.0f, height, width, 0.0f);
else
renderArea = CEGUI::Rectf(0.0f, 0.0f, width, height);

textureTargetImage->setArea(renderArea);
</source>

For rendering you need to call the rendering function of your new GuiContext directly. Here is an example of how to call the renderer and the guicontext in the right order when rendering:

<source lang="cpp">
CEGUI::Renderer* gui_renderer(gui_system.getRenderer());
gui_renderer->beginRendering();

renderTextureTarget->clear();
renderGuiContext.draw();

gui_renderer->endRendering();
</source>

Also do not forget to correctly update CEGUI and the GUIContext with all timepulses and inputs, just as you would do it normally but by using your new GUIContext instead of the default one!

If you want to retrieve the renderer-specific texture from a CEGUI texture you will need to cast it:

For example for OpenGL:
<source lang="cpp">
CEGUI::OpenGLTexture& glTexture = static_cast<CEGUI::OpenGLTexture&>(d_textureTarget->getTexture());
</source>

After that you can use the member function to receive whatever render-specific traits you need, such as the textureID in Opengl as an unsigned integer, etc.

[[Category:HowTo]]

Rendering to texture (RTT) in CEGUI

2014-03-03T19:19:41Z

Mmixlinus:

{{VersionBadge|0.8}}

Since version 0.8 the new GUIContext class allows it to render your CEGUI interface into a texture instead of rendering it normally into your main buffer.

<source lang="cpp">
CEGUI::System& ceSystem = CEGUI::System::getSingleton();
//Taking some random values as example for a GUIContext size.
int width = 1024;
int height = 800;
CEGUI::Sizef size(static_cast<float>(width), static_cast<float>(height));

// We create a CEGUI texture target and create a GUIContext that will use it.
CEGUI::TextureTarget* renderTextureTarget = ceSystem.getRenderer()->createTextureTarget();
CEGUI::GUIContext* renderGuiContext = ceSystem.createGUIContext(static_cast<CEGUI::RenderTarget&>(*renderTextureTarget) );
renderTextureTarget->declareRenderSize(size);

// We create a BasicImage and set the Texture
textureTargetImage = static_cast<CEGUI::BitmapImage*>(&CEGUI::ImageManager::getSingleton().create("BitmapImage", "SomeGroup/MyTexturesName"));
textureTargetImage->setTexture(&renderTextureTarget->getTexture());

// We size the image using a function
setTextureTargetImageArea(static_cast<float>(height), static_cast<float>(width));
</source>

Here is the function for sizing the BasicImage:

<source lang="cpp">
void setTextureTargetImageArea(float height, float width)
{
if(d_textureTarget)
{
bool isTextureTargetVerticallyFlipped = renderTextureTarget->isRenderingInverted();
CEGUI::Rectf renderArea;
if (isTextureTargetVerticallyFlipped)
renderArea = CEGUI::Rectf(0.0f, height, width, 0.0f);
else
renderArea = CEGUI::Rectf(0.0f, 0.0f, width, height);

if(textureTargetImage)
textureTargetImage->setImageArea(renderArea);
}
}
</source>

If you want to retrieve the renderer-specific texture from a CEGUI texture you will need to cast it:

For example for OpenGL:
<source lang="cpp">
CEGUI::OpenGLTexture& glTexture = static_cast<CEGUI::OpenGLTexture&>(d_textureTarget->getTexture());
</source>

After that you can use the member function to receive whatever render-specific traits you need, such as the textureID in Opengl as an unsigned integer, etc.

[[Category:HowTo]]

Rendering to texture (RTT) in CEGUI

2014-03-03T19:09:45Z

Mmixlinus:

{{VersionBadge|0.8}}

Since version 0.8 the new GUIContext class allows it to render your CEGUI interface into a texture instead of rendering it normally into your main buffer.

<source lang="cpp">
//Taking some random values as example for a guicontext size.
int width = 1024;
int height = 800;
CEGUI::Sizef size(static_cast<float>(width), static_cast<float>(height));

// We create a CEGUI texture target and create a GUIContext that will use it.
CEGUI::TextureTarget* renderTextureTarget = system.getRenderer()->createTextureTarget();
CEGUI::GUIContext* renderGuiContext = &CEGUI::System::getSingleton().createGUIContext(static_cast<CEGUI::RenderTarget&>(*renderTextureTarget) );
renderTextureTarget->declareRenderSize(size);

// We create a BasicImage and set the Texture
d_textureTargetImage = static_cast<CEGUI::BitmapImage*>(&CEGUI::ImageManager::getSingleton().create("BitmapImage", "SomeGroup/MyTexturesName"));
d_textureTargetImage->setTexture(&d_textureTargetImage->getTexture());

// We size the image using a function
setTextureTargetImageArea(static_cast<float>(height), static_cast<float>(width));
</source>

Here is the function for sizing the BasicImage:

<source lang="cpp">
void setTextureTargetImageArea(float height, float width)
{
if(d_textureTarget)
{
bool isTextureTargetVerticallyFlipped = d_textureTarget->isRenderingInverted();
CEGUI::Rectf renderArea;
if(isTextureTargetVerticallyFlipped)
renderArea = CEGUI::Rectf(0.0f, height, width, 0.0f);
else
renderArea = CEGUI::Rectf(0.0f, 0.0f, width, height);

if(d_textureTargetImage)
d_textureTargetImage->setImageArea(renderArea);
}
}
</source>

if you want to retrieve the renderer-specific texture from a CEGUI texture you will need to cast it:

For example for OpenGL:
<source lang="cpp">
CEGUI::OpenGLTexture& glTexture = static_cast<CEGUI::OpenGLTexture&>(d_textureTarget->getTexture());
</source>

After that u can use the member function to receive whatever render-specific traits you need, such as the textureID in Opengl as an unsigned integer, etc.

[[Category:HowTo]]

Porting tips and changes from 0.7.X to 0.8.X

2014-01-25T22:23:05Z

Mmixlinus:

{{VersionBadge|0.7}}

{{Section|1=Introduction|2=
The 0.8.x branch has already seen releases. Please see the sourceforge page for tarball downloads.
}}
{{Section|1=Major renames/API changes|2=
* CEGUI::Window was renamed to CEGUI::Widget as Widget is the coined term for that, WindowManager renamed to WidgetManager, etc... (not in mercurial yet!)
* The stock/standard window renderer set (now widget renderer set) FalagardWRBase was renamed to StandardWRSet to avoid confusion with core [[Falagard]] facilities (not in mercurial yet!)
* Windows now don't have absolute names! Every window's name only has to be unique in it's parent window. Therefore WindowManager::getSingleton().getWindow no longer made sense and was removed. If root's name was "Root" and your the window name was "Root/Stuff/After/Root/Name", you can emulate its behaviour with root->getChild("Stuff/After/Root/Name"). It's recommended to migrate to a more encapsulated model.
* CEGUI::GUIContext class has been created that is responsible for injecting input and event handling, setting the default font, setting the root window, setting a default tooltip object and type, and manipulating the mouse cursor.
* CEGUI::GUIContext needs time impulses injected separately! You should also inject time pulses into CEGUI::System. This API "wart" may disappear in future versions.
* CEGUI::MouseCursor is no longer a singleton, and can be accessed and manipulated from CEGUI::GUIContext.
}}
{{Section|1=General|2=
* All XML attributes must now be in lowercase, e.g. <WidgetLook Name="TaharezLook/FrameWindow"> must be <WidgetLook name="TaharezLook/FrameWindow">
* PropertyHelper has been turned into a template class, instead of PropertyHelper::uintToString you do PropertyHelper<uint>::toString, instead of PropertyHelper::stringToUint you do PropertyHelper<uint>::fromString
* All instances of the word caret that were incorrectly spelt 'carat' have been corrected. This affects all APIs, properties, events and datafiles.
* Window::EventWindowUpdated renamed to Window::EventUpdated and the associated string is changed from "WindowUpdate" to "Updated"
* ListHeader::SegmentNameSuffix changed type from character array to CEGUI::String
* BiDiVisualMapping renamed to BidiVisualMapping. Also renamed the files, so CEGUIBiDiVisualMapping.h is now CEGUIBidiVisualMapping.h
* class colour renamed to Colour, as a side effect the "colour" interpolator is now "Colour" interpolator, this breaks animation definitions!
* Point typedef removed, please use Vector2 instead
* Many event string values changed to match the C++ name (but without the Event prefix). A list of which strings changed value will appear here soon.
* Window::setRestoreCapture renamed to Window::setRestoreOldCapture
* CEGUI now supports custom memory allocation, see [[Memory Allocation]] to check if this concerns you or not.
* Window::addChildWindow renamed to Window::addChild, Window::removeChildWindow renamed to Window::removeChild, several other methods (mostly in layout containers) changed from *ChildWindow* to *Child*
* CEGUI::String can now be just a typedef or a class, depending on String configuration (CEGUI can now use std::string as CEGUI::String for apps not requiring unicode)
* Window::getChild_impl method completely removed, it was only used by Window::getParentPixelSize, shouldn't be hard to replace
* Vector2, Vector3, Size and Rect are now templated, you should use Vector2<float> (or just Vector2<> as a shortcut since float is the default type) instead of Vector2, UVector2 class was removed, UVector2 is now just a typedef to Vector2<UDim>. Same with Vector3, Size and Rect.
* Texture::saveToMemory is renamed Texture::blitToMemory.
* Renderer and Texture interfaces changed in order to support named textures.
* Window::isDisabled(localOnly) is now split into Window::isDisabled (= old isDisabled(true) and Window::isEffectiveDisabled (= old isDisabled(false))
* Window::isVisible(localOnly) is now split into Window::isVisible (= old isDisabled(true) and Window::isEffectiveVisible (= old isVisible(false))
* WindowManager::loadWindowLayout is renamed to WindowManager::loadLayoutFromFile
* NamedXMLResourceManager::create is renamed to NamedXMLResourceManager::createFromFile (Ex. CEGUI::SchemeManager::createFromFile)
* CEGUI::DefaultLogger no longer throws const char* but a real exception in setLogFilename - http://www.cegui.org.uk/mantis/view.php?id=443
* CEGUI now has inbuilt copy, cut, paste support, if you used a custom solution, you might want to check CEGUI::Clipboard and System::inject{Copy,Cut,Paste}Request
* CEGUI::ProgressBar::getStep renamed to getStepSize for consistency with setStepSize
* CEGUI::WidgetLookManager::parseLookNFeelSpecification is now called parseLookNFeelSpecificationFromFile, variants for loading from string and raw data container have been added
* XRotation, YRotation, ZRotation properties merged into the new Rotation property, which is a Quaternion.
}}
{{Section|1=Property Name Changes|2=
* Property from Window called "ZOrderChangeEnabled" renamed to "ZOrderingEnabled"
* Property from Window called "MouseButtonDownAutoRepeat" renamed to "MouseAutoRepeatEnabled"
* Property from Window called "CustomTooltipType" renamed to "TooltipType"
* Property from Window called "Tooltip" renamed to "TooltipText"
* Property from Window called "RiseOnClick" renamed to "RiseOnClickEnabled"
* Property from Window called "UnifiedAreaRect" renamed to "Area", "UnifiedSize" renamed to "Size", etc...
* Property "MaxEditTextLength" renamed to "MaxTextLength"
}}
{{Section|1=Event Name Changes|2=
* EventMouseEnters renamed to EventMouseEntersSurface (old name removed)
* EventMouseLeaves renamed to EventMouseLeavesSurface (old name removed)
* CheckStateChanged renamed to SelectStateChanged (for ToggleButton (old Checkbox))
}}
{{Section|1=Image and ImageManager|2=
* Image::draw renamed to Image::render
* Image class is now an abstract interface. BasicImage implementation is provided, and used for internally created Image objects.
* Imageset class is removed. It remains a CEGUI format that allows to conveniently define multiple images on one texture but the data is no longer stored in any class. When Imageset is loaded, the ImageManager creates a new BasicImage for each of the images in the imageset. Only the images themselves will remain after imageset is loaded. You now use the new ImageManager to access defined images.
* ImagesetManager class is removed. You now use the new ImageManager.
* Images belonging to a certain imageset can be accessed like so: "ImageSetName/ImageName" (ex. "AlfiskoSkin/MouseArrow").
}}
{{Section|1=GUIContext|2=
A lot of API has been moved from CEGUI::System to CEGUI::GUIContext. CEGUI now allows you to create multiple independent GUI contexts with their own input injection.

As a rule of thumb, whenever you see "There is no CEGUI::System::some_foobar_method method", it is likely that you can replace the call with CEGUI::System::getSingleton().getDefaultGUIContext().someFoobarMethod(). This holds for all the System::inject* methods for example.

WindowManager::getSingleton().getWindow() was removed. You can emulate its behaviour with root->getChild("Stuff/After/Root/Name").
To get Root Window you can call GUIContext::getRootWindow();

SIDE NOTE: The chain call of methods CEGUI::System::getSingleton().getDefaultGUIContext() should be called as rarely as possible, instead one should keep it's result in appropriate variable.

}}
{{Section|1=PyCEGUI|2=
* EventSet.subscribeEvent now has a different, more pythonic syntax, any python callable (bound member function, free function, lambda, functor, ...) is allowed (EventSet.subscribeEvent("EventName", instance, "someMethodInIt") is now EventSet.subscribeEvent("EventName", instance.someMethodInIt)
}}

{{Section|1=Datafiles|2=
* All XML datafiles must specify a version attribute. Example: <GUILayout '''version="4"'''>
* All attributes in datafiles must begin with a lower-case letter. Example: <Property '''n'''ame="Alpha" '''v'''alue="1.0" />
* See '''Property Name Changes''' and '''Event Name Changes''' above

* '''.looknfeel:'''
** <Falagard version="7">
** old: <Image '''type'''="TopEdge" '''imageset'''="TaharezLook" '''image'''="TitlebarTop" /> new: <Image '''component'''="TopEdge" '''name'''="TaharezLook/TitlebarTop" />
** Change: MaxEditTextLength → MaxTextLength
** Change: MouseButtonDownAutoRepeat → MouseAutoRepeatEnabled
** Change: DimOperator → OperatorDim. Please compare [http://static.cegui.org.uk/docs/0.7.9/fal_element_ref.html#fal_elem_ref_sec_10 0.7.9] with [http://static.cegui.org.uk/docs/current/fal_element_ref.html#fal_elem_ref_sec_operatordim latest] for functional change description
*** old formatting: VALUE1 { DIMOPERATOR() { VALUE2 } } new formatting: OPERATORDIM() { VALUE1, VALUE2 }
* '''.scheme:'''
** <GUIScheme name="MySkin" version="5">
** Change: <WindowRendererSet Filename="CEGUIFalagardWRBase" /> → <WindowRendererSet filename="CEGUICoreWindowRendererSet" />
** Change: renderer="Falagard/... → renderer="Core/...
** Change: "Core/SystemButton" → "Core/Button"
** Change: "CEGUI/Checkbox" → "CEGUI/ToggleButton"
* '''.layout:'''
** <GUILayout version="4">
** UnifiedPosition, UnifiedAreaRect, UnifiedSize, UnifiedMinSize, UnifiedMaxSize → Position, Area, Size, MinSize, MaxSize
** Tooltip → TooltipText
** old: <Property name="Image" value="set:Buttons image:Settings" /> new: <Property name="Image" value="Buttons/Settings" />
* '''.imageset:'''
** <Imageset version="2" ... />
* '''.font:'''
** 
}}
[[Category:Manuals]]

Porting tips and changes from 0.7.X to 0.8.X

2014-01-25T22:22:38Z

Mmixlinus:

{{VersionBadge|0.7}}

{{Section|1=Introduction|2=
The 0.8.x branch has already seen releases. Please see the sourceforge page for tarball downloads.
}}
{{Section|1=Major renames/API changes|2=
* CEGUI::Window was renamed to CEGUI::Widget as Widget is the coined term for that, WindowManager renamed to WidgetManager, etc... (not in mercurial yet!)
* The stock/standard window renderer set (now widget renderer set) FalagardWRBase was renamed to StandardWRSet to avoid confusion with core [[Falagard]] facilities (not in mercurial yet!)
* Windows now don't have absolute names! Every window's name only has to be unique in it's parent window. Therefore WindowManager::getSingleton().getWindow no longer made sense and was removed. If root's name was "Root" and your the window name was "Root/Stuff/After/Root/Name", you can emulate its behaviour with root->getChild("Stuff/After/Root/Name"). It's recommended to migrate to a more encapsulated model.
* CEGUI::GUIContext class has been created that is responsible for injecting input and event handling, setting the default font, setting the root window, setting a default tooltip object and type, and manipulating the mouse cursor.
* CEGUI::GUIContext needs time impulses injected separately! You should also inject time pulses into CEGUI::System. This API "wart" may disappear in future versions.
* CEGUI::MouseCursor is no longer a singleton, and can be accessed and manipulated from CEGUI::GUIContext.
}}
{{Section|1=General|2=
* All XML attributes must now be in lowercase, e.g. <WidgetLook Name="TaharezLook/FrameWindow"> must be <WidgetLook name="TaharezLook/FrameWindow">
* PropertyHelper has been turned into a template class, instead of PropertyHelper::uintToString you do PropertyHelper<uint>::toString, instead of PropertyHelper::stringToUint you do PropertyHelper<uint>::fromString
* All instances of the word caret that were incorrectly spelt 'carat' have been corrected. This affects all APIs, properties, events and datafiles.
* Window::EventWindowUpdated renamed to Window::EventUpdated and the associated string is changed from "WindowUpdate" to "Updated"
* ListHeader::SegmentNameSuffix changed type from character array to CEGUI::String
* BiDiVisualMapping renamed to BidiVisualMapping. Also renamed the files, so CEGUIBiDiVisualMapping.h is now CEGUIBidiVisualMapping.h
* class colour renamed to Colour, as a side effect the "colour" interpolator is now "Colour" interpolator, this breaks animation definitions!
* Point typedef removed, please use Vector2 instead
* Many event string values changed to match the C++ name (but without the Event prefix). A list of which strings changed value will appear here soon.
* Window::setRestoreCapture renamed to Window::setRestoreOldCapture
* CEGUI now supports custom memory allocation, see [[Memory Allocation]] to check if this concerns you or not.
* Window::addChildWindow renamed to Window::addChild, Window::removeChildWindow renamed to Window::removeChild, several other methods (mostly in layout containers) changed from *ChildWindow* to *Child*
* CEGUI::String can now be just a typedef or a class, depending on String configuration (CEGUI can now use std::string as CEGUI::String for apps not requiring unicode)
* Window::getChild_impl method completely removed, it was only used by Window::getParentPixelSize, shouldn't be hard to replace
* Vector2, Vector3, Size and Rect are now templated, you should use Vector2<float> (or just Vector2<> as a shortcut since float is the default type) instead of Vector2, UVector2 class was removed, UVector2 is now just a typedef to Vector2<UDim>. Same with Vector3, Size and Rect.
* Texture::saveToMemory is renamed Texture::blitToMemory.
* Renderer and Texture interfaces changed in order to support named textures.
* Window::isDisabled(localOnly) is now split into Window::isDisabled (= old isDisabled(true) and Window::isEffectiveDisabled (= old isDisabled(false))
* Window::isVisible(localOnly) is now split into Window::isVisible (= old isDisabled(true) and Window::isEffectiveVisible (= old isVisible(false))
* WindowManager::loadWindowLayout is renamed to WindowManager::loadLayoutFromFile
* NamedXMLResourceManager::create is renamed to NamedXMLResourceManager::createFromFile (Ex. CEGUI::SchemeManager::createFromFile)
* CEGUI::DefaultLogger no longer throws const char* but a real exception in setLogFilename - http://www.cegui.org.uk/mantis/view.php?id=443
* CEGUI now has inbuilt copy, cut, paste support, if you used a custom solution, you might want to check CEGUI::Clipboard and System::inject{Copy,Cut,Paste}Request
* CEGUI::ProgressBar::getStep renamed to getStepSize for consistency with setStepSize
* CEGUI::WidgetLookManager::parseLookNFeelSpecification is now called parseLookNFeelSpecificationFromFile, variants for loading from string and raw data container have been added
* XRotation, YRotation, ZRotation properties merged into the new Rotation property, which is a Quaternion.
}}
{{Section|1=Property Name Changes|2=
* Property from Window called "ZOrderChangeEnabled" renamed to "ZOrderingEnabled"
* Property from Window called "MouseButtonDownAutoRepeat" renamed to "MouseAutoRepeatEnabled"
* Property from Window called "CustomTooltipType" renamed to "TooltipType"
* Property from Window called "Tooltip" renamed to "TooltipText"
* Property from Window called "RiseOnClick" renamed to "RiseOnClickEnabled"
* Property from Window called "UnifiedAreaRect" renamed to "Area", "UnifiedSize" renamed to "Size", etc...
* Property "MaxEditTextLength" renamed to "MaxTextLength"
}}
{{Section|1=Event Name Changes|2=
* EventMouseEnters renamed to EventMouseEntersSurface (old name removed)
* EventMouseLeaves renamed to EventMouseLeavesSurface (old name removed)
* CheckStateChanged renamed to SelectStateChanged (for ToggleButton (old Checkbox))
}}
{{Section|1=Image and ImageManager|2=
* Image::draw renamed to Image::render
* Image class is now an abstract interface. BasicImage implementation is provided, and used for internally created Image objects.
* Imageset class is removed. It remains a CEGUI format that allows to conveniently define multiple images on one texture but the data is no longer stored in any class. When Imageset is loaded, the ImageManager creates a new BasicImage for each of the images in the imageset. Only the images themselves will remain after imageset is loaded. You now use the new ImageManager to access defined images.
* ImagesetManager class is removed. You now use the new ImageManager.
* Images belonging to a certain imageset can be accessed like so: "ImageSetName/ImageName" (ex. "AlfiskoSkin/MouseArrow").
}}
{{Section|1=GUIContext|2=
A lot of API has been moved from CEGUI::System to CEGUI::GUIContext. CEGUI now allows you to create multiple independent GUI contexts with their own input injection.

As a rule of thumb, whenever you see "There is no CEGUI::System::some_foobar_method method", it is likely that you can replace the call with CEGUI::System::getSingleton().getDefaultGUIContext().someFoobarMethod(). This holds for all the System::inject* methods for example.

WindowManager::getSingleton().getWindow() was removed. You can emulate its behaviour with root->getChild("Stuff/After/Root/Name").
To get Root Window you can call GUIContext::getRootWindow();

SIDE NOTE: The chain call of methods CEGUI::System::getSingleton().getDefaultGUIContext() should be called as rarely as possible, instead one should keep it's result in appropriate variable.

}}
{{Section|1=PyCEGUI|2=
* EventSet.subscribeEvent now has a different, more pythonic syntax, any python callable (bound member function, free function, lambda, functor, ...) is allowed (EventSet.subscribeEvent("EventName", instance, "someMethodInIt") is now EventSet.subscribeEvent("EventName", instance.someMethodInIt)
}}

{{Section|1=Datafiles|2=
* All XML datafiles must specify a version attribute. Example: <GUILayout '''version="4"'''>
* All attributes in datafiles must begin with a lower-case letter. Example: <Property '''n'''ame="Alpha" '''v'''alue="1.0" />
* See '''Property Name Changes''' and '''Event Name Changes''' above

* '''.looknfeel:'''
** <Falagard version="7">
** old: <Image '''type'''="TopEdge" '''imageset'''="TaharezLook" '''image'''="TitlebarTop" /> new: <Image '''component'''="TopEdge" '''name'''="TaharezLook/TitlebarTop" />
** Change: MaxEditTextLength → MaxTextLength
** Change: MouseButtonDownAutoRepeat → MouseAutoRepeatEnabled
** Change: DimOperator → OperatorDim. Please compare [http://static.cegui.org.uk/docs/0.7.9/fal_element_ref.html#fal_elem_ref_sec_10 0.7.9] with [http://static.cegui.org.uk/docs/current/fal_element_ref.html#fal_elem_ref_sec_operatordim latest] for functional change description
*** old formatting: VALUE1 { DIMOPERATOR() { VALUE2 } } new formatting: OPERATORDIM() { VALUE1, VALUE2 }
* '''.scheme:'''
** <GUIScheme name="MySkin" version="5">
** Change: <WindowRendererSet Filename="CEGUIFalagardWRBase" /> → <WindowRendererSet filename="CEGUICoreWindowRendererSet" />
** Change: renderer="Falagard/... → renderer="Core/...
** Change: "Core/SystemButton" → "Core/Button"
** Change: "CEGUI/Checkbox" → "CEGUI/ToggleButton"
* '''.layout:'''
** <GUILayout version="4">
** UnifiedPosition, UnifiedAreaRect, UnifiedSize, UnifiedMinSize, UnifiedMaxSize → Position, Area, Size, MinSize, MaxSize
** Tooltip → TooltipText
** old: <Property name="Image" value="set:Buttons image:Settings" /> new: <Property name="Image" value="Buttons/Settings" />
* '''.imageset:'''
** 
* '''.font:'''
** 
}}
[[Category:Manuals]]

Porting tips and changes from 0.7.X to 0.8.X

2014-01-23T16:08:26Z

Mmixlinus:

Porting tips and changes from 0.7.X to 0.8.X

2014-01-23T15:56:58Z

Mmixlinus:

{{VersionBadge|0.7}}

{{Section|1=Introduction|2=
The 0.8.x branch has already seen releases. Please see the sourceforge page for tarball downloads.
}}
{{Section|1=Major renames/API changes|2=
* CEGUI::Window was renamed to CEGUI::Widget as Widget is the coined term for that, WindowManager renamed to WidgetManager, etc... (not in mercurial yet!)
* The stock/standard window renderer set (now widget renderer set) FalagardWRBase was renamed to StandardWRSet to avoid confusion with core [[Falagard]] facilities (not in mercurial yet!)
* Windows now don't have absolute names! Every window's name only has to be unique in it's parent window. Therefore WindowManager::getSingleton().getWindow no longer made sense and was removed. If root's name was "Root" and your the window name was "Root/Stuff/After/Root/Name", you can emulate its behaviour with root->getChild("Stuff/After/Root/Name"). It's recommended to migrate to a more encapsulated model.
* CEGUI::GUIContext class has been created that is responsible for injecting input and event handling, setting the default font, setting the root window, setting a default tooltip object and type, and manipulating the mouse cursor.
* CEGUI::GUIContext needs time impulses injected separately! You should also inject time pulses into CEGUI::System. This API "wart" may disappear in future versions.
* CEGUI::MouseCursor is no longer a singleton, and can be accessed and manipulated from CEGUI::GUIContext.
}}
{{Section|1=General|2=
* All XML attributes must now be in lowercase, e.g. <WidgetLook Name="TaharezLook/FrameWindow"> must be <WidgetLook name="TaharezLook/FrameWindow">
* PropertyHelper has been turned into a template class, instead of PropertyHelper::uintToString you do PropertyHelper<uint>::toString, instead of PropertyHelper::stringToUint you do PropertyHelper<uint>::fromString
* All instances of the word caret that were incorrectly spelt 'carat' have been corrected. This affects all APIs, properties, events and datafiles.
* Window::EventWindowUpdated renamed to Window::EventUpdated and the associated string is changed from "WindowUpdate" to "Updated"
* ListHeader::SegmentNameSuffix changed type from character array to CEGUI::String
* BiDiVisualMapping renamed to BidiVisualMapping. Also renamed the files, so CEGUIBiDiVisualMapping.h is now CEGUIBidiVisualMapping.h
* class colour renamed to Colour, as a side effect the "colour" interpolator is now "Colour" interpolator, this breaks animation definitions!
* Point typedef removed, please use Vector2 instead
* Many event string values changed to match the C++ name (but without the Event prefix). A list of which strings changed value will appear here soon.
* Window::setRestoreCapture renamed to Window::setRestoreOldCapture
* CEGUI now supports custom memory allocation, see [[Memory Allocation]] to check if this concerns you or not.
* Window::addChildWindow renamed to Window::addChild, Window::removeChildWindow renamed to Window::removeChild, several other methods (mostly in layout containers) changed from *ChildWindow* to *Child*
* CEGUI::String can now be just a typedef or a class, depending on String configuration (CEGUI can now use std::string as CEGUI::String for apps not requiring unicode)
* Window::getChild_impl method completely removed, it was only used by Window::getParentPixelSize, shouldn't be hard to replace
* Vector2, Vector3, Size and Rect are now templated, you should use Vector2<float> (or just Vector2<> as a shortcut since float is the default type) instead of Vector2, UVector2 class was removed, UVector2 is now just a typedef to Vector2<UDim>. Same with Vector3, Size and Rect.
* Texture::saveToMemory is renamed Texture::blitToMemory.
* Renderer and Texture interfaces changed in order to support named textures.
* Window::isDisabled(localOnly) is now split into Window::isDisabled (= old isDisabled(true) and Window::isEffectiveDisabled (= old isDisabled(false))
* Window::isVisible(localOnly) is now split into Window::isVisible (= old isDisabled(true) and Window::isEffectiveVisible (= old isVisible(false))
* WindowManager::loadWindowLayout is renamed to WindowManager::loadLayoutFromFile
* NamedXMLResourceManager::create is renamed to NamedXMLResourceManager::createFromFile (Ex. CEGUI::SchemeManager::createFromFile)
* CEGUI::DefaultLogger no longer throws const char* but a real exception in setLogFilename - http://www.cegui.org.uk/mantis/view.php?id=443
* CEGUI now has inbuilt copy, cut, paste support, if you used a custom solution, you might want to check CEGUI::Clipboard and System::inject{Copy,Cut,Paste}Request
* CEGUI::ProgressBar::getStep renamed to getStepSize for consistency with setStepSize
* CEGUI::WidgetLookManager::parseLookNFeelSpecification is now called parseLookNFeelSpecificationFromFile, variants for loading from string and raw data container have been added
* XRotation, YRotation, ZRotation properties merged into the new Rotation property, which is a Quaternion.
}}
{{Section|1=Property Name Changes|2=
* Property from Window called "ZOrderChangeEnabled" renamed to "ZOrderingEnabled"
* Property from Window called "MouseButtonDownAutoRepeat" renamed to "MouseAutoRepeatEnabled"
* Property from Window called "CustomTooltipType" renamed to "TooltipType"
* Property from Window called "Tooltip" renamed to "TooltipText"
* Property from Window called "RiseOnClick" renamed to "RiseOnClickEnabled"
* Property from Window called "UnifiedAreaRect" renamed to "Area", "UnifiedSize" renamed to "Size", etc...
* Property "MaxEditTextLength" renamed to "MaxTextLength"
}}
{{Section|1=Event NameChanges|2=
* EventMouseEnters renamed to EventMouseEntersSurface (old name removed)
* EventMouseLeaves renamed to EventMouseLeavesSurface (old name removed)
* CheckStateChanged renamed to SelectStateChanged (for ToggleButton (old Checkbox))
}}
{{Section|1=Image and ImageManager|2=
* Image::draw renamed to Image::render
* Image class is now an abstract interface. BasicImage implementation is provided, and used for internally created Image objects.
* Imageset class is removed. It remains a CEGUI format that allows to conveniently define multiple images on one texture but the data is no longer stored in any class. When Imageset is loaded, the ImageManager creates a new BasicImage for each of the images in the imageset. Only the images themselves will remain after imageset is loaded. You now use the new ImageManager to access defined images.
* ImagesetManager class is removed. You now use the new ImageManager.
* Images belonging to a certain imageset can be accessed like so: "ImageSetName/ImageName" (ex. "AlfiskoSkin/MouseArrow").
}}
{{Section|1=GUIContext|2=
A lot of API has been moved from CEGUI::System to CEGUI::GUIContext. CEGUI now allows you to create multiple independent GUI contexts with their own input injection.

As a rule of thumb, whenever you see "There is no CEGUI::System::some_foobar_method method", it is likely that you can replace the call with CEGUI::System::getSingleton().getDefaultGUIContext().someFoobarMethod(). This holds for all the System::inject* methods for example.

WindowManager::getSingleton().getWindow() was removed. You can emulate its behaviour with root->getChild("Stuff/After/Root/Name").
To get Root Window you can call GUIContext::getRootWindow();

SIDE NOTE: The chain call of methods CEGUI::System::getSingleton().getDefaultGUIContext() should be called as rarely as possible, instead one should keep it's result in appropriate variable.

}}
{{Section|1=PyCEGUI|2=
* EventSet.subscribeEvent now has a different, more pythonic syntax, any python callable (bound member function, free function, lambda, functor, ...) is allowed (EventSet.subscribeEvent("EventName", instance, "someMethodInIt") is now EventSet.subscribeEvent("EventName", instance.someMethodInIt)
}}

{{Section|1=Datafiles|2=
* All XML datafiles must specify a version attribute. Example: <GUILayout '''version="4"'''>
* All attributes in datafiles must begin with a lower-case letter. Example: <Property '''n'''ame="Alpha" '''v'''alue="1.0" />
* '''.looknfeel:'''
** <Falagard version="7">
** old: <Image '''type'''="TopEdge" '''imageset'''="TaharezLook" '''image'''="TitlebarTop" /> new: <Image '''component'''="TopEdge" '''name'''="TaharezLook/TitlebarTop" />
** Change: MaxEditTextLength → MaxTextLength
** Change: MouseButtonDownAutoRepeat → MouseAutoRepeatEnabled
** Change: DimOperator → OperatorDim. Please compare [http://static.cegui.org.uk/docs/0.7.9/fal_element_ref.html#fal_elem_ref_sec_10 0.7.9] with [http://static.cegui.org.uk/docs/current/fal_element_ref.html#fal_elem_ref_sec_operatordim latest] for functional change description
* '''.scheme:'''
** <GUIScheme name="MySkin" version="5">
** Change: <WindowRendererSet Filename="CEGUIFalagardWRBase" /> → <WindowRendererSet filename="CEGUICoreWindowRendererSet" />
** Change: renderer="Falagard/... → renderer="Core/...
** Change: "Core/SystemButton" → "Core/Button"
** Change: "CEGUI/Checkbox" → "CEGUI/ToggleButton"
* '''.layout:'''
** <GUILayout version="4">
** see '''Event-related Changes''' above
** UnifiedPosition, UnifiedAreaRect, UnifiedSize, UnifiedMinSize, UnifiedMaxSize → Position, Area, Size, MinSize, MaxSize
** Tooltip → TooltipText
** old: <Property name="Image" value="set:Buttons image:Settings" /> new: <Property name="Image" value="Buttons/Settings" />

}}
[[Category:Manuals]]

Porting tips and changes from 0.7.X to 0.8.X

2014-01-21T22:27:39Z

Mmixlinus:

{{VersionBadge|0.7}}

{{Section|1=Introduction|2=
The 0.8.x branch has already seen releases. Please see the sourceforge page for tarball downloads.
}}
{{Section|1=Major renames/API changes|2=
* CEGUI::Window was renamed to CEGUI::Widget as Widget is the coined term for that, WindowManager renamed to WidgetManager, etc... (not in mercurial yet!)
* The stock/standard window renderer set (now widget renderer set) FalagardWRBase was renamed to StandardWRSet to avoid confusion with core [[Falagard]] facilities (not in mercurial yet!)
* Windows now don't have absolute names! Every window's name only has to be unique in it's parent window. Therefore WindowManager::getSingleton().getWindow no longer made sense and was removed. If root's name was "Root" and your the window name was "Root/Stuff/After/Root/Name", you can emulate its behaviour with root->getChild("Stuff/After/Root/Name"). It's recommended to migrate to a more encapsulated model.
* CEGUI::GUIContext class has been created that is responsible for injecting input and event handling, setting the default font, setting the root window, setting a default tooltip object and type, and manipulating the mouse cursor.
* CEGUI::GUIContext needs time impulses injected separately! You should also inject time pulses into CEGUI::System. This API "wart" may disappear in future versions.
* CEGUI::MouseCursor is no longer a singleton, and can be accessed and manipulated from CEGUI::GUIContext.
}}
{{Section|1=General|2=
* All XML attributes must now be in lowercase, e.g. <WidgetLook Name="TaharezLook/FrameWindow"> must be <WidgetLook name="TaharezLook/FrameWindow">
* PropertyHelper has been turned into a template class, instead of PropertyHelper::uintToString you do PropertyHelper<uint>::toString, instead of PropertyHelper::stringToUint you do PropertyHelper<uint>::fromString
* All instances of the word caret that were incorrectly spelt 'carat' have been corrected. This affects all APIs, properties, events and datafiles.
* Window::EventWindowUpdated renamed to Window::EventUpdated and the associated string is changed from "WindowUpdate" to "Updated"
* ListHeader::SegmentNameSuffix changed type from character array to CEGUI::String
* BiDiVisualMapping renamed to BidiVisualMapping. Also renamed the files, so CEGUIBiDiVisualMapping.h is now CEGUIBidiVisualMapping.h
* class colour renamed to Colour, as a side effect the "colour" interpolator is now "Colour" interpolator, this breaks animation definitions!
* Point typedef removed, please use Vector2 instead
* Many event string values changed to match the C++ name (but without the Event prefix). A list of which strings changed value will appear here soon.
* Window::setRestoreCapture renamed to Window::setRestoreOldCapture
* CEGUI now supports custom memory allocation, see [[Memory Allocation]] to check if this concerns you or not.
* Window::addChildWindow renamed to Window::addChild, Window::removeChildWindow renamed to Window::removeChild, several other methods (mostly in layout containers) changed from *ChildWindow* to *Child*
* CEGUI::String can now be just a typedef or a class, depending on String configuration (CEGUI can now use std::string as CEGUI::String for apps not requiring unicode)
* Window::getChild_impl method completely removed, it was only used by Window::getParentPixelSize, shouldn't be hard to replace
* Vector2, Vector3, Size and Rect are now templated, you should use Vector2<float> (or just Vector2<> as a shortcut since float is the default type) instead of Vector2, UVector2 class was removed, UVector2 is now just a typedef to Vector2<UDim>. Same with Vector3, Size and Rect.
* Texture::saveToMemory is renamed Texture::blitToMemory.
* Renderer and Texture interfaces changed in order to support named textures.
* Window::isDisabled(localOnly) is now split into Window::isDisabled (= old isDisabled(true) and Window::isEffectiveDisabled (= old isDisabled(false))
* Window::isVisible(localOnly) is now split into Window::isVisible (= old isDisabled(true) and Window::isEffectiveVisible (= old isVisible(false))
* WindowManager::loadWindowLayout is renamed to WindowManager::loadLayoutFromFile
* NamedXMLResourceManager::create is renamed to NamedXMLResourceManager::createFromFile (Ex. CEGUI::SchemeManager::createFromFile)
* Property from Window called "ZOrderChangeEnabled" renamed to "ZOrderingEnabled"
* Property from Window called "MouseButtonDownAutoRepeat" renamed to "MouseAutoRepeatEnabled"
* Property from Window called "CustomTooltipType" renamed to "TooltipType"
* Property from Window called "Tooltip" renamed to "TooltipText"
* Property from Window called "RiseOnClick" renamed to "RiseOnClickEnabled"
* Property from Window called "UnifiedAreaRect" renamed to "Area", "UnifiedSize" renamed to "Size", etc...
* CEGUI::DefaultLogger no longer throws const char* but a real exception in setLogFilename - http://www.cegui.org.uk/mantis/view.php?id=443
* CEGUI now has inbuilt copy, cut, paste support, if you used a custom solution, you might want to check CEGUI::Clipboard and System::inject{Copy,Cut,Paste}Request
* CEGUI::ProgressBar::getStep renamed to getStepSize for consistency with setStepSize
* CEGUI::WidgetLookManager::parseLookNFeelSpecification is now called parseLookNFeelSpecificationFromFile, variants for loading from string and raw data container have been added
* XRotation, YRotation, ZRotation properties merged into the new Rotation property, which is a Quaternion.
}}
{{Section|1=Event-related Changes|2=
* EventMouseEnters renamed to EventMouseEntersSurface (old name removed)
* EventMouseLeaves renamed to EventMouseLeavesSurface (old name removed)
* CheckStateChanged renamed to SelectStateChanged (for ToggleButton (old Checkbox))
}}
{{Section|1=Image and ImageManager|2=
* Image::draw renamed to Image::render
* Image class is now an abstract interface. BasicImage implementation is provided, and used for internally created Image objects.
* Imageset class is removed. It remains a CEGUI format that allows to conveniently define multiple images on one texture but the data is no longer stored in any class. When Imageset is loaded, the ImageManager creates a new BasicImage for each of the images in the imageset. Only the images themselves will remain after imageset is loaded. You now use the new ImageManager to access defined images.
* ImagesetManager class is removed. You now use the new ImageManager.
* Images belonging to a certain imageset can be accessed like so: "ImageSetName/ImageName" (ex. "AlfiskoSkin/MouseArrow").
}}
{{Section|1=GUIContext|2=
A lot of API has been moved from CEGUI::System to CEGUI::GUIContext. CEGUI now allows you to create multiple independent GUI contexts with their own input injection.

As a rule of thumb, whenever you see "There is no CEGUI::System::some_foobar_method method", it is likely that you can replace the call with CEGUI::System::getSingleton().getDefaultGUIContext().someFoobarMethod(). This holds for all the System::inject* methods for example.

WindowManager::getSingleton().getWindow() was removed. You can emulate its behaviour with root->getChild("Stuff/After/Root/Name").
To get Root Window you can call GUIContext::getRootWindow();

SIDE NOTE: The chain call of methods CEGUI::System::getSingleton().getDefaultGUIContext() should be called as rarely as possible, instead one should keep it's result in appropriate variable.

}}
{{Section|1=PyCEGUI|2=
* EventSet.subscribeEvent now has a different, more pythonic syntax, any python callable (bound member function, free function, lambda, functor, ...) is allowed (EventSet.subscribeEvent("EventName", instance, "someMethodInIt") is now EventSet.subscribeEvent("EventName", instance.someMethodInIt)
}}

{{Section|1=Datafiles|2=
* All XML datafiles must specify a version attribute. Example: <GUILayout '''version="4"'''>
* All attributes in datafiles must begin with a lower-case letter. Example: <Property '''n'''ame="Alpha" '''v'''alue="1.0" />
* '''.looknfeel:'''
** <Falagard version="7">
** old: <Image '''type'''="TopEdge" '''imageset'''="TaharezLook" '''image'''="TitlebarTop" /> new: <Image '''component'''="TopEdge" '''name'''="TaharezLook/TitlebarTop" />
** Change: MaxEditTextLength → MaxTextLength
** Change: MouseButtonDownAutoRepeat → MouseAutoRepeatEnabled
** Change: DimOperator → OperatorDim. Please compare [http://static.cegui.org.uk/docs/0.7.9/fal_element_ref.html#fal_elem_ref_sec_10 0.7.9] with [http://static.cegui.org.uk/docs/current/fal_element_ref.html#fal_elem_ref_sec_operatordim latest] for functional change description
* '''.scheme:'''
** <GUIScheme name="MySkin" version="5">
** Change: <WindowRendererSet Filename="CEGUIFalagardWRBase" /> → <WindowRendererSet filename="CEGUICoreWindowRendererSet" />
** Change: renderer="Falagard/... → renderer="Core/...
** Change: "Core/SystemButton" → "Core/Button"
** Change: "CEGUI/Checkbox" → "CEGUI/ToggleButton"
* '''.layout:'''
** <GUILayout version="4">
** see '''Event-related Changes''' above
** UnifiedPosition, UnifiedAreaRect, UnifiedSize, UnifiedMinSize, UnifiedMaxSize → Position, Area, Size, MinSize, MaxSize
** Tooltip → TooltipText
** old: <Property name="Image" value="set:Buttons image:Settings" /> new: <Property name="Image" value="Buttons/Settings" />

}}
[[Category:Manuals]]

Porting tips and changes from 0.7.X to 0.8.X

2014-01-21T22:24:49Z

Mmixlinus: Added changes for datafiles

{{VersionBadge|0.7}}

{{Section|1=Introduction|2=
The 0.8.x branch has already seen releases. Please see the sourceforge page for tarball downloads.
}}
{{Section|1=Major renames/API changes|2=
* CEGUI::Window was renamed to CEGUI::Widget as Widget is the coined term for that, WindowManager renamed to WidgetManager, etc... (not in mercurial yet!)
* The stock/standard window renderer set (now widget renderer set) FalagardWRBase was renamed to StandardWRSet to avoid confusion with core [[Falagard]] facilities (not in mercurial yet!)
* Windows now don't have absolute names! Every window's name only has to be unique in it's parent window. Therefore WindowManager::getSingleton().getWindow no longer made sense and was removed. If root's name was "Root" and your the window name was "Root/Stuff/After/Root/Name", you can emulate its behaviour with root->getChild("Stuff/After/Root/Name"). It's recommended to migrate to a more encapsulated model.
* CEGUI::GUIContext class has been created that is responsible for injecting input and event handling, setting the default font, setting the root window, setting a default tooltip object and type, and manipulating the mouse cursor.
* CEGUI::GUIContext needs time impulses injected separately! You should also inject time pulses into CEGUI::System. This API "wart" may disappear in future versions.
* CEGUI::MouseCursor is no longer a singleton, and can be accessed and manipulated from CEGUI::GUIContext.
}}
{{Section|1=General|2=
* All XML attributes must now be in lowercase, e.g. <WidgetLook Name="TaharezLook/FrameWindow"> must be <WidgetLook name="TaharezLook/FrameWindow">
* PropertyHelper has been turned into a template class, instead of PropertyHelper::uintToString you do PropertyHelper<uint>::toString, instead of PropertyHelper::stringToUint you do PropertyHelper<uint>::fromString
* All instances of the word caret that were incorrectly spelt 'carat' have been corrected. This affects all APIs, properties, events and datafiles.
* Window::EventWindowUpdated renamed to Window::EventUpdated and the associated string is changed from "WindowUpdate" to "Updated"
* ListHeader::SegmentNameSuffix changed type from character array to CEGUI::String
* BiDiVisualMapping renamed to BidiVisualMapping. Also renamed the files, so CEGUIBiDiVisualMapping.h is now CEGUIBidiVisualMapping.h
* class colour renamed to Colour, as a side effect the "colour" interpolator is now "Colour" interpolator, this breaks animation definitions!
* Point typedef removed, please use Vector2 instead
* Many event string values changed to match the C++ name (but without the Event prefix). A list of which strings changed value will appear here soon.
* Window::setRestoreCapture renamed to Window::setRestoreOldCapture
* CEGUI now supports custom memory allocation, see [[Memory Allocation]] to check if this concerns you or not.
* Window::addChildWindow renamed to Window::addChild, Window::removeChildWindow renamed to Window::removeChild, several other methods (mostly in layout containers) changed from *ChildWindow* to *Child*
* CEGUI::String can now be just a typedef or a class, depending on String configuration (CEGUI can now use std::string as CEGUI::String for apps not requiring unicode)
* Window::getChild_impl method completely removed, it was only used by Window::getParentPixelSize, shouldn't be hard to replace
* Vector2, Vector3, Size and Rect are now templated, you should use Vector2<float> (or just Vector2<> as a shortcut since float is the default type) instead of Vector2, UVector2 class was removed, UVector2 is now just a typedef to Vector2<UDim>. Same with Vector3, Size and Rect.
* Texture::saveToMemory is renamed Texture::blitToMemory.
* Renderer and Texture interfaces changed in order to support named textures.
* Window::isDisabled(localOnly) is now split into Window::isDisabled (= old isDisabled(true) and Window::isEffectiveDisabled (= old isDisabled(false))
* Window::isVisible(localOnly) is now split into Window::isVisible (= old isDisabled(true) and Window::isEffectiveVisible (= old isVisible(false))
* WindowManager::loadWindowLayout is renamed to WindowManager::loadLayoutFromFile
* NamedXMLResourceManager::create is renamed to NamedXMLResourceManager::createFromFile (Ex. CEGUI::SchemeManager::createFromFile)
* Property from Window called "ZOrderChangeEnabled" renamed to "ZOrderingEnabled"
* Property from Window called "MouseButtonDownAutoRepeat" renamed to "MouseAutoRepeatEnabled"
* Property from Window called "CustomTooltipType" renamed to "TooltipType"
* Property from Window called "Tooltip" renamed to "TooltipText"
* Property from Window called "RiseOnClick" renamed to "RiseOnClickEnabled"
* Property from Window called "UnifiedAreaRect" renamed to "Area", "UnifiedSize" renamed to "Size", etc...
* CEGUI::DefaultLogger no longer throws const char* but a real exception in setLogFilename - http://www.cegui.org.uk/mantis/view.php?id=443
* CEGUI now has inbuilt copy, cut, paste support, if you used a custom solution, you might want to check CEGUI::Clipboard and System::inject{Copy,Cut,Paste}Request
* CEGUI::ProgressBar::getStep renamed to getStepSize for consistency with setStepSize
* CEGUI::WidgetLookManager::parseLookNFeelSpecification is now called parseLookNFeelSpecificationFromFile, variants for loading from string and raw data container have been added
* XRotation, YRotation, ZRotation properties merged into the new Rotation property, which is a Quaternion.
}}
{{Section|1=Event-related Changes|2=
* EventMouseEnters renamed to EventMouseEntersSurface (old name removed)
* EventMouseLeaves renamed to EventMouseLeavesSurface (old name removed)
* CheckStateChanged renamed to SelectStateChanged (for ToggleButton (old Checkbox))
}}
{{Section|1=Image and ImageManager|2=
* Image::draw renamed to Image::render
* Image class is now an abstract interface. BasicImage implementation is provided, and used for internally created Image objects.
* Imageset class is removed. It remains a CEGUI format that allows to conveniently define multiple images on one texture but the data is no longer stored in any class. When Imageset is loaded, the ImageManager creates a new BasicImage for each of the images in the imageset. Only the images themselves will remain after imageset is loaded. You now use the new ImageManager to access defined images.
* ImagesetManager class is removed. You now use the new ImageManager.
* Images belonging to a certain imageset can be accessed like so: "ImageSetName/ImageName" (ex. "AlfiskoSkin/MouseArrow").
}}
{{Section|1=GUIContext|2=
A lot of API has been moved from CEGUI::System to CEGUI::GUIContext. CEGUI now allows you to create multiple independent GUI contexts with their own input injection.

As a rule of thumb, whenever you see "There is no CEGUI::System::some_foobar_method method", it is likely that you can replace the call with CEGUI::System::getSingleton().getDefaultGUIContext().someFoobarMethod(). This holds for all the System::inject* methods for example.

WindowManager::getSingleton().getWindow() was removed. You can emulate its behaviour with root->getChild("Stuff/After/Root/Name").
To get Root Window you can call GUIContext::getRootWindow();

SIDE NOTE: The chain call of methods CEGUI::System::getSingleton().getDefaultGUIContext() should be called as rarely as possible, instead one should keep it's result in appropriate variable.

}}
{{Section|1=PyCEGUI|2=
* EventSet.subscribeEvent now has a different, more pythonic syntax, any python callable (bound member function, free function, lambda, functor, ...) is allowed (EventSet.subscribeEvent("EventName", instance, "someMethodInIt") is now EventSet.subscribeEvent("EventName", instance.someMethodInIt)
}}

{{Section|1=Datafiles|2=
* All XML datafiles must specify a version attribute. Example: <GUILayout '''version="4"'''>
* All attributes in datafiles must begin with a lower-case letter. Example: <Property '''n'''ame="Alpha" '''v'''alue="1.0" />
* '''.looknfeel:'''
** <Falagard version="7">
** old: <Image '''type'''="TopEdge" '''imageset'''="TaharezLook" '''image'''="TitlebarTop" /> new: <Image '''component'''="TopEdge" '''name'''="TaharezLook/TitlebarTop" />
** Change: MaxEditTextLength → MaxTextLength
** Change: MouseButtonDownAutoRepeat → MouseAutoRepeatEnabled
** Change: DimOperator → OperatorDim. Please compare [http://static.cegui.org.uk/docs/0.7.9/fal_element_ref.html#fal_elem_ref_sec_10 0.7.9] with [http://static.cegui.org.uk/docs/current/fal_element_ref.html#fal_elem_ref_sec_operatordim latest] for functional change description
* '''.scheme:'''
** <GUIScheme name="MySkin" version="5">
** Change: <WindowRendererSet Filename="CEGUIFalagardWRBase" /> → <WindowRendererSet filename="CEGUICoreWindowRendererSet" />
** Change: renderer="Falagard/... → renderer="Core/...
** Change: "Core/SystemButton" → "Core/Button"
** Change: "CEGUI/Checkbox" → "CEGUI/ToggleButton"
* '''.layout:'''
** <GUILayout version="4">
** see '''Event-related Changes''' above
** UnifiedPosition, UnifiedAreaRect, UnifiedSize, UnifiedMinSize, UnifiedMaxSize → Position, Area, Size, MinSize, MaxSize
** Tooltip → TooltipText
** old: <Property name="Image" value="set:Buttons image:Settings" /> new: <Property name="Image" value="Buttons/Settings" />
|}

* The attributes of the Image elements are now:
** ("component") and "name", instead of:
** ("type"), "imageset" and "image"
*** For example an up-to-date Image element inside a FrameComponent element would be: <Image component="LeftEdge" name="TaharezLook/EditBoxLeft" />
* The OperatorDim has changed to DimOperator and works slightly differently. See the new datafiles and the API for more information.
}}
[[Category:Manuals]]

Performance tips

2013-11-25T22:00:21Z

Mmixlinus: /* Small tiled images */

{{VersionBadge|0.7}} {{VersionBadge|0.8}}

This page provides some generic tips on getting the most performance out of CEGUI. People often claim that CEGUI is slow and don't realise it could be them doing something wrong. I will try to gather some areas where people claim CEGUI is slow and "just sucks" and try to provide tips about what is wrong.

== Debug vs Release mode ==
The performance difference between Debug and Release (optimisations enabled) CEGUI can be quite dramatic. Ensure you run everything in release mode when judging performance.

== Small tiled images ==
A very common mistake. If you have a very small (lets say 1px * 1px image) in your imageset and you set your looknfeel to tile that image over 100 px, CEGUI has to generate a lot of triangles to fulfil your wishes! This will lead to very bad performance and should be avoided. Tiling is fine but keep it under control!

(Note: Stretching doesn't have the same caveat, you can stretch 1px image over as many pixels as you want with just 2 triangles and one batch.)

== [[Imageset]]s & Texture atlases ==
Texture switching is a very expensive operation, which is why CEGUI uses [[Imageset|imagesets]]. [[Imageset]]s allows you to put several images in one texture ([[imageset]] ~= texture atlas), thus (potentially) lowering the amount of texture switches when rendering. If you however are from the "[[Imageset]]s suck, it sucks that CEGUI uses them!" and use one bitmap file and one [[imageset]] per image, you might expect very poor performance (many many texture switches even when rendering a single widgets - all corners are in separate file, also batching is simply not possible since you need a separate texture per every rectangle, so one widget might end up being 20 batches or even more!).

The bottom line is: Use [[Imageset|imagesets]], don't hate them! And if you still hate them and use separate files, stop whining that CEGUI is slow and sucks :-D

(Note: CEGUI 0.8 will completely change the way imagesets work. We will have images, these will simply have a reference to texture file and UV coords of the rectangle we should use in the texture file, .imageset files will still load though, so all of this still applies, furthermore the new [[CEED]] editor will support automatic imageset/atlas creation from multiple files to lessen the imageset maintenance pain)

== Problem: Loading layouts takes few seconds and halts my application! ==
This is a complaint I have seen multiple times. The reporter usually has a dialog that in its constructor loads a XML layout off the HDD and constructs its hierarchy based on that. Depending on how the layout is complex, this can indeed take a few seconds (depending on many many factors). What is flawed about this is the fact that the user loads the layout always when the dialog is constructed. Wouldn't it be better if we loaded the layout once, stored it somewhere and reused that whenever the dialog has to reappear instead of deleting the layout when user closes the dialog and loading it from scratch when it's opened?

There are two ways of avoiding this. If the dialog is modal and can only appear once, it pays off to just load it, set it to invisible and the show/hide as necessary. This is the fastest solution.

If you need multiple instances of the dialog, you need to clone the widget tree somehow. This is why Widget (Window in 0.7 and previous) ::clone method has been implemented (only CEGUI 0.7.5 and newer!). It allows you to clone the entire widget hiearchy. The idea is to load this when the dialog is first used (or even when loading the application, depends on how the dialog is used). Store the widget pointer somewhere (could be a static member variable in the Dialog class) and upon construction, just clone the hierarchy and add the cloned widget while leaving the original alone for further cloning.
(TODO: add some example code)

== Speeding up a rarely changing info window (or any widget) with complex elements inside it ==
CEGUI allows caching. This is done with the "AutoRenderingSurface" property. What this means is that the widget gets rendered once with its child widgets (the entire hierarchy). The result is stored in a texture and from this moment on, whenever rendering needs to be done, just one quad with the texture is drawn. When widgets change inside, it invalidates the cache and everything is redrawn from scratch. This is especially useful for complex deep hierarchy widgets that users rarely interact with or aren't interactive at all.

Caveat: The texture caching causes the widget to hard clip its children to its dimensions! That means that a combobox at the bottom of a frame window will get "cut" when you open the options of it. This is likely to get fixed but as of now (5th January 2011) it's still a problem in both 0.7 and 0.8.

== A quick and (relatively) painless way to get roughly 40% performance increase in certain areas (0.8 only!) ==
By default, CEGUI uses no custom allocators at all. That means the plain old new and delete. You can set the allocator to anything you want but we recommend nedmalloc. It's a very robust memory allocator tailored to give maximum performance. It speeds things up especially when initialising, loading layouts, creating windows, ... Give it a try. See [[Memory Allocation]] for more details.

[[Category:Manuals]]
[[Category:WIP]]

Performance tips

2013-11-25T21:59:18Z

Mmixlinus: /* Imagesets & Texture atlases */

{{VersionBadge|0.7}} {{VersionBadge|0.8}}

This page provides some generic tips on getting the most performance out of CEGUI. People often claim that CEGUI is slow and don't realise it could be them doing something wrong. I will try to gather some areas where people claim CEGUI is slow and "just sucks" and try to provide tips about what is wrong.

== Debug vs Release mode ==
The performance difference between Debug and Release (optimisations enabled) CEGUI can be quite dramatic. Ensure you run everything in release mode when judging performance.

== Small tiled images ==
A very common mistake. If you have a very small (lets say 1px * 1px image) in your imageset and you set your looknfeel to tile that image over 100 px, CEGUI has to generate a lot of triangles to fulfil your wishes! This will lead into very bad performance and should be avoided. Tiling is fine but keep it under control!

(Note: Stretching doesn't have the same caveat, you can stretch 1px image over as many pixels as you want with just 2 triangles and one batch.)

== [[Imageset]]s & Texture atlases ==
Texture switching is a very expensive operation, which is why CEGUI uses [[Imageset|imagesets]]. [[Imageset]]s allows you to put several images in one texture ([[imageset]] ~= texture atlas), thus (potentially) lowering the amount of texture switches when rendering. If you however are from the "[[Imageset]]s suck, it sucks that CEGUI uses them!" and use one bitmap file and one [[imageset]] per image, you might expect very poor performance (many many texture switches even when rendering a single widgets - all corners are in separate file, also batching is simply not possible since you need a separate texture per every rectangle, so one widget might end up being 20 batches or even more!).

The bottom line is: Use [[Imageset|imagesets]], don't hate them! And if you still hate them and use separate files, stop whining that CEGUI is slow and sucks :-D

(Note: CEGUI 0.8 will completely change the way imagesets work. We will have images, these will simply have a reference to texture file and UV coords of the rectangle we should use in the texture file, .imageset files will still load though, so all of this still applies, furthermore the new [[CEED]] editor will support automatic imageset/atlas creation from multiple files to lessen the imageset maintenance pain)

== Problem: Loading layouts takes few seconds and halts my application! ==
This is a complaint I have seen multiple times. The reporter usually has a dialog that in its constructor loads a XML layout off the HDD and constructs its hierarchy based on that. Depending on how the layout is complex, this can indeed take a few seconds (depending on many many factors). What is flawed about this is the fact that the user loads the layout always when the dialog is constructed. Wouldn't it be better if we loaded the layout once, stored it somewhere and reused that whenever the dialog has to reappear instead of deleting the layout when user closes the dialog and loading it from scratch when it's opened?

There are two ways of avoiding this. If the dialog is modal and can only appear once, it pays off to just load it, set it to invisible and the show/hide as necessary. This is the fastest solution.

If you need multiple instances of the dialog, you need to clone the widget tree somehow. This is why Widget (Window in 0.7 and previous) ::clone method has been implemented (only CEGUI 0.7.5 and newer!). It allows you to clone the entire widget hiearchy. The idea is to load this when the dialog is first used (or even when loading the application, depends on how the dialog is used). Store the widget pointer somewhere (could be a static member variable in the Dialog class) and upon construction, just clone the hierarchy and add the cloned widget while leaving the original alone for further cloning.
(TODO: add some example code)

== Speeding up a rarely changing info window (or any widget) with complex elements inside it ==
CEGUI allows caching. This is done with the "AutoRenderingSurface" property. What this means is that the widget gets rendered once with its child widgets (the entire hierarchy). The result is stored in a texture and from this moment on, whenever rendering needs to be done, just one quad with the texture is drawn. When widgets change inside, it invalidates the cache and everything is redrawn from scratch. This is especially useful for complex deep hierarchy widgets that users rarely interact with or aren't interactive at all.

Caveat: The texture caching causes the widget to hard clip its children to its dimensions! That means that a combobox at the bottom of a frame window will get "cut" when you open the options of it. This is likely to get fixed but as of now (5th January 2011) it's still a problem in both 0.7 and 0.8.

== A quick and (relatively) painless way to get roughly 40% performance increase in certain areas (0.8 only!) ==
By default, CEGUI uses no custom allocators at all. That means the plain old new and delete. You can set the allocator to anything you want but we recommend nedmalloc. It's a very robust memory allocator tailored to give maximum performance. It speeds things up especially when initialising, loading layouts, creating windows, ... Give it a try. See [[Memory Allocation]] for more details.

[[Category:Manuals]]
[[Category:WIP]]

Building CEGUI for Ogre / OgreRenderer

2013-11-15T15:29:22Z

Mmixlinus: /* General */

{{VersionBadge|0.7}}
{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

== General ==
Since Ogre version 1.7 the CEGUI library has stopped being an Ogre dependency and was replaced with a very simple UI overlay used for the demos. Users now have to compile the CEGUI against Ogre by themselves. This guide was made to help accomplish this.

This means that from now on, you have to build CEGUI for your Ogre project yourself, in case you want to use the latest Ogre or CEGUI versions. Otherwise, you can grab the latest precompiled dependencies from [http://www.ogre3d.org/download the Ogre download section] and [http://www.cegui.org.uk/wiki/index.php/Downloads the CEGUI download section].

The recommended approach however is to build CEGUI against the Ogre version you want to use.

Here are all the links you will need:
* Visit the [http://static.cegui.org.uk/docs/current/downloading.html reference manual] for instructions on obtaining the source code.
'''Note''': If the branch version's source code seems to be unstable or not working at all, you can try the [http://sourceforge.net/projects/crayzedsgui/files/CEGUI%20Mk-2/snapshot latest stable snapshot]
* '''Additionally''' to the source code you will need [http://sourceforge.net/projects/crayzedsgui/files/ dependencies suiting your compiler]. Download them for your CEGUI version and unpack the "dependencies" folder into your CEGUI main folder, so that it will co-exist next to the folders "bin", "cegui", "datafiles" etc. - You are then required to build the dependencies that you want to use and - if using Windows - to place the required dll's into the folder of your executable.

== Step-by-step guide ==
* 1. Get the appropriate '''CEGUI''' version from the CEGUI download page or get the very latest CEGUI version from the SVN repository (see links and info above).

* 2. Get the latest '''Ogre''' version. If you are compiling it yourself, you will need to build it first to get Ogre's .lib and .dll files ready for CEGUI.

=== Steps for Microsoft Visual Studio ===

====CEGUI 0.8.x ====
* 3 Open the CMake GUI Utility
* 4 Set the '''source path''' to the directory where your CEGUI source code is located(e.g. C:/soft/cegui/cegui-0.8.2)
* 5 Set the '''build path''' to the directory where you want CMake to generate your build configuration(e.g. C:/soft/cegui/cegui-0.8.2/build)
* 6 Press the '''Configure''' button. At this stage CMake will ask you for a generator for this project(e.g. Visual Studio 10) and then will try to find the required packages needed by CEGUI. Please note that you should have the CEGUI dependencies built and installed in your CEGUI_ROOT directory. If you don't know how to build and install the CEGUI dependencies then follow this tutorial: [http://www.cegui.org.uk/docs/0.8.2/building_deps.html building_deps]
* 7 Search the '''CEGUI_BUILD_RENDERER_OGRE''' boolean variable in the list of CMake GUI Utility and set the value to TRUE by clicking on the checkbox. Optionally, you can set the CEGUI_SAMPLES_USE_OGRE aswell.
* 8 Check if Boost, OGRE and OIS were found by cmake. Look in the CMake GUI Utility output and if you spot a message like 'Could NOT find OGRE' then you need to set some variables manually, otherwise you can jump to step #10
* 9 In case CMake didn't found OGRE or other mandatory packages then you neeed to add some entries. For example, if the OGRE package was not found then you need to set the following variables:
OGRE_FOUND - variable of type BOOL which must be set to TRUE
OGRE_INCLUDE_DIR - variable of type PATH which must be set to the directory where the OGRE header files are(e.g. C:/soft/OgreSDK/include/OGRE)
OGRE_LIBRARIES - variable of type FILEPATH which must be set to the full file path of OgreMain.lib (e.g. OGRE_HOME/lib/release/OgreMain.lib)
OGRE_LIBRARIES_DBG(optional - if you don't intend to debug or are using CEGUI's "Release with Debug" build) - variable of type FILEPATH which must be set to the full file path of OgreMain_d.lib (e.g. OGRE_HOME/lib/debug/OgreMain_d.lib)

* 10 Rerun '''Configure'''. You need to do this in order to save your additional variables in the CMake cache and in the build configuration.Note that cmake will still say that it didn't found your package even if you set the variables correctly but when you will generate a solution, cmake will take the correct values from its cache.
* 11 Press the '''Generate''' button. At this stage CMake will read your build configuration and then generate a solution using your selected generator.
* 12 Go to the cegui build directory and open the Visual Studio solution '''cegui.sln'''
* 13 Add boost include directory(BOOST_ROOT) and libraries(BOOST_ROOT/lib or BOOST_ROOT/stage/lib) to the additional include directories and additional library directories for the CEGUIOgreRenderer-0 project. You need to do this because Ogre forwards the boost dependency to CEGUI. If you set the CEGUI_SAMPLES_USE_OGRE then you need to do the same thing for the CEGUISampleFramework-0.8 project.
* 14 Build the entire cegui solution
* 15 (Optional) Build the INSTALL project(skipped by default) inside cegui.sln to install cegui and ogre renderer to Program Files/cegui

====CEGUI 0.7.x ====
* 3. In your CEGUI folder there should be a folder called "'''projects'''" with a subfolder called "'''premake'''". It is recommended to use the [https://sourceforge.net/projects/crayzedsgui/files/CEGUI%20Mk-2/premake/premake-3.7-custom.zip/download custom premake version of CEGUI]. Otherwise you can get version 3.6 or 3.7 of premake. Once you have premake extract the '''premake.exe''' file into the said folder.

* 4. Open '''config.lua''' in the premake folder and edit the Ogre and OIS paths accordingly, so that they will point to the dependency files. In my case for example the 2 lines look like this (having the OGRE and CEGUI main folders on the same level):

<pre>
OGRE_PATHS = { "../OGRE", "include/OGRE", "lib" }
OIS_PATHS = { "../OGRE", "include/OIS", "lib" }
</pre>

'''Note:''' Remember to use forward slashes here! Just copying the paths from the Windows explorer will give you backward slashes. Replace them!

Next, set all Renderers you do not need to "false", in this case we will only need ''OGRE_RENDERER''. You can also set all samples to false, except maybe ''SAMPLES_OGRE'' if you want to compile those.

'''Important:''' Since Ogre 1.7 the "boost" library is a new dependency of OGRE. If you are unsure if your Ogre version needs boost, you might want to check if there is a boost folder in your Ogre main folder. In case your Ogre version makes use of boost, you will additionally add boost to the extra paths of CEGUIOgreRenderer, in my case it looks like this:
<pre>
CEGUI_EXTRA_PATHS = {
{ "../OGRE/boost_1_42", "", "lib", "CEGUIOgreRenderer" }
}
</pre>

* 5. Next, we create our Visual Studio Projects - Execute '''build_vs2008.bat''' to create a Visual Studio 2008 project or execute any other .bat file for your respective compiler version.

* 6. This should create '''CEGUI.sln''' in the premake folder. Open it.

* 7. If you have the Ogre lib files seperated into a Debug and Release folder, you will have to change the path in the '''Linker''' settings of the project so they will point to the '''lib/Debug''' or '''lib/Release''' folder for each configuration respectively.

* 8. '''Build''' the '''CEGUIOgreRenderer''' in Debug and Release mode.
* 9. Now that you have built the .dll files and .lib files for CEGUI by yourself, you only have to change the linker settings of your project so that the needed .lib files and their folder paths are included there. Also you might want to include the dll's into a folder where your executable application will find them (for example just the folder your executable starts from). Finally remember to set the CEGUI '''include''' directory (for example "..\..\CEGUI\cegui\include\cegui") inside your C++ project settings.

=== Steps for GNU and Unix-like environments ===
====CEGUI 0.8.x ====
'''TODO'''

====CEGUI 0.7.x ====
Going to the extracted CEGUI source directory and running the following commands seems to work (noobnote: don't include the dollar-signs at the start of the lines. They represent the prompt.):

<pre>
$ ./bootstrap && mkdir build && cd build

$ export NUMBER_OF_CORES=`cat /proc/cpuinfo | grep "cpu cores" | uniq | awk '{print $4}'`

$ ../configure && make -j$NUMBER_OF_CORES

$ sudo make install

$ sudo ldconfig
</pre>

If everything worked out, you now have CEGUI up and running!

==Questions==
Feel free to edit this page using your CEGUI forum account login if you want to append something. If you have questions you can ask in the CEGUI forum or join our IRC channel #cegui on irc.freenode.net -
In case you need help building Ogre in general, I'd recommend reading for example [http://blog.tidalware.com/2009/08/building-ogre-with-visual-studio/ this short guide (might be outdated though)].

For the Ogre-wiki version of this article you can also check this link: http://www.ogre3d.org/tikiwiki/tiki-index.php?page=Building+CEGUI

[[Category:HowTo]]

Projects Using CEGUI

2013-02-15T10:20:35Z

Mmixlinus: /* Applications */

== Introduction ==
This page lists finished projects which make use of the CEGUI library. The intros are mostly quoted from the original locations.

== Games ==
=== Open source ===
* [http://wiki.worldforge.org/wiki/Ember Ember] A GPL 3d client for the Worldforge system
* [http://www.ryzom.com/ Ryzom] MMORPG that recently got released under AGPL (including all art!)
* [http://www.secretmaryo.org/ Secret Maryo Chronicles] A GPL 2D platform game using SDL and OpenGL.
* [http://www.sumwars.org/ Summoning Wars] open source role-playing game, featuring both a single-player and a multiplayer mode for about 2 to 8 players
* [http://www.orxonox.net/ Orxonox] open source spacecraft shooter that plays in the post-apocalyptic world of our future
* [http://opengamestudio.org/ OGS Mahjong] is a simple mahjong solitaire game with nice 3D graphics and relaxing soundtrack
* [http://sourceforge.net/projects/opendungeons/ Open Dungeons] OpenDungeons is an open source game based on the Dungeon Keeper series of games with a different story and new creatures.
* [http://tnlgame.net/ Thunder&Lightning] An Open Source Futuristic Action Flight Simulator Game Inspired By Carrier Command

=== Proprietary ===
* [http://www.torchlightgame.com/ Torchlight] An action role-playing game by [http://www.runicgames.com/ Runic Games]
* [http://www.salvationprophecy.com/ Salvation Prophecy] A military space epic. Human, mutant, and robotic factions are at war for galactic domination.
* [http://www.ankh-game.com/ Ankh 3] A commercial adventure point and click game.
* [http://www.jack-keane-game.de/ Jack Keane] A commercial adventure point and click game.
* [http://www.shipsim.com/products/shipsimulatorextremes Ship Simulator Extremes] A commercial hardcore simulator game by [http://www.vstep.nl/ VSTEP]
* [http://www.dawntide.net/ Dawntide] Open-ended sandbox MMORPG by [http://www.waisoft.com/ WAISOFT]
* [http://www.venetica-game.com/ Venetica] Fantasy themed adventure game.
* [http://www.matrixgames.com/products/374/details/Operation.Barbarossa.-.The.Struggle.for.Russia/ Operation Barbarossa - The Struggle for Russia] A commercial turnbased strategy game
* [http://global.lunia.com/ Lunia] MMORPG featuring anime characters.
* [http://en.wikipedia.org/wiki/The_Book_of_Unwritten_Tales The Book of Unwritten Tales] 3D adventure game by HMH Interactive
* [http://voiddestroyer.com/ Void Destroyer] An independent (self funded) space combat simulator with real time strategy elements.
* [http://www.lifeon.pl/ LifeON] A MMO Virtual Worlds 3D Game using Ogre and CEGUI
* [http://www.worldofbattles.com/ World of battles] Free Online MMORTS
* [http://edeneternal.aeriagames.com/ Eden Eternal] A free Anime MMORPG Game from Aeria Games
* [http://www.snakeworldsgame.com/ Snakeworlds - Spherical 3D snake game] The game classic on spheres / globes.
* [http://www.wiraingames.com/ Interstellar defense troops] Tower defense style game in space by Winter rain games
* [http://www.ivan.org.es/showcase/gameview.php?id=2 Photopolys] A challenge for your mind in which you must compose puzzles based on your own photos.
* [http://www.dancingdots-studio.com/ Ride!] An equestrian simulation by Dancing Dots.
* [http://www.moonpod.com/English/about_pirateprincess.php/ Pirate Princess] Semi-casual word game based adventure in a pirate setting.
* [http://www.zeroballistics.com/game_info.php?um=1&lm=1 Zero Ballistics] a unique blend of multiplayer first person shooter and tank combat game

=== Educational ===
* [http://citycardriving.com/ City Car Driving] is designed to help users feel the car driving in ? big city or in a country

=== Addons ===
* [http://www.mtasa.com/ Multi Theft Auto: SA] Third party mod for GTA3: San Andreas providing multiplayer
* [http://www.iv-multiplayer.com/ IV:M] Third party mod for GTA4 providing multiplayer

=== Defunct? ===
* [http://www.cubecombat.net/ Cube Combat] 3D Bomberman like game, supporting up to 4 player through lan or internet.
* [http://www.opengate.ontheserver.de OpenGate] Opengate is an open source remake of the game Jumpgate©
* [http://www.smootsy.com/ Smootsy] A MMO Social Network 3D Game using Ogre

== Applications ==
* [http://www.psychosynth.com PsychoSynth] aims to create an interactive modular soft-synth inspired by the ideas of the Reactable.
* [http://www.navit-project.org/ NAVIT] is a car navigation system with routing engine.
* [http://mmix.me/ MMiX.Me] 3D Media Player for Microsoft Windows.

== Engines and frameworks ==
=== The Delta3D Open Source Game Engine ===
The Delta3D Game Engine integrates the functionality of CEGUI, allowing users to have robust user interfaces active in their applications. The Delta3D Game Engine was an early adopter of the CEGUI technology and has contributed to its development over the years.

For more information, see [http://delta3d.org http://delta3d.org].

=== Reality factory ===
Reality Factory is a program that, in conjunction with other tools, allows you to create first- and third- person perspective games - without programming!

CEGUI is used in version 2.0 and upwards.
More at [http://www.realityfactory.info http://www.realityfactory.info] and [http://realityfactory2.sourceforge.net/ http://realityfactory2.sourceforge.net/]

== Game related tools ==
=== TeamSpeak 3 overlay ===
TeamSpeak 3 overlay is an injection engine that displays TeamSpeak activities (e.g. when people are talking) while in-game.

For more information, check [http://ts3overlay.r-dev.de ts3overlay.r-dev.de]

=== OGRE particle editor ===
"The OGRE Particle Editor is a real-time visual particle system editor. It is a tool that provides the ability to rapidly create OGRE particle system templates that can be used in any OGRE driven application. The effects are stored and loaded as templates via standard OGRE particle scripts (*.particle)."

It can be downloaded [http://www.ogre3d.org/index.php?option=com_remository&Itemid=74&func=fileinfo&filecatid=35&parent=category here].

And the manual can be found [http://www.game-cat.com/ogre/pe/docs/ here].

=== Nimble 3D ===
Nimble is WMI's second realtime visualization product. Based on advanced physics models, Nimble follows in its predecessor's footsteps and delivers another first in simulation graphics- truly photorealistic 3D clouds, completely in realtime

For more information, see [http://www.windwardmark.net/products.php?page=nimble&sub=technology| windwardmark.net]