Add glfwGetJoystickGUID

This function completes the first round of support for
SDL_GameControllerDB.

Fixes #900.

README.md

@@ -130,6 +130,8 @@ information on what to include when reporting a bug.
   SDL\_GameControllerDB format (#900)
 - Added `glfwJoystickIsGamepad` function for querying whether a joystick has
   a gamepad mapping (#900)
+- Added `glfwGetJoystickGUID` function for querying the SDL compatible GUID of
+  a joystick (#900)
 - Added `glfwGetGamepadName` function for querying the name provided by the
   gamepad mapping (#900)
 - Added `glfwGetGamepadState` function, `GLFW_GAMEPAD_*` and `GLFWgamepadstate`

docs/news.dox

@@ -16,9 +16,9 @@ human-readable description with @ref glfwGetError.
 @subsection news_33_gamepad SDL_GameControllerDB support and gamepad input
 
 GLFW now supports remapping of gamepads and controllers to a 360-like controller
-layout with @ref glfwJoystickIsGamepad, @ref glfwGetGamepadName, @ref
-glfwGetGamepadState and @ref glfwUpdateGamepadMappings, and the input state
-struct @ref GLFWgamepadstate.
+layout with @ref glfwJoystickIsGamepad, @ref glfwGetJoystickGUID, @ref
+glfwGetGamepadName, @ref glfwGetGamepadState and @ref glfwUpdateGamepadMappings,
+and the input state struct @ref GLFWgamepadstate.
 
 @sa @ref gamepad
 

include/GLFW/glfw3.h

@@ -4381,6 +4381,43 @@ GLFWAPI const unsigned char* glfwGetJoystickHats(int jid, int* count);
  */
 GLFWAPI const char* glfwGetJoystickName(int jid);
 
+/*! @brief Returns the SDL comaptible GUID of the specified joystick.
+ *
+ *  This function returns the SDL compatible GUID, as a UTF-8 encoded
+ *  hexadecimal string, of the specified joystick.  The returned string is
+ *  allocated and freed by GLFW.  You should not free it yourself.
+ *
+ *  If the specified joystick is not present this function will return `NULL`
+ *  but will not generate an error.  Call @ref glfwJoystickPresent to check
+ *  device presence.
+ *
+ *  The GUID uses the format introduced in SDL 2.0.5.  This GUID tries to
+ *  uniquely identify the make and model of a joystick but does not identify
+ *  a specific unit, e.g. all wired Xbox 360 controllers will have the same
+ *  GUID on that platform.  The GUID for a unit may vary between platforms
+ *  depending on what hardware information the platform specific APIs provide.
+ *
+ *  @param[in] jid The [joystick](@ref joysticks) to query.
+ *  @return The UTF-8 encoded GUID of the joystick, or `NULL` if the joystick
+ *  is not present or an [error](@ref error_handling) occurred.
+ *
+ *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
+ *  GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
+ *
+ *  @pointer_lifetime The returned string is allocated and freed by GLFW.  You
+ *  should not free it yourself.  It is valid until the specified joystick is
+ *  disconnected or the library is terminated.
+ *
+ *  @thread_safety This function must only be called from the main thread.
+ *
+ *  @sa @ref gamepad
+ *
+ *  @since Added in version 3.3.
+ *
+ *  @ingroup input
+ */
+GLFWAPI const char* glfwGetJoystickGUID(int jid);
+
 /*! @brief Returns whether the specified joystick has a gamepad mapping.
  *
  *  This function returns whether the specified joystick is both present and has

src/input.c

@@ -896,6 +896,31 @@ GLFWAPI const char* glfwGetJoystickName(int jid)
     return js->name;
 }
 
+GLFWAPI const char* glfwGetJoystickGUID(int jid)
+{
+    _GLFWjoystick* js;
+
+    assert(jid >= GLFW_JOYSTICK_1);
+    assert(jid <= GLFW_JOYSTICK_LAST);
+
+    _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
+
+    if (jid < 0 || jid > GLFW_JOYSTICK_LAST)
+    {
+        _glfwInputError(GLFW_INVALID_ENUM, "Invalid joystick ID %i", jid);
+        return NULL;
+    }
+
+    js = _glfw.joysticks + jid;
+    if (!js->present)
+        return NULL;
+
+    if (!_glfwPlatformPollJoystick(js, _GLFW_POLL_PRESENCE))
+        return NULL;
+
+    return js->guid;
+}
+
 GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun cbfun)
 {
     _GLFW_REQUIRE_INIT_OR_RETURN(NULL);

tests/joysticks.c

@@ -228,6 +228,8 @@ int main(void)
                 GLFWgamepadstate state;
 
                 nk_layout_row_dynamic(nk, 30, 1);
+                nk_labelf(nk, NK_TEXT_LEFT, "Hardware GUID %s",
+                          glfwGetJoystickGUID(joysticks[i]));
                 nk_label(nk, "Joystick state", NK_TEXT_LEFT);
 
                 axes = glfwGetJoystickAxes(joysticks[i], &axis_count);