From 259f7e93b6f7b2de14ed5bde271082bb85ab800d Mon Sep 17 00:00:00 2001 From: Samuel Onoja Date: Sat, 3 Oct 2026 01:01:44 +0100 Subject: [PATCH] Document animation configuration and desktop comparisons --- README.md | 22 ++++++++++++++ docs/configuration.md | 70 ++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 91 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index bab8ecf..d22fc96 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,28 @@ Ferese combines a window manager and desktop shell with one configuration. - A built-in lock screen and authentication dialogs - Settings and Control Center with Wi-Fi, Bluetooth and audio controls +## How Ferese compares + +Ferese combines scrolling and tree layouts with its own desktop controls. The table +compares current upstream features and names separate tools where they are needed. + +| Feature | Ferese | [Hyprland](https://github.com/hyprwm/Hyprland) | [niri](https://github.com/niri-wm/niri) | +| --- | --- | --- | --- | +| Tiling layouts | Scrolling columns and tree tiling; switch per workspace | [Scrolling, dwindle, master and monocle; per-workspace layouts](https://github.com/hyprwm/Hyprland#features) | Scrolling columns | +| Floating windows | Built in | Built in | Built in | +| Workspace overview | Built in | Plugins such as [HyprExpo](https://github.com/sandwichfarm/hyprexpo) | Built in | +| Animations | Spring and easing animations | Bézier and spring curves | [Spring and easing animations; custom shaders](https://niri-wm.github.io/niri/Configuration:-Animations.html) | +| Live configuration reload | Yes | Yes | Yes | +| Monitor mirroring | Built in | [Built in](https://wiki.hypr.land/configuring/core/monitors/) | Separate tool, such as [wl-mirror](https://niri-wm.github.io/niri/Screencasting.html#screen-mirroring) | +| Desktop controls | Included Settings and Control Center | [Separate utilities](https://wiki.hypr.land/hypr-ecosystem/) or a desktop shell | [Separate desktop shell or tools](https://niri-wm.github.io/niri/Integrating-niri.html#desktop-components) | +| Notifications | Included in ferese-shell | [Separate notification daemon](https://wiki.hypr.land/Useful-Utilities/Must-have/) | [Separate notification daemon or shell](https://niri-wm.github.io/niri/Integrating-niri.html) | +| Lock screen | Included ferese-lock | Separate [hyprlock](https://wiki.hypr.land/Hypr-Ecosystem/hyprlock/) | Separate locker, such as [swaylock or hyprlock](https://niri-wm.github.io/niri/Integrating-niri.html) | +| Screen-sharing backend | xdg-desktop-portal-ferese | [xdg-desktop-portal-hyprland](https://wiki.hypr.land/Hypr-Ecosystem/xdg-desktop-portal-hyprland/) | [xdg-desktop-portal-gnome](https://niri-wm.github.io/niri/Screencasting.html#overview) | + +Ferese's shell, Settings, lock screen and dialogs use a shared theme. Other desktop +shells, including [DankMaterialShell and Noctalia](https://niri-wm.github.io/niri/Integrating-niri.html#desktop-components), +also include desktop controls; their features depend on the shell and tools you install. + ## Install Start with the [dependencies](docs/installation.md#requirements), then clone Ferese and diff --git a/docs/configuration.md b/docs/configuration.md index 0f8f755..62a0ad7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -112,7 +112,34 @@ the focused column. `paged` packs columns into viewport-sized pages: halves form form triples; mixed widths and client minimum sizes determine actual boundaries. Changing default width preserves manually resized columns. -## Motion +## Animations + +Set animation speed in Settings → Motion or edit the `animations` block in +`~/.config/ferese/config.kdl`. Changes apply live. Start with `speed` if you only +want faster or slower transitions; you do not need to change the springs. + +```kdl +animations { + enabled #true + reduced-motion #false + speed 1.0 + + spring { + mass 1.0 + stiffness 700.0 + damping 53.0 + } + + viewport-spring { + mass 1.0 + stiffness 320.0 + damping-ratio 1.0 + } +} +``` + +This example uses the built-in defaults. The packaged config sets `speed 0.9`. +You can omit either spring block to keep its defaults. | Section / key | Type | Default | Meaning | | --- | --- | --- | --- | @@ -126,6 +153,47 @@ Changing default width preserves manually resized columns. | `animations.viewport-spring.stiffness` | number > 0 | `320` | Scrolling stiffness | | `animations.viewport-spring.damping-ratio` | number > 0 | `1` | `1` is critically damped | +### Speed and reduced motion + +`speed` changes window motion, scrolling, workspace transitions, overview, +theme transitions and shell popup, notification and hover transitions. `0.5` +gives an animation twice as much time; `2.0` gives it half as much. Overview +uses 60% of this speed when opening or closing, including when selecting a +window. There is no separate overview-speed setting. + +Set `reduced-motion #true` or `enabled #false` to make these transitions +immediate. Reduced motion takes precedence over `enabled #true`; setting +`speed 0` is invalid. These settings control Ferese's animations, not animations +inside other applications. + +### Spring tuning + +`spring` controls window position and size motion, fullscreen/maximize zoom and +overview entrance motion. `viewport-spring` controls the scrolling viewport and +the column-width animation that runs with it. Shell popups and theme fades use +timed transitions, so the spring parameters do not change their curves. + +Spring motion has no fixed duration. Its settling time depends on the distance +to the target, current velocity and the spring parameters. The `animations` +block has no settings for per-animation durations, custom curves or animation +shaders. + +With the other parameters unchanged, higher stiffness makes motion faster and +higher mass makes it slower. Damping controls how quickly velocity dies away. +The default window spring is slightly overdamped, close to critical damping; +the viewport spring is critically damped. + +For `viewport-spring`, `damping-ratio 1.0` is critical damping, values below `1` +are underdamped and values above `1` are overdamped. The window spring uses a +damping coefficient instead: critical damping is +`damping = 2 * sqrt(stiffness * mass)`. Ferese stops spring animations +at their first target crossing, so lowering damping does not make them bounce +past the target. + +Mass, stiffness, damping ratio and speed must be finite and greater than zero. +The window spring's damping coefficient may also be zero. Invalid edits leave +the last accepted configuration active. + ## Appearance Settings → Appearance offers six paired themes: **Ferese Blue** (default),