Commit 7c2c7858 authored by Camilla Löwy's avatar Camilla Löwy
Browse files

Add monitor and joystick user pointers

parent 9da2285b
......@@ -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)
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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.
......
......@@ -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
......
......@@ -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);
......
......@@ -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;
......
......@@ -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);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment