Revision as of 12:31, 1 January 2015

Rendering to a texture (RTT) using a CEGUI GUIContext

Since version 0.8 the new GUIContext class allows to render its content into a texture instead of rendering it normally into the framebuffer of your display. This allows to directly render UIs to a texture, and for example display it inside your 3D world, as you would regularly do with a texture.

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();
renderTextureTarget->declareRenderSize(size);
CEGUI::GUIContext& renderGuiContext = ceguiSystem.createGUIContext(static_cast<CEGUI::RenderTarget&>(*renderTextureTarget) );

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:

    CEGUI::Renderer* gui_renderer(gui_system.getRenderer());
    gui_renderer->beginRendering();
 
    renderTextureTarget->clear();
    renderGuiContext.draw();
 
    gui_renderer->endRendering();

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:

CEGUI::OpenGLTexture& glTexture = static_cast<CEGUI::OpenGLTexture&>(renderTextureTarget->getTexture());

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, or an Ogre::Texture*, etc. ...

Displaying a (RTT) texture inside your GUI using a CEGUI window

The following section can be used to display a texture that you created in your Renderer, and to which you might be rendering continuously (RTT), inside a window of a CEGUI GUI. For doing so, you need to create a CEGUI Image based on the rendered texture. The following code snippet shows you the full process of creating the CEGUI::Image and setting it up for your Renderer's texture:

// We create a CEGUI Texture using the renderer you use:
CEGUI::Texture& texture = gui_renderer->createTexture("MyCEGUITextureName");
 
// Now we need to cast it to the CEGUI::Texture superclass which matches your Renderer. This can be CEGUI::OgreTexture or CEGUI::OpenGLTexture, depending on the renderer you use in your application
// We will use Ogre here as an example
CEGUI::OgreTexture& rendererTexture = static_cast<CEGUI::OgreTexture&>(texture);
// Now we can set the appropriate Ogre::Texture for our CEGUI Texture
rendererTexture.setOgreTexture(whateverTextureYouWannaUse, false);
 
// We create a BasicImage and set the Texture
CEGUI::BasicImage* image = static_cast<CEGUI::BasicImage*>(&CEGUI::ImageManager::getSingleton().create("BasicImage", "MyImageGroup/MyImageName"));
image ->setTexture(&rendererTexture);
 
//Flipping is necessary due to differences between renderers regarding top or bottom being the origin
bool isTextureTargetVerticallyFlipped = renderTextureTarget->isRenderingInverted();
CEGUI::Rectf imageArea;
 
if (isTextureTargetVerticallyFlipped)
    imageArea= CEGUI::Rectf(0.0f, textureHeight, textureWidth, 0.0f);
else
    imageArea= CEGUI::Rectf(0.0f, 0.0f, textureWidth, textureHeight);
 
image ->setArea(imageArea);
image ->setAutoScaled(ASM_Disabled);

Important: If you modify the CEGUI::Image or the CEGUI::Texture (OpenGLTexture, OgreTexture, etc), for example when changing CEGUI:Texture's internal texture, you will have to call the CEGUI::Window's invalidate() function. If adjusting Image* or Texture* instances directly, the CEGUI Window will not be notified about the changes, which requires a manual update call to the windows using the instance. For example:

ceguiOgreTexture->setOgreTexture(someNewOgreTexture); //CEGUI::OgreTexture   and parameter   Ogre::TexturePtr
windowUsingTheTexture->invalidate(); // CEGUI::Window*

Important: Please ensure that the window that displays the RTT Texture (or any other parent) has AutoRenderingSurface switched off. Typically FrameWindows have this property activated. If it is on, the entire CEGUI::Window might be cached in situations where you actually want it to be rendered continuously without caching (such as when rendering to the texture continuously). When the window is cached, only an invalidation (by calling invalidate() or performing a click or move) will trigger a render update. Normally you only need to call invalidate on the window when pointing a CEGUI::Texture* instance to a new OpenGL or Ogre Texture, or similar.