Add steering wheel API for SDL3

[IOBYTE]

We need a hardware independent API for steering wheels just like we have for gamepads. The axes for steering, brake, clutch and accelerator and buttons for shifters and force feedback are not standardized for different hardware and different operating systems so a mapping system is needed just like we have for gamepads.

[flibitijibibo]

Might be something for #4464, but I wonder how much research Feral has leftover from their F1 games...

[berarma]

This is really needed. It's a big hole in the SDL API. I came here to open a ticket for this.

I can offer some help. I've implemented an improved Logitech driver, a ffb testing tool, a wheel settings manager tool, and somewhat tried to help other wheel driver projects for Thrustmaster (and 2) and Fanatec wheels. I think the owners of those projects would be willing to help too.

Besides detecting wheels like we currently detect game controllers, the axes and buttons mappings, we should have a function to change the rotation range of the wheel. More things could be added but this would be a good start.

[slouken]

@berarma, I'm open to this for SDL3.

FWIW, I haven't been able to get wheels working in any game on any platform for the last 5 years. I have sitting here the Logitech G923 for Xbox and the PXN V900, and Linux and Windows don't see any input from the G923, and the V900 looks like a standard Xbox or PS3 controller depending on what mode it's in, but games don't see it mapped as a wheel.

Maybe you can help me get wheels working in general before we add an API for them? :)

[berarma]

@berarma, I'm open to this for SDL3.

FWIW, I haven't been able to get wheels working in any game on any platform for the last 5 years. I have sitting here the Logitech G923 for Xbox and the PXN V900, and Linux and Windows don't see any input from the G923, and the V900 looks like a standard Xbox or PS3 controller depending on what mode it's in, but games don't see it mapped as a wheel.

Maybe you can help me get wheels working in general before we add an API for them? :)

I don't know about the PXN V900 and the G923 for XBox isn't supported yet as far as I know.

There was a pending kernel patch for the G923 Xbox (I'd have to check its status again): https://www.spinics.net/lists/linux-input/msg73531.html

The G923 for Xbox uses the HIDPP protocol for FFB, same as the G920. In its initial state after plugging it in, the G920 isn't usable and the G923 might be the same. It has to switch modes internally using usb_modeswitch. This changes its USB product id and puts it in PC mode. Most (if not all) distributions already ship udev rules to do it. But not for the G923. And it would still need a patched HIDPP driver.

Logitech maintains a document with the technical information for their wheels: https://opensource.logitech.com/wiki/Technical_Information/

It should be possible to get the G923 for Xbox working like a G920 with the linked patch above and the information in that document.

The Logitech G923 for PS is similar to the Logitech G29 and it's currently supported by my driver new-lg4ff thanks to the patch provided by a user.

I have a summary of Linux wheel support at: https://github.com/berarma/oversteer/blob/master/README.md

The Logitech G29 is perhaps the most tested and better working wheel, followed by the G25 and G27. The G920 should work well too although there were reports of messages about a full command queue in the driver and laggy FFB in the past.

If the PXN V900 had a PS3 mode that worked like the Logitech wheels then it might be compatible. The USB id should be added to the Logitech driver to recognize the wheel though.

[IOBYTE]

Speed Dreams https://sourceforge.net/projects/speed-dreams/ is a car racing game that uses SDL2 for user input and works fine for me with a Logitech G29 on both Windows and linux. The game currently requires you to manually configure every aspect of the wheel before it can be used. I attempted to add auto configuration to Speed Dreams based on device ID using a mapping scheme like SDL currently has for game controllers. I got that working great on Windows. You could install the game and immediately start playing it without having to configure the wheel. I then tried to play the game on linux with the same configuration settings and it didn't work. Linux uses different axes than Windows for the same control so I would have to add an OS specific mapping for each device just like SDL does for game controllers. That's where I gave up because I would have to duplicate what SDL already has for game controllers for wheels and that's something that should be done in SDL and not the application.

[IOBYTE]

The new API should probably also handle aircraft controls.

[IOBYTE]

Another issue with high end steering wheels is that they consist of multiple USB devices. There will be a USB joystick device for the steering wheel base which is just the steering axis and the force feedback (haptic). There will be another USB joystick device just for the steering wheel which will have buttons, hats, analog clutches and LEDs. There will be another USB joystick device just for the pedals which could also have haptic. There could be another USB joystick device for a shifter which could be an H pattern or sequential. There could be another USB joystick device for the handbrake. There could be another USB joystick device for the dashboard or button box. I believe the type of the joystick device should be more than just SDL_JOYSTICK_TYPE_WHEEL and a joystick could have multiple device types. A wheel like a Logitech G29 would have multiple types because it supports many functions (wheel base, wheel, pedals, shifter) in a single device.

This same problem also exists for aircraft controls.

[expikr]

Seconded, there is a serious market void for a device-agnostic force feedback wheel API. Perhaps it would be good to reach out to the OpenSimWheel community for what they would like to see -- SDL really have the opportunity here to do for simwheels what it had done for Joysticks.

This is something that can be added as an extension after the initial SDL3 release, I presume?

[Kethen]

IMO defining what the most common things are on wheels would be a good first step

It's not quite the easy task tho, considering how different button layouts are across wheels

The new API should probably also handle aircraft controls.

How would you define

SDL/include/SDL3/SDL_gamepad.h

Lines 149 to 179 in 7b3bd8c

	typedef enum SDL_GamepadButton
	{
	SDL_GAMEPAD_BUTTON_INVALID = -1,
	SDL_GAMEPAD_BUTTON_SOUTH, /**< Bottom face button (e.g. Xbox A button) */
	SDL_GAMEPAD_BUTTON_EAST, /**< Right face button (e.g. Xbox B button) */
	SDL_GAMEPAD_BUTTON_WEST, /**< Left face button (e.g. Xbox X button) */
	SDL_GAMEPAD_BUTTON_NORTH, /**< Top face button (e.g. Xbox Y button) */
	SDL_GAMEPAD_BUTTON_BACK,
	SDL_GAMEPAD_BUTTON_GUIDE,
	SDL_GAMEPAD_BUTTON_START,
	SDL_GAMEPAD_BUTTON_LEFT_STICK,
	SDL_GAMEPAD_BUTTON_RIGHT_STICK,
	SDL_GAMEPAD_BUTTON_LEFT_SHOULDER,
	SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER,
	SDL_GAMEPAD_BUTTON_DPAD_UP,
	SDL_GAMEPAD_BUTTON_DPAD_DOWN,
	SDL_GAMEPAD_BUTTON_DPAD_LEFT,
	SDL_GAMEPAD_BUTTON_DPAD_RIGHT,
	SDL_GAMEPAD_BUTTON_MISC1, /**< Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */
	SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /**< Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */
	SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /**< Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */
	SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /**< Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */
	SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /**< Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */
	SDL_GAMEPAD_BUTTON_TOUCHPAD, /**< PS4/PS5 touchpad button */
	SDL_GAMEPAD_BUTTON_MISC2, /**< Additional button */
	SDL_GAMEPAD_BUTTON_MISC3, /**< Additional button */
	SDL_GAMEPAD_BUTTON_MISC4, /**< Additional button */
	SDL_GAMEPAD_BUTTON_MISC5, /**< Additional button */
	SDL_GAMEPAD_BUTTON_MISC6, /**< Additional button */
	SDL_GAMEPAD_BUTTON_COUNT
	} SDL_GamepadButton;

and

SDL/include/SDL3/SDL_gamepad.h

Lines 192 to 203 in 7b3bd8c

	typedef enum SDL_GamepadButtonLabel
	{
	SDL_GAMEPAD_BUTTON_LABEL_UNKNOWN,
	SDL_GAMEPAD_BUTTON_LABEL_A,
	SDL_GAMEPAD_BUTTON_LABEL_B,
	SDL_GAMEPAD_BUTTON_LABEL_X,
	SDL_GAMEPAD_BUTTON_LABEL_Y,
	SDL_GAMEPAD_BUTTON_LABEL_CROSS,
	SDL_GAMEPAD_BUTTON_LABEL_CIRCLE,
	SDL_GAMEPAD_BUTTON_LABEL_SQUARE,
	SDL_GAMEPAD_BUTTON_LABEL_TRIANGLE
	} SDL_GamepadButtonLabel;

, for both steering wheel AND flight control?