Expose the keymap separately from the event keycode

This adds functions to query the keymap:
* SDL_GetCurrentKeymap()
* SDL_GetKeymapKeycode()
* SDL_GetKeymapScancode()
* SDL_ReleaseKeymap()

and these are distinct from the function to query the event keycode associated with a scancode, which might be affected by SDL_HINT_KEYCODE_OPTIONS.

Also added an SDL_bool parameter to SDL_GetKeyName() and SDL_GetKeyFromName() to enable upper case handling of the name.

include/SDL3/SDL_keyboard.h

@@ -185,80 +185,91 @@ extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
 extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
 
 /**
- * Get the key code corresponding to the given scancode according to a default
- * en_US keyboard layout.
+ * A keymap is a mapping from scancode and modifier state to keycode.
  *
- * See SDL_Keycode for details.
+ * \sa SDL_GetCurrentKeymap
+ * \sa SDL_GetKeymapKeycode
+ * \sa SDL_GetKeymapScancode
+ * \sa SDL_ReleaseKeymap
+ */
+typedef struct SDL_Keymap SDL_Keymap;
+
+/**
+ * Get a reference to the current keyboard layout.
  *
- * \param scancode the desired SDL_Scancode to query.
- * \param modstate the modifier state to use when translating the scancode to
- *                 a keycode.
- * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
+ * You should release the reference to the keymap with SDL_ReleaseKeymap() when you're done with it.
+ *
+ * \returns the current keymap, or NULL if the default US-QWERTY keymap is being used.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetKeyName
- * \sa SDL_GetScancodeFromKey
+ * \sa SDL_GetKeymapKeycode
+ * \sa SDL_GetKeymapScancode
+ * \sa SDL_ReleaseKeymap
  */
-extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetDefaultKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate);
+extern SDL_DECLSPEC SDL_Keymap * SDLCALL SDL_GetCurrentKeymap(void);
 
 /**
- * Get the key code corresponding to the given scancode according to the
- * current keyboard layout.
+ * Get the key code corresponding to the given scancode and modifier state using the provided keymap.
  *
- * See SDL_Keycode for details.
+ * Note that this is not the same as the input that would be generated by pressing this key. There are many factors involved, such as dead key composition, input method editors, etc. If you're looking for a way to get text input, you should handle SDL_EVENT_TEXT_INPUT.
  *
- * \param scancode the desired SDL_Scancode to query.
+ * \param keymap the SDL_Keymap to query, or NULL for the default keymap.
+ * \param scancode the SDL_Scancode to translate.
  * \param modstate the modifier state to use when translating the scancode to
  *                 a keycode.
  * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetDefaultKeyFromScancode
- * \sa SDL_GetKeyName
- * \sa SDL_GetScancodeFromKey
+ * \sa SDL_GetCurrentKeymap
+ * \sa SDL_GetKeymapScancode
  */
-extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate);
+extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeymapKeycode(SDL_Keymap *keymap, SDL_Scancode scancode, SDL_Keymod modstate);
 
 /**
- * Get the scancode corresponding to the given key code according to a default
- * en_US keyboard layout.
+ * Get the scancode and modifier state corresponding to the given key code using the provided keymap.
  *
  * Note that there may be multiple scancode+modifier states that can generate
  * this keycode, this will just return the first one found.
  *
- * \param key the desired SDL_Keycode to query.
+ * \param keymap the SDL_Keymap to query, or NULL for the default keymap.
+ * \param keycode the SDL_Keycode to translate.
  * \param modstate a pointer to the modifier state that would be used when the
  *                 scancode generates this key, may be NULL.
  * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetScancodeFromKey
- * \sa SDL_GetScancodeName
+ * \sa SDL_GetCurrentKeymap
+ * \sa SDL_GetKeymapKeycode
  */
-extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetDefaultScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate);
+extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetKeymapScancode(SDL_Keymap *keymap, SDL_Keycode keycode, SDL_Keymod *modstate);
 
 /**
- * Get the scancode corresponding to the given key code according to the
- * current keyboard layout.
- *
- * Note that there may be multiple scancode+modifier states that can generate
- * this keycode, this will just return the first one found.
+ * Release a reference to the current keyboard layout.
  *
- * \param key the desired SDL_Keycode to query.
- * \param modstate a pointer to the modifier state that would be used when the
- *                 scancode generates this key, may be NULL.
- * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
+ * \param keymap the SDL_Keymap to release, may be NULL.
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_GetDefaultScancodeFromKey
- * \sa SDL_GetKeyFromScancode
- * \sa SDL_GetScancodeName
+ * \sa SDL_GetCurrentKeymap
  */
-extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate);
+extern SDL_DECLSPEC void SDLCALL SDL_ReleaseKeymap(SDL_Keymap *keymap);
+
+/**
+ * Get the key code that would be sent with the given scancode in a key event.
+ *
+ * This uses the information from the current keymap along with the options specified in SDL_HINT_KEYCODE_OPTIONS to get the keycode that would be delivered to the application in a key event. This is typically the unmodified version of the key based on the current keyboard layout. For example, the keycode for SDL_SCANCODE_A + SDL_KMOD_SHIFT using the US QWERTY layout would be 'a'.
+ *
+ * \param scancode the SDL_Scancode to translate.
+ * \param modstate the modifier state to use when translating the scancode to
+ *                 a keycode.
+ * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate);
 
 /**
  * Set a human-readable name for a scancode.
@@ -318,12 +329,10 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam
 /**
  * Get a human-readable name for a key.
  *
- * Both lowercase and uppercase alphabetic keycodes have uppercase names, e.g.
- * SDL_Keycode 'a' and 'A' both have the name "A".
- *
  * If the key doesn't have a name, this function returns an empty string ("").
  *
  * \param key the desired SDL_Keycode to query.
+ * \param uppercase SDL_TRUE if the name should be the letter printed on the key on the keyboard, which is usually uppercase, or SDL_FALSE to return the name of the key unchanged.
  * \returns a UTF-8 encoded string of the key name.
  *
  * \since This function is available since SDL 3.0.0.
@@ -332,12 +341,13 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam
  * \sa SDL_GetKeyFromScancode
  * \sa SDL_GetScancodeFromKey
  */
-extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key);
+extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key, SDL_bool uppercase);
 
 /**
  * Get a key code from a human-readable name.
  *
  * \param name the human-readable key name.
+ * \param uppercase SDL_TRUE if the name is the letter printed on the key on the keyboard, which is usually uppercase, and this function should return the unshifted version of the key, or SDL_FALSE to return the key unchanged.
  * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
  *          SDL_GetError() for more information.
  *
@@ -347,7 +357,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key);
  * \sa SDL_GetKeyName
  * \sa SDL_GetScancodeFromName
  */
-extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
+extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name, SDL_bool uppercase);
 
 /**
  * Start accepting Unicode text input events in a window.

src/dynapi/SDL_dynapi.sym

@@ -199,6 +199,7 @@ SDL3_0.0.0 {
     SDL_GetCurrentCameraDriver;
     SDL_GetCurrentDisplayMode;
     SDL_GetCurrentDisplayOrientation;
+    SDL_GetCurrentKeymap;
     SDL_GetCurrentRenderOutputSize;
     SDL_GetCurrentThreadID;
     SDL_GetCurrentTime;
@@ -211,8 +212,6 @@ SDL3_0.0.0 {
     SDL_GetDaysInMonth;
     SDL_GetDefaultAssertionHandler;
     SDL_GetDefaultCursor;
-    SDL_GetDefaultKeyFromScancode;
-    SDL_GetDefaultScancodeFromKey;
     SDL_GetDesktopDisplayMode;
     SDL_GetDirect3D9AdapterIndex;
     SDL_GetDisplayBounds;
@@ -329,6 +328,8 @@ SDL3_0.0.0 {
     SDL_GetKeyboardNameForID;
     SDL_GetKeyboardState;
     SDL_GetKeyboards;
+    SDL_GetKeymapKeycode;
+    SDL_GetKeymapScancode;
     SDL_GetLogOutputFunction;
     SDL_GetLogPriority;
     SDL_GetMasksForPixelFormat;
@@ -413,7 +414,6 @@ SDL3_0.0.0 {
     SDL_GetRendererProperties;
     SDL_GetRevision;
     SDL_GetSIMDAlignment;
-    SDL_GetScancodeFromKey;
     SDL_GetScancodeFromName;
     SDL_GetScancodeName;
     SDL_GetSemaphoreValue;
@@ -644,6 +644,7 @@ SDL3_0.0.0 {
     SDL_RegisterApp;
     SDL_RegisterEvents;
     SDL_ReleaseCameraFrame;
+    SDL_ReleaseKeymap;
     SDL_ReloadGamepadMappings;
     SDL_RemovePath;
     SDL_RemoveStoragePath;

src/dynapi/SDL_dynapi_overrides.h

@@ -224,6 +224,7 @@
 #define SDL_GetCurrentCameraDriver SDL_GetCurrentCameraDriver_REAL
 #define SDL_GetCurrentDisplayMode SDL_GetCurrentDisplayMode_REAL
 #define SDL_GetCurrentDisplayOrientation SDL_GetCurrentDisplayOrientation_REAL
+#define SDL_GetCurrentKeymap SDL_GetCurrentKeymap_REAL
 #define SDL_GetCurrentRenderOutputSize SDL_GetCurrentRenderOutputSize_REAL
 #define SDL_GetCurrentThreadID SDL_GetCurrentThreadID_REAL
 #define SDL_GetCurrentTime SDL_GetCurrentTime_REAL
@@ -236,8 +237,6 @@
 #define SDL_GetDaysInMonth SDL_GetDaysInMonth_REAL
 #define SDL_GetDefaultAssertionHandler SDL_GetDefaultAssertionHandler_REAL
 #define SDL_GetDefaultCursor SDL_GetDefaultCursor_REAL
-#define SDL_GetDefaultKeyFromScancode SDL_GetDefaultKeyFromScancode_REAL
-#define SDL_GetDefaultScancodeFromKey SDL_GetDefaultScancodeFromKey_REAL
 #define SDL_GetDesktopDisplayMode SDL_GetDesktopDisplayMode_REAL
 #define SDL_GetDirect3D9AdapterIndex SDL_GetDirect3D9AdapterIndex_REAL
 #define SDL_GetDisplayBounds SDL_GetDisplayBounds_REAL
@@ -354,6 +353,8 @@
 #define SDL_GetKeyboardNameForID SDL_GetKeyboardNameForID_REAL
 #define SDL_GetKeyboardState SDL_GetKeyboardState_REAL
 #define SDL_GetKeyboards SDL_GetKeyboards_REAL
+#define SDL_GetKeymapKeycode SDL_GetKeymapKeycode_REAL
+#define SDL_GetKeymapScancode SDL_GetKeymapScancode_REAL
 #define SDL_GetLogOutputFunction SDL_GetLogOutputFunction_REAL
 #define SDL_GetLogPriority SDL_GetLogPriority_REAL
 #define SDL_GetMasksForPixelFormat SDL_GetMasksForPixelFormat_REAL
@@ -438,7 +439,6 @@
 #define SDL_GetRendererProperties SDL_GetRendererProperties_REAL
 #define SDL_GetRevision SDL_GetRevision_REAL
 #define SDL_GetSIMDAlignment SDL_GetSIMDAlignment_REAL
-#define SDL_GetScancodeFromKey SDL_GetScancodeFromKey_REAL
 #define SDL_GetScancodeFromName SDL_GetScancodeFromName_REAL
 #define SDL_GetScancodeName SDL_GetScancodeName_REAL
 #define SDL_GetSemaphoreValue SDL_GetSemaphoreValue_REAL
@@ -669,6 +669,7 @@
 #define SDL_RegisterApp SDL_RegisterApp_REAL
 #define SDL_RegisterEvents SDL_RegisterEvents_REAL
 #define SDL_ReleaseCameraFrame SDL_ReleaseCameraFrame_REAL
+#define SDL_ReleaseKeymap SDL_ReleaseKeymap_REAL
 #define SDL_ReloadGamepadMappings SDL_ReloadGamepadMappings_REAL
 #define SDL_RemovePath SDL_RemovePath_REAL
 #define SDL_RemoveStoragePath SDL_RemoveStoragePath_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -244,6 +244,7 @@ SDL_DYNAPI_PROC(const char*,SDL_GetCurrentAudioDriver,(void),(),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetCurrentCameraDriver,(void),(),return)
 SDL_DYNAPI_PROC(const SDL_DisplayMode*,SDL_GetCurrentDisplayMode,(SDL_DisplayID a),(a),return)
 SDL_DYNAPI_PROC(SDL_DisplayOrientation,SDL_GetCurrentDisplayOrientation,(SDL_DisplayID a),(a),return)
+SDL_DYNAPI_PROC(SDL_Keymap*,SDL_GetCurrentKeymap,(void),(),return)
 SDL_DYNAPI_PROC(int,SDL_GetCurrentRenderOutputSize,(SDL_Renderer *a, int *b, int *c),(a,b,c),return)
 SDL_DYNAPI_PROC(SDL_ThreadID,SDL_GetCurrentThreadID,(void),(),return)
 SDL_DYNAPI_PROC(int,SDL_GetCurrentTime,(SDL_Time *a),(a),return)
@@ -256,8 +257,6 @@ SDL_DYNAPI_PROC(int,SDL_GetDayOfYear,(int a, int b, int c),(a,b,c),return)
 SDL_DYNAPI_PROC(int,SDL_GetDaysInMonth,(int a, int b),(a,b),return)
 SDL_DYNAPI_PROC(SDL_AssertionHandler,SDL_GetDefaultAssertionHandler,(void),(),return)
 SDL_DYNAPI_PROC(SDL_Cursor*,SDL_GetDefaultCursor,(void),(),return)
-SDL_DYNAPI_PROC(SDL_Keycode,SDL_GetDefaultKeyFromScancode,(SDL_Scancode a, SDL_Keymod b),(a,b),return)
-SDL_DYNAPI_PROC(SDL_Scancode,SDL_GetDefaultScancodeFromKey,(SDL_Keycode a, SDL_Keymod *b),(a,b),return)
 SDL_DYNAPI_PROC(const SDL_DisplayMode*,SDL_GetDesktopDisplayMode,(SDL_DisplayID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetDirect3D9AdapterIndex,(SDL_DisplayID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetDisplayBounds,(SDL_DisplayID a, SDL_Rect *b),(a,b),return)
@@ -367,13 +366,15 @@ SDL_DYNAPI_PROC(SDL_JoystickType,SDL_GetJoystickTypeForID,(SDL_JoystickID a),(a)
 SDL_DYNAPI_PROC(Uint16,SDL_GetJoystickVendor,(SDL_Joystick *a),(a),return)
 SDL_DYNAPI_PROC(Uint16,SDL_GetJoystickVendorForID,(SDL_JoystickID a),(a),return)
 SDL_DYNAPI_PROC(SDL_JoystickID*,SDL_GetJoysticks,(int *a),(a),return)
-SDL_DYNAPI_PROC(SDL_Keycode,SDL_GetKeyFromName,(const char *a),(a),return)
+SDL_DYNAPI_PROC(SDL_Keycode,SDL_GetKeyFromName,(const char *a, SDL_bool b),(a, b),return)
 SDL_DYNAPI_PROC(SDL_Keycode,SDL_GetKeyFromScancode,(SDL_Scancode a, SDL_Keymod b),(a,b),return)
-SDL_DYNAPI_PROC(const char*,SDL_GetKeyName,(SDL_Keycode a),(a),return)
+SDL_DYNAPI_PROC(const char*,SDL_GetKeyName,(SDL_Keycode a, SDL_bool b),(a,b),return)
 SDL_DYNAPI_PROC(SDL_Window*,SDL_GetKeyboardFocus,(void),(),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetKeyboardNameForID,(SDL_KeyboardID a),(a),return)
 SDL_DYNAPI_PROC(const Uint8*,SDL_GetKeyboardState,(int *a),(a),return)
 SDL_DYNAPI_PROC(SDL_KeyboardID*,SDL_GetKeyboards,(int *a),(a),return)
+SDL_DYNAPI_PROC(SDL_Keycode,SDL_GetKeymapKeycode,(SDL_Keymap *a, SDL_Scancode b, SDL_Keymod c),(a,b,c),return)
+SDL_DYNAPI_PROC(SDL_Scancode,SDL_GetKeymapScancode,(SDL_Keymap *a, SDL_Keycode b, SDL_Keymod *c),(a,b,c),return)
 SDL_DYNAPI_PROC(void,SDL_GetLogOutputFunction,(SDL_LogOutputFunction *a, void **b),(a,b),)
 SDL_DYNAPI_PROC(SDL_LogPriority,SDL_GetLogPriority,(int a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetMasksForPixelFormat,(SDL_PixelFormat a, int *b, Uint32 *c, Uint32 *d, Uint32 *e, Uint32 *f),(a,b,c,d,e,f),return)
@@ -458,7 +459,6 @@ SDL_DYNAPI_PROC(const char *,SDL_GetRendererName,(SDL_Renderer *a),(a),return)
 SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetRendererProperties,(SDL_Renderer *a),(a),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetRevision,(void),(),return)
 SDL_DYNAPI_PROC(size_t,SDL_GetSIMDAlignment,(void),(),return)
-SDL_DYNAPI_PROC(SDL_Scancode,SDL_GetScancodeFromKey,(SDL_Keycode a, SDL_Keymod *b),(a,b),return)
 SDL_DYNAPI_PROC(SDL_Scancode,SDL_GetScancodeFromName,(const char *a),(a),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetScancodeName,(SDL_Scancode a),(a),return)
 SDL_DYNAPI_PROC(Uint32,SDL_GetSemaphoreValue,(SDL_Semaphore *a),(a),return)
@@ -680,6 +680,7 @@ SDL_DYNAPI_PROC(SDL_bool,SDL_ReadU8,(SDL_IOStream *a, Uint8 *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_RegisterApp,(const char *a, Uint32 b, void *c),(a,b,c),return)
 SDL_DYNAPI_PROC(Uint32,SDL_RegisterEvents,(int a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_ReleaseCameraFrame,(SDL_Camera *a, SDL_Surface *b),(a,b),return)
+SDL_DYNAPI_PROC(void,SDL_ReleaseKeymap,(SDL_Keymap *a),(a),)
 SDL_DYNAPI_PROC(int,SDL_ReloadGamepadMappings,(void),(),return)
 SDL_DYNAPI_PROC(int,SDL_RemovePath,(const char *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_RemoveStoragePath,(SDL_Storage *a, const char *b),(a,b),return)

src/events/SDL_keyboard.c

@@ -225,12 +225,19 @@ void SDL_ResetKeyboard(void)
     }
 }
 
+SDL_Keymap *SDL_GetCurrentKeymap(void)
+{
+    SDL_Keyboard *keyboard = &SDL_keyboard;
+
+    return keyboard->keymap;
+}
+
 void SDL_SetKeymap(SDL_Keymap *keymap, SDL_bool send_event)
 {
     SDL_Keyboard *keyboard = &SDL_keyboard;
 
     if (keyboard->keymap) {
-        SDL_DestroyKeymap(keyboard->keymap);
+        SDL_ReleaseKeymap(keyboard->keymap);
     }
 
     keyboard->keymap = keymap;
@@ -424,8 +431,9 @@ static SDL_Keycode SDL_ConvertNumpadKeycode(SDL_Keycode keycode, SDL_bool numloc
     }
 }
 
-static SDL_Keycode SDL_GetEventKeycode(SDL_Keyboard *keyboard, SDL_Scancode scancode, SDL_Keymod modstate)
+SDL_Keycode SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate)
 {
+    SDL_Keyboard *keyboard = &SDL_keyboard;
     SDL_bool numlock = (modstate & SDL_KMOD_NUM) != 0;
     SDL_Keycode keycode;
 
@@ -434,7 +442,7 @@ static SDL_Keycode SDL_GetEventKeycode(SDL_Keyboard *keyboard, SDL_Scancode scan
 
     if ((keyboard->keycode_options & KEYCODE_OPTION_LATIN_LETTERS) &&
          keyboard->non_latin_letters) {
-        keycode = SDL_GetDefaultKeyFromScancode(scancode, modstate);
+        keycode = SDL_GetKeymapKeycode(NULL, scancode, modstate);
     } else {
         if ((keyboard->keycode_options & KEYCODE_OPTION_FRENCH_NUMBERS) &&
             keyboard->french_numbers &&
@@ -443,7 +451,7 @@ static SDL_Keycode SDL_GetEventKeycode(SDL_Keyboard *keyboard, SDL_Scancode scan
             modstate |= SDL_KMOD_SHIFT;
         }
 
-        keycode = SDL_GetKeyFromScancode(scancode, modstate);
+        keycode = SDL_GetKeymapKeycode(keyboard->keymap, scancode, modstate);
     }
 
     if (keyboard->keycode_options & KEYCODE_OPTION_HIDE_NUMPAD) {
@@ -501,7 +509,7 @@ static int SDL_SendKeyboardKeyInternal(Uint64 timestamp, Uint32 flags, SDL_Keybo
         /* Update internal keyboard state */
         keyboard->keystate[scancode] = state;
 
-        keycode = SDL_GetEventKeycode(keyboard, scancode, keyboard->modstate);
+        keycode = SDL_GetKeyFromScancode(scancode, keyboard->modstate);
 
     } else if (rawcode == 0) {
         /* Nothing to do! */
@@ -607,8 +615,9 @@ static int SDL_SendKeyboardKeyInternal(Uint64 timestamp, Uint32 flags, SDL_Keybo
 
 int SDL_SendKeyboardUnicodeKey(Uint64 timestamp, Uint32 ch)
 {
+    SDL_Keyboard *keyboard = &SDL_keyboard;
     SDL_Keymod modstate = SDL_KMOD_NONE;
-    SDL_Scancode scancode = SDL_GetScancodeFromKey(ch, &modstate);
+    SDL_Scancode scancode = SDL_GetKeymapScancode(keyboard->keymap, ch, &modstate);
 
     // Make sure we have this keycode in our keymap
     if (scancode == SDL_SCANCODE_UNKNOWN && ch < SDLK_SCANCODE_MASK) {
@@ -836,7 +845,7 @@ void SDL_QuitKeyboard(void)
     SDL_keyboards = NULL;
 
     if (SDL_keyboard.keymap) {
-        SDL_DestroyKeymap(SDL_keyboard.keymap);
+        SDL_ReleaseKeymap(SDL_keyboard.keymap);
         SDL_keyboard.keymap = NULL;
     }
 
@@ -879,13 +888,3 @@ void SDL_ToggleModState(const SDL_Keymod modstate, const SDL_bool toggle)
     }
 }
 
-SDL_Keycode SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate)
-{
-    return SDL_GetKeymapKeycode(SDL_keyboard.keymap, scancode, modstate);
-}
-
-SDL_Scancode SDL_GetScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate)
-{
-    return SDL_GetKeymapScancode(SDL_keyboard.keymap, key, modstate);
-}
-

src/events/SDL_keymap.c

@@ -26,10 +26,14 @@
 
 struct SDL_Keymap
 {
+    int refcount;
     SDL_HashTable *scancode_to_keycode;
     SDL_HashTable *keycode_to_scancode;
 };
 
+static SDL_Keycode SDL_GetDefaultKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate);
+static SDL_Scancode SDL_GetDefaultScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate);
+
 SDL_Keymap *SDL_CreateKeymap(void)
 {
     SDL_Keymap *keymap = (SDL_Keymap *)SDL_malloc(sizeof(*keymap));
@@ -37,15 +41,23 @@ SDL_Keymap *SDL_CreateKeymap(void)
         return NULL;
     }
 
+    keymap->refcount = 1;
     keymap->scancode_to_keycode = SDL_CreateHashTable(NULL, 64, SDL_HashID, SDL_KeyMatchID, NULL, SDL_FALSE);
     keymap->keycode_to_scancode = SDL_CreateHashTable(NULL, 64, SDL_HashID, SDL_KeyMatchID, NULL, SDL_FALSE);
     if (!keymap->scancode_to_keycode || !keymap->keycode_to_scancode) {
-        SDL_DestroyKeymap(keymap);
+        SDL_ReleaseKeymap(keymap);
         return NULL;
     }
     return keymap;
 }
 
+void SDL_AcquireKeymap(SDL_Keymap *keymap)
+{
+    if (keymap) {
+        ++keymap->refcount;
+    }
+}
+
 static SDL_Keymod NormalizeModifierStateForKeymap(SDL_Keymod modstate)
 {
     // The modifiers that affect the keymap are: SHIFT, CAPS, ALT, and MODE
@@ -116,21 +128,20 @@ SDL_Scancode SDL_GetKeymapScancode(SDL_Keymap *keymap, SDL_Keycode keycode, SDL_
     return scancode;
 }
 
-void SDL_ResetKeymap(SDL_Keymap *keymap)
+void SDL_ReleaseKeymap(SDL_Keymap *keymap)
 {
-    if (keymap) {
-        SDL_EmptyHashTable(keymap->scancode_to_keycode);
-        SDL_EmptyHashTable(keymap->keycode_to_scancode);
+    if (!keymap) {
+        return;
     }
-}
 
-void SDL_DestroyKeymap(SDL_Keymap *keymap)
-{
-    if (keymap) {
-        SDL_DestroyHashTable(keymap->scancode_to_keycode);
-        SDL_DestroyHashTable(keymap->keycode_to_scancode);
-        SDL_free(keymap);
+    --keymap->refcount;
+    if (keymap->refcount != 0) {
+        return;
     }
+
+    SDL_DestroyHashTable(keymap->scancode_to_keycode);
+    SDL_DestroyHashTable(keymap->keycode_to_scancode);
+    SDL_free(keymap);
 }
 
 static const SDL_Keycode normal_default_symbols[] = {
@@ -193,7 +204,7 @@ static const SDL_Keycode shifted_default_symbols[] = {
     SDLK_QUESTION
 };
 
-SDL_Keycode SDL_GetDefaultKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate)
+static SDL_Keycode SDL_GetDefaultKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate)
 {
     if (((int)scancode) < SDL_SCANCODE_UNKNOWN || scancode >= SDL_NUM_SCANCODES) {
         SDL_InvalidParamError("scancode");
@@ -594,7 +605,7 @@ SDL_Keycode SDL_GetDefaultKeyFromScancode(SDL_Scancode scancode, SDL_Keymod mods
     }
 }
 
-SDL_Scancode SDL_GetDefaultScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate)
+static SDL_Scancode SDL_GetDefaultScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate)
 {
     if (modstate) {
         *modstate = SDL_KMOD_NONE;
@@ -984,7 +995,7 @@ SDL_Scancode SDL_GetScancodeFromName(const char *name)
     return SDL_SCANCODE_UNKNOWN;
 }
 
-const char *SDL_GetKeyName(SDL_Keycode key)
+const char *SDL_GetKeyName(SDL_Keycode key, SDL_bool uppercase)
 {
     char name[8];
     char *end;
@@ -1007,23 +1018,28 @@ const char *SDL_GetKeyName(SDL_Keycode key)
     case SDLK_DELETE:
         return SDL_GetScancodeName(SDL_SCANCODE_DELETE);
     default:
-        // SDL_Keycode is defined as the unshifted key on the keyboard,
-        // but the key name is defined as the letter printed on that key,
-        // which is usually the shifted capital letter.
-        if (key >= 'a' && key <= 'z') {
-            key = 'A' + (key - 'a');
-        } else if (key > 0x7F) {
-            SDL_Scancode scancode = SDL_GetScancodeFromKey(key, SDL_KMOD_NONE);
-            if (scancode != SDL_SCANCODE_UNKNOWN) {
-                if (key >= 0x0E00 && key <= 0x0E7F) {
-                    // Thai keyboards are QWERTY plus Thai characters, so let's use the ASCII key names
-                    return SDL_GetScancodeName(scancode);
-                }
+        if (uppercase) {
+            // SDL_Keycode is defined as the unshifted key on the keyboard,
+            // but the key name is defined as the letter printed on that key,
+            // which is usually the shifted capital letter.
+            if (key >= 'a' && key <= 'z') {
+                key = 'A' + (key - 'a');
+            } else if (key > 0x7F) {
+                SDL_Keymap *keymap = SDL_GetCurrentKeymap();
+                SDL_Scancode scancode = SDL_GetKeymapScancode(keymap, key, NULL);
+                if (scancode != SDL_SCANCODE_UNKNOWN) {
+                    if (key >= 0x0E00 && key <= 0x0E7F) {
+                        // Thai keyboards are QWERTY plus Thai characters, so let's use the ASCII key names
+                        SDL_ReleaseKeymap(keymap);
+                        return SDL_GetScancodeName(scancode);
+                    }
 
-                SDL_Keycode capital = SDL_GetKeyFromScancode(scancode, SDL_KMOD_SHIFT);
-                if (capital > 0x7F || (capital >= 'A' && capital <= 'Z')) {
-                    key = capital;
+                    SDL_Keycode capital = SDL_GetKeymapKeycode(keymap, scancode, SDL_KMOD_SHIFT);
+                    if (capital > 0x7F || (capital >= 'A' && capital <= 'Z')) {
+                        key = capital;
+                    }
                 }
+                SDL_ReleaseKeymap(keymap);
             }
         }
 
@@ -1033,7 +1049,7 @@ const char *SDL_GetKeyName(SDL_Keycode key)
     }
 }
 
-SDL_Keycode SDL_GetKeyFromName(const char *name)
+SDL_Keycode SDL_GetKeyFromName(const char *name, SDL_bool uppercase)
 {
     SDL_Keycode key;
 
@@ -1051,35 +1067,53 @@ SDL_Keycode SDL_GetKeyFromName(const char *name)
             key |= (Uint16)(name[++i] & 0x3F) << 12;
             key |= (Uint16)(name[++i] & 0x3F) << 6;
             key |= (Uint16)(name[++i] & 0x3F);
-            return key;
+        } else {
+            key = SDLK_UNKNOWN;
         }
-        return SDLK_UNKNOWN;
     } else if (key >= 0xE0) {
         if (SDL_strlen(name) == 3) {
             int i = 0;
             key = (Uint16)(name[i] & 0x0F) << 12;
             key |= (Uint16)(name[++i] & 0x3F) << 6;
             key |= (Uint16)(name[++i] & 0x3F);
-            return key;
+        } else {
+            key = SDLK_UNKNOWN;
         }
-        return SDLK_UNKNOWN;
     } else if (key >= 0xC0) {
         if (SDL_strlen(name) == 2) {
             int i = 0;
             key = (Uint16)(name[i] & 0x1F) << 6;
             key |= (Uint16)(name[++i] & 0x3F);
-            return key;
+        } else {
+            key = SDLK_UNKNOWN;
         }
         return SDLK_UNKNOWN;
     } else {
-        if (SDL_strlen(name) == 1) {
+        if (SDL_strlen(name) != 1) {
+            key = SDLK_UNKNOWN;
+        }
+    }
+
+    if (key != SDLK_UNKNOWN) {
+        if (uppercase) {
+            // SDL_Keycode is defined as the unshifted key on the keyboard,
+            // but the key name is defined as the letter printed on that key,
+            // which is usually the shifted capital letter.
             if (key >= 'A' && key <= 'Z') {
-                key += 32;
+                key = 'a' + (key - 'A');
+            } else if (key > 0x7F) {
+                SDL_Keymap *keymap = SDL_GetCurrentKeymap();
+                SDL_Keymod modstate;
+                SDL_Scancode scancode = SDL_GetKeymapScancode(keymap, key, &modstate);
+                if (scancode != SDL_SCANCODE_UNKNOWN && (modstate & SDL_KMOD_SHIFT)) {
+                    key = SDL_GetKeymapKeycode(keymap, scancode, SDL_KMOD_NONE);
+                }
+                SDL_ReleaseKeymap(keymap);
             }
-            return key;
         }
-
-        /* Get the scancode for this name, and the associated keycode */
-        return SDL_GetKeyFromScancode(SDL_GetScancodeFromName(name), SDL_KMOD_NONE);
+        return key;
     }
+
+    /* Get the scancode for this name, and the associated keycode */
+    return SDL_GetKeyFromScancode(SDL_GetScancodeFromName(name), SDL_KMOD_NONE);
 }

src/events/SDL_keymap_c.h

@@ -25,13 +25,11 @@
 
 #include "../SDL_hashtable.h"
 
-typedef struct SDL_Keymap SDL_Keymap;
-
 SDL_Keymap *SDL_CreateKeymap(void);
+void SDL_AcquireKeymap(SDL_Keymap *keymap);
 void SDL_SetKeymapEntry(SDL_Keymap *keymap, SDL_Scancode scancode, SDL_Keymod modstate, SDL_Keycode keycode);
 SDL_Keycode SDL_GetKeymapKeycode(SDL_Keymap *keymap, SDL_Scancode scancode, SDL_Keymod modstate);
 SDL_Scancode SDL_GetKeymapScancode(SDL_Keymap *keymap, SDL_Keycode keycode, SDL_Keymod *modstate);
-void SDL_ResetKeymap(SDL_Keymap *keymap);
-void SDL_DestroyKeymap(SDL_Keymap *keymap);
+void SDL_ReleaseKeymap(SDL_Keymap *keymap);
 
 #endif /* SDL_keymap_c_h_ */

src/test/SDL_test_common.c

@@ -1717,7 +1717,7 @@ void SDLTest_PrintEvent(const SDL_Event *event)
                 event->key.windowID,
                 event->key.scancode,
                 SDL_GetScancodeName(event->key.scancode),
-                event->key.key, SDL_GetKeyName(event->key.key),
+                event->key.key, SDL_GetKeyName(event->key.key, SDL_TRUE),
                 modstr);
         break;
     }

src/video/cocoa/SDL_cocoakeyboard.m

@@ -326,7 +326,7 @@ static void UpdateKeymap(SDL_CocoaVideoData *data, SDL_bool send_event)
             SDL_Scancode scancode = darwin_scancode_table[i];
             if (scancode == SDL_SCANCODE_UNKNOWN ||
                 scancode == SDL_SCANCODE_DELETE ||
-                (SDL_GetDefaultKeyFromScancode(scancode, SDL_KMOD_NONE) & SDLK_SCANCODE_MASK)) {
+                (SDL_GetKeymapKeycode(NULL, scancode, SDL_KMOD_NONE) & SDLK_SCANCODE_MASK)) {
                 continue;
             }
 

src/video/wayland/SDL_waylandevents.c

@@ -1124,7 +1124,7 @@ static void Wayland_keymap_iter(struct xkb_keymap *keymap, xkb_keycode_t key, vo
 
             /* Note: The default SDL scancode table sets this to right alt instead of AltGr/Mode, so handle it separately. */
             if (syms[0] != XKB_KEY_ISO_Level3_Shift) {
-                keycode = SDL_GetDefaultKeyFromScancode(sc, sdlKeymap->modstate);
+                keycode = SDL_GetKeymapKeycode(NULL, sc, sdlKeymap->modstate);
             } else {
                 keycode = SDLK_MODE;
             }
@@ -1185,7 +1185,7 @@ static void Wayland_UpdateKeymap(struct SDL_WaylandInput *input)
         keymap.state = WAYLAND_xkb_state_new(input->xkb.keymap);
         if (!keymap.state) {
             SDL_SetError("failed to create XKB state");
-            SDL_DestroyKeymap(keymap.keymap);
+            SDL_ReleaseKeymap(keymap.keymap);
             return;
         }
 

src/video/windows/SDL_windowskeyboard.c

@@ -107,7 +107,7 @@ void WIN_UpdateKeymap(SDL_bool send_event)
             scancode = windows_scancode_table[i];
             if (scancode == SDL_SCANCODE_UNKNOWN ||
                 scancode == SDL_SCANCODE_DELETE ||
-                (SDL_GetDefaultKeyFromScancode(scancode, SDL_KMOD_NONE) & SDLK_SCANCODE_MASK)) {
+                (SDL_GetKeymapKeycode(NULL, scancode, SDL_KMOD_NONE) & SDLK_SCANCODE_MASK)) {
 
                 /* The Colemak mapping swaps Backspace and CapsLock */
                 if (mods[m] == SDL_KMOD_NONE &&

src/video/x11/SDL_x11keyboard.c

@@ -280,7 +280,7 @@ int X11_InitKeyboard(SDL_VideoDevice *_this)
             if (scancode == data->key_layout[i]) {
                 continue;
             }
-            if ((SDL_GetDefaultKeyFromScancode(scancode, SDL_KMOD_NONE) & SDLK_SCANCODE_MASK) && X11_ScancodeIsRemappable(scancode)) {
+            if ((SDL_GetKeymapKeycode(NULL, scancode, SDL_KMOD_NONE) & SDLK_SCANCODE_MASK) && X11_ScancodeIsRemappable(scancode)) {
                 /* Not a character key and the scancode is safe to remap */
 #ifdef DEBUG_KEYBOARD
                 SDL_Log("Changing scancode, was %d (%s), now %d (%s)\n", data->key_layout[i], SDL_GetScancodeName(data->key_layout[i]), scancode, SDL_GetScancodeName(scancode));
@@ -382,7 +382,7 @@ void X11_UpdateKeymap(SDL_VideoDevice *_this, SDL_bool send_event)
 
             if (!keycode) {
                 SDL_Scancode keyScancode = SDL_GetScancodeFromKeySym(keysym, (KeyCode)i);
-                keycode = SDL_GetDefaultKeyFromScancode(keyScancode, keymod_masks[m].sdl_mask);
+                keycode = SDL_GetKeymapKeycode(NULL, keyScancode, keymod_masks[m].sdl_mask);
             }
             SDL_SetKeymapEntry(keymap, scancode, keymod_masks[m].sdl_mask, keycode);
         }

test/checkkeys.c

@@ -189,12 +189,13 @@ static void PrintKeymap(void)
         (SDL_KMOD_MODE | SDL_KMOD_SHIFT | SDL_KMOD_CAPS)
     };
     int i, m;
+    SDL_Keymap *keymap = SDL_GetCurrentKeymap();
 
     SDL_Log("Differences from the default keymap:\n");
     for (m = 0; m < SDL_arraysize(mods); ++m) {
         for (i = 0; i < SDL_NUM_SCANCODES; ++i) {
-            SDL_Keycode key = SDL_GetKeyFromScancode((SDL_Scancode)i, mods[m]);
-            SDL_Keycode default_key = SDL_GetDefaultKeyFromScancode((SDL_Scancode)i, mods[m]);
+            SDL_Keycode key = SDL_GetKeymapKeycode(keymap, (SDL_Scancode)i, mods[m]);
+            SDL_Keycode default_key = SDL_GetKeymapKeycode(NULL, (SDL_Scancode)i, mods[m]);
             if (key != default_key) {
                 char message[512];
                 char *spot;
@@ -203,13 +204,14 @@ static void PrintKeymap(void)
                 spot = message;
                 left = sizeof(message);
 
-                print_string(&spot, &left, "Scancode %s", SDL_GetScancodeName((SDL_Scancode)i));
+                print_string(&spot, &left, "Scancode %s (%d)", SDL_GetScancodeName((SDL_Scancode)i), i);
                 print_modifiers(&spot, &left, mods[m]);
-                print_string(&spot, &left, ": %s 0x%x (default: %s 0x%x)", SDL_GetKeyName(key), key, SDL_GetKeyName(default_key), default_key);
+                print_string(&spot, &left, ": %s 0x%x (default: %s 0x%x)", SDL_GetKeyName(key, SDL_FALSE), key, SDL_GetKeyName(default_key, SDL_FALSE), default_key);
                 SDL_Log("%s", message);
             }
         }
     }
+    SDL_ReleaseKeymap(keymap);
 }
 
 static void PrintModifierState(void)
@@ -242,7 +244,7 @@ static void PrintKey(SDL_KeyboardEvent *event)
                      event->raw,
                      event->scancode,
                      event->scancode == SDL_SCANCODE_UNKNOWN ? "UNKNOWN" : SDL_GetScancodeName(event->scancode),
-                     event->key, SDL_GetKeyName(event->key));
+                     event->key, SDL_GetKeyName(event->key, SDL_TRUE));
     } else {
         print_string(&spot, &left,
                      "Unknown Key (raw 0x%.2x, scancode %d = %s) %s ",

test/testautomation_keyboard.c

@@ -59,39 +59,43 @@ static int keyboard_getKeyFromName(void *arg)
     SDL_Keycode result;
 
     /* Case where Key is known, 1 character input */
-    result = SDL_GetKeyFromName("A");
-    SDLTest_AssertPass("Call to SDL_GetKeyFromName(known/single)");
-    SDLTest_AssertCheck(result == SDLK_A, "Verify result from call, expected: %d, got: %" SDL_PRIs32, SDLK_A, result);
+    result = SDL_GetKeyFromName("A", SDL_TRUE);
+    SDLTest_AssertPass("Call to SDL_GetKeyFromName('A', SDL_TRUE)");
+    SDLTest_AssertCheck(result == SDLK_A, "Verify result from call, expected: %d, got: %" SDL_PRIu32, SDLK_A, result);
+
+    result = SDL_GetKeyFromName("A", SDL_FALSE);
+    SDLTest_AssertPass("Call to SDL_GetKeyFromName('A', SDL_FALSE)");
+    SDLTest_AssertCheck(result == 'A', "Verify result from call, expected: %d, got: %" SDL_PRIu32, 'A', result);
 
     /* Case where Key is known, 2 character input */
-    result = SDL_GetKeyFromName("F1");
+    result = SDL_GetKeyFromName("F1", SDL_TRUE);
     SDLTest_AssertPass("Call to SDL_GetKeyFromName(known/double)");
-    SDLTest_AssertCheck(result == SDLK_F1, "Verify result from call, expected: %d, got: %" SDL_PRIs32, SDLK_F1, result);
+    SDLTest_AssertCheck(result == SDLK_F1, "Verify result from call, expected: %d, got: %" SDL_PRIu32, SDLK_F1, result);
 
     /* Case where Key is known, 3 character input */
-    result = SDL_GetKeyFromName("End");
+    result = SDL_GetKeyFromName("End", SDL_TRUE);
     SDLTest_AssertPass("Call to SDL_GetKeyFromName(known/triple)");
-    SDLTest_AssertCheck(result == SDLK_END, "Verify result from call, expected: %d, got: %" SDL_PRIs32, SDLK_END, result);
+    SDLTest_AssertCheck(result == SDLK_END, "Verify result from call, expected: %d, got: %" SDL_PRIu32, SDLK_END, result);
 
     /* Case where Key is known, 4 character input */
-    result = SDL_GetKeyFromName("Find");
+    result = SDL_GetKeyFromName("Find", SDL_TRUE);
     SDLTest_AssertPass("Call to SDL_GetKeyFromName(known/quad)");
-    SDLTest_AssertCheck(result == SDLK_FIND, "Verify result from call, expected: %d, got: %" SDL_PRIs32, SDLK_FIND, result);
+    SDLTest_AssertCheck(result == SDLK_FIND, "Verify result from call, expected: %d, got: %" SDL_PRIu32, SDLK_FIND, result);
 
     /* Case where Key is known, multiple character input */
-    result = SDL_GetKeyFromName("MediaStop");
+    result = SDL_GetKeyFromName("MediaStop", SDL_TRUE);
     SDLTest_AssertPass("Call to SDL_GetKeyFromName(known/multi)");
-    SDLTest_AssertCheck(result == SDLK_MEDIA_STOP, "Verify result from call, expected: %d, got: %" SDL_PRIs32, SDLK_MEDIA_STOP, result);
+    SDLTest_AssertCheck(result == SDLK_MEDIA_STOP, "Verify result from call, expected: %d, got: %" SDL_PRIu32, SDLK_MEDIA_STOP, result);
 
     /* Case where Key is unknown */
-    result = SDL_GetKeyFromName("NotThere");
+    result = SDL_GetKeyFromName("NotThere", SDL_TRUE);
     SDLTest_AssertPass("Call to SDL_GetKeyFromName(unknown)");
-    SDLTest_AssertCheck(result == SDLK_UNKNOWN, "Verify result from call is UNKNOWN, expected: %d, got: %" SDL_PRIs32, SDLK_UNKNOWN, result);
+    SDLTest_AssertCheck(result == SDLK_UNKNOWN, "Verify result from call is UNKNOWN, expected: %d, got: %" SDL_PRIu32, SDLK_UNKNOWN, result);
 
     /* Case where input is NULL/invalid */
-    result = SDL_GetKeyFromName(NULL);
+    result = SDL_GetKeyFromName(NULL, SDL_TRUE);
     SDLTest_AssertPass("Call to SDL_GetKeyFromName(NULL)");
-    SDLTest_AssertCheck(result == SDLK_UNKNOWN, "Verify result from call is UNKNOWN, expected: %d, got: %" SDL_PRIs32, SDLK_UNKNOWN, result);
+    SDLTest_AssertCheck(result == SDLK_UNKNOWN, "Verify result from call is UNKNOWN, expected: %d, got: %" SDL_PRIu32, SDLK_UNKNOWN, result);
 
     return TEST_COMPLETED;
 }
@@ -126,12 +130,12 @@ static int keyboard_getKeyFromScancode(void *arg)
     /* Case where input is valid */
     result = SDL_GetKeyFromScancode(SDL_SCANCODE_A, SDL_KMOD_NONE);
     SDLTest_AssertPass("Call to SDL_GetKeyFromScancode(valid)");
-    SDLTest_AssertCheck(result == SDLK_A, "Verify result from call, expected: %d, got: %" SDL_PRIs32, SDLK_A, result);
+    SDLTest_AssertCheck(result == SDLK_A, "Verify result from call, expected: %d, got: %" SDL_PRIu32, SDLK_A, result);
 
     /* Case where input is zero */
     result = SDL_GetKeyFromScancode(SDL_SCANCODE_UNKNOWN, SDL_KMOD_NONE);
     SDLTest_AssertPass("Call to SDL_GetKeyFromScancode(0)");
-    SDLTest_AssertCheck(result == SDLK_UNKNOWN, "Verify result from call is UNKNOWN, expected: %d, got: %" SDL_PRIs32, SDLK_UNKNOWN, result);
+    SDLTest_AssertCheck(result == SDLK_UNKNOWN, "Verify result from call is UNKNOWN, expected: %d, got: %" SDL_PRIu32, SDLK_UNKNOWN, result);
 
     /* Clear error message */
     SDL_ClearError();
@@ -140,13 +144,13 @@ static int keyboard_getKeyFromScancode(void *arg)
     /* Case where input is invalid (too small) */
     result = SDL_GetKeyFromScancode((SDL_Scancode)-999, SDL_KMOD_NONE);
     SDLTest_AssertPass("Call to SDL_GetKeyFromScancode(-999)");
-    SDLTest_AssertCheck(result == SDLK_UNKNOWN, "Verify result from call is UNKNOWN, expected: %d, got: %" SDL_PRIs32, SDLK_UNKNOWN, result);
+    SDLTest_AssertCheck(result == SDLK_UNKNOWN, "Verify result from call is UNKNOWN, expected: %d, got: %" SDL_PRIu32, SDLK_UNKNOWN, result);
     checkInvalidScancodeError();
 
     /* Case where input is invalid (too big) */
     result = SDL_GetKeyFromScancode((SDL_Scancode)999, SDL_KMOD_NONE);
     SDLTest_AssertPass("Call to SDL_GetKeyFromScancode(999)");
-    SDLTest_AssertCheck(result == SDLK_UNKNOWN, "Verify result from call is UNKNOWN, expected: %d, got: %" SDL_PRIs32, SDLK_UNKNOWN, result);
+    SDLTest_AssertCheck(result == SDLK_UNKNOWN, "Verify result from call is UNKNOWN, expected: %d, got: %" SDL_PRIu32, SDLK_UNKNOWN, result);
     checkInvalidScancodeError();
 
     return TEST_COMPLETED;
@@ -164,42 +168,42 @@ static int keyboard_getKeyName(void *arg)
 
     /* Case where key has a 1 character name */
     expected = "3";
-    result = SDL_GetKeyName(SDLK_3);
+    result = SDL_GetKeyName(SDLK_3, SDL_TRUE);
     SDLTest_AssertPass("Call to SDL_GetKeyName()");
     SDLTest_AssertCheck(result != NULL, "Verify result from call is not NULL");
     SDLTest_AssertCheck(SDL_strcmp(result, expected) == 0, "Verify result from call is valid, expected: %s, got: %s", expected, result);
 
     /* Case where key has a 2 character name */
     expected = "F1";
-    result = SDL_GetKeyName(SDLK_F1);
+    result = SDL_GetKeyName(SDLK_F1, SDL_TRUE);
     SDLTest_AssertPass("Call to SDL_GetKeyName()");
     SDLTest_AssertCheck(result != NULL, "Verify result from call is not NULL");
     SDLTest_AssertCheck(SDL_strcmp(result, expected) == 0, "Verify result from call is valid, expected: %s, got: %s", expected, result);
 
     /* Case where key has a 3 character name */
     expected = "Cut";
-    result = SDL_GetKeyName(SDLK_CUT);
+    result = SDL_GetKeyName(SDLK_CUT, SDL_TRUE);
     SDLTest_AssertPass("Call to SDL_GetKeyName()");
     SDLTest_AssertCheck(result != NULL, "Verify result from call is not NULL");
     SDLTest_AssertCheck(SDL_strcmp(result, expected) == 0, "Verify result from call is valid, expected: %s, got: %s", expected, result);
 
     /* Case where key has a 4 character name */
     expected = "Down";
-    result = SDL_GetKeyName(SDLK_DOWN);
+    result = SDL_GetKeyName(SDLK_DOWN, SDL_TRUE);
     SDLTest_AssertPass("Call to SDL_GetKeyName()");
     SDLTest_AssertCheck(result != NULL, "Verify result from call is not NULL");
     SDLTest_AssertCheck(SDL_strcmp(result, expected) == 0, "Verify result from call is valid, expected: %s, got: %s", expected, result);
 
     /* Case where key has a N character name */
     expected = "MediaPlay";
-    result = SDL_GetKeyName(SDLK_MEDIA_PLAY);
+    result = SDL_GetKeyName(SDLK_MEDIA_PLAY, SDL_TRUE);
     SDLTest_AssertPass("Call to SDL_GetKeyName()");
     SDLTest_AssertCheck(result != NULL, "Verify result from call is not NULL");
     SDLTest_AssertCheck(SDL_strcmp(result, expected) == 0, "Verify result from call is valid, expected: %s, got: %s", expected, result);
 
     /* Case where key has a N character name with space */
     expected = "Keypad MemStore";
-    result = SDL_GetKeyName(SDLK_KP_MEMSTORE);
+    result = SDL_GetKeyName(SDLK_KP_MEMSTORE, SDL_TRUE);
     SDLTest_AssertPass("Call to SDL_GetKeyName()");
     SDLTest_AssertCheck(result != NULL, "Verify result from call is not NULL");
     SDLTest_AssertCheck(SDL_strcmp(result, expected) == 0, "Verify result from call is valid, expected: %s, got: %s", expected, result);
@@ -246,8 +250,8 @@ static int keyboard_getKeyNameNegative(void *arg)
 
     /* Unknown keycode */
     keycode = SDLK_UNKNOWN;
-    result = SDL_GetKeyName(keycode);
-    SDLTest_AssertPass("Call to SDL_GetKeyName(%" SDL_PRIs32 "/unknown)", keycode);
+    result = SDL_GetKeyName(keycode, SDL_TRUE);
+    SDLTest_AssertPass("Call to SDL_GetKeyName(%" SDL_PRIu32 "/unknown)", keycode);
     SDLTest_AssertCheck(result != NULL, "Verify result from call is not NULL");
     SDLTest_AssertCheck(SDL_strcmp(result, expected) == 0, "Verify result from call is valid, expected: '%s', got: '%s'", expected, result);
 
@@ -257,8 +261,8 @@ static int keyboard_getKeyNameNegative(void *arg)
 
     /* Negative keycode */
     keycode = (SDL_Keycode)SDLTest_RandomIntegerInRange(-255, -1);
-    result = SDL_GetKeyName(keycode);
-    SDLTest_AssertPass("Call to SDL_GetKeyName(%" SDL_PRIs32 "/negative)", keycode);
+    result = SDL_GetKeyName(keycode, SDL_TRUE);
+    SDLTest_AssertPass("Call to SDL_GetKeyName(%" SDL_PRIu32 "/negative)", keycode);
     SDLTest_AssertCheck(result != NULL, "Verify result from call is not NULL");
     SDLTest_AssertCheck(SDL_strcmp(result, expected) == 0, "Verify result from call is valid, expected: '%s', got: '%s'", expected, result);
     checkInvalidScancodeError();
@@ -494,25 +498,25 @@ static int keyboard_setTextInputAreaNegative(void *arg)
 }
 
 /**
- * Check call to SDL_GetScancodeFromKey
+ * Check call to SDL_getKeymapScancode
  *
- * \sa SDL_GetScancodeFromKey
+ * \sa SDL_getKeymapScancode
  * \sa SDL_Keycode
  */
-static int keyboard_getScancodeFromKey(void *arg)
+static int keyboard_getKeymapScancode(void *arg)
 {
     SDL_Scancode scancode;
     SDL_Keymod modstate;
 
     /* Regular key */
-    scancode = SDL_GetDefaultScancodeFromKey(SDLK_4, &modstate);
-    SDLTest_AssertPass("Call to SDL_GetScancodeFromKey(SDLK_4)");
+    scancode = SDL_GetKeymapScancode(NULL, SDLK_4, &modstate);
+    SDLTest_AssertPass("Call to SDL_GetKeymapScancode(SDLK_4)");
     SDLTest_AssertCheck(scancode == SDL_SCANCODE_4, "Validate return value from SDL_GetDefaultScancodeFromKey, expected: %d, got: %d", SDL_SCANCODE_4, scancode);
     SDLTest_AssertCheck(modstate == SDL_KMOD_NONE, "Validate modstate from SDL_GetDefaultScancodeFromKey, expected: %d, got: %d", SDL_KMOD_NONE, modstate);
 
     /* Virtual key */
-    scancode = SDL_GetDefaultScancodeFromKey(SDLK_PLUS, &modstate);
-    SDLTest_AssertPass("Call to SDL_GetScancodeFromKey(SDLK_PLUS)");
+    scancode = SDL_GetKeymapScancode(NULL, SDLK_PLUS, &modstate);
+    SDLTest_AssertPass("Call to SDL_GetKeymapScancode(SDLK_PLUS)");
     SDLTest_AssertCheck(scancode == SDL_SCANCODE_EQUALS, "Validate return value from SDL_GetDefaultScancodeFromKey, expected: %d, got: %d", SDL_SCANCODE_EQUALS, scancode);
     SDLTest_AssertCheck(modstate == SDL_KMOD_SHIFT, "Validate modstate from SDL_GetDefaultScancodeFromKey, expected: %d, got: %d", SDL_KMOD_SHIFT, modstate);
 
@@ -674,7 +678,7 @@ static const SDLTest_TestCaseReference keyboardTest9 = {
 };
 
 static const SDLTest_TestCaseReference keyboardTest10 = {
-    (SDLTest_TestCaseFp)keyboard_getScancodeFromKey, "keyboard_getScancodeFromKey", "Check call to SDL_GetScancodeFromKey", TEST_ENABLED
+    (SDLTest_TestCaseFp)keyboard_getKeymapScancode, "keyboard_getKeymapScancode", "Check call to SDL_getKeymapScancode", TEST_ENABLED
 };
 
 static const SDLTest_TestCaseReference keyboardTest11 = {

test/testime.c

@@ -1209,7 +1209,7 @@ int main(int argc, char *argv[])
                         event.key.scancode,
                         SDL_GetScancodeName(event.key.scancode),
                         SDL_static_cast(Uint32, event.key.key),
-                        SDL_GetKeyName(event.key.key));
+                        SDL_GetKeyName(event.key.key, SDL_TRUE));
                 break;
             }
             case SDL_EVENT_TEXT_INPUT: {