Game Controller
Glossary Item Box
| Microsoft Robotics Developer Studio | Send feedback on this topic |
Game Controller
.png "Game Controller Icon")
The Game Controller service provides access to the output of a DirectInput device (a keyboard, mouse, joystick or other game controller that supports the DirectInput Application Programming Interface).
Mostly you listen for notifications from the Game Controller. These include notifications whenever the joystick is moved, buttons are pressed or released, and when other controls like sliders or Point-Of-View (POV) "hats" are moved.
Operations
The Game Controller supports the following operations:
| Operation | Description |
|---|---|
| ChangeController | Changes which game controller is in use or indicates that the game controller has changed. |
| GetControllers | Returns a list of attached controllers. |
| Poll | Requests the controller to read its current state (values). However, you typically do not need to issue this request because this service updates itself 20 times per second. |
| Replace | Changes or indicates a change to the state of the game controller. |
| UpdateAxes | Indicates when one (or both) of the axes of the joystick is moved. |
| UpdateButtons | Indicates when one or more buttons is pressed or released. |
| UpdatePovHats | Indicates when the position of a Point-Of-View (POV) hat switch is changed. |
| UpdateSliders | Indicates when the position of a slider is changed. |
Get and Replace provide access to the entire state of the controller. However, Replace generates a notification when used as a request, not when the axes, buttons, POV hats, or slides are moved or pressed.
Service State
The state of the controller service includes the following properties:
| Name | Type | Description |
|---|---|---|
| Axes | Axes | Specifies the current position of the axes. |
| Buttons | Buttons | Specifies the current state of all the buttons. |
| Controller | Controller | Specifies the current controller used by this instance of the Game Controller service. |
| Sliders | Sliders | Specifies the current positions of the sliders (if present). |
| PovHats | PovHats | Specifies the current directions of the Point-Of-View hats (if present). |
| TimeStamp | DateTime | Specifies the timestamp of the most recent update. |
A device may have many controllers connected to it. The Game Controller service automatically selects the first controller (if any) it finds. GetController and ChangeController enable you to determine or change the current game controller.
Each controller is defined by the following properties:
| Name | Type | Description |
|---|---|---|
| Current | Boolean | Specifies if this is the current controller in use. |
| Instance | GUID | Specifies the unique identifier (GUID) for this controller. |
| InstanceName | Controller | Specifies a user friendly name for the controller. |
| Product | GUID | Specifies the unique product identifier (GUID) for this controller. |
| ProductName | string | Specifies a user friendly product name for this controller. |
| TimeStamp | DateTime | Specifies the timestamp (in milliseconds) of the latest reading of this controller. |
You can set the initial value of ProductName and InstanceName of a controller explicitly using the Set initial configuration option in VPL.
Each of the update notifications includes the state values of the components of the game controller.
The Axes includes the X, Y and Z position of the joystick, as well as the rotations (RX, RY and RZ) for those controllers that support twisting and turning of the joystick. A joystick is typically a 2D device with the X direction being from left to right and the Y direction running from backward to forward. When the joystick is released it should return to its center position where the X and Y values are zero. For a 3D joystick the Z coordinate corresponds to movements up and down. Some joysticks have a separate trigger or slider control that maps to the Z coordinate and is often used to control speed, acceleration or braking. The range of coordinate values is -1000 to +1000.
The Buttons includes a List of Boolean values called Pressed, one for each button on the controller. If a button is pressed then the corresponding value of Pressed[index] will be true where index is the number of the button starting from zero. You can determine the total number of buttons for the controller using Pressed.Count. Because the actual buttons on your game controller may be labeled with letters like "A" and "B" and not numbers. You may need to write a simple diagram to determine the correspondence between the labels on the buttons on your joystick and the numbers in the List.
The Sliders includes a List of Integer values called Position. Each value Position[index] corresponds to a particular slider where index is the number of the slider beginning at zero. You can determine total number of sliders is available using Position.Count. Note that this will be zero if your joystick does not have any sliders. You will not receive any slider notifications if there are no sliders.
The PovHats includes a List of Integer values called Direction. POV hats indicate a direction of view and have a small number of different positions such as left, right, up, down. These are represented as Integers. Each value Direction[index] is the direction of the corresponding POVhat. The total number of hats is available using Direction.Count. Note that this will be zero if your joystick does not have any POV hats. You will not receive any POV hat notifications if there are no hats.
© 2012 Microsoft Corporation. All Rights Reserved.