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

Make a custom resource provider

2016-01-16T19:17:45Z

Iceiceice:

Note: This page is a work in progress, targetted at CEGUI v0.8.4

The <code>ResourceProvider</code> is the interface that CEGUI uses to load data files of all kinds -- XML, images, fonts, etc.

If you followed the tutorial, then you are probably already vaguely familiar with the <code>DefaultResourceProvider</code>. The default resource provider requires you to specify certain folders for each kind of resource. When CEGUI needs to acquire a resource, the default resource provider simply tries to fetch it from disk, accounting for differences between Unix-like and Windows systems.

There are a few other resource providers that come with CEGUI, particularly, an OGRE resource provider, and Irrlicht one, which integrate with those systems more tightly.

However, maybe you want to write your own resource provider. Why might you want to do this?

# Maybe you want to limit how CEGUI accesses your filesystem. Perhaps you have some kind of virtual filesystem setup, and you prefer for security reasons to have all filesystem calls go through your interface rather than directly through the C / C++ filesystem API. Maybe you are trying to cope with bugs when handling unicode characters in filepaths on some platforms.
# Maybe you are targetting a platform where the filesystem is a bit unusual -- for instance, in emscripten.
# Maybe you are trying to optimize the resource acquisition process by making it cache all available on-disk resources up front for some scenario, and then serve them fast from buffers to CEGUI after that.

To do this, you simply need to derive from <code>CEGUI::ResourceProvider</code>, and start CEGUI using an instance of that instead of the default. This page is to help explain in greater detail what these overrided methods that you provide should do, what responsibilities they have, when they will be called, etc. And especially, to explain how the ownership of the various involved objects works, so that you can avoid leaking / creating undefined behavior.

== ResourceProvider ==

Here is a synopsis of the <code>CEGUI::ResourceProvider</code> class and its most important methods:

class CEGUIEXPORT ResourceProvider :
public AllocatedObject<ResourceProvider>
{
public:
ResourceProvider() { }
virtual ~ResourceProvider() {}

virtual void loadRawDataContainer(const String& filename, RawDataContainer& output, const String& resourceGroup) = 0;
virtual void unloadRawDataContainer(RawDataContainer&) { }
};

The <code>AllocatedObject</code> template is essentially a CEGUI internal detail related to memory management. You don't need to do anything special as a result of that inheritance -- you can just <code>new</code> objects of this type, or derived from this type, and pass them to CEGUI as an appropriate argument to <code>CEGUI::System::create</code>. CEGUI will take ownership of them and delete them as necessary.

The two most important functions are the two that I picked out -- CEGUI calls these when it wants to load or unload a resource. It expects your resource provider to manipulate these <code>RawDataContainer</code> objects to pass it data.

== RawDataContainer ==

<code>RawDataContainer</code> is somewhat like a stripped-down <code>std::vector</code>, except that it always points to an buffer of type <code>unsigned char</code> and there are no "resize" methods or similar. It is always easy to get / set the size / data pointer of the <code>RawDataContainer</code>, as it is intended that you should manipulate the class to get the semantics that you want.

Synopsis of <code>RawDataContainer</code>:

class CEGUIEXPORT RawDataContainer :
public AllocatedObject<RawDataContainer>
{
public:

RawDataContainer() : mData(0), mSize(0) {}
~RawDataContainer() { release(); }

void setData(uint8* data) { mData = data; }
uint8* getDataPtr() { return mData; }

void setSize(size_t size) { mSize = size; }
size_t getSize() const { return mSize; }

void release();

private:
uint8* mData;
size_t mSize;
};

The <code>release</code> function of a <code>RawDataContainer</code> calls <code>operator delete[]</code> on the buffer pointer, unless the buffer pointer is null. If that would cause a problem for you, then the <code>unloadRawDataContainer</code> function is your opportunity to empty the <code>RawDataContainer</code> before it is destroyed so that you can do cleanup in a different way.

== Examples ==

For example: If you are using a C++ function like this to open files,

typedef unsigned char uchar;

std::pair<uchar *, size_t> open_file(const std::string & file) {
if (FILE * source = fopen(file.str().c_str(), "rb")) {
fseek(source, 0, SEEK_END);
int size = ftell(source);
fseek(source, 0, SEEK_SET);

uchar * buffer = new uchar[size];
size_t num_read = fread(buffer, size, 1, source);
(void)num_read;
fclose(source);

return std::make_pair(buffer, size);
}
throw file_not_found_exception(file);
}

you can overload <code>loadRawDataContainer</code> like this:

void myResourceProvider::loadRawDataContainer(const String& filename, RawDataContainer& output, const String& resourceGroup) {
std::pair<uchar *, size_t> result = open_file(filename);
output.setData(result.first);
output.setSize(result.second);
}

You then don't need to override <code>unloadRawDataContainer</code>, as CEGUI will call <code>delete[]</code> later on its own. CEGUI owns the buffer that you loaded in this case.
However, if you implemented <code>open_file</code> using <code>malloc</code> instead of <code>new[]</code>, you will get undefined behavior. Or even, if you compiled your project with one compiler and CEGUI with a different compiler, you may have problems if their memory allocation implementations are not compatible.

If YOU want to own the buffer and not have CEGUI take ownership of it, you might do it like this instead:

typedef unsigned char uchar;

std::vector<uchar> open_file(const std::string & file) {
if (FILE * source = fopen(file.str().c_str(), "rb")) {
std::vector<uchar> buffer;

fseek(source, 0, SEEK_END);
int size = ftell(source);
fseek(source, 0, SEEK_SET);

buffer.resize(size);
size_t num_read = fread(&buffer[0], size, 1, source);
(void)num_read;
fclose(source);

return buffer;
}
throw file_not_found_exception(file);
}

I'll assume, for sake of exposition, that as a member of the resource provider, or somewhere else available to you, you have a variable <code>std::map<std::string, std::vector<uchar>> cache_</code> that keeps track of loaded files for the resource provider. Then your resource provider implementation might look like this:

typedef std::map<std::string, std::vector<uchar>> file_map;

std::vector<uchar> & myResourceProvider::load_helper(const std::string & filename) {
file_map::iterator it = cache_.find(filename);
if (it != cache_.end()) {
return it->second;
}
cache_[filename] = open_file(filename);
return cache_[filename];
}

void myResourceProvider::loadRawDataContainer(const String& filename, RawDataContainer& output, const String& resourceGroup) {
std::vector<uchar> & data = load_helper(filename);
output.setData(&data[0]);
output.setSize(data.size());
}

void myResourceProvider::unloadRawDataContainer(RawDataContainer & output) {
// Make sure cegui doesn't try to delete a buffer owned by our vector!
output.setData(0);
output.setSize(0);
}

[[Category:HowTo]]

Make a custom resource provider

2016-01-16T19:16:24Z

Iceiceice: Created page with "Note: This page is a work in progress, targetted at CEGUI v0.8.4 The <code>ResourceProvider</code> is the interface that CEGUI uses to load data files of all kinds -- XML, im..."

CEED

2015-11-24T18:07:12Z

Iceiceice: /* Ubuntu Trusty */

The CEGUI unified editor. Includes project management and multi-file/multi-tab editing.

== Building CEED on Windows ==
Follow these instructions for building and installing CEED on Windows OS: http://cegui.org.uk/wiki/Building_CEED_for_Windows

Or, if you don't want to build it yourself, you can use the precompiled binaries: http://sourceforge.net/projects/crayzedsgui/files/CEED/0.8/

== Install ==

CEED from the v0-8 branch (and all snapshots) depend on CEGUI 0.8. Even though it may work with CEGUI "default" it is not tested with it so don't expect any help if you try to make it work that way.

[http://www.cegui.org.uk/phpBB2/viewtopic.php?f=15&t=5566 Original post at the forums] (very old, don't use!)

=== Dependencies ===

You need CMake, Python >= 2.6 (preferably Python 2.7), PyOpenGL, PySide (+ utils/tools), Boost.Python.

==== Debian Wheezy ====

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

apt-get install cmake python-opengl pyside-tools boost-python

==== Ubuntu Trusty ====

In ubuntu, you must install the python-pyside package as well as pyside-tools, pyside-tools does not pull it in.

apt-get install python python-pyside pyside-tools python-opengl libboost-python-dev

==== Arch Linux ====

You need at least python2, boost, python2-opengl, python2-pyside (AUR), python2-pyside-tools (AUR). PySide will bring in several other packages and will probably take a few hours to compile.

'''Important Note''': You probably need to add "-DPYTHON_EXECUTABLE=/usr/bin/python2 -DPYTHON_INCLUDE_DIR=/usr/include/python2.7 -DPYTHON_LIBRARY=/usr/lib/python2.7" (without the quotes) to the cmake command line below because Arch Linux defaults to python 3 but the python modules CMake script expects python2. Also different GLFW version might get mixed up causing the compilation to fail. So if you are just interested in compiling CEGUI for CEED, you might also want to add "-DCEGUI_SAMPLES_ENABLED=OFF" to the cmake command below.

Arch Linux has the entire ceed packaged, see the AUR repo and save yourself all this trouble.

==== Fedora ====

You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools

=== Build CEGUI and PyCEGUI ===

(Or get it from distribution repo and skip this)

hg clone https://bitbucket.org/cegui/cegui
hg clone https://bitbucket.org/cegui/ceed
cd ceed
hg update v0-8
cd ../
cd cegui
hg update v0-8
cd ../
mkdir cegui/build
cd cegui/build
cmake -DCEGUI_BUILD_PYTHON_MODULES=ON -DCEGUI_BUILD_RENDERER_OPENGL=ON -DCEGUI_BUILD_RENDERER_OPENGL3=ON ../

==== Renderers ====

CEED requires the OpenGL2 renderer to be enabled. This is what it uses to function. However in CEGUI 0.8 you have to enable both OpenGL2 and OpenGL3 renderers for the bindings to work correctly.

Make sure "CEGUI_BUILD_RENDERER_OPENGL" and "CEGUI_BUILD_RENDERER_OPENGL3" are both enabled before you build CEGUI.

== Launch ==

cd ../ceed
cd bin
./runwrapper.sh
./ceed-gui

or
$ cd ../ceed/bin
$ PYTHONPATH=../../cegui/build/lib:../:$PYTHONPATH python2 ./ceed-gui

You will see a window like this:

[[Image:Ceed_main_window.png]]

=== Troubleshooting ===
* If it fails to import ceed.ui.* then you need to compile UI files, call
[ceed] ./maintenance compile-ui-files
Or alternatively edit ceed/version.py and set CEED_developerMode to True.
* If the data files are missing you need to run the 'maintenance' script like this:
[ceed/bin]$ cd ..
[ceed]$ ./maintenance fetch-datafiles

== Project ==

Unlike old editors (CELayoutEditor and CEImagesetEditor), CEED has a notion of a project. Each project has its own combination of resources and runs its own CEGUI version to render your CEGUI resources. This allows you to have more that one scheme loaded at a time.

To create a new project, you should go to '''File -> New project'''.

The dialog appears. You should input project name and location of the ".project" file. '''Note''': parent directory of the ".project" file must exist.

[[Image:Ceed_new_project.png]]

After you press '''OK''', Project settings window appears.

=== Project settings ===

(The window is also accessible from '''Edit -> Project settings''')

[[Image:Ceed_project_settings.png]]

CEED can create assets for CEGUI versions: 0.6 to 0.8. 0.7 is the latest stable, so select it.

Point "Resource directory" to the place where "fonts", "schemes" and the rest directories are located, then press '''Apply'''. It will change the paths below.

Press '''OK''' and will load your resources. If it fails to, it will show you a warning dialog:

[[Image:Ceed_new_project_warning.png]]

In our case, the resource directory does not have "schemes" subdirectory, as noted on the last line. Correct the paths and retry.

=== Project resources ===

Currently CEED can only work with imagesets and layouts. Add them to your project by clicking with the right mouse button on '''Project manager''' and selecting '''Add existing file(s)''':

[[Image:Ceed_project_add_existing.png]]

Select the necessary imagesets and layouts, and save the project.

=== Layouts ===

[[Image:Ceed_layout.png]]

To create a new widget, drag it from the left bottom panel.

If you just created a new layout using CEED, you will notice that both the Visual and the Code views are empty. The created file is indeed entirely empty so far. In order to start working, we recommend to add a DefaultWindow as root, and add everything else to this root. In CEGUI it is always recommended to have a root window that covers the entire screen (you can do this by simply setting a window's size to {1.0, 1.0} relative sizes and the position to 0, which is both the default for DefaultWindow's). You can simply drag a DefaultWindow into the Widget Hierarchy or into the Visual window to add a new DefaultWindow as root for your empty layout. If you switch to the code window you will see that the basic XML structure of your layout has been set up for you.

To edit it, you can either do it visually, or switch to "Code" tab seen below, and edit it manually. There's also "Preview" tab, where you can test your layout in real time.

=== Imagesets ===

[[Image:Ceed_imageset.png]]

To create a new image, press tool bar button second from the right, or click with the right mouse button on the image itself and select '''Create image''':

[[Image:Ceed_imageset_create_image.png]]

It creates a 50 x 50 rectangle centered at where mouse cursor is. Move and resize it as you see fit.

== Settings ==
Go to '''Edit -> Application settings'''.

[[Image:Ceed_application_settings.png]]

There are many settings you can tweak. One of the most important might be '''Shortcuts'''. It allows you to assign shortcuts to zoom, image creation, opening a project, and so on.

== Notes ==

You can now use the ceed-migrate tool for converting between old and new CEGUI datafiles. Here is a quick guide for that: http://cegui.org.uk/wiki/Using_CEED-Migrate

Currently you may have problems with Imagesets that use TGA, since some versions of Qt may be built without TGA support. CEGUI 0.8 has all imagery as PNG (CEGUI 0.7 used TGA), and we advise you to use PNG instead of TGA.

== Complete Install Notes for Ubuntu ==

This script was tested Nov 24 2015 with a fresh install of Ubuntu 15.10 Wily, and successfully installed working ceed in home directory. Build took approximately 1 hour with 3 cores.

#!/bin/bash
set -e
set -u

# Install dependencies
sudo apt-get update
sudo apt-get -y upgrade

# Build tools
sudo apt-get -y install gcc g++
sudo apt-get -y install mercurial cmake-data cmake scons make ccache

# Cegui deps
sudo apt-get -y install libfreetype6-dev libsilly-dev libxml2-dev libexpat1-dev libgles2-mesa-dev libglfw-dev libglew-dev libglm-dev

# Ceed deps
sudo apt-get -y install python python-pyside pyside-tools python-opengl libboost-python-dev

# Clone Repositories
hg clone https://bitbucket.org/cegui/cegui
hg clone https://bitbucket.org/cegui/ceed
cd ceed
hg update v0-8
cd ../
cd cegui
hg update v0-8
cd ../

# Build cegui with python bindings
mkdir cegui/build
cd cegui/build
cmake -DCEGUI_BUILD_PYTHON_MODULES=ON -DCEGUI_BUILD_RENDERER_OPENGL=ON -DCEGUI_BUILD_RENDERER_OPENGL3=ON ../
make -j3
cd ../..

# Adjust ceed "runwrapper.sh" path
cd ceed/bin
sed -i "s|/../../cegui-v0-8|/../../cegui|g" runwrapper.sh

# Now run from ceed/bin with commands:
# ./runwrapper.sh
# ./ceed-gui

CEED

2015-11-24T18:03:01Z

Iceiceice: /* Complete Install Notes for Ubuntu */

The CEGUI unified editor. Includes project management and multi-file/multi-tab editing.

== Building CEED on Windows ==
Follow these instructions for building and installing CEED on Windows OS: http://cegui.org.uk/wiki/Building_CEED_for_Windows

Or, if you don't want to build it yourself, you can use the precompiled binaries: http://sourceforge.net/projects/crayzedsgui/files/CEED/0.8/

== Install ==

CEED from the v0-8 branch (and all snapshots) depend on CEGUI 0.8. Even though it may work with CEGUI "default" it is not tested with it so don't expect any help if you try to make it work that way.

[http://www.cegui.org.uk/phpBB2/viewtopic.php?f=15&t=5566 Original post at the forums] (very old, don't use!)

=== Dependencies ===

You need CMake, Python >= 2.6 (preferably Python 2.7), PyOpenGL, PySide (+ utils/tools), Boost.Python.

==== Debian Wheezy ====

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

apt-get install cmake python-opengl pyside-tools boost-python

==== Ubuntu Trusty ====

In ubuntu, you must install the python-pyside package as well as pyside-tools, pyside-tools does not pull it in.

sudo apt-get install python python-pyside pyside-tools python-opengl libboost-python-dev

==== Arch Linux ====

You need at least python2, boost, python2-opengl, python2-pyside (AUR), python2-pyside-tools (AUR). PySide will bring in several other packages and will probably take a few hours to compile.

'''Important Note''': You probably need to add "-DPYTHON_EXECUTABLE=/usr/bin/python2 -DPYTHON_INCLUDE_DIR=/usr/include/python2.7 -DPYTHON_LIBRARY=/usr/lib/python2.7" (without the quotes) to the cmake command line below because Arch Linux defaults to python 3 but the python modules CMake script expects python2. Also different GLFW version might get mixed up causing the compilation to fail. So if you are just interested in compiling CEGUI for CEED, you might also want to add "-DCEGUI_SAMPLES_ENABLED=OFF" to the cmake command below.

Arch Linux has the entire ceed packaged, see the AUR repo and save yourself all this trouble.

==== Fedora ====

You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools

=== Build CEGUI and PyCEGUI ===

(Or get it from distribution repo and skip this)

hg clone https://bitbucket.org/cegui/cegui
hg clone https://bitbucket.org/cegui/ceed
cd ceed
hg update v0-8
cd ../
cd cegui
hg update v0-8
cd ../
mkdir cegui/build
cd cegui/build
cmake -DCEGUI_BUILD_PYTHON_MODULES=ON -DCEGUI_BUILD_RENDERER_OPENGL=ON -DCEGUI_BUILD_RENDERER_OPENGL3=ON ../

==== Renderers ====

CEED requires the OpenGL2 renderer to be enabled. This is what it uses to function. However in CEGUI 0.8 you have to enable both OpenGL2 and OpenGL3 renderers for the bindings to work correctly.

Make sure "CEGUI_BUILD_RENDERER_OPENGL" and "CEGUI_BUILD_RENDERER_OPENGL3" are both enabled before you build CEGUI.

== Launch ==

cd ../ceed
cd bin
./runwrapper.sh
./ceed-gui

or
$ cd ../ceed/bin
$ PYTHONPATH=../../cegui/build/lib:../:$PYTHONPATH python2 ./ceed-gui

You will see a window like this:

[[Image:Ceed_main_window.png]]

=== Troubleshooting ===
* If it fails to import ceed.ui.* then you need to compile UI files, call
[ceed] ./maintenance compile-ui-files
Or alternatively edit ceed/version.py and set CEED_developerMode to True.
* If the data files are missing you need to run the 'maintenance' script like this:
[ceed/bin]$ cd ..
[ceed]$ ./maintenance fetch-datafiles

== Project ==

Unlike old editors (CELayoutEditor and CEImagesetEditor), CEED has a notion of a project. Each project has its own combination of resources and runs its own CEGUI version to render your CEGUI resources. This allows you to have more that one scheme loaded at a time.

To create a new project, you should go to '''File -> New project'''.

The dialog appears. You should input project name and location of the ".project" file. '''Note''': parent directory of the ".project" file must exist.

[[Image:Ceed_new_project.png]]

After you press '''OK''', Project settings window appears.

=== Project settings ===

(The window is also accessible from '''Edit -> Project settings''')

[[Image:Ceed_project_settings.png]]

CEED can create assets for CEGUI versions: 0.6 to 0.8. 0.7 is the latest stable, so select it.

Point "Resource directory" to the place where "fonts", "schemes" and the rest directories are located, then press '''Apply'''. It will change the paths below.

Press '''OK''' and will load your resources. If it fails to, it will show you a warning dialog:

[[Image:Ceed_new_project_warning.png]]

In our case, the resource directory does not have "schemes" subdirectory, as noted on the last line. Correct the paths and retry.

=== Project resources ===

Currently CEED can only work with imagesets and layouts. Add them to your project by clicking with the right mouse button on '''Project manager''' and selecting '''Add existing file(s)''':

[[Image:Ceed_project_add_existing.png]]

Select the necessary imagesets and layouts, and save the project.

=== Layouts ===

[[Image:Ceed_layout.png]]

To create a new widget, drag it from the left bottom panel.

If you just created a new layout using CEED, you will notice that both the Visual and the Code views are empty. The created file is indeed entirely empty so far. In order to start working, we recommend to add a DefaultWindow as root, and add everything else to this root. In CEGUI it is always recommended to have a root window that covers the entire screen (you can do this by simply setting a window's size to {1.0, 1.0} relative sizes and the position to 0, which is both the default for DefaultWindow's). You can simply drag a DefaultWindow into the Widget Hierarchy or into the Visual window to add a new DefaultWindow as root for your empty layout. If you switch to the code window you will see that the basic XML structure of your layout has been set up for you.

To edit it, you can either do it visually, or switch to "Code" tab seen below, and edit it manually. There's also "Preview" tab, where you can test your layout in real time.

=== Imagesets ===

[[Image:Ceed_imageset.png]]

To create a new image, press tool bar button second from the right, or click with the right mouse button on the image itself and select '''Create image''':

[[Image:Ceed_imageset_create_image.png]]

It creates a 50 x 50 rectangle centered at where mouse cursor is. Move and resize it as you see fit.

== Settings ==
Go to '''Edit -> Application settings'''.

[[Image:Ceed_application_settings.png]]

There are many settings you can tweak. One of the most important might be '''Shortcuts'''. It allows you to assign shortcuts to zoom, image creation, opening a project, and so on.

== Notes ==

You can now use the ceed-migrate tool for converting between old and new CEGUI datafiles. Here is a quick guide for that: http://cegui.org.uk/wiki/Using_CEED-Migrate

Currently you may have problems with Imagesets that use TGA, since some versions of Qt may be built without TGA support. CEGUI 0.8 has all imagery as PNG (CEGUI 0.7 used TGA), and we advise you to use PNG instead of TGA.

== Complete Install Notes for Ubuntu ==

This script was tested Nov 24 2015 with a fresh install of Ubuntu 15.10 Wily, and successfully installed working ceed in home directory. Build took approximately 1 hour with 3 cores.

#!/bin/bash
set -e
set -u

# Install dependencies
sudo apt-get update
sudo apt-get -y upgrade

# Build tools
sudo apt-get -y install gcc g++
sudo apt-get -y install mercurial cmake-data cmake scons make ccache

# Cegui deps
sudo apt-get -y install libfreetype6-dev libsilly-dev libxml2-dev libexpat1-dev libgles2-mesa-dev libglfw-dev libglew-dev libglm-dev

# Ceed deps
sudo apt-get -y install python python-pyside pyside-tools python-opengl libboost-python-dev

# Clone Repositories
hg clone https://bitbucket.org/cegui/cegui
hg clone https://bitbucket.org/cegui/ceed
cd ceed
hg update v0-8
cd ../
cd cegui
hg update v0-8
cd ../

# Build cegui with python bindings
mkdir cegui/build
cd cegui/build
cmake -DCEGUI_BUILD_PYTHON_MODULES=ON -DCEGUI_BUILD_RENDERER_OPENGL=ON -DCEGUI_BUILD_RENDERER_OPENGL3=ON ../
make -j3
cd ../..

# Adjust ceed "runwrapper.sh" path
cd ceed/bin
sed -i "s|/../../cegui-v0-8|/../../cegui|g" runwrapper.sh

# Now run from ceed/bin with commands:
# ./runwrapper.sh
# ./ceed-gui

CEED

2015-11-24T18:01:08Z

Iceiceice: Add a complete install log for Ubuntu 15.10 Wily

The CEGUI unified editor. Includes project management and multi-file/multi-tab editing.

== Building CEED on Windows ==
Follow these instructions for building and installing CEED on Windows OS: http://cegui.org.uk/wiki/Building_CEED_for_Windows

Or, if you don't want to build it yourself, you can use the precompiled binaries: http://sourceforge.net/projects/crayzedsgui/files/CEED/0.8/

== Install ==

CEED from the v0-8 branch (and all snapshots) depend on CEGUI 0.8. Even though it may work with CEGUI "default" it is not tested with it so don't expect any help if you try to make it work that way.

[http://www.cegui.org.uk/phpBB2/viewtopic.php?f=15&t=5566 Original post at the forums] (very old, don't use!)

=== Dependencies ===

You need CMake, Python >= 2.6 (preferably Python 2.7), PyOpenGL, PySide (+ utils/tools), Boost.Python.

==== Debian Wheezy ====

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

apt-get install cmake python-opengl pyside-tools boost-python

==== Ubuntu Trusty ====

In ubuntu, you must install the python-pyside package as well as pyside-tools, pyside-tools does not pull it in.

sudo apt-get install python python-pyside pyside-tools python-opengl libboost-python-dev

==== Arch Linux ====

You need at least python2, boost, python2-opengl, python2-pyside (AUR), python2-pyside-tools (AUR). PySide will bring in several other packages and will probably take a few hours to compile.

'''Important Note''': You probably need to add "-DPYTHON_EXECUTABLE=/usr/bin/python2 -DPYTHON_INCLUDE_DIR=/usr/include/python2.7 -DPYTHON_LIBRARY=/usr/lib/python2.7" (without the quotes) to the cmake command line below because Arch Linux defaults to python 3 but the python modules CMake script expects python2. Also different GLFW version might get mixed up causing the compilation to fail. So if you are just interested in compiling CEGUI for CEED, you might also want to add "-DCEGUI_SAMPLES_ENABLED=OFF" to the cmake command below.

Arch Linux has the entire ceed packaged, see the AUR repo and save yourself all this trouble.

==== Fedora ====

You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools

=== Build CEGUI and PyCEGUI ===

(Or get it from distribution repo and skip this)

hg clone https://bitbucket.org/cegui/cegui
hg clone https://bitbucket.org/cegui/ceed
cd ceed
hg update v0-8
cd ../
cd cegui
hg update v0-8
cd ../
mkdir cegui/build
cd cegui/build
cmake -DCEGUI_BUILD_PYTHON_MODULES=ON -DCEGUI_BUILD_RENDERER_OPENGL=ON -DCEGUI_BUILD_RENDERER_OPENGL3=ON ../

==== Renderers ====

CEED requires the OpenGL2 renderer to be enabled. This is what it uses to function. However in CEGUI 0.8 you have to enable both OpenGL2 and OpenGL3 renderers for the bindings to work correctly.

Make sure "CEGUI_BUILD_RENDERER_OPENGL" and "CEGUI_BUILD_RENDERER_OPENGL3" are both enabled before you build CEGUI.

== Launch ==

cd ../ceed
cd bin
./runwrapper.sh
./ceed-gui

or
$ cd ../ceed/bin
$ PYTHONPATH=../../cegui/build/lib:../:$PYTHONPATH python2 ./ceed-gui

You will see a window like this:

[[Image:Ceed_main_window.png]]

=== Troubleshooting ===
* If it fails to import ceed.ui.* then you need to compile UI files, call
[ceed] ./maintenance compile-ui-files
Or alternatively edit ceed/version.py and set CEED_developerMode to True.
* If the data files are missing you need to run the 'maintenance' script like this:
[ceed/bin]$ cd ..
[ceed]$ ./maintenance fetch-datafiles

== Project ==

Unlike old editors (CELayoutEditor and CEImagesetEditor), CEED has a notion of a project. Each project has its own combination of resources and runs its own CEGUI version to render your CEGUI resources. This allows you to have more that one scheme loaded at a time.

To create a new project, you should go to '''File -> New project'''.

The dialog appears. You should input project name and location of the ".project" file. '''Note''': parent directory of the ".project" file must exist.

[[Image:Ceed_new_project.png]]

After you press '''OK''', Project settings window appears.

=== Project settings ===

(The window is also accessible from '''Edit -> Project settings''')

[[Image:Ceed_project_settings.png]]

CEED can create assets for CEGUI versions: 0.6 to 0.8. 0.7 is the latest stable, so select it.

Point "Resource directory" to the place where "fonts", "schemes" and the rest directories are located, then press '''Apply'''. It will change the paths below.

Press '''OK''' and will load your resources. If it fails to, it will show you a warning dialog:

[[Image:Ceed_new_project_warning.png]]

In our case, the resource directory does not have "schemes" subdirectory, as noted on the last line. Correct the paths and retry.

=== Project resources ===

Currently CEED can only work with imagesets and layouts. Add them to your project by clicking with the right mouse button on '''Project manager''' and selecting '''Add existing file(s)''':

[[Image:Ceed_project_add_existing.png]]

Select the necessary imagesets and layouts, and save the project.

=== Layouts ===

[[Image:Ceed_layout.png]]

To create a new widget, drag it from the left bottom panel.

If you just created a new layout using CEED, you will notice that both the Visual and the Code views are empty. The created file is indeed entirely empty so far. In order to start working, we recommend to add a DefaultWindow as root, and add everything else to this root. In CEGUI it is always recommended to have a root window that covers the entire screen (you can do this by simply setting a window's size to {1.0, 1.0} relative sizes and the position to 0, which is both the default for DefaultWindow's). You can simply drag a DefaultWindow into the Widget Hierarchy or into the Visual window to add a new DefaultWindow as root for your empty layout. If you switch to the code window you will see that the basic XML structure of your layout has been set up for you.

To edit it, you can either do it visually, or switch to "Code" tab seen below, and edit it manually. There's also "Preview" tab, where you can test your layout in real time.

=== Imagesets ===

[[Image:Ceed_imageset.png]]

To create a new image, press tool bar button second from the right, or click with the right mouse button on the image itself and select '''Create image''':

[[Image:Ceed_imageset_create_image.png]]

It creates a 50 x 50 rectangle centered at where mouse cursor is. Move and resize it as you see fit.

== Settings ==
Go to '''Edit -> Application settings'''.

[[Image:Ceed_application_settings.png]]

There are many settings you can tweak. One of the most important might be '''Shortcuts'''. It allows you to assign shortcuts to zoom, image creation, opening a project, and so on.

== Notes ==

You can now use the ceed-migrate tool for converting between old and new CEGUI datafiles. Here is a quick guide for that: http://cegui.org.uk/wiki/Using_CEED-Migrate

Currently you may have problems with Imagesets that use TGA, since some versions of Qt may be built without TGA support. CEGUI 0.8 has all imagery as PNG (CEGUI 0.7 used TGA), and we advise you to use PNG instead of TGA.

== Complete Install Notes for Ubuntu ==

This script was tested Nov 24 2015 with a fresh install of Ubuntu 15.10 Wily, and successfully installed working ceed in home directory.

#!/bin/bash
set -e
set -u

sudo apt-get update
sudo apt-get -y upgrade

# Build tools
sudo apt-get -y install gcc g++
sudo apt-get -y install mercurial cmake-data cmake scons make ccache

# Cegui deps
sudo apt-get -y install libfreetype6-dev libsilly-dev libxml2-dev libexpat1-dev libgles2-mesa-dev libglfw-dev libglew-dev libglm-dev

# Ceed deps
sudo apt-get install python python-pyside pyside-tools python-opengl libboost-python-dev

# Clone Repositories
hg clone https://bitbucket.org/cegui/cegui
hg clone https://bitbucket.org/cegui/ceed
cd ceed
hg update v0-8
cd ../
cd cegui
hg update v0-8
cd ../

# Build cegui with python bindings
mkdir cegui/build
cd cegui/build
cmake -DCEGUI_BUILD_PYTHON_MODULES=ON -DCEGUI_BUILD_RENDERER_OPENGL=ON -DCEGUI_BUILD_RENDERER_OPENGL3=ON ../
make -j3
cd ../..

# Adjust ceed "runwrapper.sh" path
cd ceed/bin
sed -i "s|/../../cegui-v0-8|/../../cegui|g" runwrapper.sh

# Now run from ceed/bin with commands:
# ./runwrapper.sh
# ./ceed-gui