diff --git a/README.md b/README.md index 0892b403..3353dacc 100644 --- a/README.md +++ b/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` diff --git a/docs/news.dox b/docs/news.dox index 2d4b621d..d8bb23a5 100644 --- a/docs/news.dox +++ b/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 diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 83fad737..25326252 100644 --- a/include/GLFW/glfw3.h +++ b/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 diff --git a/src/input.c b/src/input.c index 2a5dfef0..101b6859 100644 --- a/src/input.c +++ b/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); diff --git a/tests/joysticks.c b/tests/joysticks.c index 9425af78..88489d4e 100644 --- a/tests/joysticks.c +++ b/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);