View source for The Zandalar project

Jump to: navigation, search
You do not have permission to edit this page, for the following reason:
The action you have requested is limited to users in the group: Users.
You can view and copy the source of this page:
The Zandalar Project is a codename for the new Input archtecture and GUI navigation features.

= Input Aggregator & events =
== Use Cases ==

The use cases are described by steps. For each step there might be some actions done at different levels:
* Raw input = the data that comes directly from the input system the application is using (OIS, glfw, etc.).
* Input Injection = the `InjectedInputReceiver`-ish function called with the right parameters
** For backwards compatibility-ish, we can persist the same interface(InjectedInputReceiver), but provide in it a default implementation that generates the input events for the current interface's functions.
* InputEvent = the `InputEvent` type generated from the injected input. This is the final step, and this is fed to the CEGUI library.

=== Clicking a button using a mouse ===
{| class="wikitable"
|-
! Step description !! Raw input !! Input Injection !! InputEvent fed to CEGUI
|-
| Move the mouse over the button || Mouse movement || injectMouseMove/injectMousePosition || MovementInputEvent
|-
| Press the LMB || Mouse button press || injectMouseButtonDown(LMB) || PressedButtonInputEvent(Mouse_LMB)
|-
| Release the LMB|| Mouse button release || injectMouseButtonUp(LMB) || ReleasedButtonInputEvent(Mouse_LMB)
|-
| The button is clicked (Click event is triggered)|| N/A || N/A || N/A
|}

=== Clicking/activating a button using the keyboard (new feature) ===
{| class="wikitable"
|-
! Step description !! Raw input !! Input Injection !! InputEvent fed to CEGUI
|-
| Focus the button || colspan = 3 | Uses the use case "''Focus a button using the keyboard/gamepad''"
|-
| Press the ENTER key (1) || Key Button press || injectKeyDown(Enter) || PressedButtonInputEvent(Keyb_Enter)
|-
| Release the ENTER key || Key Button release || injectKeyUp(Enter) || ReleasedButtonInputEvent(Keyb_Enter)
|-
| The button is clicked (Click event is triggered)|| N/A || N/A || N/A
|}

(1) the key will be defined as per the NavigationStrategy (GUINavigation project part). If there is no such key defined, the event will be ignored.

=== Clicking/activating a button using a gamepad ===
The same as previous ''Clicking/activating a button using the keyboard'', but with the difference that it uses a Gamepad button instead of a Keyboard one.

=== Type text into a textbox ===
{| class="wikitable"
|-
! Step description !! Raw input !! Input Injection !! InputEvent fed to CEGUI
|-
| Focus the textbox || colspan = 3 | Uses the use case "''Focus a textbox using the keyboard/gamepad''"
|-
| Press a character key || Char press || injectChar(chr) || TextInputEvent(chr)
|-
| Press a non-character key || Key Button press || injectKeyDown(key) || PressedButtonInputEvent(Keyb_key)
|-
| Release a non-character key || Key Button release || injectKeyUp(key) || ReleasedButtonInputEvent(Keyb_key
|}

=== Focus a button using the keyboard/gamepad ===
TODO - This should go into the GUI Navigation part.

== Proposed design ==
=== Events ===
For start, the following events will cover all existing functions in the 'InjectedInputReceiver' interface:

MovementInputEvent
* '''Data''':
** Position : Vector2
** Delta : Vector2
* '''Functions''':
** injectMouseMove
** injectMousePosition

PressedButtonInputEvent
* '''Data''':
** Button : Buttons Enum/integer or long for maximum flexibility
* '''Functions''':
** injectMouseButtonDown
** injectKeyDown

ReleasedButtonInputEvent
* '''Data''':
** Button : Buttons Enum/integer or long for maximum flexibility
* '''Functions''':
** injectMouseButtonUp
** injectKeyUp

ActivatedInputEvent
* '''Data''':
** Count (1+) : int
* '''Functions''':
** injectMouseButtonClick
** injectMouseButtonDoubleClick
** injectMouseButtonTripleClick

TextInputEvent
* '''Data''':
** Text : string/char
* '''Functions''':
** injectChar

Unmapped (yet) functions:
* injectMouseLeaves
* injectMouseWheelChange

== Original proposition ==
I propose an input abstraction so we can use the GUI in environments where we don�t have a keyboard and mouse. This will imply changing much (if not all) of the existing input architecture.

First of all we won�t use anymore the raw inputs we were used to (e.g.: injectMouseDown, injectMouseUp), but rather `Input Events`. An `InputEvent` is the basic input unit CEGUI will use, and that is generated from raw input. The input event is a basic POD class (just like the current EventArgs) that contains different information based on where it came from and from what raw input it was generated.

Some examples of input events are:
* MovementInputEvent
**   Generated from mouse x/y
**   Generated from joystick/thumbstick x/y
* PressedInputEvent
**   Generated from mouse button
**   Generated from keyboard button
**   Generated from a gamepad button
* ReleasedInputEvent � the opposite of the previous event

One can see that this solution leads us to allow a variety of input to be mapped to certain input events. Of course, each different input event will have some specific payload (the button pressed, the x/y coordinates of the movement, etc.).

Now, on the API part the window will have a single method: `injectInputEvent(InputEvent)`. With the use of �Int-To-Type� idiom, we can easily and at compile-time (maximum performance) dispatch the events to their respective handlers (without using dynamic_cast). Moreover, we get infinite (ok, it�s really a maximum of sizeof(int) but it�s enough) types of input events. The user can create new input events inside his custom controls as he sees fit, and just creates handlers for them, and they will be called accordingly by our system in a transparent way.

Then, after we�ve created the new input representation we  need a way to generate those from raw input. For this, we�ll have the so-called `Input Aggregator` which will be able to aggregate raw inputs from multiple input devices into input events. In order to define the way we get those inputs, we will have an interface for each type of input device supported, and attach it to the aggregator dynamically as required by the user. This �supported input device� wording shouldn�t scare us. I am not talking about actually implementing the support for those input devices, but rather just defining the interface we require to be implemented so we can use those input directly, without having the user emulate it (e.g.: emulate the mouse movement from the input of a joystick maneuver).

In order for the library to work with some basic input events out of the box I will create a default `Input Aggregator` implementation for mouse and keyboard (and if time allows it for gamepad). Basically what is required to be done is: take the current methods used in the `InjectedInputReceiver` and move them in device-specific files (e.g.: MouseInputReceiver, KeyboardInputReceiver). In there, we�ll generate some input events from the raw input, to be used by the CEGUI library. Then, we�ll add the instances of the receivers to the input aggregator instance. And, at each update step in the game, when the users wants, it will take all aggregated input events from the input aggregator, and send each one of them to the `GUIContext` of CEGUI. Of course, the user can create new `InputReceivers` for each device they want � or replace the default ones - and add them to the aggregator.

At the end of the day, the samples that exist now should work (from the functionality point of view) the same way after the input system is replaced.
Return to The Zandalar project.
Retrieved from "http://cegui.org/wiki/The_Zandalar_project"
View source for The Zandalar project

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Main

Community

Documentation

Tools
