When designing a game controller compliant with the Human Interface Devices (HID) firmware specification, care should be taken to ensure that the device expresses its capabilities in a manner that applications can exploit. This document briefly outlines issues that should be taken into consideration to allow the device to be used by the widest range of applications across a variety of operating system platforms.
Since input devices can be oriented in several attitudes, this document will attempt to avoid using terms such as "up" and "left". Instead, compass directions will be used ("north", "west", etc.) For a control mounted on a horizontal surface, "north" is typically represented by motion away from the user. For a control mounted on a vertical surface, "north" is typically represented by motion away from the earth. In general, devices should choose a northerly direction that is intuitively obvious to the user.
For DirectInput to recognize a HID game controller as a joystick or gamepad, it must declare its top-level collection as belonging to the Generic Desktop Page (0x01), and deploy usage Joystick (0x04) or Game Pad (0x05), respectively.
Although devices declared otherwise will still be accessible to DirectInput applications which request non-joystick-compatible devices, the vast majority of gaming applications restrict themselves to joystick-compatible input devices.
Absolute axes on gaming devices should express their physical ranges entirely with non-negative integers. Historically, calibration information has been expressed in unspecified time units, indicating how long it takes the joystick gameport capacitor to charge after a discharge. Consequently, applications have assumed that calibration values are never negative.
Logical ranges, of course, can indeed be negative. It is recommended that the device translate its logical range by the minimum value, thereby making all physical values non-negative. For example, a joystick might report its X-axis with the logical range -512 to +511. A corresponding physical range of 0 to +1023 would retain full resolution while ensuring that the resulting physical values are non-negative.
It is also recommended that the logical range accurately describes the full range of motion of the control and that the center position of the control lie at the midpoint between the minimum and maximum values. When DirectInput first encounters a device, it uses the logical range information as the basis for the default calibration. If a device conforms to this recommendation, the end-user is relieved of the responsibility of calibration, allowing your device to be truly Plug-and-Play.
Applications assume that all axes on a game controller return absolute coordinates rather than relative coordinates. If a device reports its axes as relative, applications which use DirectInput will receive integrated values, but applications which use the old Multimedia functions to access the device will receive non-integrated deltas and will likely not handle the values properly. Furthermore, even applications which use DirectInput typically do not expect to receive unrestricted values (as would result from integration of a relative control).
Beginning with Windows 98 and Windows NT 5.0, DirectInput maps HID usages to its own concept of axis semantics, named X, Y, Z, Rx, Ry, Rz (rotations), and Slider. Again, each application is free to apply arbitrary semantics to each of these axis types.
The following table describes how DirectInput maps HID usages to axis types.
| Usage Page | Usage | DirectInput |
|---|---|---|
| 0x01 (Generic) | 0x30 (X) | X |
| 0x01 (Generic) | 0x31 (Y) | Y |
| 0x01 (Generic) | 0x32 (Z) | Z |
| 0x02 (Simulation) | 0xBA (Rudder) | Z |
| 0x01 (Generic) | 0x33 (RX) | Rx |
| 0x01 (Generic) | 0x34 (RY) | Ry |
| 0x01 (Generic) | 0x35 (RZ) | Rz |
| 0x01 (Generic) | 0x36 (Slider) | Slider |
| 0x01 (Generic) | 0x37 (Dial) | Slider |
| 0x01 (Generic) | 0x38 (Wheel) | Slider |
| 0x02 (Simulation) | 0xBB (Throttle) | Slider |
| 0x01 (Generic) | 0x39 (Hatswitch) | POV |
| 0x09 (Button) | any | Buttons |
| any | any (see below) | Buttons |
DirectInput treats any usage on any usage page with bit size of unity as a button. Furthermore, any usage on the Button page is treated as a button, even if its bit size is greater than unity. Under such conditions, DirectInput treats the button as a "button with intermediate positions". Such a button can report to the application states such as "half-pressed".
DirectInput does not limit the number of usages that can map to each type of axis. Applications designed for DirectInput typically request up to 128 buttons, four POV's, two sliders, and one each of X, Y, Z, Rx, Ry, and Rz.
X and Y axes must report their values as increasing east and south, respectively. This requirement is in agreement with the HID specification.
Hat Switch controls must report a Null value when not pressed. When pressed, the logical minimum value represents north, and increasing logical values represent directions equally spaced clockwise around the compass. For example, the following two tables describe two different types of Hat Switches, one with eight positions and one with four positions.
| Value | 8-direction | 4-direction |
|---|---|---|
| Logical Minimum | 0 | 0 |
| Logical Maximum | 7 | 3 |
| Null value | -1 | -1 |
| North | 0 | 0 |
| Northeast | 1 | N/A |
| East | 2 | 1 |
| Southeast | 3 | N/A |
| South | 4 | 2 |
| Southwest | 5 | N/A |
| West | 6 | 3 |
| Northwest | 7 | N/A |
Devices are strongly recommended not to report logical ranges with higher resolution than physically supported by the device. For example, a device whose Hat Switch supports four compass directions could in principle report itself as if it were an 8-direction Hat Switch. However, devices which do so will mislead applications into believing that the control supports a higher degree of resolution than it actually does. (DirectInput provides a method for applications to query the resolution of a hat switch, and DirectInput relies on the accuracy of the values in the report descriptor to report the resolution accurately.)
DirectInput requires that the Hat Switch reside in its own capability descriptor. Do not combine the Hat Switch capability with capabilities for adjacent usages (Wheel and Counted Buffer).
Although usages not listed in the above table will still be accessible via DirectInput, few game applications will take advantage of their existence.
In Windows 98, the HID-to-legacy mapper (JoyHID.VxD) maps HID usages to the "classical" joystick axes, named X, Y, Z, R, U, and V. Each application is free to apply arbitrary semantics to each of these axes, although the X and Y axes are customarily used for two-dimensional motion control, and the R control is customarily as a rudder. The Z control is often used as a throttle.
(The issue of allowing applications to assign semantics to controls in an intelligent manner is the subject of a separate document.)
The following table describes how JOYHID maps HID usages to "classical" joystick axes, buttons, and POV controllers.
| Usage Page | Usage | JoyHID.VxD |
|---|---|---|
| 0x01 (Generic) | 0x30 (X) | X |
| 0x01 (Generic) | 0x31 (Y) | Y |
| 0x01 (Generic) | 0x32 (Z) | Z |
| 0x02 (Simulation) | 0xBB (Throttle) | Z or U |
| 0x02 (Simulation) | 0xBA (Rudder) | R |
| 0x01 (Generic) | 0x35 (RZ) | R |
| 0x01 (Generic) | 0x36 (Slider) | U |
| 0x01 (Generic) | 0x37 (Dial) | U |
| 0x01 (Generic) | 0x33 (RX) | V |
| 0x09 (Button) | any | Buttons |
| 0x01 (Generic) | 0x39 (Hatswitch) | POV |
If more than one control can map to an axis or button or POV, then the first one on the list is used and the others are ignored. For example, if a joystick has both a slider and a dial, then the slider will be mapped to classical axis U, and the dial will be ignored.
As a special case, a throttle will be mapped to the Z-axis unless the Z-axis has already been claimed by the Z control, in which case it will be mapped to the U-axis. (In such case, the throttle will displace any slider or dial that would otherwise be mapped to the U-axis.)
For buttons, all usages reported on the Button page (0x09) will be reported, but they must be consecutively numbered starting from zero.
The requirements on X-axis, Y-axis, and Hat Switch controls which apply to DirectInput also apply here.
Any usages that do not appear in the above table are ignored by JoyHID.VxD.
Universal Serial Bus HID Usage Tables, Version 1.0, USB Implementers Forum.
DirectX 5.0 DDK , Microsoft Corporation.
DirectX 5.0 SDK , Microsoft Corporation.