Implement spring animations

1 files changed, 35 insertions, 7 deletions

diff --git a/resources/default-config.kdl b/resources/default-config.kdl
index 616cd48f..bacf7983 100644
--- a/resources/default-config.kdl
+++ b/resources/default-config.kdl
@@ -254,18 +254,48 @@ animations {
     // slowdown 3.0
 
     // You can configure all individual animations.
-    // Available settings are the same for all of them:
+    // Available settings are the same for all of them.
     // - off disables the animation.
+    //
+    // Niri supports two animation types: easing and spring.
+    //
+    // Easing has the following settings:
     // - duration-ms sets the duration of the animation in milliseconds.
     // - curve sets the easing curve. Currently, available curves
     //   are "ease-out-cubic" and "ease-out-expo".
+    //
+    // Spring animations work better with touchpad gestures, because they
+    // take into account the velocity of your fingers as you release the swipe.
+    // The parameters are less obvious and generally should be tuned
+    // with trial and error. Notably, you cannot directly set the duration.
+    // You can use this app to help visualize how the spring parameters
+    // change the animation: https://flathub.org/apps/app.drey.Elastic
+    //
+    // A spring animation is configured like this:
+    // - spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
+    //
+    // The damping ratio goes from 0.1 to 10.0 and has the following properties:
+    // - below 1.0: underdamped spring, will oscillate in the end.
+    // - above 1.0: overdamped spring, won't oscillate.
+    // - 1.0: critically damped spring, comes to rest in minimum possible time
+    //        without oscillations.
+    //
+    // However, even with damping ratio = 1.0 the spring animation may oscillate
+    // if "launched" with enough velocity from a touchpad swipe.
+    //
+    // Lower stiffness will result in a slower animation more prone to oscillation.
+    //
+    // Set epsilon to a lower value if the animation "jumps" in the end.
+    //
+    // The spring mass is hardcoded to 1.0 and cannot be changed. Instead, change
+    // stiffness proportionally. E.g. increasing mass by 2x is the same as
+    // decreasing stiffness by 2x.
 
     // Animation when switching workspaces up and down,
     // including after the touchpad gesture.
     workspace-switch {
         // off
-        // duration-ms 250
-        // curve "ease-out-cubic"
+        // spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
     }
 
     // All horizontal camera view movement:
@@ -275,8 +305,7 @@ animations {
     // - And so on.
     horizontal-view-movement {
         // off
-        // duration-ms 250
-        // curve "ease-out-cubic"
+        // spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
     }
 
     // Window opening animation. Note that this one has different defaults.
@@ -290,8 +319,7 @@ animations {
     // open/close animation.
     config-notification-open-close {
         // off
-        // duration-ms 250
-        // curve "ease-out-cubic"
+        // spring damping-ratio=0.6 stiffness=1000 epsilon=0.001
     }
 }