History: OgreDotNet Intermediate Tutorial 2

Source of version: 2 (current)

__Intermediate Tutorial 2: RaySceneQueries and Basic Mouse Usage__

Original version by [http://www.idleengineer.net|Clay Culver] 

Initial .NET C# port by DigitalCyborg

__Note:__ This was written for Ogre 1.2 and is known to compile against it. Any problems you encounter while working with this tutorial should be posted to the [http://www.ogre3d.org/phpBB2addons/viewforum.php?f=1|OgreDotNet Forum].

{maketoc}

!!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
# More usage of the OgreDotNet.EventHandler
# Using the mouse to select x and y coordinates on the terrain

!!Prerequisites
This tutorial will assume that you already know how to set up an OgreDotNet project and make it compile successfully. Knowledge of basic Ogre objects (SceneNodes, Entities, etc) is assumed.

Familiarity with STL iterators also helps since the cpp version of the tutorial uses them and we'll introduce how IEnumerator works in a similar fashion. Clay says "(Ogre also uses a lot of STL, if you are not familiar with it, you should take the time to learn it.)" which to us, means take the to learn the how the functionality IEnumator defines is intended to be used.

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

{CODE(wrap="1", colors="c#")} using System;
 using System.Drawing;
 using System.Text;
 
 using Math3D;
 using OgreDotNet;
 using OgreDotNet.Cegui;
 using CeguiDotNet;
 
 namespace OgreDotNetTutorial
 {
    class IntermediateTutorial2 : ExampleApplication
    {
        protected RaySceneQuery mRaySceneQuery = null;      // The ray scene query pointer
        protected bool mLMouseDown, mRMouseDown = false;    // True if the mouse buttons are down
        protected int mCount = 0;                           // The number of robots on the screen
        protected SceneNode mCurrentObject = null;          // The newly created object
 
        protected OgreCEGUIRenderer mGUIRenderer = null;    //CEGUI Renderer
        protected GuiSystem mGUISystem = null;              //GUISystem
        
        float mouseX, mouseY;
 
        protected override void MouseClick(MouseEvent e)
        {
        }
 
        protected override void MouseDragged(MouseMotionEvent e)
        {
        }
 
        protected override void MouseMotion(MouseMotionEvent e)
        {
        }
 
        protected override void MousePressed(MouseEvent e)
        {
        }
 
        protected override void MouseReleased(MouseEvent e)
        {
        }
 
        protected override bool FrameStarted(FrameEvent e)
        {
            if (!base.FrameStarted(e))
                return false;
            return true;
        }
 
        protected override bool FrameEnded(FrameEvent e)
        {
            return base.FrameEnded(e);
        }
 
        protected override void CreateSceneManager()
        {
            mSceneManager = mRoot.CreateSceneManager((ushort)SceneType.ExteriorClose);
        }
 
        protected override void CreateScene()
        {
        }
 
        protected override void CreateEventHandler() 
        {
            base.CreateEventHandler();
        }
 
     public IntermediateTutorial2() : base()
        { 
        }
 
        public override void Dispose()
        {
            base.Dispose();
        }
 
        [MTAThread]
        static void Main(string[] args)
        {
            using (IntermediateTutorial2 app = new IntermediateTutorial2())
                app.Start();
        }
    }
 }
{CODE}
Be sure this code compiles before continuing.

!!Setting up the Scene
Go to the 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

{CODE(wrap="1", colors="c#")}            // Set ambient light 
            mSceneManager.SetAmbientLight(Color.FromArgb(127, 127, 127));
 
            // World geometry & Sky
            mSceneManager.SetSkyDome(true,"Examples/CloudySky", 5, 8);
            mSceneManager.SetWorldGeometry("terrain.cfg");
             
            // Set camera look point           
            mCamera.SetPosition(new Math3D.Vector3(40,100,280));
            mCamera.Pitch(new Radian(new Degree(-30)));
            mCamera.Yaw(new Radian(new Degree(-45)));
{CODE}
Also, since we are using terrian, we need to setup a SceneManager which can use it. Add this line to CreateSceneManager:

{CODE(wrap="1", colors="c#")}            mSceneManager = mRoot.CreateSceneManager((ushort)SceneType.ExteriorClose);
{CODE}
I think we already covered why we need it in an earlier tutorial.

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.

{CODE(wrap="1", colors="c#")}         // CEGUI setup
            mGUIRenderer = new OgreCEGUIRenderer(base.mRenderWindow,
                (byte)RenderQueueGroupID.RENDER_QUEUE_OVERLAY, false, 3000, mSceneManager);
            mGUIRenderer.Initialise();
            mGUISystem = GuiSystem.CreateGuiSystemSpecial(mGUIRenderer);
{CODE}
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.
{CODE(wrap="1", colors="c#")}            
            //Setup Mouse cursor
            CeguiDotNet.SchemeManager.getSingleton().LoadScheme("TaharezLook.scheme");
            CeguiDotNet.MouseCursor.getSingleton().setImage("TaharezLook", "MouseArrow");
{CODE}
Now, since OgreCEGUIRender and GUISystem both implement IDisposable, we'll need to call thier Dispose methods in our applications Dispose method just before we call base.Dispose()

{CODE(wrap="1", colors="c#")}            mGUISystem.Dispose();
            mGUIRenderer.Dispose();
{CODE}
If you compile and run the code, you will see a cursor at the center of the screen. yay!

!!Introducing the EventHandler
That was all that needed to be done for the application. The EventHandler 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):

{CODE(wrap="1", colors="c#")}        protected RaySceneQuery mRaySceneQuery = null;      // The ray scene query pointer
        protected bool mLMouseDown, mRMouseDown = false;    // True if the mouse buttons are down
        protected int mCount = 0;                           // The number of robots on the screen
        protected SceneNode mCurrentObject = null;          // The newly created object
 
        protected OgreCEGUIRenderer mGUIRenderer = null;    //CEGUI Renderer
        protected GuiSystem mGUISystem = null;              //GUISystem
{CODE}
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 (i.e. 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 EventHandler. We will not be using all of them in this demo, but they must be there. Since the ExampleApplication already defines them, and we want to create our own versions of them, we use the override keyword.

!!Setting up the EventHandler
Go to the IntermediateTutorial2 constructor, and add the following initialization code. Note that we are reducing the movement speed since the Terrain is fairly small, and increasing the rotational speed.

{CODE(wrap="1", colors="c#")}         // Reduce move speed
         mMoveSpeed = 50;
         mRotateSpeed *= 2;
{CODE}
Remember that, in order for the EventHandler to recieve events, it be must be subscribed to the events. Since our base class ExampleApplication already does this and we already covered it in an earlier tutorial I won't go into it again here. But, I think the CreateEventHandler function is an ideal place the create the RaySceneQuery... so add this line to CreateEventHandler, right after the call to base.CreateEventHandler();

{CODE(wrap="1", colors="c#")}            // Create RaySceneQuery
            mRaySceneQuery = mSceneManager.CreateRayQuery(new Ray());
       {CODE}
This is all we do to create the SceneQuery, but if we create a RaySceneQuery, we must later dispose of it since it implements IDisposable. Go to the Applications Dispose() method and add the following line above what is already there.

{CODE(wrap="1", colors="c#")}           mRaySceneQuery.Dispose();
{CODE}
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 MouseMotion method. We will be adding code to move the mouse cursor every time the mouse has been moved. Add this code to the function:

{CODE(wrap="1", colors="c#")}            // Update CEGUI with the mouse motion
            GuiSystem.Instance.InjectMouseMove(e.DeltaX * mRenderWindow.Width, 
                e.DeltaY*mRenderWindow.Height);
 {CODE}
Since the mouse being dragged is stored in a seperate callback (and the mouse needs to be moved then too), we need to add this to the beginning of MouseDragged as well:

{CODE(wrap="1", colors="c#")}           // Update CEGUI with the mouse motion
           MouseMotion(e);
{CODE}
Now find the MousePressed method. This chunk of code hides the cursor when the right mouse button goes down, and sets the mRMouseDown variable to true. I don't really like that the switch statement uses numerical values (16,32)and not enums... if there is an enum that exists for the ButtonID, please update this.

{CODE(wrap="1", colors="c#")}            switch (e.ButtonID)
            {
                case 16:
                    mLMouseDown = true;
                    break;
                case 32:
                    mRMouseDown = true;
                    CeguiDotNet.MouseCursor.getSingleton().hide();
                    break;
                default:
                    break;
            }
{CODE}
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:

{CODE(wrap="1", colors="c#")}            switch (e.ButtonID)
            {
                case 16:
                    mLMouseDown = false;
                    break;
                case 32:
                    mRMouseDown = false;
                    CeguiDotNet.MouseCursor.getSingleton().show();
                    break;
                default:
                    break;
            }
{CODE}
Now that 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 accomplished by using the DeltaX & DelatY methods. This code should be added to the MouseDragged function above where it calls MouseMotion. When you normally move your mouse, MouseMotion is called, but when you move your mouse while a button is pressed, MouseDragged is called instead.

{CODE(wrap="1", colors="c#")}            if (mLMouseDown)
            {
            } // if mLMouseDown
 
            // If we are dragging the right mouse button.
            else if (mRMouseDown)
            {
                mCamera.Yaw(new Radian(-e.DeltaX * mRotateScale));
                mCamera.Pitch(new Radian(-e.DeltaY * mRotateScale));
            } // else if mRMouseDown
{CODE}
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 base class ExampleApplication already handles moving the camera, we are not going to touch that code. Instead, after the EventHandler 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 time.

Go to the FrameStarted method and remove all of the code from the method. The first thing we are going to do is call the base class (ExampleApplication) FrameStarted method to do all of its normal functions. If it returns false, we will return false as well.

{CODE(wrap="1", colors="c#")}             if (!base.FrameStarted(e))
                return false;
{CODE}
Now the camera has been moved. Our trick 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 NegativeUnitY, since we are pointing the ray straight down. Once we have created the ray, we tell the RaySceneQuery object to use it.

{CODE(wrap="1", colors="c#")}            // Setup the scene query
            Math3D.Vector3 camPos = mCamera.GetPosition();
            Ray cameraRay = new Ray( new Math3D.Vector3(camPos.x, 5000.0f, camPos.z),
                Math3D.Vector3.NegativeUnitY);
            mRaySceneQuery.setRay(cameraRay);
{CODE}
Next we need to execute the query and get the results. The results of the query come in the form of an RaySceneQueryResultEnumerator, which I will breifly describe. First thing to know is that it implements IEnumerator which means there are some functions that are guaranteed (by the compiler) to be implemented. Let's add the code to perform the query, then we'll talk about it a little more.

{CODE(wrap="1", colors="c#")}            // Perform the scene query;
            RaySceneQueryResult result = mRaySceneQuery.execute();
            RaySceneQueryResult.RaySceneQueryResultEnumerator itr = result.GetEnumerator();
{CODE}
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 IEnumerator, to get the enumerator we have to call GetEnumerator (one of the methods that all classes that implement IEnumerator must have). We also have to call MoveNext to actually go to the first element. MoveNext() returns false, then there were no results returned. 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 != null && itr.MoveNext ), and that the result is the terrain (itr.Current.getWWorldFragment).

{CODE(wrap="1", colors="c#")}            // Get the results, set the camera height
            if((itr != null) && itr.MoveNext()){
{CODE}
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.

{CODE(wrap="1", colors="c#")}                float terrainHeight = itr.Current.getWorldFragment().getSingleIntersection().y;
 
                if((terrainHeight + 10.0f) > camPos.y) 
                    mCamera.SetPosition(camPos.x,terrainHeight + 10.0f, camPos.z);
            }
            return true;
{CODE}
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 MousePressed function. We will be adding code __inside__ this case statement.

{CODE(wrap="1", colors="c#")}            mouseX = e.X;
            mouseY = e.Y;
 
            switch (e.ButtonID)
            {
                case 16:
                    mLMouseDown = true;
                    break;
{CODE}
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.GetCameraToViewpointRay; 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.

{CODE(wrap="1", colors="c#")}                    // Setup the ray scene query
                    Ray mouseRay = mCamera.GetCameraToViewportRay(e.X,e.Y);
                    mRaySceneQuery.setRay(mouseRay);
                
                    // Execute query
                    RaySceneQueryResult result = mRaySceneQuery.execute();
                    RaySceneQueryResult.RaySceneQueryResultEnumerator itr = result.GetEnumerator();
                    
                    // Get results, create a node/entity on the position
                    if ( itr != null && itr.MoveNext() )
                    {
{CODE}
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 "RobotNode1", "RobotNode2", "RobotNode3"... and so on. To do this we are going to make use of the way strings are handled in C# (namely that the + operation concatenates 2 strings) and the ToString method. We'll be forming the strings Robot1 and RobotNode1 like this:

{CODE(wrap="1", colors="c#")}              "Robot" + mCount.ToString()
              "RobotNode" + mCount.ToString()
{CODE}
Next we create the Entity and SceneNode. Note that we use itr.Current.GetWorldFragment().GetSingleIntersection() 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.

{CODE(wrap="1", colors="c#")}                        Entity ent = mSceneManager.CreateEntity(
                            "Robot" + mCount.ToString(), "robot.mesh");
 
                        mCurrentObject = mSceneManager.GetRootSceneNode().CreateChildSceneNode(
                            "RobotNode" + mCount.ToString(),
                            itr.Current.getWorldFragment().getSingleIntersection());
                        
                        mCount++;
                        mCurrentObject.AttachObject(ent);
                        mCurrentObject.SetScale( 0.1f, 0.1f, 0.1f );
                    } //
                    mLMouseDown = true;
                    break;
 {CODE}
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. Go to the MouseDragged function. We will be adding code inside this if statement:

{CODE(wrap="1", colors="c#")}        // If we are dragging the left mouse button.
        if ( mLMouseDown )
        {
        } // if
{CODE}
This entire code chunk 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.

{CODE(wrap="1", colors="c#")}            if (mLMouseDown)
            {
                mouseX += e.DeltaX;
                mouseY += e.DeltaY;
                Ray mouseRay = mCamera.GetCameraToViewportRay(mouseX,mouseY)
                mRaySceneQuery.setRay(mouseRay);
 
                RaySceneQueryResult result = mRaySceneQuery.execute();
                RaySceneQueryResult.RaySceneQueryResultEnumerator itr = result.GetEnumerator();
 
                if ((itr != null) && itr.MoveNext())
                {
                    mCurrentObject.SetPosition(itr.Current.getWorldFragment().getSingleIntersection());
                }
            } // if mLMouseDown
{CODE}
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]

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

!!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.
History: OgreDotNet Intermediate Tutorial 2

Source of version: 2 (current)

Search by Tags

Latest Changes

Search

Online Users
