Better deadzones (#19)

Reviewed-on: #19
Co-authored-by: Anna Rose Wiggins <annabunches@gmail.com>
Co-committed-by: Anna Rose Wiggins <annabunches@gmail.com>

docs/examples/multiple_files/axes.yml

@@ -92,8 +92,9 @@ rules:
     input:
       device: left-stick
       axis: RY
-      deadzone_start: 0
-      deadzone_end: 30500
+      deadzones:
+        - start: 0
+          end: 30500
     output:
       device: mouse
       axis: REL_WHEEL
@@ -108,8 +109,9 @@ rules:
     input:
       device: left-stick
       axis: RY
-      deadzone_start: 29500
-      deadzone_end: 64000
+      deadzones:
+        - start: 29500
+          end: 64000
       inverted: true
     output:
       device: mouse

docs/examples/multiple_files/devices.yml

@@ -1,6 +1,6 @@
 devices:
   - name: primary
-    type: virtual
+    type: Virtual
     preset: joystick
   - name: secondary
     type: virtual

docs/examples/ruletypes.yml

@@ -18,8 +18,9 @@ rules:
     input:
       device: flightstick
       # To find reasonable values for your device's deadzones, use the evtest command
-      deadzone_start: 28000
-      deadzone_end: 30000
+      deadzones:
+        - start: 28000
+          end: 30000
       inverted: false
       axis: ABS_X
     output:
@@ -33,8 +34,9 @@ rules:
       # size value. This will create a deadzone that covers a range of deadzone_size,
       # centered on the center value. Note that if your deadzone_center is at the lower or upper end
       # of the axis, the total size will still be as given; the deadzone will be "shifted" into bounds.
-      deadzone_center: 29000
-      deadzone_size: 2000
+      deadzones:
+        - center: 29000
+          size: 2000
       inverted: false
       axis: Y # The ABS_ prefix is optional
     output:
@@ -46,8 +48,9 @@ rules:
       device: flightstick
       # A final way to specify deadzones is to use a size percentage instead of an absolute size.
       # This works exactly like deadzone_size, but calculates a percentage of the axis' total range.
-      deadzone_center: 29000
-      deadzone_size_percent: 5
+      deadzones:
+        - center: 29000
+          size_percent: 5
       inverted: false
       axis: Y # The ABS_ prefix is optional
     output:

docs/readme.md

@@ -73,13 +73,17 @@ evtest | grep BTN_
 
 **NOTE: For most axis mappings, you probably don't want to specify a deadzone!** Use deadzone configurations in your target game instead. Joyful-configured deadzones are intended to be used in conjunction with the `axis-to-button` and `axis-to-relaxis` input types, or when splitting an axis into multiple outputs. Using them with standard `axis` mappings may result in a loss of fidelity and "stuck" inputs.
 
-There are three ways to specify deadzones:
+Axis inputs can define a list of deadzones. Each deadzone can be specified a few ways:
 
-* Define `deadzone_start` and `deadzone_end` to explicitly set the deadzone bounds.
-* Define `deadzone_center` and `deadzone_size`; this will create a deadzone of the indicated size centered at the given axis position.
-* Define `deadzone_center` and `deadzone_size_percent` to use a percentage of the total axis size.
+* Define `start` and `end` to explicitly set the deadzone bounds.
+* Define `center` and `size`; this will create a deadzone of the indicated size centered at the given axis position.
+* Define `center` and `size_percent` to use a percentage of the total axis size.
 
-See <examples/ruletypes.yml> for usage examples.
+In addition, deadzones can set `emit` to `true` and `emit_value` to a value that should be emitted when inside the deadzone.
+
+**Note**: The `emit_value` is the final output value and should be between -32,768 and 32,767.
+
+See the <examples/> directory for usage examples.
 
 ## Modes