X11/Wayland: Support the "Mod3" modifier and add extra keycodes for common Xkb keys

[Kontrabant]

This adds support for the "Mod3" modifier, commonly used as "Level 5 Shift" (or often remapped for custom purposes), as well as adding some extra key codes for common Xkb mappings. Left Tab is found in the default ASCII keymap, Level 5 Shift is found in some international layouts, and the Meta, Hyper, and Multi-key Compose keys are often enabled by tweak tools for customizing the keyboard layout, so it makes sense to add them. These keycodes, which don't correspond to any particular scancodes in the USB spec, are mapped to SDL keycodes by setting bit 30 of the raw keysym value. This is safe, as keysyms are only 29 bits, and this is well out of the range of UTF32 characters.

This also allows for passing through unknown keysyms with the keysym bit set, which allows clients to handle any esoteric Xkb keys they want, of which there are many, without having to explicitly add them as SDL keycodes. This is particularly useful for virtual keyboards, which can have arbitrary layouts with symbols that don't map to physical keys.

Modifier key handling in X and Wayland is also made more robust, and will self-correct more quickly if common modifiers are remapped or toggled via some other means, and don't necessarily correspond to the currently pressed keys.

Fixes #11562
Fixes #11767

[slouken]

You've defined bit 30 as used by platform dependent keysyms but then defined constants in the API that use them, which means that if another platform wants to pass through platform dependent keysyms, they have to avoid those values. It seems like we either want those keysyms in the normal range and available for mapping or we want to add a raw keysym in addition to the raw scancode. However, since we pass through the raw scancode, if somebody wants the keysym, they can grab the X11 connection and do the lookup themselves, right?

[Kontrabant]

if somebody wants the keysym, they can grab the X11 connection and do the lookup themselves, right?

On X11, yes, although it's still not completely trivial. On Wayland it's quite a bit more complicated, as they would have to pull in xkbcommon as a dependency, get the keymap from the backend, and mirror all of the state themselves.

If passing the keysyms as keycodes is a NAK, I think a better solution would be something like a simple, system-specific SDL_GetXkbKeysymFromRawKey() function that clients could use if they want to query the keysym from the raw keycode without mandating excessive work on their end.

For moving these key codes into the normal range, any recommendations for adding a key like left tab, where a scancode entry doesn't really make sense, since it's just a shifted key code for the physical tab key? Maybe keep bit 30 as an "extended" flag for key codes that don't have a corresponding scancode and aren't Unicode values, but use simple incrementing values for the lower bits instead of Xkb keysyms?

[slouken]

If passing the keysyms as keycodes is a NAK, I think a better solution would be something like a simple, system-specific SDL_GetXkbKeysymFromRawKey() function that clients could use if they want to query the keysym from the raw keycode without mandating excessive work on their end.

This seems reasonable to add if someone has a need for it. I wouldn't bother in advance though.

For moving these key codes into the normal range, any recommendations for adding a key like left tab, where a scancode entry doesn't really make sense, since it's just a shifted key code for the physical tab key? Maybe keep bit 30 as an "extended" flag for key codes that don't have a corresponding scancode and aren't Unicode values, but use simple incrementing values for the lower bits instead of Xkb keysyms?

Sure, that sounds good. We currently assume "scancode bit" or unicode in a bunch of places, so everywhere SDLK_SCANCODE_MASK is used would need to be evaluated for correctness.

[Kontrabant]

Added a bit in the migration docs to note the new keycode bitmask, and I think this is good to go.

A perusal of GitHub doesn't turn up anything that blindly presumes that any keycode without the scancode bit set is a Unicode value (some old versions of Quake 3 ports, but they also discard any non-ASCII characters). Still, it seems prudent to filter out these new key codes in sdl2-compat, as anything using SDL2 wouldn't know what to do with them anyways.