JoyFish - Submitting a DirectInput
Device Profile
Uploaded :
DirectInput was introduced in 1995 as part of Microsoft’s DirectX, then proceeded to enjoy a ten-year reign as the library for interacting with joysticks and game controllers in Windows. After XInput’s release in 2005 along with the new XBOX 360 - the aging DirectInput was quietly retired, all devices using it were dumped in a landfill, and nobody ever spoke of or linked with it again.
There’s only one problem with this story… it’s not what actually happened.
As I’m typing this, DirectInput continues to survive a quarter century after its introduction and remains a valuable addition to Windows software. Devices like the DualShock 4, DualSense, and Switch Pro Controller are recognized by it out of the box - no third party drivers or mapping utilities required.
There’s only one problem with this feature… it’s difficult to do well.
DirectInput’s architecture reflects the time it was written in, resulting in a library which was arguably over-engineered as a precaution. This isn’t necessarily a bad thing - as it’s capable of supporting devices like flight sticks which require numerous axes to tilt, sliders to adjust, and buttons to press. But it also means developers need to be mindful of a wide variety of hardware which doesn’t behave consistently. This is actually XInput’s greatest asset, as it was the first time a uniform controller layout was enforced in Windows.
Yet, as mentioned previously, not all users own (or want to use) an XBOX Controller - and still deserve a good experience with DirectInput. So during JoyFish’s implementation I opted to add profile support for both DirectInput and XInput devices. This allows for uniform behavior under the hood and nets cool features such as automapping. It also requires a profile for every input device, of which there’s an entropic quantity.
But that’s why you’re reading this, right?
Let’s add support for your GRAVIS JOYBLASTER or other obscure whatever to JoyFish!
In order for a device to be added to JoyFish it must be from a reputable manufacturer, have a distinct identity, and connect via USB or Bluetooth. So the off-brand USB GAME JOY you grabbed on clearance might not make the cut, nor would any 15-Pin Game Port dinosaurs. But it’s still good to know about these - especially if they don’t work.
This guide walks through the procedure of determining a device’s Identity, Mapping, and Quirks using a Sony DualShock 4 and BupSystem 0.9.6.3. Instructions are also provided for retrieving this information only using the facilities available in Windows. Developers or curious users may find the Quirks section helpful, as this contains select inconsistencies and rude behaviors which may confuse or break software.
JoyFish recognizes input devices through their Product Name and VID:PID, the latter of which takes priority during identification. Both of these are necessary when submitting profiles and are available through select library implementations or from Windows itself.
Device Identification in JoyFish
Programs using JoyFish 0.8.6.1 or later may feature a persistent device history - its contents are displayed by pressing Ctrl+D which summons the dialog below…
All devices are sorted from most to least recently used - and our DualShock 4 is at the top of the list. So its Product Name would be Wireless Controller with a VID:PID of 054C:05C4. Since this controller is already supported, it’s also been recognized as a DualShock 4 in the type column. Unrecognized devices are always tagged as Generic.
This information is usually saved in a *.jdl file (i.e. BupSystem.jdl), and should be submitted along with the device’s Product Name and VID:PID if available.
Device Identification in Windows
Retrieving the Product Name and VID:PID solely through Windows is a bit more involved. The former can be located during the Mapping process, so we’ll cover the latter here.
Versions of Windows released prior to the introduction of the Devices and Printers panel (such as 95, 98, and XP) require some hunting in the Device Manager. A DirectInput controller will show up as a USB Input Device or Bluetooth HID Device (depending upon how it’s connected) and an HID-compliant game controller - both of which feature the same VID:PID. So as long as you can find either you’re all set. In the default view by type mode, both items will appear under the Human Interface Devices category…
Switching to view by connection clarifies the devices’ relationship, allowing us to see which USB Human Interface Device is also a game controller…
View either device’s properties then skip ahead for instructions on locating their VID:PID.
If you’re using a version of Windows which includes the Devices and Printers panel (such as 7, 8, and 10) then your DirectInput controller should reside in it. Locate the controller and view its properties…
Once the new dialog is open, navigate to its Hardware tab - this should reveal both Human Interface Devices associated with the controller…
Viewing either device’s properties will finally net us a VID:PID. Navigate to the Details tab and select the Hardware Ids Property…
One entry in the Value section should contain the VID:PID as *\*_VID&VVVVVVVV_PID&PPPP - of which only the last four digits of the VID are necessary. So the VID:PID would be 054C:05C4, matching our DualShock 4’s previous results in JoyFish. Rad!
Windows includes a joystick calibration and test feature which has been mostly unchanged since its inception. This can be used to identify which junk on the controller corresponds to the various axes, sliders, point of view hats, and buttons in DirectInput. In the before times (so Windows 95, 98, and XP) it lived in the Control Panel under several identities…
Upon the release of Windows 7 it was evicted from the Control Panel and went into hiding. Open the Control Panel and search for “Joystick” to yield a Set up USB game controllers result - there it is! You may also summon it from the Devices and Printers panel by right-clicking your input device and selecting Game controller settings…
Once you’ve managed to find Waldo he’ll summon a small dialog with a list of game controllers…
The Wireless Controller is our DualShock 4, and this label is also its Product Name. Opting to view its properties will bring up another dialog containing a test tab. Proceed to twaddle sticks, pull triggers, and mash buttons until you figure out what’s what…
After significant prodding we’ve finally got a device map…
|
DirectInput |
DualShock 4 |
|
X Axis |
Left Stick - Horizontal |
|
Y Axis |
Left Stick - Vertical |
|
Z Axis |
Right Stick - Horizontal |
|
X Rotation |
L2 Pulled : Maximum |
|
Y Rotation |
R2 Idle : Minimum * Pulled : Maximum |
|
Z Rotation |
Right Stick - Vertical |
|
Point of View Hat |
D-Pad |
|
Button 1 |
■ |
|
Button 2 |
x |
|
Button 3 |
● |
|
Button 4 |
▲ |
|
Button 5 |
L1 |
|
Button 6 |
R1 |
|
Button 7 |
L2 |
|
Button 8 |
R2 |
|
Button 9 |
SHARE |
|
Button 10 |
OPTIONS |
|
Button 11 |
Left Stick - Click |
|
Button 12 |
Right Stick - Click |
|
Button 13 |
PS |
|
Button 14 |
Touchpad - Click |
* L2 and R2 may exhibit inconsistent
idle states over Bluetooth.
Supplying a good photo of the device along its map is ideal. All analog throws including axes and sliders require clear documentation of their idle state and reaction to movement, as these aren’t standardized. One cool feature in our DualShock 4 is that L2 and R2 have both digital and analog readings available through separate buttons and axes. Neat.
Keep in mind - everything in the Game Controllers dialog is one-indexed. Not all software may follow this convention, including JoyFish which is zero-indexed. This may result in discrepancies between how your device’s features are represented in the test tab and how they appear elsewhere (i.e. Button 1 → Button 0, Slider 3 → Slider 2).
With great flexibility comes great inconsistency.
- Axis Centering
/ Idle State
DirectInput devices may feature up to six axes (X / Y / Z Axis and X / Y / Z Rotation). One application for these is an X / Y Axis pairing to read an analog stick, where both axes would center at zero and swing between a negative minimum and positive maximum.
However, that’s only one example - devices can assign and center an axis however they want. This is a problem for unidirectional throws such as analog triggers. Do they idle at the center of an axis or the lower extremity of its range? Lots of software will expect the former but a DualShock 4 will exhibit the latter.
It gets better if we lean into the DualShock 4 example - when connected via Bluetooth its X / Y Rotation (L2 and R2) will also have different idle states if the controller is awake or asleep. This is somewhat expected, as the controller wouldn’t send any data while sleeping and all axes default to zero (center) - but it’s yet another quirk.
- Axis Swing / Range
of Motion
Remember long ago, when joysticks required calibration? They still do.
|
|
Microsoft XBOX 360 Wireless Controller |
|
|
Sony DualShock 4 |
|
|
Nintendo Switch Pro Controller |
|
|
CiRKA NGC USB GamePad |
- Surprise
Movement
If a joystick is connected to a computer but there’s nobody around to twaddle inputs - does it register movement? Sometimes.
Just because an axis is tilting, a slider is adjusting, or a button is being pressed doesn’t mean you’re actually causing it. I’ve only encountered this once in RetroUSB’s NES RetroPort 2.0, whose sliders vibrate intensely with a humdrum NES-004 pad attached.
- Hardware Identity
Crisis
Devices which offer multiple connections (i.e. both Bluetooth and USB) may not use the same Product Name and VID:PID through all of them. 8Bitdo is a frequent offender here - their SN30 Pro+ identifies as 8BitDo SN30 Pro+ / 2DC8:6002 over USB and Bluetooth Wireless Controller / 2DC8:6102 over Bluetooth.
Others may give inconsistent identities over a single connection depending upon how the device is interrogated. RetroUSB’s SNES RetroPort will appear as SNES RetroPort in the Devices and Printers panel but just SNES when queried through DirectInput.
Product Names like "SNES PC Game Pad " (yes - space space space) and weird VID:PIDs such as F000:0003 or 1234:0004 may also show up. Sometimes two unique devices are given the same identity. Mayflash’s SNES/USB and Dreamcast/USB Adapters have identical Product Names and VID:PIDs, but exhibit different quirks. As of writing, this allows us to support neither.
- Nope
It’s possible to attach a controller which appears to be a valid DirectInput device but then… no axis tilting, no button presses, no nothing. That controller is a DualShock 3 without third party drivers or an adapter.