diff options
Diffstat (limited to 'wiki')
| -rw-r--r-- | wiki/Configuration:-Animations.md | 152 | ||||
| -rw-r--r-- | wiki/_Sidebar.md | 1 |
2 files changed, 153 insertions, 0 deletions
diff --git a/wiki/Configuration:-Animations.md b/wiki/Configuration:-Animations.md new file mode 100644 index 00000000..5a397de8 --- /dev/null +++ b/wiki/Configuration:-Animations.md @@ -0,0 +1,152 @@ +### Overview + +Niri has several animations which you can configure in the same way. +Additionally, you can disable or slow down all animations at once. + +Here's a quick glance at the available animations with their default values. + +``` +animations { + // Uncomment to turn off all animations. + // You can also put "off" into each individual animation to disable it. + // off + + // Slow down all animations by this factor. Values below 1 speed them up instead. + // slowdown 3.0 + + // Individual animations. + + workspace-switch { + spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001 + } + + horizontal-view-movement { + spring damping-ratio=1.0 stiffness=800 epsilon=0.0001 + } + + window-open { + duration-ms 150 + curve "ease-out-expo" + } + + config-notification-open-close { + spring damping-ratio=0.6 stiffness=1000 epsilon=0.001 + } +} +``` + +### Animation Types + +There are two animation types: easing and spring. +Each animation can be either an easing or a spring. + +#### Easing + +This is a common animation type that changes the value over a set duration using a Bézier curve. + +To use this animation, set the following parameters: + +- `duration-ms`: duration of the animation in milliseconds. +- `curve`: the easing curve to use. + +Currently, niri only supports two curves: `ease-out-cubic` and `ease-out-expo`. +You can get a feel for them on pages like [easings.net](https://easings.net/). + +#### Spring + +Spring animations use a model of a physical spring to animate the value. +They notably feel better with touchpad gestures, because they take into account the velocity of your fingers as you release the swipe. +Springs can also oscillate / bounce at the end with the right parameters if you like that sort of thing, but they don't have to (and by default they mostly don't). + +Due to springs using a physical model, the animation parameters are less obvious and generally should be tuned with trial and error. +Notably, you cannot directly set the duration. +You can use the [Elastic](https://flathub.org/apps/app.drey.Elastic) app to help visualize how the spring parameters change the animation. + +A spring animation is configured like this, with three mandatory parameters: + +``` +animations { + workspace-switch { + 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" at the end. + +> [!TIP] +> The spring *mass* (which you can see in Elastic) is hardcoded to 1.0 and cannot be changed. +> Instead, change `stiffness` proportionally. +> E.g. increasing mass by 2× is the same as decreasing stiffness by 2×. + +### Animations + +Now let's go into more detail on the animations that you can configure. + +#### `workspace-switch` + +Animation when switching workspaces up and down, including after the vertical touchpad gesture (a spring is recommended). + +``` +animations { + workspace-switch { + spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001 + } +} +``` + +#### `horizontal-view-movement` + +All horizontal camera view movement animations, such as: + +- When a window off-screen is focused and the camera scrolls to it. +- When a new window appears off-screen and the camera scrolls to it. +- When a window resizes bigger and the camera scrolls to show it in full. +- After a horizontal touchpad gesture (a spring is recommended). + +``` +animations { + horizontal-view-movement { + spring damping-ratio=1.0 stiffness=800 epsilon=0.0001 + } +} +``` + +#### `window-open` + +Window opening animation. + +This one uses an easing type by default. + +``` +animations { + window-open { + duration-ms 150 + curve "ease-out-expo" + } +} +``` + +#### `config-notification-open-close` + +The open/close animation of the config parse error and new default config notifications. + +This one uses an underdamped spring by default (`damping-ratio=0.6`) which causes a slight oscillation in the end. + +``` +animations { + config-notification-open-close { + spring damping-ratio=0.6 stiffness=1000 epsilon=0.001 + } +} +``` diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md index e4180beb..eb451bfd 100644 --- a/wiki/_Sidebar.md +++ b/wiki/_Sidebar.md @@ -9,6 +9,7 @@ * [Overview](./Configuration:-Overview.md) * [Input](./Configuration:-Input.md) * [Window Rules](./Configuration:-Window-Rules.md) +* [Animations](./Configuration:-Animations.md) ## Development * [Design Principles](./Design-Principles.md) |