Intermediate Tutorial 2

From Ogre Wiki

Intermediate Tutorial 2: RaySceneQueries and Basic Mouse Usage

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

1 Introduction
2 Prerequisites
3 Getting Started
4 Setting up the Scene
5 Introducing the FrameListener
6 Setting up the FrameListener
7 Adding Mouse Look
8 Terrain Collision Detection
9 Terrain Selection
10 Exercises for Further Study

Introduction

In this tutorial we will create the beginnings of a basic Scene Editor. During this process, we will cover:

How to use RaySceneQueries to keep the camera from falling through the terrain
How to use the MouseListener and MouseMotionListener interfaces
Using the mouse to select x and y coordinates on the terrain

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

This tutorial will assume that you already know how to set up an Ogre project and make it compile successfully. Knowledge of basic Ogre objects (SceneNodes, Entities, etc) is assumed. You should also be familiar with basic STL iterators, as this tutorial uses them. (Ogre also uses a lot of STL, if you are not familiar with it, you should take the time to learn it.)

Getting Started

First, you need to create a new project for the demo. Add a file called "MouseQuery.cpp" to the project, and add this to it:

#include <CEGUI/CEGUISystem.h>
#include <CEGUI/CEGUISchemeManager.h>
#include <OgreCEGUIRenderer.h>

#include "ExampleApplication.h"

class MouseQueryListener : public ExampleFrameListener, public OIS::MouseListener
{
public:

    MouseQueryListener(RenderWindow* win, Camera* cam, SceneManager *sceneManager, CEGUI::Renderer *renderer)
        : ExampleFrameListener(win, cam, false, true), mGUIRenderer(renderer)
    {
    } // MouseQueryListener

    ~MouseQueryListener()
    {
    }

    bool frameStarted(const FrameEvent &evt)
    {
        return ExampleFrameListener::frameStarted(evt);
    }

    /* MouseListener callbacks. */
    bool mouseMoved(const OIS::MouseEvent &arg)
    {
        return true;
    }

    bool mousePressed(const OIS::MouseEvent &arg, OIS::MouseButtonID id)
    {
        return true;
    }

    bool mouseReleased(const OIS::MouseEvent &arg, OIS::MouseButtonID id)
    {
        return true;
    }


protected:
    RaySceneQuery *mRaySceneQuery;     // The ray scene query pointer
    bool mLMouseDown, mRMouseDown;     // True if the mouse buttons are down
    int mCount;                        // The number of robots on the screen
    SceneManager *mSceneMgr;           // A pointer to the scene manager
    SceneNode *mCurrentObject;         // The newly created object
    CEGUI::Renderer *mGUIRenderer;     // CEGUI renderer
};

class MouseQueryApplication : public ExampleApplication
{
protected:
    CEGUI::OgreCEGUIRenderer *mGUIRenderer;
    CEGUI::System *mGUISystem;         // cegui system
public:
    MouseQueryApplication()
    {
    }

    ~MouseQueryApplication() 
    {
    }
protected:
    void chooseSceneManager(void)
    {
        // Use the terrain scene manager.
        mSceneMgr = mRoot->createSceneManager(ST_EXTERIOR_CLOSE);
    }

    void createScene(void)
    {
    }

    void createFrameListener(void)
    {
        mFrameListener = new MouseQueryListener(mWindow, mCamera, mSceneMgr, mGUIRenderer);
        mFrameListener->showDebugOverlay(true);
        mRoot->addFrameListener(mFrameListener);
    }
};


#if OGRE_PLATFORM == PLATFORM_WIN32 || 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
    MouseQueryApplication app;

    try {
        app.go();
    } catch(Exception& e) {
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
        MessageBox(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 this code compiles before continuing.

Setting up the Scene

Go to the MouseQueryApplication::createScene method. The following code should all be familiar. If you do not know what something does, please consult the Ogre API reference before continuing. Add this to createScene:

       // Set ambient light
       mSceneMgr->setAmbientLight(ColourValue(0.5, 0.5, 0.5));
       mSceneMgr->setSkyDome(true, "Examples/CloudySky", 5, 8);

       // World geometry
       mSceneMgr->setWorldGeometry("terrain.cfg");

       // Set camera look point
       mCamera->setPosition(40, 100, 580);
       mCamera->pitch(Degree(-30));
       mCamera->yaw(Degree(-45));

Now that we have the basic world geometry set up, we need to turn on the cursor. We do this using some CEGUI function calls. Before we can do that, however, we need to start up CEGUI. We first create an OgreCEGUIRenderer, then we create the System object and give it the Renderer we just created. I will leave the specifics of setting up CEGUI for a later tutorial, just know that you always have to tell CEGUI which SceneManager you are using with the last paramater to mGUIRenderer.

       // CEGUI setup
       mGUIRenderer = new CEGUI::OgreCEGUIRenderer(mWindow, Ogre::RENDER_QUEUE_OVERLAY, false, 3000, mSceneMgr);
       mGUISystem = new CEGUI::System(mGUIRenderer);

Now we need to actually show the cursor. Again, I'm not going to explain most of this code. We will revisit it in a later tutorial.

       // Mouse
       CEGUI::SchemeManager::getSingleton().loadScheme((CEGUI::utf8*)"TaharezLookSkin.scheme");
       CEGUI::MouseCursor::getSingleton().setImage("TaharezLook", "MouseArrow");

If you compile and run the code, you will see a cursor at the center of the screen, but it will not move (yet).

Introducing the FrameListener

That was all that needed to be done for the application. The FrameListener is the complicated portion of the code, so I will spend some time outlining what we are trying to accomplish with the application so you have an idea before we start implementing it.

First, we want to bind the right mouse button to a "mouse look" mode. It's fairly annoying not being able to use the mouse to look around, so our first priority will be making adding mouse control back to the program (though only when we hold the right mouse button down).
Second, we want to make it so that the camera does not pass through the Terrain. This will make it closer to how we would expect program like this to work.
Third, we want to add entities to the scene anywhere on the terrain we left click.
Finally, we want to be able to "drag" entities around. That is by left clicking and holding the button down we want to see the entity, and move him to where we want to place him. Letting go of the button will actually lock him into place.

To do this we are going to use several protected variables (these are already added to the class):

    RaySceneQuery *mRaySceneQuery;     // The ray scene query pointer
    bool mLMouseDown, mRMouseDown;     // True if the mouse buttons are down
    int mCount;                        // The number of robots on the screen
    SceneManager *mSceneMgr;           // A pointer to the scene manager
    SceneNode *mCurrentObject;         // The newly created object
    CEGUI::Renderer *mGUIRenderer;     // cegui renderer

The mRaySceneQuery variable holds a copy of the RaySceneQuery we will be using to find the coordinates on the terrain. The mLMouseDown and mRMouseDown variables will track whether we have the mouse held down (IE mLMouseDown is true when the user holds down the left mouse button, false otherwise). mCount counts the number of entities we have on screen. mCurrentObject holds a pointer to the most recently created SceneNode that we have created (we will be using this to "drag" the entity around). Finally, mGUIRenderer holds a pointer to the CEGUI Renderer, which we will be using to update CEGUI with.

Also note that there are many functions related to Mouse listeners. We will not be using all of them in this demo, but they must be there or the compiler will complain that you did not define them.

Setting up the FrameListener

Go to the MouseQueryListener constructor, and add the following inialization code. Note that we are also reducing the movement speed and rotation speed since the Terrain is fairly small.

        // Setup default variables
        mCount = 0;
        mCurrentObject = NULL;
        mLMouseDown = false;
        mRMouseDown = false;
        mSceneMgr = sceneManager;

        // Reduce move speed
        mMoveSpeed = 50;
        mRotateSpeed /= 500;

In order for the MouseQueryListener to receive mouse events, we must register it as a MouseListener. If any of this is unfamiliar, please consult Basic Tutorial 5

        // Register this so that we get mouse events.
        mMouse->setEventCallback(this);

Finally, in the constructor we need to create the RaySceneQuery object. This is done with a call to the SceneManager:

        // Create RaySceneQuery
        mRaySceneQuery = mSceneMgr->createRayQuery(Ray());

This is all we need for the constructor, but if we create a RaySceneQuery, we must later destroy it. Go to the MouseQueryListener destructor (~MouseQueryListener) and add the following line:

        // We created the query, and we are also responsible for deleting it.
        mSceneMgr->destroyQuery(mRaySceneQuery);

Be sure you can compile your code before moving on to the next section.

Adding Mouse Look

We are going to bind the mouse look mode to the right mouse button. To do this, we are going to:

update CEGUI when the mouse is moved (so that the cursor is also moved)
set mRMouseButton to be true when the mouse is pressed
set mRMouseButton to be false when it is released
change the view when the mouse is "dragged" (that is held down and moved)
hide the mouse cursor when the mouse is dragging

Find the MouseQueryListener::mouseMoved method. We will be adding code to move the mouse cursor every time the mouse has been moved. Add this code to the function:

       // Update CEGUI with the mouse motion
       CEGUI::System::getSingleton().injectMouseMove(arg.state.X.rel, arg.state.Y.rel);

Now find the MouseQueryListener::mousePressed method. This chunk of code hides the cursor when the right mouse button goes down, and sets the mRMouseDown variable to true.

       // Left mouse button down
       if (id == OIS::MB_Left)
       {
           mLMouseDown = true;
       } // if

       // Right mouse button down
       else if (id == OIS::MB_Right)
       {
           CEGUI::MouseCursor::getSingleton().hide();
           mRMouseDown = true;
       } // else if

Next we need to show the mouse cursor again and toggle mRMouseDown when the right button is let up. Find the mouseReleased function, and add this code:

       // Left mouse button up
       if (id == OIS::MB_Left)
       {
           mLMouseDown = false;
       } // if

       // Right mouse button up
       else if (id == OIS::MB_Right)
       {
           CEGUI::MouseCursor::getSingleton().show();
           mRMouseDown = false;
       } // else if

Now we have all of the prerequisite code written, we want to change the view when the mouse is moved while holding the right button down. What we are going to do is read the distance it has moved since the last time the method was called. This is done in the same way that we rotated the camera in Basic Tutorial 5. Find the MouseQueryListener::mouseMoved function and add the following code just before the return statement:

       // If we are dragging the left mouse button.
       if (mLMouseDown)
       {
       } // if

       // If we are dragging the right mouse button.
       else if (mRMouseDown)
       {
           mCamera->yaw(Degree(-arg.state.X.rel * mRotateSpeed));
           mCamera->pitch(Degree(-arg.state.Y.rel * mRotateSpeed));
       } // else if

Now if you compile and run this code you will be able to control where the camera looks by holding the right mouse button down.

Terrain Collision Detection

We are now going to make it so that when we move towards the terrain, we cannot pass through it. Since the BaseFrameListener already handles moving the camera, we are not going to touch that code. Instead, after the BaseFrameListener moves the camera we are going to make sure the camera is 10 units above the terrain. If it is not, we are going to move it there. Please follow this code closely. We will use the RaySceneQuery to do several other things by the time this tutorial is finished, and I will not go into as much detail after this section.

Go to the MouseQueryListener::frameStarted method and remove all of the code from the method. The first thing we are going to do is call the ExampleFrameListener::frameStarted method to do all of its normal functions. If it returns false, we will return false as well.

        // Process the base frame listener code.  Since we are going to be
        // manipulating the translate vector, we need this to happen first.
        if (!ExampleFrameListener::frameStarted(evt))
            return false;

We do this at the top of our frameStarted function because the ExampleFrameListener's frameStarted member function moves the camera, and we need to perform the rest our actions in this function after this happens. Our goal is to find the camera's current position, and fire a Ray straight down it into the terrain. This is called a RaySceneQuery, and it will tell us the height of the Terrain below us. After getting the camera's current position, we need to create a Ray. A Ray takes in an origin (where the ray starts), and a direction. In this case our direction will be NEGATIVE_UNIT_Y, since we are pointing the ray straight down. Once we have created the ray, we tell the RaySceneQuery object to use it.

       // Setup the scene query
       Vector3 camPos = mCamera->getPosition();
       Ray cameraRay(Vector3(camPos.x, 5000.0f, camPos.z), Vector3::NEGATIVE_UNIT_Y);
       mRaySceneQuery->setRay(cameraRay);

Note that we have used a height of 5000.0f instead of the camera's actual position. If we used the camera's Y position instead of this height we would miss the terrain entirely if the camera is under the terrain. Now we need to execute the query and get the results. The results of the query comes in the form of an std::iterator, which I will briefly describe.

        // Perform the scene query
        RaySceneQueryResult &result = mRaySceneQuery->execute();
        RaySceneQueryResult::iterator itr = result.begin();

The result of the query is basically (oversimplification here) a list of worldFragments (in this case the Terrain) and a list of movables (we will cover movables in a later tutorial). If you are not familiar with STL iterators, just know that to get the first element of the iterator, call the begin method. If the result.begin() == result.end(), then there were no results to return. In the next demo we will have to deal with multiple return values for SceneQuerys. For now, we'll just do some hand waving and move through it. The following line of code ensures that the query returned at least one result ( itr != result.end() ), and that the result is the terrain (itr->worldFragment).

        // Get the results, set the camera height
        if (itr != result.end() && itr->worldFragment)
        {

The worldFragment struct contains the location where the Ray hit the terrain in the singleIntersection variable (which is a Vector3). We are going to get the height of the terrain by assigning the y value of this vector to a local variable. Once we have the height, we are going to see if the camera is below the height, and if so we are going to move the camera up to that height. Note that we actually move the camera up by 10 units. This ensures that we can't see through the Terrain by being too close to it.

            Real terrainHeight = itr->worldFragment->singleIntersection.y;
            if ((terrainHeight + 10.0f) > camPos.y)
                mCamera->setPosition( camPos.x, terrainHeight + 10.0f, camPos.z );
        }

        return true;

Lastly, we return true to continue rendering. At this point you should compile and test your program.

Terrain Selection

In this section we will be creating and adding objects to the screen every time you click the left mouse button. Every time you click and hold the left mouse button, an object will be created and "held" on your cursor. You can move the object around until you let go of the button, at which point it will lock into place. To do this we are going to need to change the mousePressed function to do something different when you click the left mouse button. Find the following code in the MouseQueryListener::mousePressed function. We will be adding code inside this if statement.

       // Left mouse button down
       if (id == OIS::MB_Left)
       {
           mLMouseDown = true;
       } // if

The first piece of code will look very familiar. We will be creating a Ray to use with the mRaySceneQuery object, and setting the Ray. Ogre provides us with Camera::getCameraToViewportRay; a nice function that translates a click on the screen (x and y coordinates) into a Ray that can be used with a RaySceneQuery object.

           // Left mouse button down
           if (id == OIS::MB_Left)
           {
               // Setup the ray scene query, use CEGUI's mouse position
               CEGUI::Point mousePos = CEGUI::MouseCursor::getSingleton().getPosition();
               Ray mouseRay = mCamera->getCameraToViewportRay(mousePos.d_x/float(arg.state.width), mousePos.d_y/float(arg.state.height));
               mRaySceneQuery->setRay(mouseRay);

Next we will execute the query and make sure it returned a result.

               // Execute query
               RaySceneQueryResult &result = mRaySceneQuery->execute();
               RaySceneQueryResult::iterator itr = result.begin( );

               // Get results, create a node/entity on the position
               if (itr != result.end() && itr->worldFragment)
               {

Now that we have the worldFragment (and therefore the position that was clicked on), we are going to create the object and place it on that position. Our first difficulty is that each Entity and SceneNode in ogre needs a unique name. To accomplish this we are going to name each Entity "Robot1", "Robot2", "Robot3"... and each SceneNode "Robot1Node", "Robot2Node", "Robot3Node"... and so on. First we create the name (consult a reference on C for more information on sprintf).

               char name[16];
               sprintf( name, "Robot%d", mCount++ );

Next we create the Entity and SceneNode. Note that we use itr->worldFragment->singleIntersection for our default position of the Robot. We also scale him down to 1/10th size because of how small the terrain is. Be sure to take note that we are assigning this newly created object to the member variable mCurrentObject. We will be using that in the next section.

                   Entity *ent = mSceneMgr->createEntity(name, "robot.mesh");
                   mCurrentObject = mSceneMgr->getRootSceneNode()->createChildSceneNode(String(name) + "Node", itr->worldFragment->singleIntersection);
                   mCurrentObject->attachObject(ent);
                   mCurrentObject->setScale(0.1f, 0.1f, 0.1f);
               } // if

               mLMouseDown = true;
           } // if

Now compile and run the demo. You can now place Robots on the scene by clicking anywhere on the Terrain. We have almost completed our program, but we need to implement object dragging before we are finished. We will be adding code inside this if statement:

       // If we are dragging the left mouse button.
	if (mLMouseDown)
	{
	} // if

This next chunk of code should be self explanatory now. We create a Ray based on the mouse's current location, we then execute a RaySceneQuery and move the object to the new position. Note that we don't have to check mCurrentObject to see if it is valid or not, because mLMouseDown would not be true if mCurrentObject had not been set by mousePressed.

       if (mLMouseDown)
       {
           CEGUI::Point mousePos = CEGUI::MouseCursor::getSingleton().getPosition();
           Ray mouseRay = mCamera->getCameraToViewportRay(mousePos.d_x/float(arg.state.width),mousePos.d_y/float(arg.state.height));
           mRaySceneQuery->setRay(mouseRay);

           RaySceneQueryResult &result = mRaySceneQuery->execute();
           RaySceneQueryResult::iterator itr = result.begin();

           if (itr != result.end() && itr->worldFragment)
               mCurrentObject->setPosition(itr->worldFragment->singleIntersection);
       } // if

Compile and run the program. We are now finished! Your result should look something like this, after some strategic clicking: http://www.idleengineer.net/images/tutorial_02.png

Note: You (= the Ray's origin) must be over the Terrain for the RaySceneQuery to report the intersection when using the TerrainSceneManager.

Note: If you are using your own framework, make sure your scene query has access to the frame listener, e.g. in your frameStarted() method. Otherwise, if you use it in an init() function you may get no results.

Exercises for Further Study

Easy Exercises

To keep the camera from looking through the terrain, we chose 10 units above the Terrain. This selection was arbitrary. Could we improve on this number and get closer to the Terrain without going through it? If so, make this variable a static class member and assign it there.
We sometimes do want to pass through the terrain, especially in a SceneEditor. Create a flag which turns toggles collision detection on and off, and bind this to a key on the keyboard. Be sure you do not make a SceneQuery in frameStarted if collision detection is turned off.

Intermediate Exercises

We are currently doing the SceneQuery every frame, regardless of whether or not the camera has actually moved. Fix this problem and only do a SceneQuery if the camera has moved. (Hint: Find the translation vector in ExampleFrameListener, after the function is called test it against Vector3::ZERO.)

Advanced Exercises

Notice that there is a lot of code duplication every time we make a scene query call. Wrap all of the SceneQuery related functionality into a protected function. Be sure to handle the case where the Terrain is not intersected at all.

Exercises for Further Study

In this tutorial we used RaySceneQueries to place objects on the Terrain. We could have used it for many other purposes. Take the code from Tutorial 1 and complete Difficult Question 1 and Expert Question 1. Then merge that code with this one so that the Robot now walks on the terrain instead of empty space.
Add code so that every time you click on a point on the scene, the robot moves to that location.