Cross-Platform Game Programming with gameplay3d/Getting Some Input

Handling input in your gameplay3d game is easy - the gameplay::Game class, from which your game inherits, contains a number of virtual methods which are called whenever there is any input to be handled, so all you need to do is to override these methods in your game.

Mouse

Game::mouseEvent() is called when a mouse event occurs. The function signature for the mouseEvent() method is as follows:

virtual bool mouseEvent(Mouse::MouseEvent evt, int x, int y, int wheelDelta);

where:

• evt represents the mouse event that occurred and is one of the following enum values defined in Mouse.h:
  • MOUSE_PRESS_LEFT_BUTTON
  • MOUSE_RELEASE_LEFT_BUTTON
  • MOUSE_PRESS_MIDDLE_BUTTON
  • MOUSE_RELEASE_MIDDLE_BUTTON
  • MOUSE_PRESS_RIGHT_BUTTON
  • MOUSE_RELEASE_RIGHT_BUTTON
  • MOUSE_MOVE
  • MOUSE_WHEEL
• x is the x position of the mouse in pixels. (Left edge is zero.)
• y is the y position of the mouse in pixels. (Top edge is zero.)
• wheelDelta is the number of mouse wheel ticks. (Positive is up/forward, negative is down/backward.)

Mouse events that are not consumed will be interpreted as a touch event. You can consume a mouse event by overriding Game::mouseEvent() and returning true. This gives you the option to uniquely handle mouse events from touch events. Game::mouseEvent() returns false by default.

Note that some mobile devices can use a Bluetooth mouse.

You can enable or disable "mouse capture" using the Game::setMouseCaptured() method, which takes a boolean value as an argument. On platforms that support a mouse, when mouse capture is enabled, the platform cursor will be hidden and the mouse will be warped to the center of the screen. While mouse capture is enabled, all mouse move events will then be delivered as deltas instead of absolute positions.

Game::setCursorVisible(), which also takes a boolean value, can be used to show (true) or hide (false) the mouse cursor.

Keyboard

Game::keyEvent() is called when a keyboard event occurs. The function signature for the keyEvent() method is as follows:

virtual void keyEvent(Keyboard::KeyEvent evt, int key);

where:

• evt represents the key event that occurred and is one of the following enum values defined in Keyboard.h:
  • KEY_PRESS
  • KEY_RELEASE
  • KEY_CHAR - this is used for textual characters and is therefore not triggered by pressing keys such as Ctrl, Shift, the arrow keys, Home, End etc.
• key - If evt is KEY_PRESS or KEY_RELEASE then key is the key code from Keyboard::Key. If evt is KEY_CHAR then key is the unicode value of the character.

A full list of the different key codes in the Keyboard::Key enum can be found at this page in the gameplay3d API reference, or in the Keyboard.h source file.

You can call Game::displayKeyboard(), which takes a boolean value, to show (true) or hide (false) a virtual keyboard for platforms that support it.

Touch

Basics

Game::touchEvent() is called when a touch event occurs. The function signature for the touchEvent() method is as follows:

virtual void touchEvent(Touch::TouchEvent evt, int x, int y, unsigned int contactIndex);

where:

• evt represents the touch event that occurred and is one of the following enum values defined in Touch.h:
  • TOUCH_PRESS
  • TOUCH_RELEASE
  • TOUCH_MOVE
• x is the x position of the touch in pixels. (Left edge is zero.)
• y is the y position of the touch in pixels. (Top edge is zero.)
• contactIndex is used to differentiate multiple touch contacts where multi-touch is enabled, and represents the order of occurrence for multiple touch contacts starting at zero. However, do not assume that the contactIndex values are sequential.

Some platforms may allow you to touch outside the bounds of the screen, so negative x and y values are possible.

You can enable multi-touch using Game::setMultiTouch(), which takes a boolean value. The default is disabled (false).

Gestures

Some platforms support gestures. Game::isGestureSupported() can be used to determine which gestures are supported.

The gestures you can check for are defined in the GestureEvent enum in Gesture.h and are as follows:

• GESTURE_TAP
• GESTURE_SWIPE
• GESTURE_PINCH
• GESTURE_LONG_TAP
• GESTURE_DRAG
• GESTURE_DROP
• GESTURE_ANY_SUPPORTED

Game::registerGesture(), which takes a GestureEvent value as an argument, is used to register for a type of gesture.

Once a gesture is registered, you will receive callbacks via the following virtual methods. See the function declarations in Game.h for details of the parameters:

virtual void gestureTapEvent(int x, int y);
virtual void gestureSwipeEvent(int x, int y, int direction);
virtual void gesturePinchEvent(int x, int y, float scale);
virtual void gestureLongTapEvent(int x, int y, float duration);
virtual void gestureDragEvent(int x, int y);
virtual void gestureDropEvent(int x, int y);