From 7c2c7858c67280d2a53cf1a80ee92bcfe73bf72b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Camilla=20L=C3=B6wy?= Date: Thu, 7 Dec 2017 16:19:57 +0100 Subject: [PATCH] Add monitor and joystick user pointers --- README.md | 4 ++ docs/input.dox | 18 ++++++++ docs/monitor.dox | 19 ++++++-- docs/news.dox | 7 +++ docs/window.dox | 2 +- include/GLFW/glfw3.h | 100 +++++++++++++++++++++++++++++++++++++++++++ src/input.c | 32 ++++++++++++++ src/internal.h | 2 + src/monitor.c | 18 ++++++++ 9 files changed, 198 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 421bdab8..9e174ebc 100644 --- a/README.md +++ b/README.md @@ -151,6 +151,10 @@ information on what to include when reporting a bug. - Added `glfwWindowHintString` for setting string type window hints (#893,#1139) - Added `glfwGetWindowOpacity` and `glfwSetWindowOpacity` for controlling whole window transparency (#1089) +- Added `glfwSetMonitorUserPointer` and `glfwGetMonitorUserPointer` for + per-monitor user pointers +- Added `glfwSetJoystickUserPointer` and `glfwGetJoystickUserPointer` for + per-joystick user pointers - Added `glfwGetX11SelectionString` and `glfwSetX11SelectionString` functions for accessing X11 primary selection (#894,#1056) - Added headless [OSMesa](http://mesa3d.org/osmesa.html) backend (#850) diff --git a/docs/input.dox b/docs/input.dox index bb486b2f..a72ba150 100644 --- a/docs/input.dox +++ b/docs/input.dox @@ -511,6 +511,9 @@ present with @ref glfwJoystickPresent. int present = glfwJoystickPresent(GLFW_JOYSTICK_1); @endcode +Each joystick has zero or more axes, zero or more buttons, zero or more hats, +a human-readable name, a user pointer and an SDL compatible GUID. + When GLFW is initialized, detected joysticks are added to to the beginning of the array. Once a joystick is detected, it keeps its assigned ID until it is disconnected or the library is terminated, so as joysticks are connected and @@ -613,6 +616,17 @@ and make may have the same name. Only the [joystick token](@ref joysticks) is guaranteed to be unique, and only until that joystick is disconnected. +@subsection joystick_userptr Joystick user pointer + +Each joystick has a user pointer that can be set with @ref +glfwSetJoystickUserPointer and queried with @ref glfwGetJoystickUserPointer. +This can be used for any purpose you need and will not be modified by GLFW. The +value will be kept until the joystick is disconnected or until the library is +terminated. + +The initial value of the pointer is `NULL`. + + @subsection joystick_event Joystick configuration changes If you wish to be notified when a joystick is connected or disconnected, set @@ -645,6 +659,10 @@ functions. Joystick disconnection may also be detected and the callback called by joystick functions. The function will then return whatever it returns for a disconnected joystick. +Only @ref glfwGetJoystickName and @ref glfwGetJoystickUserPointer will return +useful values for a disconnected joystick and only before the monitor callback +returns. + @subsection gamepad Gamepad input diff --git a/docs/monitor.dox b/docs/monitor.dox index 3aa9a775..08c11933 100644 --- a/docs/monitor.dox +++ b/docs/monitor.dox @@ -86,14 +86,16 @@ void monitor_callback(GLFWmonitor* monitor, int event) @endcode If a monitor is disconnected, all windows that are full screen on it will be -switched to windowed mode. +switched to windowed mode before the callback is called. Only @ref +glfwGetMonitorName and @ref glfwGetMonitorUserPointer will return useful values +for a disconnected monitor and only before the monitor callback returns. @section monitor_properties Monitor properties Each monitor has a current video mode, a list of supported video modes, -a virtual position, a human-readable name, an estimated physical size and -a gamma ramp. +a virtual position, a human-readable name, a user pointer, an estimated physical +size and a gamma ramp. @subsection monitor_modes Video modes @@ -187,6 +189,17 @@ and make may have the same name. Only the monitor handle is guaranteed to be unique, and only until that monitor is disconnected. +@subsection monitor_userptr User pointer + +Each monitor has a user pointer that can be set with @ref +glfwSetMonitorUserPointer and queried with @ref glfwGetMonitorUserPointer. This +can be used for any purpose you need and will not be modified by GLFW. The +value will be kept until the monitor is disconnected or until the library is +terminated. + +The initial value of the pointer is `NULL`. + + @subsection monitor_gamma Gamma ramp The gamma ramp of a monitor can be set with @ref glfwSetGammaRamp, which accepts diff --git a/docs/news.dox b/docs/news.dox index 3a4c2ce6..b7083d4d 100644 --- a/docs/news.dox +++ b/docs/news.dox @@ -139,6 +139,13 @@ creation API, intended for automated testing. This backend does not provide input. +@subsection news_33_userptr Monitor and joystick user pointers + +GLFW now supports setting and querying user pointers for connected monitors and +joysticks with @ref glfwSetMonitorUserPointer, @ref glfwGetMonitorUserPointer, +@ref glfwSetJoystickUserPointer and @ref glfwGetJoystickUserPointer. + + @subsection news_33_primary X11 primary selection access GLFW now supports querying and setting the X11 primary selection via the native diff --git a/docs/window.dox b/docs/window.dox index 1d2b4651..b5348ac2 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -531,7 +531,7 @@ See @ref events. @subsection window_userptr User pointer Each window has a user pointer that can be set with @ref -glfwSetWindowUserPointer and fetched with @ref glfwGetWindowUserPointer. This +glfwSetWindowUserPointer and queried with @ref glfwGetWindowUserPointer. This can be used for any purpose you need and will not be modified by GLFW throughout the life-time of the window. diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 9ade8c74..3c6876c6 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -1970,6 +1970,56 @@ GLFWAPI void glfwGetMonitorContentScale(GLFWmonitor* monitor, float* xscale, flo */ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor); +/*! @brief Sets the user pointer of the specified monitor. + * + * This function sets the user-defined pointer of the specified monitor. The + * current value is retained until the monitor is disconnected. The initial + * value is `NULL`. + * + * This function may be called from the monitor callback, even for a monitor + * that is being disconnected. + * + * @param[in] monitor The monitor whose pointer to set. + * @param[in] pointer The new value. + * + * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. + * + * @thread_safety This function may be called from any thread. Access is not + * synchronized. + * + * @sa @ref monitor_userptr + * @sa @ref glfwGetMonitorUserPointer + * + * @since Added in version 3.3. + * + * @ingroup monitor + */ +GLFWAPI void glfwSetMonitorUserPointer(GLFWmonitor* monitor, void* pointer); + +/*! @brief Returns the user pointer of the specified monitor. + * + * This function returns the current value of the user-defined pointer of the + * specified monitor. The initial value is `NULL`. + * + * This function may be called from the monitor callback, even for a monitor + * that is being disconnected. + * + * @param[in] monitor The monitor whose pointer to return. + * + * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. + * + * @thread_safety This function may be called from any thread. Access is not + * synchronized. + * + * @sa @ref monitor_userptr + * @sa @ref glfwSetMonitorUserPointer + * + * @since Added in version 3.3. + * + * @ingroup monitor + */ +GLFWAPI void* glfwGetMonitorUserPointer(GLFWmonitor* monitor); + /*! @brief Sets the monitor configuration callback. * * This function sets the monitor configuration callback, or removes the @@ -4594,6 +4644,56 @@ GLFWAPI const char* glfwGetJoystickName(int jid); */ GLFWAPI const char* glfwGetJoystickGUID(int jid); +/*! @brief Sets the user pointer of the specified joystick. + * + * This function sets the user-defined pointer of the specified joystick. The + * current value is retained until the joystick is disconnected. The initial + * value is `NULL`. + * + * This function may be called from the joystick callback, even for a joystick + * that is being disconnected. + * + * @param[in] joystick The joystick whose pointer to set. + * @param[in] pointer The new value. + * + * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. + * + * @thread_safety This function may be called from any thread. Access is not + * synchronized. + * + * @sa @ref joystick_userptr + * @sa @ref glfwGetJoystickUserPointer + * + * @since Added in version 3.3. + * + * @ingroup input + */ +GLFWAPI void glfwSetJoystickUserPointer(int jid, void* pointer); + +/*! @brief Returns the user pointer of the specified joystick. + * + * This function returns the current value of the user-defined pointer of the + * specified joystick. The initial value is `NULL`. + * + * This function may be called from the joystick callback, even for a joystick + * that is being disconnected. + * + * @param[in] joystick The joystick whose pointer to return. + * + * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. + * + * @thread_safety This function may be called from any thread. Access is not + * synchronized. + * + * @sa @ref joystick_userptr + * @sa @ref glfwSetJoystickUserPointer + * + * @since Added in version 3.3. + * + * @ingroup input + */ +GLFWAPI void* glfwGetJoystickUserPointer(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 88a27fa3..7d81cd57 100644 --- a/src/input.c +++ b/src/input.c @@ -979,6 +979,38 @@ GLFWAPI const char* glfwGetJoystickGUID(int jid) return js->guid; } +GLFWAPI void glfwSetJoystickUserPointer(int jid, void* pointer) +{ + _GLFWjoystick* js; + + assert(jid >= GLFW_JOYSTICK_1); + assert(jid <= GLFW_JOYSTICK_LAST); + + _GLFW_REQUIRE_INIT(); + + js = _glfw.joysticks + jid; + if (!js->present) + return; + + js->userPointer = pointer; +} + +GLFWAPI void* glfwGetJoystickUserPointer(int jid) +{ + _GLFWjoystick* js; + + assert(jid >= GLFW_JOYSTICK_1); + assert(jid <= GLFW_JOYSTICK_LAST); + + _GLFW_REQUIRE_INIT_OR_RETURN(NULL); + + js = _glfw.joysticks + jid; + if (!js->present) + return NULL; + + return js->userPointer; +} + GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun cbfun) { _GLFW_REQUIRE_INIT_OR_RETURN(NULL); diff --git a/src/internal.h b/src/internal.h index dda8ae75..8cd0c480 100644 --- a/src/internal.h +++ b/src/internal.h @@ -456,6 +456,7 @@ struct _GLFWwindow struct _GLFWmonitor { char* name; + void* userPointer; // Physical dimensions in millimeters. int widthMM, heightMM; @@ -514,6 +515,7 @@ struct _GLFWjoystick unsigned char* hats; int hatCount; char* name; + void* userPointer; char guid[33]; _GLFWmapping* mapping; diff --git a/src/monitor.c b/src/monitor.c index e9a1fb65..21e52723 100644 --- a/src/monitor.c +++ b/src/monitor.c @@ -351,6 +351,24 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* handle) return monitor->name; } +GLFWAPI void glfwSetMonitorUserPointer(GLFWmonitor* handle, void* pointer) +{ + _GLFWmonitor* monitor = (_GLFWmonitor*) handle; + assert(monitor != NULL); + + _GLFW_REQUIRE_INIT(); + monitor->userPointer = pointer; +} + +GLFWAPI void* glfwGetMonitorUserPointer(GLFWmonitor* handle) +{ + _GLFWmonitor* monitor = (_GLFWmonitor*) handle; + assert(monitor != NULL); + + _GLFW_REQUIRE_INIT_OR_RETURN(NULL); + return monitor->userPointer; +} + GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun) { _GLFW_REQUIRE_INIT_OR_RETURN(NULL);