History: BasicTutorial5-new

Source of version: 5 (current)

{TRANSCLUDE(page="tutbox")}In this short tutorial you will be learning to use OIS's buffered input as opposed to the unbuffered input we used last tutorial. This tutorial differs from the last in that we will be handling keyboard and mouse events immediately, as they happen, instead of once per frame. Note that this is only meant as an introduction to buffered input, and not a complete tutorial on how to use OIS. For more information on that, be sure to look at the ((Using OIS)) article.{TRANSCLUDE}

%tutorialhelp%

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

You can find the code for this tutorial ((BasicTutorial5Source-new|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
This tutorial will be building on the last tutorial, but we are changing the way that we do input. Since the functionality will be basically the same, we will use the same TutorialApplication class from last time, but we will be starting over on the TutorialFrameListener. Create a project in the compiler of your choice for this project, and add a source file which contains this code:

{CODE(wrap="1", colors="c++")}
//code here
{CODE}

!!Buffered Input in a Nutshell
!!!Introduction
In the previous tutorial we used unbuffered input, that is, every frame we queried the state of OIS::Keyboard and OIS::Mouse instances to see what keys and mouse buttons were being held down.
Buffered input uses listener interfaces to inform your program that events have occurred.
For example, when a key is pressed, a KeyListener::keyPressed event is fired and when the button is released (no longer being pressed) a KeyListener::keyReleased event is fired to all registered KeyListener classes.
This takes care of having to keep track of toggle times or whether the key was unpressed the previous frame.

OIS also supports unbuffered Joystick events through the OIS::JoystickListener interface, though we will not cover how to use this in this tutorial.

One important thing to note about OIS's listener system is that you can only have one listener per Keyboard, Mouse, or Joystick object.
This is done for simplicity (and for speed).
Calling the setEventCallback function (which we will cover later) multiple times will result in only the last registered listener getting events.
If you need multiple objects to get Key, Mouse, or Joystick events, you will have to write a message dispatch yourself.
Also, be sure to note that we still call the Keyboard::capture and Mouse::capture in the frameStarted method.
OIS does not use threads (or magic) to determine the keyboard and mouse states, so you will have to specify when it should capture the input.

!!!The KeyListener Interface
OIS's KeyListener interface provides two pure virtual functions.
The first is the keyPressed function, which is called every time a key is pressed.
The second is the keyReleased function, which is called every time a key is let up.
The parameter passed to these functions is a KeyEvent, which contains the key code of what is being pressed/released.

!!!The MouseListener Interface
The MouseListener interface is only slightly more complex than the KeyListener interface.
It contains functions to see when a mouse button was pressed or released: MouseListener::mousePressed and MouseListener::mouseReleased.
It also contains a mouseMoved function, which is called when the mouse is moved.
Each of these functions receive a MouseEvent object, which contains the current state of the mouse in the "state" variable.

The most important thing to note about the MouseState object is that it contains not only the relative X and Y coordinates of the mouse move (that is, how far it has moved since the last time the MouseListener::mouseMoved function was called), but also the absolute X and Y coordinates (that is, where exactly on the screen they are).

!!The Code

{CODE(wrap="1", colors="c++")}
class TutorialFrameListener : public ExampleFrameListener, public OIS::MouseListener, public OIS::KeyListener
    : ExampleFrameListener(win, cam, true, true)
{CODE}
We subclass the OIS MouseListener and KeyListener classes so that we can receive events from them. Note that the OIS MouseListener handles both mouse button events and mouse movement events.  The third and forth parameters of ExampleFrameListener have been change to true, which specifies that we will be using buffered input for the keyboard and mouse. We will go into more detail on how to manually set up OIS as well as the rest of Ogre in the next tutorial.

!!!Variables
A few variables have changed from the last tutorial. I have removed mToggle and mMouseDown (which are no longer needed). I have added a few as well:

{CODE(wrap="1", colors="c++")}
Real mRotate;          // The rotate constant
Real mMove;            // The movement constant

SceneManager *mSceneMgr;   // The current SceneManager
SceneNode *mCamNode;   // The SceneNode the camera is currently attached to

bool mContinue;        // Whether to continue rendering or not
Vector3 mDirection;     // Value to move in the correct direction
{CODE}
The mRotate, mMove, mSceneMgr, and mCamNode are the same as the last tutorial (though we will be changing the value of mRotate since we are using it differently). The mContinue variable is returned from the frameStarted method. When we set mContinue to be false the program will exit. The mDirection variable contains information on how we are going to translate camera node every frame.

!!!TutorialFrameListener Constructor
In the constructor, we will initialize some of the variables as we did in the previous tutorial, and we will set the mContinue rendering to be true. Add the following code to TutorialFrameListener's constructor:

{CODE(wrap="1", colors="c++")}
// Populate the camera and scene manager containers
mCamNode = cam->getParentSceneNode();
mSceneMgr = sceneMgr;

// set the rotation and move speed
mRotate = 0.13;
mMove = 250;

// continue rendering
mContinue = true;
{CODE}
The OIS mMouse and mKeyboard objects are already obtained in the ExampleFrameListener constructor. We can register the TutorialFrameListener as the listener by calling the setEventCallback method on these input objects as follows:

{CODE(wrap="1", colors="c++")}
mMouse->setEventCallback(this);
mKeyboard->setEventCallback(this);
{CODE}
Last, we need to initialise mDirection to be the zero vector (since we are initially not moving):

{CODE(wrap="1", colors="c++")}
mDirection = Vector3::ZERO;
{CODE}
!!!Key Bindings


Before we go any further, we should bind the Escape key to exiting the program so we can run it. Find the TutorialFrameListener::keyPressed method. This method is called with a KeyEvent object every time a button on the keyboard goes down. We can obtain the key code (KC_*) of the key that was pressed by checking the "key" variable on the object. We will build a switch for all of the key bindings we use in the application based on this value. Find the keyPressed method and replace it with the following code:

{CODE(wrap="1", colors="c++")}
bool keyPressed(const OIS::KeyEvent &e)
{
    switch (e.key)
    {
    case OIS::KC_ESCAPE: 
        mContinue = false;
        break;
    default:
        break;
    }
    return mContinue;
}
{CODE}
Make sure you can compile and run the application before continuing.

We need to add bindings for other keys in that switch statement. The first thing we are going to do is allow the user to switch between the viewpoints by pressing 1 and 2. The code for this (needs to be included in the switch statement) is the same as it was in the previous tutorial, except we no longer have to deal with the mToggle variable:

{CODE(wrap="1", colors="c++")}
case OIS::KC_1:
    mCamera->getParentSceneNode()->detachObject(mCamera);
    mCamNode = mSceneMgr->getSceneNode("CamNode1");
    mCamNode->attachObject(mCamera);
    break;
 
case OIS::KC_2:
    mCamera->getParentSceneNode()->detachObject(mCamera);
    mCamNode = mSceneMgr->getSceneNode("CamNode2");
    mCamNode->attachObject(mCamera);
    break;
{CODE}
As you can see, this is much cleaner than dealing with a temporary variable to keep track of toggle times.

The next thing we are going to add is keyboard movement. Every time the user presses a key that is bound for movement, we will add or subtract mMove (depending on direction) from the correct direction in the vector:

{CODE(wrap="1", colors="c++")}
case OIS::KC_UP:
case OIS::KC_W:
    mDirection.z = -mMove;
    break;
  
case OIS::KC_DOWN:
case OIS::KC_S:
    mDirection.z = mMove;
    break;
  
case OIS::KC_LEFT:
case OIS::KC_A:
    mDirection.x = -mMove;
    break;

case OIS::KC_RIGHT:
case OIS::KC_D:
    mDirection.x = mMove;
    break;
 
case OIS::KC_PGDOWN:
case OIS::KC_E:
    mDirection.y = -mMove;
    break;
  
case OIS::KC_PGUP:
case OIS::KC_Q:
    mDirection.y = mMove;
    break; 
{CODE}
Now we need to "undo" the change to the mDirection vector whenever the key is released to stop the movement. Find the keyReleased method and add this code to it:

{CODE(wrap="1", colors="c++")}
switch (e.key)
{
case OIS::KC_UP:
case OIS::KC_W:
    mDirection.z = 0;
    break;

case OIS::KC_DOWN:
case OIS::KC_S:
    mDirection.z = 0;
    break;

case OIS::KC_LEFT:
case OIS::KC_A:
    mDirection.x = 0;
    break;

case OIS::KC_RIGHT:
case OIS::KC_D:
    mDirection.x = 0;
    break;

case OIS::KC_PGDOWN:
case OIS::KC_E:
    mDirection.y = 0;
    break;

case OIS::KC_PGUP:
case OIS::KC_Q:
    mDirection.y = 0;
    break;

default:
    break;
}
return true;
{CODE}
Now that we have mDirection updated based on key input, we need to actually make the translation happen. This code is the exact same as the last tutorial, so add this to the frameStarted function:

{CODE(wrap="1", colors="c++")}
mCamNode->translate(mDirection * evt.timeSinceLastFrame, Node::TS_LOCAL);
{CODE}
Compile and run the application. We now have key-based movement using buffered input!

!!!Mouse Bindings
Now that we have key bindings completed, we need to work on getting the mouse working. We'll start with toggling the light on and off based on a left mouse click. Find the mousePressed function and take a look at the parameters. With OIS, we have access to both a MouseEvent as well as a MouseButtonID. We can switch on the MouseButtonID to determine the button that was pressed. Replace the code in the mousePressed function with the following:

{CODE(wrap="1", colors="c++")}
Light *light = mSceneMgr->getLight("Light1");
switch (id)
{
case OIS::MB_Left:
    light->setVisible(! light->isVisible());
    break;
default:
    break;
}
return true;
{CODE}
Compile and run the application. VoilÃ ! Now that this is working, the only thing we have left is to bind the right mouse button to a mouse look mode. Every time the mouse is moved, we will check to see if the right mouse button is down. If it is, we will rotate the camera based on the relative movement. We can access the relative movement of the mouse from the MouseEvent object passed into this function. It contains a variable called "state" which contains the MouseState (which is basically detailed information about the mouse). The MouseState::buttonDown will tell us whether or not a particular mouse button is held down, and the "X" and "Y" variables will tell us the relative mouse movement. Find the mouseMoved function and replace the code in it with the following:

{CODE(wrap="1", colors="c++")}
if (e.state.buttonDown(OIS::MB_Right))
{
    mCamNode->yaw(Degree(-mRotate * e.state.X.rel), Node::TS_WORLD);
    mCamNode->pitch(Degree(-mRotate * e.state.Y.rel), Node::TS_LOCAL);
}
return true;
{CODE}
Compile and run the application and the camera will act in free-look mode while the right mouse button is held down.

!!Other Input Systems
OIS is generally very good, and should suit most purposes for your application. With that said, there are alternatives if you wish to use something different. Some windowing systems may be what you are looking for, such as [http://www.wxwindows.org/|wxWidgets], which people have successfully integrated with Ogre. You can use the standard Windows message system or one of the many Linux GUI toolkits for input, if you don't mind your application being platform specific.

You can also try SDL, which provides not only cross platform windowing/input systems, but also joystick/gamepad input. While I cannot give you guidance on setting up wx/gtk/qt/etc with Ogre (as I've never done it before), I have had a good amount of success getting SDL's joystick/gamepad input to work well with Ogre. To get SDL's joystick system started, wrap your application's intial startup with SDL_Init and SDL_Quit calls (this can be in your application's main function, or possibly in your application object):

{CODE(wrap="1", colors="c++")}
SDL_Init(SDL_INIT_JOYSTICK | SDL_INIT_NOPARACHUTE);
SDL_JoystickEventState(SDL_ENABLE);

app.go();

SDL_Quit();
{CODE}
To setup the Joystick, call SDL_JoystickOpen with the Joystick number (you can specify multiple joysticks by calling with 0, 1, 2...):

{CODE(wrap="1", colors="c++")}
SDL_Joystick* mJoystick;
mJoystick = SDL_JoystickOpen(0);
 
if ( mJoystick == NULL )
    ; // error handling
{CODE}
If SDL_JoystickOpen returns NULL, then there was a problem opening the joystick. This almost always means that the joystick you requested doesn't exist. Use SDL_NumJoysticks to find out how many joysticks are attached to the system. You also need to close the joystick after you are done with it:

{CODE(wrap="1", colors="c++")}
SDL_JoystickClose(mJoystick);
{CODE}
To use the joystick, call the SDL_JoystickGetButton and SDL_JoystickGetAxis buttons. I personally used this with a [http://www.toysnjoys.com/access_ps2/ps2_controller.jpg|playstation2 controller], so I had four axes to play with and twelve buttons to play with. This is my movement code:

{CODE(wrap="1", colors="c++")}
SDL_JoystickUpdate();
 
mTrans.z += evt.timeSinceLastFrame * mMoveAmount * SDL_JoystickGetAxis(mJoystick, 1) / 32767;
mTrans.x += evt.timeSinceLastFrame * mMoveAmount * SDL_JoystickGetAxis(mJoystick, 0) / 32767;

xRot -= evt.timeSinceLastFrame * mRotAmount * SDL_JoystickGetAxis(mJoystick, 3) / 32767;
yRot -= evt.timeSinceLastFrame * mRotAmount * SDL_JoystickGetAxis(mJoystick, 2) / 32767;
{CODE}
mTrans was later fed into the camera's SceneNode::translate method, xRot was fed into SceneNode::yaw, and yRot was fed into SceneNode::pitch. Note that the SDL_JoystickGetAxis returns a value between -32767 and 32767, so I have scaled it to be between -1 and 1. This should get you started using SDL joystick input. If you are looking for more information in this area, the best documentation comes from the SDL joystick [http://www.jikos.cz/~crag/private/dox/SDL__joystick_8h-source.html|header].

You should also refer to the standard SDL documentation if you start to seriously use this in your application.

Proceed to ((Basic Tutorial 6)) ''The Ogre Startup Sequence''
History: BasicTutorial5-new

Source of version: 5 (current)

Search by Tags

Latest Changes

Search

Online Users
