Basic Tutorial 8

From Ogre Wiki

Basic Tutorial 8: Using Multiple Scene Managers

Any problems you encounter while working with this tutorial should be posted to the Help Forum.

Contents 1 Introduction 2 Prerequisites 3 Setting up the Application 3.1 Creating the SceneManagers 3.2 Creating the Cameras 3.3 Creating the Viewports 3.4 Creating the Scene 4 Adding Functionality 4.1 Dual SceneManagers 4.2 Swapping SceneManagers 5 Conclusion 5.1 Overlays 5.2 One Last Note

Introduction

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

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.

Prerequisites

Create a cpp file in the IDE of your choice and add the following code to it:

#include "ExampleApplication.h"
#define CAMERA_NAME "SceneCamera"

void setupViewport(RenderWindow *win, SceneManager *curr)
{
}

void dualViewport(RenderWindow *win, SceneManager *primary, SceneManager *secondary)
{
}

class SMTutorialListener : public ExampleFrameListener, public OIS::KeyListener
{
public:
    SMTutorialListener(RenderWindow* win, SceneManager *primary, SceneManager *secondary)
        : ExampleFrameListener(win, primary->getCamera(CAMERA_NAME), true, false),
          mPrimary(primary), mSecondary(secondary), mDual(false), mContinue(true)
    {
        mKeyboard->setEventCallback(this);
    }

    bool frameStarted(const FrameEvent& evt)
    {
        mKeyboard->capture();
        return mContinue;
    }

    bool keyPressed(const OIS::KeyEvent &arg)
    {
       switch (arg.key)
       {
       case OIS::KC_ESCAPE:
           mContinue = false;
           break;

       default:
           break;
       }

       return true;
    }

    bool keyReleased(const OIS::KeyEvent &) {return true;}

private:
    SceneManager *mPrimary, *mSecondary;
    bool mDual, mContinue;

    static void swap(SceneManager *&first, SceneManager *&second)
    {
        SceneManager *tmp = first;
        first = second;
        second = tmp;
    }
};

class SMTutorialApplication : public ExampleApplication
{
public:
    SMTutorialApplication()
    {
    }

    ~SMTutorialApplication() 
    {
    }
protected:
    SceneManager *mPrimary, *mSecondary;

    void chooseSceneManager(void)
    {
    }

    void createCamera()
    {
    }

    void createViewports()
    {
    }

    void createScene(void)
    {
    }

    void createFrameListener(void)
    {
        mFrameListener = new SMTutorialListener(mWindow, mPrimary, mSecondary);
        mFrameListener->showDebugOverlay(true);
        mRoot->addFrameListener(mFrameListener);
    }
};

#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32 
#define WIN32_LEAN_AND_MEAN
#include "windows.h"

INT WINAPI WinMain(HINSTANCE hInst, HINSTANCE, LPSTR strCmdLine, INT)
#else
int main(int argc, char **argv)
#endif
{
    // Create application object
    SMTutorialApplication app;

    try {
        app.go();
    } catch(Exception& e) {
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
        MessageBoxA(NULL, e.getFullDescription().c_str(), "An exception has occurred!", MB_OK | MB_ICONERROR | MB_TASKMODAL);
#else
        fprintf(stderr, "An exception has occurred: %s\n",
            e.getFullDescription().c_str());
#endif
    }

    return 0;
}

Be sure you can compile this code before continuing, but do not attempt to run the program at this point.

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:

       mPrimary = mRoot->createSceneManager(ST_GENERIC, "primary");
       mSecondary = mRoot->createSceneManager(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:

       mPrimary->createCamera(CAMERA_NAME);
       mSecondary->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: setup 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(mWindow, mPrimary);

The actual code for setting up the Viewport resides in this 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 setup the Viewports just like we have in previous tutorials. Add the following code to the setupViewport function at the top of the file:

   win->removeAllViewports();

   Camera *cam = curr->getCamera(CAMERA_NAME);
   Viewport *vp = win->addViewport(cam);

   vp->setBackgroundColour(ColourValue(0,0,0));
   cam->setAspectRatio(Real(vp->getActualWidth()) / 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:

       // Setup the TerrainSceneManager
       mPrimary->setSkyBox(true, "Examples/SpaceSkyBox");

       // Setup the Generic SceneManager
       mSecondary->setSkyDome(true, "Examples/CloudySky", 5, 8);

Be sure your code compiles before continuing. You may run the program at this point, but it currently has no functionality other than exiting when you press Escape.

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 to the switch in the keyPressed function:

       case OIS::KC_V:
           mDual = !mDual;

           if (mDual)
               dualViewport(mWindow, mPrimary, mSecondary);
           else
               setupViewport(mWindow, mPrimary);

           break;

Now we have swapped the mDual variable and called the appropriate function based on which mode we are in. Now we will 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:

   win->removeAllViewports();

   Viewport *vp = 0;
   Camera *cam = primary->getCamera(CAMERA_NAME);
   vp = win->addViewport(cam, 0, 0, 0, 0.5, 1);
   vp->setBackgroundColour(ColourValue(0,0,0));
   cam->setAspectRatio(Real(vp->getActualWidth()) / Real(vp->getActualHeight()));

   cam = secondary->getCamera(CAMERA_NAME);
   vp = win->addViewport(cam, 1, 0.5, 0, 0.5, 1);
   vp->setBackgroundColour(ColourValue(0,0,0));
   cam->setAspectRatio(Real(vp->getActualWidth()) / 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 mPrimary and mSecondary 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 switch in the keyPressed function:

       case OIS::KC_C:
           swap(mPrimary, mSecondary);

After we swap the variables, we need to actually 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:

           if (mDual)
               dualViewport(mWindow, mPrimary, mSecondary);
           else
               setupViewport(mWindow, mPrimary);
           break;

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 setup a Viewport for each Camera you are showing. Also don't forget to clear out Viewports you are not using before creating more.