Basic Tutorial 8

From PyWiki

[edit] Basic Tutorial 8: Using Multiple Scene Managers

[edit] 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.

[edit] Prerequisites

Create a python file in the IDE of your choice, add the following code, and save it in the python-ogre demos folder.

import ogre.renderer.OGRE as ogre 
import ogre.io.OIS as OIS 
import SampleFramework as sf 
 
CAMERA_NAME = "SceneCamera" 
 
def setupViewport(RenderWindow, SceneManager): 
    pass 
 
def dualViewport(win, primary, secondary): 
    pass
 
class SMTutorialListener(sf.FrameListener): 
    def __init__(self, win, primary, secondary): 
        sf.FrameListener.__init__(self, win, primary.getCamera(CAMERA_NAME)) 
        self.mContinue = True 
        self.mDual = False 
        self.mWindow = win 
        self.mPrimary = primary 
        self.mSecondary = secondary 
 
    def frameStarted(self, frameEvent): 
        return sf.FrameListener.frameStarted(self, frameEvent) 
 
    def _processUnbufferedKeyInput(self, frameEvent): 
        pass
 
 
class SMTutorialApplication(sf.Application): 
    def __init__(self): 
        sf.Application.__init__(self) 
 
    def _chooseSceneManager(self): 
        pass
 
    def _createCamera(self): 
        pass
 
    def _createViewports(self): 
        pass 
 
    def _createScene(self): 
        pass  
 
    def _createFrameListener(self): 
        self.mFrameListener = SMTutorialListener(self.renderWindow, self.mPrimary, self.mSecondary); 
        self.mFrameListener.showDebugOverlay(True) 
        ogre.Root.getSingleton().addFrameListener(self.mFrameListener)
 
    def __del__(self):
        "Clear variables, this should not actually be needed."
        del self.camera
        del self.mPrimary
        del self.mSecondary
        del self.frameListener
        if self.world:
            del self.world
        del self.root
        del self.renderWindow
 
 
if __name__ == '__main__': 
    app = SMTutorialApplication() 
    app.go()

[edit] Setting up the Application

[edit] 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 in place of 'pass':

       self.mPrimary = ogre.Root.getSingleton().createSceneManager(ogre.ST_GENERIC, "primary") 
       self.mSecondary = ogre.Root.getSingleton().createSceneManager(ogre.ST_GENERIC, "secondary")

[edit] 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 replace 'pass' with the following code:

       self.mPrimary.createCamera(CAMERA_NAME) 
       self.mSecondary.createCamera(CAMERA_NAME)

[edit] 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 (in all these instances, you must replace 'pass' with the new code):

      setupViewport(self.renderWindow, self.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, replacing 'pass':

   RenderWindow.removeAllViewports() 
   cam = SceneManager.getCamera(CAMERA_NAME) 
   vp = RenderWindow.addViewport(cam) 
   vp.setBackgroundColour((0,0,0)) 
   cam.setAspectRatio(float(vp.getActualWidth()) / float(vp.getActualHeight()))

[edit] 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:

       self.mPrimary.setSkyBox(True, "Examples/SpaceSkyBox") 
       self.mSecondary.setSkyDome(True, "Examples/CloudySky", 5, 8)

[edit] Adding Functionality

[edit] 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 _processUnbufferedKeyInput function:

       if self.Keyboard.isKeyDown(OIS.KC_V) and self.timeUntilNextToggle <= 0:
           self.timeUntilNextToggle = 1
           self.mDual = not self.mDual 
           if self.mDual: 
               dualViewport(self.mWindow, self.mPrimary, self.mSecondary) 
           else: 
               setupViewport(self.mWindow, self.mPrimary)

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 at the top of the file:

   win.removeAllViewports() 
   cam = primary.getCamera(CAMERA_NAME) 
   vp = win.addViewport(cam, 0, 0, 0, 0.5, 1) 
   vp.setBackgroundColour((0,0,0)) 
   cam.setAspectRatio(float(vp.getActualWidth()) / float(vp.getActualHeight()))
 
   cam = secondary.getCamera(CAMERA_NAME) 
   vp = win.addViewport(cam, 1, 0.5, 0, 0.5, 1) 
   vp.setBackgroundColour((1,0,0)) 
   cam.setAspectRatio(float(vp.getActualWidth()) / float(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.

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

[edit] 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:

       if self.Keyboard.isKeyDown(OIS.KC_C) and self.timeUntilNextToggle <= 0:
           self.timeUntilNextToggle = 1
           self.mPrimary, self.mSecondary = self.mSecondary, self.mPrimary

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 self.mDual: 
               dualViewport(self.mWindow, self.mPrimary, self.mSecondary) 
           else: 
               setupViewport(self.mWindow, self.mPrimary)

Finally, we need to return the normal frameListener's _processUnbufferedKeyInput function, to capture things like the ESC key being pressed to exit the program

       return sf.FrameListener._processUnbufferedKeyInput(self, frameEvent) 

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

[edit] Conclusion

[edit] 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.

[edit] 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.

[edit] Complete Code

Here's the full code listing, in case you just want to copy and paste it to see it working:

import ogre.renderer.OGRE as ogre 
import ogre.io.OIS as OIS 
import SampleFramework as sf 
 
CAMERA_NAME = "SceneCamera" 
 
def setupViewport(RenderWindow, SceneManager): 
    RenderWindow.removeAllViewports() 
    cam = SceneManager.getCamera(CAMERA_NAME) 
    vp = RenderWindow.addViewport(cam) 
    vp.setBackgroundColour((0,0,0)) 
    cam.setAspectRatio(float(vp.getActualWidth()) / float(vp.getActualHeight())) 
 
def dualViewport(win, primary, secondary): 
    win.removeAllViewports() 
    cam = primary.getCamera(CAMERA_NAME) 
    vp = win.addViewport(cam, 0, 0, 0, 0.5, 1) 
    vp.setBackgroundColour((0,0,0)) 
    cam.setAspectRatio(float(vp.getActualWidth()) / float(vp.getActualHeight())) 
    cam = secondary.getCamera(CAMERA_NAME) 
    vp = win.addViewport(cam, 1, 0.5, 0, 0.5, 1) 
    vp.setBackgroundColour((1,0,0)) 
    cam.setAspectRatio(float(vp.getActualWidth()) / float(vp.getActualHeight())) 
 
class SMTutorialListener(sf.FrameListener): 
    def __init__(self, win, primary, secondary): 
        sf.FrameListener.__init__(self, win, primary.getCamera(CAMERA_NAME)) 
        self.mContinue = True 
        self.mDual = False 
        self.mWindow = win 
        self.mPrimary = primary 
        self.mSecondary = secondary  
 
    def frameStarted(self, frameEvent): 
        return sf.FrameListener.frameStarted(self, frameEvent) 
 
    def _processUnbufferedKeyInput(self, frameEvent): 
        if self.Keyboard.isKeyDown(OIS.KC_V) and self.timeUntilNextToggle <= 0:
            self.timeUntilNextToggle = 1
            self.mDual = not self.mDual 
            if self.mDual: 
                dualViewport(self.mWindow, self.mPrimary, self.mSecondary) 
            else: 
                setupViewport(self.mWindow, self.mPrimary) 
 
        if self.Keyboard.isKeyDown(OIS.KC_C) and self.timeUntilNextToggle <= 0:
            self.timeUntilNextToggle = 1
            self.mPrimary, self.mSecondary = self.mSecondary, self.mPrimary
            if self.mDual: 
                dualViewport(self.mWindow, self.mPrimary, self.mSecondary) 
            else: 
                setupViewport(self.mWindow, self.mPrimary) 
 
        return sf.FrameListener._processUnbufferedKeyInput(self, frameEvent)  
 
class SMTutorialApplication(sf.Application): 
    def __init__(self): 
        sf.Application.__init__(self)  
 
    def _chooseSceneManager(self): 
        self.mPrimary = ogre.Root.getSingleton().createSceneManager(ogre.ST_GENERIC, "primary") 
        self.mSecondary = ogre.Root.getSingleton().createSceneManager(ogre.ST_GENERIC, "secondary") 
 
    def _createCamera(self): 
        self.mPrimary.createCamera(CAMERA_NAME) 
        self.mSecondary.createCamera(CAMERA_NAME)  
 
    def _createViewports(self): 
        setupViewport(self.renderWindow, self.mPrimary)  
 
    def _createScene(self): 
        self.mPrimary.setSkyBox(True, "Examples/SpaceSkyBox") 
        self.mSecondary.setSkyDome(True, "Examples/CloudySky", 5, 8)  
 
    def _createFrameListener(self): 
        self.mFrameListener = SMTutorialListener(self.renderWindow, self.mPrimary, self.mSecondary); 
        self.mFrameListener.showDebugOverlay(True) 
        ogre.Root.getSingleton().addFrameListener(self.mFrameListener)
 
    def __del__(self):
        "Clear variables, this should not actually be needed."
        del self.camera
        del self.mPrimary
        del self.mSecondary
        del self.frameListener
        if self.world:
            del self.world
        del self.root
        del self.renderWindow
 
 
if __name__ == '__main__': 
    app = SMTutorialApplication() 
    app.go()