History: Basic Tutorial 8

Source of version: 14 (current)

{TRANSCLUDE(page="tutbox")}In this short tutorial we will be covering how to swap between multiple scene managers.{TRANSCLUDE}

%tutorialhelp%

{INCLUDE(page="Basic Tutorials Prerequsites")}{INCLUDE}

You can find the code for this tutorial ((BasicTutorial8Source|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.

{maketoc}

!Getting Started
!!The Initial Code
Modify your Basic Tutorial 8 class header to look like this:

{CODE(wrap="1", colors="c++")}
#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_

{CODE}

Make sure that your Basic Tutorial 8 implementation file looks like this: 
{CODE(wrap="1", colors="c++")}
#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

{CODE}
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:

{CODE(wrap="1", colors="c++")}
mPrimarySceneMgr = mRoot->createSceneManager(Ogre::ST_GENERIC, "primary");
mSecondarySceneMgr = mRoot->createSceneManager(Ogre::ST_GENERIC, "secondary");
{CODE}
!!!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:

{CODE(wrap="1", colors="c++")}
mPrimarySceneMgr->createCamera(CAMERA_NAME);
mSecondarySceneMgr->createCamera(CAMERA_NAME);
{CODE}
!!!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:

{CODE(wrap="1", colors="c++")}
setupViewport(mPrimarySceneMgr);
{CODE}
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:

{CODE(wrap="1", colors="c++")}
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()));
{CODE}
!!!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:

{CODE(wrap="1", colors="c++")}
// Set up the space SceneManager
mPrimarySceneMgr->setSkyBox(true, "Examples/SpaceSkyBox");
// Set up the Cloudy SceneManager
mSecondarySceneMgr->setSkyDome(true, "Examples/CloudySky", 5, 8);
{CODE}
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:

{CODE(wrap="1", colors="c++")}
else if(arg.key == OIS::KC_V){
    mDual = !mDual;

    if (mDual)
	dualViewport(mPrimarySceneMgr, mSecondarySceneMgr);
    else
	setupViewport(mPrimarySceneMgr);
}
{CODE}
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:

{CODE(wrap="1", colors="c++")}
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()));
{CODE}
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:

{CODE(wrap="1", colors="c++")}
else if(arg.key == OIS::KC_C){
    swap(mPrimarySceneMgr, mSecondarySceneMgr);

    if (mDual)
	dualViewport(mPrimarySceneMgr, mSecondarySceneMgr);
    else
	setupViewport(mPrimarySceneMgr);
}
{CODE}
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 ((BasicTutorial8Source|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: (alias(Basic_Tutorial_8))
History: Basic Tutorial 8

Source of version: 14 (current)

Search by Tags

Latest Changes

Search

Online Users
