Add monitor and joystick user pointers

This commit is contained in:
Camilla Löwy 2017-12-07 16:19:57 +01:00
parent 9da2285b14
commit 7c2c7858c6
9 changed files with 198 additions and 4 deletions

View File

@ -151,6 +151,10 @@ information on what to include when reporting a bug.
- Added `glfwWindowHintString` for setting string type window hints (#893,#1139) - Added `glfwWindowHintString` for setting string type window hints (#893,#1139)
- Added `glfwGetWindowOpacity` and `glfwSetWindowOpacity` for controlling whole - Added `glfwGetWindowOpacity` and `glfwSetWindowOpacity` for controlling whole
window transparency (#1089) 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` - Added `glfwGetX11SelectionString` and `glfwSetX11SelectionString`
functions for accessing X11 primary selection (#894,#1056) functions for accessing X11 primary selection (#894,#1056)
- Added headless [OSMesa](http://mesa3d.org/osmesa.html) backend (#850) - Added headless [OSMesa](http://mesa3d.org/osmesa.html) backend (#850)

View File

@ -511,6 +511,9 @@ present with @ref glfwJoystickPresent.
int present = glfwJoystickPresent(GLFW_JOYSTICK_1); int present = glfwJoystickPresent(GLFW_JOYSTICK_1);
@endcode @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 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 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 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. 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 @subsection joystick_event Joystick configuration changes
If you wish to be notified when a joystick is connected or disconnected, set 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 called by joystick functions. The function will then return whatever it
returns for a disconnected joystick. 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 @subsection gamepad Gamepad input

View File

@ -86,14 +86,16 @@ void monitor_callback(GLFWmonitor* monitor, int event)
@endcode @endcode
If a monitor is disconnected, all windows that are full screen on it will be 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 @section monitor_properties Monitor properties
Each monitor has a current video mode, a list of supported video modes, 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 virtual position, a human-readable name, a user pointer, an estimated physical
a gamma ramp. size and a gamma ramp.
@subsection monitor_modes Video modes @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. 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 @subsection monitor_gamma Gamma ramp
The gamma ramp of a monitor can be set with @ref glfwSetGammaRamp, which accepts The gamma ramp of a monitor can be set with @ref glfwSetGammaRamp, which accepts

View File

@ -139,6 +139,13 @@ creation API, intended for automated testing. This backend does not provide
input. 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 @subsection news_33_primary X11 primary selection access
GLFW now supports querying and setting the X11 primary selection via the native GLFW now supports querying and setting the X11 primary selection via the native

View File

@ -531,7 +531,7 @@ See @ref events.
@subsection window_userptr User pointer @subsection window_userptr User pointer
Each window has a user pointer that can be set with @ref 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 can be used for any purpose you need and will not be modified by GLFW throughout
the life-time of the window. the life-time of the window.

View File

@ -1970,6 +1970,56 @@ GLFWAPI void glfwGetMonitorContentScale(GLFWmonitor* monitor, float* xscale, flo
*/ */
GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor); 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. /*! @brief Sets the monitor configuration callback.
* *
* This function sets the monitor configuration callback, or removes the * 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); 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. /*! @brief Returns whether the specified joystick has a gamepad mapping.
* *
* This function returns whether the specified joystick is both present and has * This function returns whether the specified joystick is both present and has

View File

@ -979,6 +979,38 @@ GLFWAPI const char* glfwGetJoystickGUID(int jid)
return js->guid; 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) GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun cbfun)
{ {
_GLFW_REQUIRE_INIT_OR_RETURN(NULL); _GLFW_REQUIRE_INIT_OR_RETURN(NULL);

View File

@ -456,6 +456,7 @@ struct _GLFWwindow
struct _GLFWmonitor struct _GLFWmonitor
{ {
char* name; char* name;
void* userPointer;
// Physical dimensions in millimeters. // Physical dimensions in millimeters.
int widthMM, heightMM; int widthMM, heightMM;
@ -514,6 +515,7 @@ struct _GLFWjoystick
unsigned char* hats; unsigned char* hats;
int hatCount; int hatCount;
char* name; char* name;
void* userPointer;
char guid[33]; char guid[33];
_GLFWmapping* mapping; _GLFWmapping* mapping;

View File

@ -351,6 +351,24 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* handle)
return monitor->name; 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) GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun)
{ {
_GLFW_REQUIRE_INIT_OR_RETURN(NULL); _GLFW_REQUIRE_INIT_OR_RETURN(NULL);