Tutorial Introduction In this short tutorial we will be covering how to swap between multiple scene managers.

Prerequisites

• This tutorial assumes you have knowledge of C++ programming and are able to set up and compile an Ogre application.
• This tutorial also assumes that you have created a project using the Ogre Wiki Tutorial Framework, either manually, using CMake or the Ogre AppWizard - see Setting Up An Application for instructions.
• This tutorial builds on the previous basic tutorials, and it assumes you have already worked through them.

 
You can find the code for this tutorial here. As you go through the tutorial you should be slowly adding code to your own project and watching the results as we build it.

Getting Started

The Initial Code

Modify your Basic Tutorial 8 class header to look like this:

#ifndef __BasicTutorial8_h_
#define __BasicTutorial8_h_
 
#include "BaseApplication.h"
 
class BasicTutorial8 : public BaseApplication
{
public:
    BasicTutorial8(void);
    virtual ~BasicTutorial8(void);
protected:
    virtual void createScene(void);
    virtual void chooseSceneManager(void);
    virtual void createCamera(void);
    virtual void createViewports(void);
    virtual void createFrameListener(void);
    virtual bool frameRenderingQueued(const Ogre::FrameEvent& evt);
 
    // OIS::KeyListener
    virtual bool keyPressed( const OIS::KeyEvent &arg );
    virtual bool keyReleased( const OIS::KeyEvent &arg );
    // OIS::MouseListener
    virtual bool mouseMoved( const OIS::MouseEvent &arg );
    virtual bool mousePressed( const OIS::MouseEvent &arg, OIS::MouseButtonID id );
    virtual bool mouseReleased( const OIS::MouseEvent &arg, OIS::MouseButtonID id );
private:
    Ogre::SceneManager* mPrimarySceneMgr;
    Ogre::SceneManager* mSecondarySceneMgr;
    bool mDual;
    virtual void setupViewport(Ogre::SceneManager *curr);
    virtual void dualViewport(Ogre::SceneManager *primarySceneMgr, Ogre::SceneManager *secondarySceneMgr);
};
 
#endif // #ifndef __BasicTutorial8_h_

 
Make sure that your Basic Tutorial 8 implementation file looks like this:

#include "BasicTutorial8.h"
#define CAMERA_NAME "SceneCamera"
 
//-------------------------------------------------------------------------------------
BasicTutorial8::BasicTutorial8(void)
    :mPrimarySceneMgr(0),
    mSecondarySceneMgr(0),
    mDual(false)
{
}
//-------------------------------------------------------------------------------------
BasicTutorial8::~BasicTutorial8(void)
{
}
 
//-------------------------------------------------------------------------------------
 
//Local Functions
void BasicTutorial8::setupViewport(Ogre::SceneManager *curr)
{
}
 
void BasicTutorial8::dualViewport(Ogre::SceneManager *primarySceneMgr, Ogre::SceneManager *secondarySceneMgr)
{
}
 
static void swap(Ogre::SceneManager *&first, Ogre::SceneManager *&second)
{
    Ogre::SceneManager *tmp = first;
    first = second;
    second = tmp;
}
 
//-------------------------------------------------------------------------------------
void BasicTutorial8::createScene(void)
{
}
 
void BasicTutorial8::chooseSceneManager(void)
{
}
 
void BasicTutorial8::createCamera()
{
}
 
void BasicTutorial8::createViewports()
{
}
 
void BasicTutorial8::createFrameListener(void)
{
    Ogre::LogManager::getSingletonPtr()->logMessage("*** Initializing OIS ***");
    OIS::ParamList pl;
    size_t windowHnd = 0;
    std::ostringstream windowHndStr;
 
    mWindow->getCustomAttribute("WINDOW", &windowHnd);
    windowHndStr << windowHnd;
    pl.insert(std::make_pair(std::string("WINDOW"), windowHndStr.str()));
 
    mInputManager = OIS::InputManager::createInputSystem( pl );
    mKeyboard = static_cast<OIS::Keyboard*>(mInputManager->createInputObject( OIS::OISKeyboard, true ));
    mMouse = static_cast<OIS::Mouse*>(mInputManager->createInputObject( OIS::OISMouse, true )); 
    mMouse->setEventCallback(this);
    mKeyboard->setEventCallback(this);
 
    //Set initial mouse clipping size
    windowResized(mWindow);
 
    //Register Window/Frame listener
    Ogre::WindowEventUtilities::addWindowEventListener(mWindow, this);
    mRoot->addFrameListener(this);
}
 
bool BasicTutorial8::frameRenderingQueued(const Ogre::FrameEvent& evt)
{
    if(mWindow->isClosed())
        return false;
 
    if(mShutDown)
        return false;
 
    //Need to capture/update each device
    mKeyboard->capture();
    mMouse->capture();
 
    return true;
}
 
bool BasicTutorial8::keyPressed( const OIS::KeyEvent &arg )
{
    if (arg.key == OIS::KC_ESCAPE)
    {
        mShutDown = true;
    }
    return true;
}
 
bool BasicTutorial8::keyReleased( const OIS::KeyEvent &arg )
{
    return true;
}
 
bool BasicTutorial8::mouseMoved( const OIS::MouseEvent &arg )
{
    return true;
}
 
bool BasicTutorial8::mousePressed( const OIS::MouseEvent &arg, OIS::MouseButtonID id )
{
    return true;
}
 
bool BasicTutorial8::mouseReleased( const OIS::MouseEvent &arg, OIS::MouseButtonID id )
{
    return true;
}
 
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
#define WIN32_LEAN_AND_MEAN
#include "windows.h"
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
    INT WINAPI WinMain( HINSTANCE hInst, HINSTANCE, LPSTR strCmdLine, INT )
#else
    int main(int argc, char *argv[])
#endif
    {
        // Create application object
        BasicTutorial8 app;
        try {
            app.go();
        } catch( Ogre::Exception& e ) {
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
            MessageBox( NULL, e.getFullDescription().c_str(), "An exception has occured!", MB_OK | MB_ICONERROR | MB_TASKMODAL);
#else
            std::cerr << "An exception has occured: " <<
                e.getFullDescription().c_str() << std::endl;
#endif
        }
 
        return 0;
    }
 
#ifdef __cplusplus
}
#endif

Be sure you can compile this code before continuing, running the program will only show a black screen. Press Esc to exit.

Setting up the Application

Creating the SceneManagers

We have previously covered how to select your SceneManager, so I will not go into detail about this function. The only thing we have changed is that we are creating two of them. Find the chooseSceneManager function and add the following code:

mPrimarySceneMgr = mRoot->createSceneManager(Ogre::ST_GENERIC, "primary");
mSecondarySceneMgr = mRoot->createSceneManager(Ogre::ST_GENERIC, "secondary");

Creating the Cameras

 

The next thing we need to do is create a Camera object for each of the two SceneManagers. The only difference from previous tutorials is that we are creating two of them, with the same name. Find the createCamera function and add the following code:

mPrimarySceneMgr->createCamera(CAMERA_NAME);
mSecondarySceneMgr->createCamera(CAMERA_NAME);

Creating the Viewports

 

In creating the Viewport for this application, we will be taking a small departure from previous tutorials. When you create a Viewport, you must do two things: set up the Viewport itself and then set the aspect ratio of the camera you are using. To begin with, add the following code to the createViewports function:

setupViewport(mPrimarySceneMgr);

The actual code for setting up the Viewport resides in our setupViewport() function since we will use this code again elsewhere. The first thing we need to do is remove all the previously created Viewports. None have been created yet, but when we call this function again later, we will need to make sure that they are all removed before creating new ones. After that we will set up the Viewports just like we have in previous tutorials. Add the following code to the setupViewport() function at the top of the file:

mWindow->removeAllViewports();
 
Ogre::Camera *cam = curr->getCamera(CAMERA_NAME); //The Camera
Ogre::Viewport *vp = mWindow->addViewport(cam); //Our Viewport linked to the camera
 
vp->setBackgroundColour(Ogre::ColourValue(0,0,0));
cam->setAspectRatio(Ogre::Real(vp->getActualWidth()) / Ogre::Real(vp->getActualHeight()));

Creating the Scene

 

Lastly, we need to create a scene for each SceneManager to contain. We won't make anything complex, just something different so that we know when we have swapped between the two. Find the createScene function and add the following code:

// Set up the space SceneManager
mPrimarySceneMgr->setSkyBox(true, "Examples/SpaceSkyBox");
// Set up the Cloudy SceneManager
mSecondarySceneMgr->setSkyDome(true, "Examples/CloudySky", 5, 8);

Be sure your code compiles before continuing. Running the program should show a space sky box. Nothing exciting yet.

Adding Functionality

Dual SceneManagers

The first piece of functionality we want to add to the program is to allow the user to render both SceneManagers side by side. When the V key is pressed we will toggle dual Viewport mode. The basic plan for this is simple. To turn off dual Viewport mode, we simply call setupViewport (which we created in the previous section) with the primary SceneManager to recreate the Viewport in single mode. When we want to turn it on, we will call a new function called dualViewport. We will keep track of the state of the Viewport with the mDual variable. Add the following code at the end of the keyPressed() function:

else if(arg.key == OIS::KC_V){
    mDual = !mDual;
 
    if (mDual)
	dualViewport(mPrimarySceneMgr, mSecondarySceneMgr);
    else
	setupViewport(mPrimarySceneMgr);
}

Now we have toggled the mDual variable and called the appropriate function based on which mode we are in. The next step is to define the dualViewport() function, which actually contains the code to show two Viewports at once.

In order to display two SceneManagers side by side, we basically do the same thing we have already done in the setupViewport() function. The only difference is that we will create two Viewports, one for each Camera in our SceneManagers. Add the following code to the dualViewport() function:

mWindow->removeAllViewports();
 
Ogre::Viewport *vp = 0;
Ogre::Camera *cam = primarySceneMgr->getCamera(CAMERA_NAME);
vp = mWindow->addViewport(cam, 0, 0, 0, 0.5, 1);
vp->setBackgroundColour(Ogre::ColourValue(0,0,0));
cam->setAspectRatio(Ogre::Real(vp->getActualWidth()) / Ogre::Real(vp->getActualHeight()));
 
cam = secondarySceneMgr->getCamera(CAMERA_NAME);
vp = mWindow->addViewport(cam, 1, 0.5, 0, 0.5, 1);
vp->setBackgroundColour(Ogre::ColourValue(0,0,0));
cam->setAspectRatio(Ogre::Real(vp->getActualWidth()) / Ogre::Real(vp->getActualHeight()));

All of this should be familiar except for the extra parameters we have added to the addViewport function call. The first parameter to this function is still the Camera we are using. The second parameter is the z order of the Viewport. A higher z order sits on top of the lower z orders. Note that you cannot have two Viewports with the same z order, even if they do not overlap. The next two parameters are the left and top positions of the Viewport, which must be between 0 and 1. Finally, the last two parameters are the width and the height of the Viewport as a percentage of the screen (again, they must be between 0 and 1). So in this case, the first Viewport we create will be at the position (0, 0) and will take up half of the screen horizontally and all of the screen vertically. The second Viewport will be at position (0.5, 0) and also take up half the horizontal space and all of the vertical space.

Compile and run the application. By pressing V you can now display two SceneManagers at the same time.

Swapping SceneManagers

The last piece of functionality we want to add to our program is to swap the SceneManagers whenever the C key is pressed. To do that, we will first swap the primarySceneMgr and secondarySceneMgr variables so that when the setupViewport() or dualViewport() functions are called, we never need to worry about which SceneManager is in which variable. The primary SceneManager will always be displayed in single mode, and the primary will always be on the left side in dualViewport mode. Add the following code to the end of the keyPressed() function:

else if(arg.key == OIS::KC_C){
    swap(mPrimarySceneMgr, mSecondarySceneMgr);
 
    if (mDual)
	dualViewport(mPrimarySceneMgr, mSecondarySceneMgr);
    else
	setupViewport(mPrimarySceneMgr);
}

After swapping the SceneManager variables, we perform the change. All we have to do is call the appropriate Viewport setup function depending on whether we are in dual or single mode.

That's it! Compile and run the application. We can now swap the SceneManagers with the C key, and swap single and dual mode with the V key.

Conclusion

Overlays

I'm sure you have noticed in your program that when you run in dual Viewport mode, the Ogre debug Overlay shows up on both sides. You may turn off Overlay rendering on a per-Viewport basis. Use the Viewport::setOverlaysEnabled function to turn them on and off. I have made this relatively simple change to the full source of this tutorial, so if you are confused as to how this is done, see that page for the details.

One Last Note

Always keep in mind that the Viewport class, while not having a lot of functionality itself, is the key to all Ogre rendering. It doesn't matter how many SceneManagers you create or how many Cameras in each SceneManager, none of them will be rendered to the window unless you set up a Viewport for each Camera you are showing. Also don't forget to clear out Viewports you are not using before creating more.

Alias: Basic_Tutorial_8