Completed implementation and testing of mouse axis mapper parsing fro…

…m a configuration file. Updated documentation.

DEVELOPERS.md

@@ -95,6 +95,13 @@ Behavior is very similar to ButtonMapper in terms of the logic. However, instead
 This type of mapper is considered to have a side effect because, unlike other types, it does not not contribute directly to virtual controller state but rather to the keyboard state. As a result it implements `ContributeNeutral` so that associated keyboard buttons can be released in the absence of input from the controller.
 
 
+##### MouseAxisMapper
+
+Behavior and implementation is similar to AxisMapper and DigitalAxisMapper. However, instead of a virtual controller axis, this type of element mapper simulates motion of the system mouse along one of the four supported axes (X, Y, horizontal mouse wheel, vertical mouse wheel).
+
+This mapper uses an opaque source identifier to allow the Mouse module to aggregate across all possible sources of mouse input for the purpose of determining the net contribution Xidi will make at any given time to movement of the system mouse. Unlike virtual controller motion, mouse movement is always relative.
+
+
 ##### MouseButtonMapper
 
 Behavior and implementation is extremely similar to KeyboardMapper. However, instead of a virtual keyboard key, this type of element mapper simulates a mouse button press on the system mouse.
@@ -196,7 +203,7 @@ Source code documentation is available and can be built using Doxygen. This sect
 
 **MapperParser** implements all string-parsing functionality for identifying XInput controller elements, identifying force feedback actuators, and constructing both of these types of objects based on strings contained within a configuration file.
 
-**Mouse** tracks virtual mouse state as reported by any `MouseButtonMapper` objects that may exist. It maintains state information for each possible mouse button and periodically submits mouse events to the system using the `SendInput` Windows API function.
+**Mouse** tracks virtual mouse state as reported by any `MouseAxisMapper` and `MouseButtonMapper` objects that may exist. It maintains state information for each possible mouse axis and button, periodically submitting mouse events to the system using the `SendInput` Windows API function. For mouse axes, this module keeps track of movement contributions from all physical sources, aggregates across them using summation, and appropriately converts from the absolute position scheme reported by game controllers to the relative motion scheme that Windows uses for mouse movement.
 
 **PhysicalController** manages all communication with the underlying XInput API. It periodically polls devices for changes to physical state and supports notifying other modules whenever a physical state change is detected.
 

README.md

@@ -48,7 +48,7 @@ The remainder of this document is organized as follows.
 
 # Getting Started
 
-1. Ensure the system is running Windows 10 or 11. Xidi is built to target Windows 10 or 11 and does not support older versions of Windows.
+1. Ensure the system is running Windows 10 or 11. Xidi is built to target Windows 10 or 11 and may not run correctly on older versions of Windows.
 
 1. Ensure the [Visual C++ Runtime for Visual Studio 2022](https://docs.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) is installed. Xidi is linked against this runtime and will not work without it. If running a 64-bit operating system, install both the x86 and the x64 versions of this runtime, otherwise install just the x86 version.
 
@@ -517,7 +517,33 @@ ButtonBack          = Keyboard(Esc)
 ```
 
 
-#### MouseButton *(unreleased)*
+#### MouseAxis
+
+A mouse axis element mapper links an XInput controller element to mouse movement along one of the possible mouse axes. It otherwise behaves very similarly to an axis mapper.
+
+MouseAxis requires a parameter specifying the mouse motion axis to which to link. Supported axis names are `X`, `Y`, `WheelHorizontal`, `WheelVertical`; the first two correspond to physical mouse movement, and the second two correspond to rotation of the scroll wheel that is present on some mouse hardware. A second optional parameter is additionally allowed to specify the axis direction, either `+` or `-` (alternative values `Positive` and `Negative` are also accepted).
+
+As an example, the below configuration links the right stick and the d-pad to mouse cursor movement.
+
+```ini
+[CustomMapper:MouseAxisExample]
+
+; This example is not complete.
+; It only defines element mappers for a small subset of controller elements.
+
+; For the right stick one mouse axis maps entirely to an analog controller axis.
+StickRightX         = MouseAxis(X)
+StickRightY         = MouseAxis(Y)
+
+; For the d-pad one button corresponds to a different direction of motion.
+DpadUp              = MouseAxis(Y, -)
+DpadDown            = MouseAxis(Y, +)
+DpadLeft            = MouseAxis(X, -)
+DpadRight           = MouseAxis(X, +)
+```
+
+
+#### MouseButton
 
 A mouse button element mapper links an XInput controller element to a mouse button. It behaves very similarly to a keyboard element mapper except it acts on a mouse button rather than on a keyboard key.