Add glfwGetKeyScancode

Allows retrieval of platform scancode from GLFW_KEY_*.  Implemented for
Win32, Cocoa and X11.  Stubs for Mir and Wayland.

Closes #830.

README.md

@@ -99,6 +99,8 @@ information on what to include when reporting a bug.
 
 ## Changelog
 
+- Added `glfwGetKeyScancode` function that allows retrieving platform depen-
+  dent scancodes for keys
 - Bugfix: Calling `glfwMaximizeWindow` on a full screen window was not ignored
 
 
@@ -243,6 +245,7 @@ skills.
  - Santi Zupancic
  - Jonas Ådahl
  - Lasse Öörni
+ - Michael Stocker
  - All the unmentioned and anonymous contributors in the GLFW community, for bug
    reports, patches, feedback, testing and encouragement
 

docs/input.dox

@@ -223,6 +223,20 @@ ignored.  This matches the behavior of the key callback, meaning the callback
 arguments can always be passed unmodified to this function.
 
 
+@subsection input_key_scancode Key scancodes
+
+If you need the platform dependent scancode for any given key, you can query
+it with @ref glfwGetKeyScancode.
+
+@code
+const short int scancode = glfwGetKeyScancode(GLFW_KEY_X);
+set_key_mapping(scancode, swap_weapons);
+@encode
+
+If the key is `GLFW_KEY_UNKNOWN` or does not exist on the keyboard this
+method will return `-1`.
+
+
 @section input_mouse Mouse input
 
 Mouse input comes in many forms, including cursor motion, button presses and

docs/news.dox

@@ -5,6 +5,12 @@
 @section news_33 New features in 3.3
 
 
+@subsection new_33_keyscancode Platform dependent scancodes
+
+GLFW now supports querying the platform dependent scancode of any key with
+@ref glfwGetKeyScancode.
+
+
 @section news_32 New features in 3.2
 
 

include/GLFW/glfw3.h

@@ -3003,6 +3003,30 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value);
  */
 GLFWAPI const char* glfwGetKeyName(int key, int scancode);
 
+/*! @brief Returns the platform dependent scancode of the specified key.
+ *
+ *  This function returns the platform dependent scancode of the specified key.
+ *  This is intended for platform specific default keybindings.
+ *
+ *  If the key is `GLFW_KEY_UNKNOWN` or does not exist on the keyboard this
+ *  method will return `-1`.
+ *
+ *  @param[in] key The key to query.
+ *  @return The platform dependent scancode for the key, or `-1`.
+ *
+ *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
+ *  GLFW_PLATFORM_ERROR.
+ *
+ *  @thread_safety This function may be called from any thread.
+ *
+ *  @sa @ref input_key_scancode
+ *
+ *  @since Added in version 3.3.
+ *
+ *  @ingroup input
+ */
+GLFWAPI const short int glfwGetKeyScancode(int key);
+
 /*! @brief Returns the last reported state of a keyboard key for the specified
  *  window.
  *

src/cocoa_window.m

@@ -1511,6 +1511,16 @@ const char* _glfwPlatformGetKeyName(int key, int scancode)
     return _glfw.ns.keyName;
 }
 
+const short int _glfwPlatformGetKeyScancode(int key)
+{
+    if(key <= -1 || key >= (sizeof(_glfw.ns.nativeKeys) / sizeof(_glfw.ns.nativeKeys[0])))
+    {
+        return -1;
+    }
+
+    return _glfw.ns.nativeKeys[key];
+}
+
 int _glfwPlatformCreateCursor(_GLFWcursor* cursor,
                               const GLFWimage* image,
                               int xhot, int yhot)

src/input.c

@@ -256,6 +256,12 @@ GLFWAPI const char* glfwGetKeyName(int key, int scancode)
     return _glfwPlatformGetKeyName(key, scancode);
 }
 
+GLFWAPI const short int glfwGetKeyScancode(int key)
+{
+    _GLFW_REQUIRE_INIT_OR_RETURN(-1);
+    return _glfwPlatformGetKeyScancode(key);
+}
+
 GLFWAPI int glfwGetKey(GLFWwindow* handle, int key)
 {
     _GLFWwindow* window = (_GLFWwindow*) handle;

src/internal.h

@@ -542,6 +542,11 @@ void _glfwPlatformSetCursorMode(_GLFWwindow* window, int mode);
  */
 const char* _glfwPlatformGetKeyName(int key, int scancode);
 
+/*! @copydoc glfwGetKeyScancode
+ *  @ingroup platform
+ */
+const short int _glfwPlatformGetKeyScancode(int key);
+
 /*! @copydoc glfwGetMonitors
  *  @ingroup platform
  */

src/mir_window.c

@@ -744,6 +744,13 @@ const char* _glfwPlatformGetKeyName(int key, int scancode)
     return NULL;
 }
 
+const int _glfwPlatformGetKeyScancode(int key)
+{
+    _glfwInputError(GLFW_PLATFORM_ERROR,
+                    "Mir: Unsupported function %s", __PRETTY_FUNCTION__);
+    return NULL;
+}
+
 void _glfwPlatformSetClipboardString(_GLFWwindow* window, const char* string)
 {
     _glfwInputError(GLFW_PLATFORM_ERROR,

src/win32_window.c

@@ -1511,6 +1511,16 @@ const char* _glfwPlatformGetKeyName(int key, int scancode)
     return _glfw.win32.keyName;
 }
 
+const short int _glfwPlatformGetKeyScancode(int key)
+{
+    if(key <= -1 || key >= (sizeof(_glfw.win32.nativeKeys) / sizeof(_glfw.win32.nativeKeys[0])))
+    {
+        return -1;
+    }
+
+    return _glfw.win32.nativeKeys[key];
+}
+
 int _glfwPlatformCreateCursor(_GLFWcursor* cursor,
                               const GLFWimage* image,
                               int xhot, int yhot)

src/wl_window.c

@@ -686,6 +686,12 @@ const char* _glfwPlatformGetKeyName(int key, int scancode)
     return NULL;
 }
 
+const int _glfwPlatformGetKeyScancode(int key)
+{
+    // TODO
+	return -1;
+}
+
 int _glfwPlatformCreateCursor(_GLFWcursor* cursor,
                               const GLFWimage* image,
                               int xhot, int yhot)

src/x11_window.c

@@ -2186,6 +2186,16 @@ const char* _glfwPlatformGetKeyName(int key, int scancode)
     return _glfw.x11.keyName;
 }
 
+const short int _glfwPlatformGetKeyScancode(int key)
+{
+    if(key <= -1 || key >= (sizeof(_glfw.x11.nativeKeys) / sizeof(_glfw.x11.nativeKeys[0])))
+    {
+        return -1;
+    }
+
+    return _glfw.x11.nativeKeys[key];
+}
+
 int _glfwPlatformCreateCursor(_GLFWcursor* cursor,
                               const GLFWimage* image,
                               int xhot, int yhot)