update ramp effect documentation

1 files changed, 230 insertions, 27 deletions

diff --git a/docs/FFBEFFECTS.md b/docs/FFBEFFECTS.md
index 93dbb80..60b2e50 100644
--- a/docs/FFBEFFECTS.md
+++ b/docs/FFBEFFECTS.md
@@ -190,14 +190,70 @@ have model specific peculiarities, though.
 
 Ramps seem to follow triangle wave parameters.
 
+```
+00001110 00000001 0e 01 - slope
+00001110 00000010 0e 02 - center
+01001001          49    - invert
+00001110 00000011 0e 03 - slope + center
+01001110 00000001 4e 01 - slope + invert
+01001110 00000011 4e 03 - slope + center + invert
+01001110 00001000 4e 08 - duration
+01001001          49    - offset
+01001110 00001000 4e 08 - duration + offset
+00110001 10000001 31 81 - envelope attack length
+00110001 10000010 31 82 - envelope attack level
+00110001 10000100 31 84 - envelope fade length
+00110001 10001000 31 88 - envelope fade level
+00101001          29    - envelope (all)
+01110110 00000011 76 03 - envelope attack & fade length + slope + center + invert
+00101110 00000011 2e 03 - envelope + slope + center + invert
+01101110 00001011 6e 0b - duration + offset + envelope + slope + center + invert
+```
+
+### Notes
+
+#### Invert
+
+There is a bug in the Windows driver during the Ramp effect update.
+If the update requires inverting the effect and the duration or the offset is
+not changed, the effect just stops.
+
+This can be fixed by adding the `update type` byte with the value of `40`.
+
+Affected examples:
+ - slope + invert
+ - slope + center + invert
+ - invert
+ - envelope attack & fade length + slope + center + invert
+ - envelope + slope + center + invert
+
+Example:
+```
+Invalid:
+    60 00 - standard header
+    01 - ID
+    49
+    05 - effect type?
+    00 <- missing "update type"
+    [...]
+
+Valid:
+    60 00 - standard header
+    01 - ID
+    49
+    05 - effect type?
+    40 - update type <- correct update type
+    [...]
+```
+
+
 ### Init:
 ```
     60 00 - standard header
     01 - ID
     6b - new ramp effect
-    f6 7f - difference ***
-    fe ff - level? *** (level = (if end_level > start_level, end_level, else
-        start_level) - difference?) (signed)
+    f6 7f - slope *** abs(start - stop) / 2
+    fe ff - center *** (start + end) / 2 (signed)
     00 00
     f7 17 - time
     00 80 - some kind of marker
@@ -216,53 +272,200 @@ Ramps seem to follow triangle wave parameters.
 ```
 
 ### Modifying:
+
 ```
+center: 
+    60 00 - standard header
+    01 - ID
+    0e 02
+    1e 40 - center
+    00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+slope + invert:
+    This packet is affected by the "invert" driver bug. See Notes above.
+
+    60 00 - standard header
+    01 - ID
+    4e 01
+    20 00 - slope
+    04 - effect type? (invert) 04 or 05
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+slope + center + invert:
+    This packet is affected by the "invert" driver bug. See Notes above.
+
     60 00 - standard header
     01 - ID
-    0e - ???
-    03 - ramp?
-    e3 04 - difference?
-    7d 75 - "level"?
-    05 - ????
+    4e 03
+    06 00 - slope
+    25 40 - center
+    04 - effect type? (invert) 04 or 05
     00 00 00 00 00 00
     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 ```
 
-#### Envelope:
+#### Duration, offset, invert:
+
 ```
+duration:
     60 00 - standard header
     01 - ID
-    31 - modify envelope
-    84 - ID of envelope attribute ( attack_level 82,
-                                    attack_length 81,
-                                    fade_level 88,
-                                    fade_length 84 )
-    63 04 - value attribute should be set to
-    00 00 00 00 00 00 00 00 00
+    4e 08
+    88 13 - duration
+    04 - effect type? must reflect the actual inversion 04 or 05
+    41 - update type
+    88 13 - duration
+    00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+offset:
+    60 00 - standard header
+    01 - ID
+    49
+    04 - effect type? must reflect the actual inversion 04 or 05
+    44 - update type
+    00 00 - offset
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+duration + offset:
+    60 00 - standard header
+    01 - ID
+    4e 08
+    88 13 - duration
+    04 - effect type? must reflect the actual inversion 04 or 05
+    45 - update type
+    88 13 - duration
+    00 00 - offset
+    00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+dir + offset:
+    60 00 - standard header
+    01 - ID
+    49
+    05 - effect type? must reflect the actual inversion 04 or 05
+    44 - update type
+    00 00 - offset
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+invert:
+    This packet is affected by the "invert" driver bug. See Notes above.
+
+    60 00 - standard header
+    01 - ID
+    49
+    05 - effect type? invert 04 or 05
+    00 00 00 00 00 00 00 00 00 00 00
     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 ```
 
-#### Duration:
-```     
-    60 00
+#### Envelope:
+
+```
+envelope attack/fade level/length:
+    multiple values can be updated with one packet
+
+    60 00 - standard header
     01 - ID
-    4e - ?
-    08 - ?
-    01 00 - time in milliseconds
-    05 - ?
-    41 - ?
-    01 00 - time in milliseconds
-    00 00 00 00 00
+    31 85
+    d0 07 - attack length
+    dc 05 - fade length
+    00 00 00 00 00 00 00
     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+envelope (all):
+    60 00 - standard header
+    01 - ID
+    29
+    d0 07 - attack length
+    69 34 - attack level
+    dc 05 - fade length
+    32 1a - fade level
+    00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+```
+
+#### Combined:
+
 ```
+envelope attack & fade length + slope + center + invert:
+    This packet is affected by the "invert" driver bug. See Notes above.
+
+    60 00 - standard header
+    01 - ID
+    76 03
+    06 00 - slope
+    25 40 - center
+    85 - envelope update type
+    d0 07 - attack length
+    dc 05 - fade length
+    04 - effect type? (invert) 04 or 05
+    00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+envelope + slope + center + invert:
+    This packet is affected by the "invert" driver bug. See Notes above.
 
-#### Offset: `N/A`
+    60 00 - standard header
+    01 - ID
+    6e 03
+    06 00 - slope
+    25 40 - center
+    d0 07 - attack length
+    69 34 - attack level
+    dc 05 - fade length
+    32 1a - fade level
+    04 - effect type? (invert) 04 or 05
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+duration + offset + envelope + slope + center + invert:
+    60 00 - standard header
+    01 - ID
+    6e 0b
+    06 00 - slope
+    25 40 - center
+    88 13 - length
+    d0 07 - attack length
+    69 34 - attack level
+    dc 05 - fade length
+    32 1a - fade level
+    04 - effect type? (invert) 04 or 05
+    45 - update type
+    88 13 - length 2
+    00 00 - offset
+    00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+```
 
 ## FF_DAMPER + FF_FRICTION + FF_INERTIA + FF_SPRING:
 ### Init: