add "inertia" mode for mouse keys (#18774)

Co-authored-by: Selene ToyKeeper <git@toykeeper.net>

1 files changed, 33 insertions, 1 deletions

diff --git a/docs/feature_mouse_keys.md b/docs/feature_mouse_keys.md
index 8e474c4245..eed4f4f4aa 100644
--- a/docs/feature_mouse_keys.md
+++ b/docs/feature_mouse_keys.md
@@ -48,8 +48,9 @@ Mouse keys supports three different modes to move the cursor:
 * **Kinetic:** Holding movement keys accelerates the cursor with its speed following a quadratic curve until it reaches its maximum speed.
 * **Constant:** Holding movement keys moves the cursor at constant speeds.
 * **Combined:** Holding movement keys accelerates the cursor until it reaches its maximum speed, but holding acceleration and movement keys simultaneously moves the cursor at constant speeds.
+* **Inertia:** Cursor accelerates when key held, and decelerates after key release.  Tracks X and Y velocity separately for more nuanced movements.  Applies to cursor only, not scrolling.
 
-The same principle applies to scrolling.
+The same principle applies to scrolling, in most modes.
 
 Configuration options that are times, intervals or delays are given in milliseconds. Scroll speed is given as multiples of the default scroll step. For example, a scroll speed of 8 means that each scroll action covers 8 times the length of the default scroll step as defined by your operating system or application.
 
@@ -170,6 +171,37 @@ To use combined speed mode, you must at least define `MK_COMBINED` in your keyma
 #define MK_COMBINED
 ```
 
+### Inertia mode
+
+This mode provides smooth motion, like sliding on ice.  The cursor accelerates
+along a quadratic curve while a key is held, then glides to a stop after the
+key is released.  Vertical and horizontal movements are tracked independently,
+so the cursor can move in many directions and make curves.
+
+Cannot be used at the same time as Kinetic mode, Constant mode, or Combined mode.
+
+Recommended settings in your keymap’s `config.h` file:
+
+|Define                      |Default  |Description                                                |
+|----------------------------|---------|-----------------------------------------------------------|
+|`MOUSEKEY_INERTIA`          |undefined|Enable Inertia mode                                        |
+|`MOUSEKEY_DELAY`            |150      |Delay between pressing a movement key and cursor movement  |
+|`MOUSEKEY_INTERVAL`         |16       |Time between cursor movements in milliseconds (16 = 60fps) |
+|`MOUSEKEY_MAX_SPEED`        |32       |Maximum cursor speed at which acceleration stops           |
+|`MOUSEKEY_TIME_TO_MAX`      |32       |Number of frames until maximum cursor speed is reached     |
+|`MOUSEKEY_FRICTION`         |24       |How quickly the cursor stops after releasing a key         |
+|`MOUSEKEY_MOVE_DELTA`       |1        |How much to move on first frame (1 strongly recommended)   |
+
+Tips:
+
+* Set `MOUSEKEY_DELAY` to roughly the same value as your host computer's key repeat delay, in ms.  Recommended values are 100 to 300.
+* Set `MOUSEKEY_INTERVAL` to a value of 1000 / your monitor's FPS.  For 60 FPS, 1000/60 = 16.
+* Set `MOUSEKEY_MAX_SPEED` based on your screen resolution and refresh rate, like Width / FPS.  For example, 1920 pixels / 60 FPS = 32 pixels per frame.
+* Set `MOUSEKEY_TIME_TO_MAX` to a value of approximately FPS / 2, to make it reach full speed in half a second (or so).
+* Set `MOUSEKEY_FRICTION` to something between 1 and 255.  Lower makes the cursor glide longer. Values from 8 to 40 are the most effective.
+* Keep `MOUSEKEY_MOVE_DELTA` at 1.  This allows precise movements before the gliding effect starts.
+* Mouse wheel options are the same as the default accelerated mode, and do not use inertia.
+
 ## Use with PS/2 Mouse and Pointing Device
 
 Mouse keys button state is shared with [PS/2 mouse](feature_ps2_mouse.md) and [pointing device](feature_pointing_device.md) so mouse keys button presses can be used for clicks and drags.