From b9acd9d45f0a3d3cfc2a9646e482de8ed8367935 Mon Sep 17 00:00:00 2001
From: NarrikSynthfox <80410683+NarrikSynthfox@users.noreply.github.com>
Date: Wed, 10 Apr 2024 13:39:41 -0400
Subject: [PATCH] Update docs, readme, news, and contributors

---
 CONTRIBUTORS.md |  3 ++
 README.md       |  2 +-
 docs/input.md   | 79 +++++++++++++++++++++++++++++++++++++++++++++++++
 docs/news.md    | 15 ++++++++++
 4 files changed, 98 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
index 1371aedb..d3349217 100644
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -294,6 +294,9 @@ video tutorials.
  - Jonas Ådahl
  - Lasse Öörni
  - Leonard König
+ - Beoran
+ - Enthuin
+ - Narrik Synthfox
  - All the unmentioned and anonymous contributors in the GLFW community, for bug
    reports, patches, feedback, testing and encouragement
 
diff --git a/README.md b/README.md
index 2718e45e..44f3fadd 100644
--- a/README.md
+++ b/README.md
@@ -129,7 +129,7 @@ information on what to include when reporting a bug.
  - [Null] Added EGL context creation on Mesa via `EGL_MESA_platform_surfaceless`
  - [EGL] Allowed native access on Wayland with `GLFW_CONTEXT_CREATION_API` set to
    `GLFW_NATIVE_CONTEXT_API` (#2518)
-
+ - Added `GLFWgamepadstatefun`, `glfwSetGamepadStateCallback`, `GLFWjoystickbuttonfun`,`glfwSetJoystickButtonCallback`, `GLFWjoystickaxisfun`, `glfwSetJoystickAxisCallback`, `GLFWjoystickhatfun`, and `glfwSetJoystickHatCallback` for event-based joystick/gamepad input.
 
 ## Contact
 
diff --git a/docs/input.md b/docs/input.md
index 3ef1aebe..acfcfcdb 100644
--- a/docs/input.md
+++ b/docs/input.md
@@ -911,6 +911,85 @@ righttrigger:a5,dpup:h0.1,dpright:h0.2,dpdown:h0.4,dpleft:h0.8,
 were recently added to SDL.  The input modifiers `+`, `-` and `~` are supported
 and described above.
 
+### Event-based joystick and gamepad input {#joystick_input_event}
+
+If you wish to be notified when a button on a joystick is pressed or released, set a joystick button callback.
+
+```c
+glfwSetJoystickButtonCallback(joystick_button_callback);
+```
+
+The callback function receives the joystick id, the [joystick button](@ref joystick_button) that was pressed or released, and action.
+
+```c
+void joystick_button_callback(int jid, int button, int action)
+{
+    if (button == 0 && action == GLFW_PRESS)
+        jump();
+}
+```
+
+The action is one of `GLFW_PRESS` or `GLFW_RELEASE`
+
+If you wish to be notified when an axis on a joystick is moved, set a joystick axis callback.
+
+```c
+glfwSetJoystickAxisCallback(joystick_axis_callback);
+```
+
+The callback function receives the joystick id, [joystick axis](@ref joystick_axis) that was moved, and float value from -1.0 to 1.0 for the axis.
+
+```c
+void joystick_axis_callback(int jid, int axis, float value)
+{
+    if (axis == 0){
+        if(value == -1.0f)
+            move_left();
+        else if(value == 1.0f)
+            move_right();
+    }
+}
+```
+
+If you wish to be notified when a hat on a joystick is moved, set a joystick hat callback.
+
+```c
+glfwSetJoystickHatCallback(joystick_hat_callback);
+```
+
+The callback function receives the joystick id, hat, and the [hat states](@ref hat_state).
+
+```c
+void joystick_hat_callback(int jid, int hat, int position)
+{
+    if(hat == 0 && position == GLFW_HAT_UP)
+        move_up();
+}
+```
+
+If you wish to be notified when the state of a gamepad is updated, set a gamepad state callback. This callback will occur every time any button, axis, or hat updates, so with this, you will have to handle checks for if a value is changed.
+
+```c
+glfwSetGamepadStateCallback(gamepad_state_callback);
+```
+
+The callback function recieves the joystick id and the gamepad state.
+
+```c
+bool jumpButtonHeld = false;
+
+gamepad_state_callback(int jid, GLFWgamepadstate state){
+    if (state.buttons[GLFW_GAMEPAD_BUTTON_A] && !jumpButtonHeld)
+    {
+        input_jump();
+        jumpButtonHeld = true;
+    }
+    else if (!state.buttons[GLFW_GAMEPAD_BUTTON_A] && jumpButtonHeld)
+    {
+        jumpButtonHeld = false;
+    }
+}
+```
 
 ## Time input {#time}
 
diff --git a/docs/news.md b/docs/news.md
index 148d0871..cf02ac1d 100644
--- a/docs/news.md
+++ b/docs/news.md
@@ -14,6 +14,11 @@ values over 8. For compatibility with older versions, the
 @ref GLFW_UNLIMITED_MOUSE_BUTTONS input mode needs to be set to make use of
 this.
 
+### Callback functions for gamepad state, joystick buttons, joystick axes, and joystick hat inputs {#joystick_input_callbacks}
+
+GLFW now has callback functions for [gamepad state](@ref glfwSetGamepadStateCallback), [joystick buttons](@ref glfwSetJoystickButtonCallback), [joystick axes](@ref glfwSetJoystickAxisCallback), and [joystick hats](@ref glfwSetJoystickHatCallback), allowing for 
+event-based inputs for joysticks and gamepads.
+
 ## Caveats {#caveats}
 
 ## Deprecations {#deprecations}
@@ -24,8 +29,18 @@ this.
 
 ### New functions {#new_functions}
 
+- @ref glfwSetJoystickButtonCallback
+- @ref glfwSetJoystickAxisCallback
+- @ref glfwSetJoystickHatCallback
+- @ref glfwSetGamepadStateCallback
+
 ### New types {#new_types}
 
+- @ref GLFWjoystickbuttonfun
+- @ref GLFWjoystickaxisfun
+- @ref GLFWjoystickhatfun
+- @ref GLFWgamepadstatefun
+
 ### New constants {#new_constants}
 
 - @ref GLFW_UNLIMITED_MOUSE_BUTTONS