Upgrade to SDL3 #578

[kanthoney]

Upgrade to SDL3 #578

This pretty much works on my machine, so I figure it's close enough to ready to be tested on a wider range of setups.

I haven't been able to resolve the Linux/Wayland splash screen problem where the game screen ends up largely off screen due to Wayland not allowing programatic window placement, so we'll have to continue with the separate splash screen program work around for now.

On Windows, Oolite starts with the window underneath the command prompt I'm launching from - I'm not sure what's causing that.

[mcarans]

PR to fix Ubuntu test and flatpak build: #653

Looks like the linux builds still fail

[mcarans]

A temporary error. The builds all succeed now with a change that was simply to kickstart the build. Windows uses the latest 0.1.3 dependencies created today that use latest GNUstep libraries (which include the PR gnustep/libs-base#614 I made to fix compilation errors that occur if you build GNUstep Base without -Wno-incompatible-pointer-types on Windows).

[mcarans]

I have done very basic testing (ie. install start choices OXP, check I can see the new choices, launch ship) of appimage (including joystick), Flatpak and Windows build (including HDR). All were fine.

[phkb]

I noticed that on my joystick (a basic Logitech F310 gamepad), the right stick axis appear to be swapped. that is, up/down used to be "Stick 1 axis 4" and left/right used to be "Stick 1 axis 5", but now up/down is "Stick 1 axis 5" and left/right is "Stick 1 axis 4". Is this expected behaviour?

[mcarans]

@phkb I asked AI and it said:

Yes, this is completely expected behavior when moving from SDL 1.2 to SDL 3.

While it feels like a bug or a random driver regression, it is actually the result of a massive, intentional overhaul in how SDL handles game controllers that happened between SDL 1.2 and SDL 2.0, and has been further refined in SDL 3.

---

1. The Death of Direct OS Axis Mapping

In SDL 1.2, the library did very little processing on joystick axes. It essentially asked the underlying operating system (like the Linux joystick subsystem or Windows DirectInput) for a list of axes and handed them to you in the exact order the OS reported them.

Because every controller manufacturer wired up their hardware differently, "Axis 4" might be the right stick Y-axis on a Logitech F310, but on a PlayStation or Xbox controller, it could be a trigger or the right stick X-axis.

2. The Introduction of the Gamepad API

Starting in SDL 2 (and modernized in SDL 3), SDL introduced the Gamepad API (formerly SDL_GameController). Instead of forcing developers to manually guess which axis belongs to which stick, SDL built an internal database of hardware mappings.

To ensure consistency across all different types of controllers, SDL established a standardized internal layout based on the standard Xbox/XInput layout:

• Left Stick X -> SDL_GAMEPAD_AXIS_LEFTX (0)
• Left Stick Y -> SDL_GAMEPAD_AXIS_LEFTY (1)
• Right Stick X -> SDL_GAMEPAD_AXIS_RIGHTX (2)
• Right Stick Y -> SDL_GAMEPAD_AXIS_RIGHTY (3)

Because SDL now enforces this uniform layout across Windows, macOS, and Linux, it re-maps the raw OS joystick indexes to fit this predictable structure.

For the Logitech F310 (especially if it is switched to DirectInput/D-mode on the back), the raw OS axis indices for the right stick are inherently flipped compared to standard XInput. SDL 3 actively corrects this so that X always comes before Y in the gamepad mappings, which is why your axis indices swapped places.

---

How to Handle This in SDL 3

• Use the Gamepad API (Recommended): If your game uses standard dual-stick controllers like the F310, you should stop using the raw SDL_Joystick functions and switch to the SDL_Gamepad API. If you open the gamepad and query semantic constants like SDL_GAMEPAD_AXIS_RIGHTX, SDL handles the hardware-specific mapping automatically.
• Stick with Raw Joysticks: If you are building a simulation game that must use raw, unmapped joystick inputs (like flight sticks or steering wheels), you can continue to use SDL_Joystick. However, you will need to implement an in-game input configuration menu so players can manually bind their axes, because SDL 3's underlying driver hints will still cause raw axis indexing to differ from the 15-year-old SDL 1.2 behavior.

Does that fit what you found?

[phkb]

Yeah pretty much! Glad to know it isn't just me, and worth adding a note somewhere so players know what's going on. Probably in the release notes is the best spot.

[phkb]

It looks like Gamma correction has been removed entirely? Is there no equivalent in SDL3?

[mcarans]

@phkb See @AnotherCommander's comment: #578 (comment)
"The gamma option we have in the game options should probably be retired completely. It was added back when we had no idea about proper gamma correction and it more or less did its thing, but now I don't really think we need it anymore and I've seen it does not work on multi monitor setups so its usefulness in effectively non-existent today. If we do want brighter images we can use exposure or light source radiance in the shaders to achieve even better results."

[phkb]

Ah, got it. Thanks!

[phkb]

I've tested SDR/HDR, joystick functions, keyboard functions, non-US keyboards. It all looks good to me.

[oocube]

Testing this version (which is so much easier now that we have them all as prereleases) I find the display be off in a strange way. My feeing is the screen is distorted, and the effect is that my view is slightly to the left instead of where it should be. Here are some screenshots.

[oocube]

Strange. While the first three startups of the game were distorted as above (it took me that long to make the screenshots), I ran it again to see whether in combat you also need to aim elsewhere. And all of a sudden the complete behaviour is normal again. Not sure where the effect came from but I cannot reproduce it.

[mcarans]

Guess we're good to merge then?