Integrating Renderer_Ogre

Renderer_Ogre can be easily added to an existing Ogre application. The process for doing so is defined below.

Include files

You will need to set up include search paths for Renderer_Ogre, OpenGUI, and Ogre before using Renderer_Ogre. After you have done that, you should be able to include "Renderer_Ogre.h", and "OpenGUI.h" without much trouble. (Order doesn't matter)

It may be important to note that Renderer_Ogre.h includes both OpenGUI.h, as well as some specific include files from Ogre. You will want to keep this in mind as it may cause issues with Ogre's built in memory manager.

Note:: Renderer_Ogre was originally built with Ogre's memory manager disabled, so if you run into problems, try turning it off. There are other methods of leak checking available, so don't feel tied down to it. We test the renderer for compatibility with the Ogre SDKs (which currently has the memory manager enabled), but the uniqueness of your application may induce previously unknown issues.

Example include layout:

#include "Ogre.h"
#include "OpenGUI.h"
#include "Renderer_Ogre.h"

Linking

Using Renderer_Ogre requires libraries from Ogre, OpenGUI, and Renderer_Ogre. Be sure to set up the correct library paths for your linker.

Linking with Renderer_Ogre will require:
Debug: OgreMain_d.lib, OpenGUI_d.lib and Renderer_Ogre_d.lib
Release: OgreMain.lib, OpenGUI.lib and Renderer_Ogre.lib

Runtime Requirements

After you've compiled and linked you application, you will need to ensure that the following DLLs are available to the application:
Debug: OgreMain_d.dll, OpenGUI_d.dll and Renderer_Ogre_d.dll
Release: OgreMain.dll, OpenGUI.dll and Renderer_Ogre.dll

Initialization

Creating the linkage between OpenGUI and Ogre can be done in just a few lines of code. This should be done after Ogre has been initialized and an Ogre::RenderSystem has been selected.

// This must be a pointer to the Ogre Root object
// Ogre::Root* ogreRoot;

// This must be a pointer to the Ogre RenderSystem
// Ogre::RenderSystem* ogreRenderSystem

OpenGUI::OgreRenderer* myRenderer = new OpenGUI::OgreRenderer(ogreRoot, ogreRenderSystem);
OpenGUI::OgreResourceProvider* myResourceProvider = new OpenGUI::OgreResourceProvider();
OpenGUI::System* mySystem = new OpenGUI::System(myRenderer, myResourceProvider);

And that's it! OpenGUI will now be called automatically every frame to update its internal timing, and will automatically refresh the GUI for a viewport after the Viewport's frame has ended. On top of that, your GUI assets (such as xml layout files, and textures) will be loaded directly out of Ogre's resource system.

Note:: Both the Ogre::Root and Ogre::RenderSystem are optional parameters. However, Renderer_Ogre requires these to run, and it will attempt to obtain them through Singleton access if you do not provide them. There is no way to change the Root or RenderSystem pointers after you have initialized Renderer_Ogre.

See also:: OpenGUI::OgreRenderer::setTextureResourceGroup() and OpenGUI::OgreResourceProvider::setResourceGroup() for information on changing the Ogre resource groups used when loading textures and other OpenGUI assets.

Destruction

When shutting down your application, failure to destroy objects in the correct order can lead to crashes and other errors. The proper destruction order when using Renderer_Ogre is:

OpenGUI
Renderer_Ogre
Ogre

Using Viewports

In order to actually display a Screen, you need to provide OpenGUI with a Viewport that can be selected prior to the draw operations. Renderer_Ogre comes with the OpenGUI::OgreViewport class, which can be used to bind an OpenGUI::Screen to any standard Ogre::Viewport. To create one of these viewports, you perform the following:

// ogreViewportPtr is a pointer to a valid Ogre::Viewport
OpenGUI::OgreViewport* myGuiViewport = new OpenGUI::OgreViewport(ogreViewportPtr);

This will create the Ogre specialized OpenGUI::Viewport, which can then be used to attach Screens as so:

// myScreenPtr is a pointer to a valid OpenGUI::Screen
myScreenPtr->setViewport(myGuiViewport);

You can attach several Screens to a single viewport, but a Screen can only be attached to 1 viewport. To unattach a Screen from its viewport you can either assign a new viewport or simply call Screen::setViewport() again, passing 0 as the viewport pointer.

Once you have an OpenGUI::OgreViewport attached to an Ogre::Viewport, and a Screen is bound to it, the Screen is finally renderable, and will automatically be redrawn after Ogre updates the Viewport contents. Only Screens that are Active and AutoUpdating will be redrawn, so you can select which Screens are drawn to a viewport by controlling those settings. If you want to prevent the drawing of all Screens, you can turn off overlays for the Ogre::Viewport, and Renderer_Ogre will honor that setting and skip drawing the GUIs on that Ogre::Viewport.

To destroy a Viewport, you simply delete it.

delete myGuiViewport;

It is not necessary to detach all Screens from a viewport before destroying it. The viewport will automatically detach all attached Screens during destruction.

That should cover everything you need to know about using OpenGUI with Ogre in your application via Renderer_Ogre. If you run into trouble, try the following online resources for help:

OpenGUI website (forums and wiki): http://opengui.sourceforge.net/
Ogre website (forums and wiki): http://www.ogre3d.org/