Update README.md

README.md

@@ -1,35 +1,39 @@
 # wpaperd
 
-![GitHub release (latest by date)](https://img.shields.io/github/v/release/danyspin97/wpaperd?logo=github&style=flat-square)
+![GitHub's release (latest by date)](https://img.shields.io/github/v/release/danyspin97/wpaperd?logo=github&style=flat-square)
 [![GitHub license](https://img.shields.io/github/license/danyspin97/wpaperd?logo=github&style=flat-square)](https://github.com/danyspin97/wpaperd/blob/main/LICENSE.md)
 ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/danyspin97/wpaperd/cargo.yml?branch=main&logo=github&style=flat-square)
 
-**wpaperd** is a minimal wallpaper daemon for Wayland. It allows the user to choose a different
-image for each output (aka for each monitor) just as *[swaybg]*. Moreover, a directory can be
-chosen and *wpaperd* will randomly choose an image from it. Optionally, the user can set a
-duration, after which the image displayed will be changed with another random one.
+**wpaperd** is the modern wallpaper daemon for Wayland. It dynamically changes the current wallpaper,
+either after a certain amount of time or via a command-line interface. It uses OpenGL ES to render
+the images and have beautiful hardware-accelerated transitions, while being easy on resources.
+
+*Notice*: wpaperd uses wayland protocols available on all wlroots based compositors (sway,
+hyprland, ...) and on KDE. **Therefore it won't work on GNOME.**
 
 ## Features
 
-- Choose your wallpaper for each input
-- Randomly choose an image from a directory
-- Change the random image after a set duration
-- Configurable via a TOML configuration file
-- Reload config at runtime and apply new settings
-- (optional) Apply a shadow on the top of the wallpaper
+- Different wallpaper for each display
+- Pick a wallpaper from a directory
+- Change the wallpaper after a set time
+- Multiple sorting methods (random or ordered)
+- Flexible TOML configuration file
+- Hot config reloading for all settings
+- Easy to use command line interface
+- Hardware-accelerated configurable transitions
+- Multiple background modes (center, fit, fill)
+- Easy on resources (low CPU and memory usage)
 
 ## Getting started
 
 ### Dependencies
 
-*wpaperd* is written entirely in Rust and, other than the crates it depends
-on, it has the following dependencies:
-
-- `pkg-config` (_build-time_)
-- `libxkbcommon`
+*wpaperd* is written in Rust and requires a working Cargo installation. It also depends on:
 
-It does not depend on `wayland-client` C library, but it instead uses a Rust
-implementation.
+- `mesa`
+- `wayland-client`
+- `wayland-egl`
+- `rinstall` (optional for installing `wpaperd`)
 
 ### Build
 
@@ -41,83 +45,113 @@ $ cd wpaperd
 $ cargo build --release
 ```
 
-### Install
-
-You can install the daemon (`wpaperd`) and cli (`wpaperctl`) using cargo:
+Generate the man pages by running `scdoc`:
 
 ```bash
-$ cargo install --path="./daemon" && cargo install --path="./cli"
+$ scdoc < man/wpaperd-output.5.scd > man/wpaperd-output.5
 ```
 
-Otherwise you can install it using rinstall:
+### Install
 
+You can install both the daemon (`wpaperd`) and cli (`wpaperctl`) using **rinstall**:
 ```bash
-# First generate the man page
-$ scdoc < man/wpaperd-output.5.scd > man/wpaperd-output.5
-$ rinstall -y
+$ rinstall --yes
 ```
 
-To run it, execute the `wpaperd` program:
+To run _wpaperd_, run the **daemon**:
 
 ```bash
 $ wpaperd
 ```
 
 If you want to automatically run it at startup, add this line to your sway configuration
-(located in `$HOME/.config/sway/config`) depending on your installation method:
+(located in `$HOME/.config/sway/config`):
+
+```
+# Assuming it has been installed in ~/.local/bin/wpaperd
+exec ~/.local/bin/wpaperd -d
+```
+
+Or in Hyprland:
 
 ```
-# For installation using cargo
-exec ~/.cargo/bin/wpaperd
-# For installation using rinstall
-exec ~/.local/bin/wpaperd
+exec-once=~/.local/bin/wpaperd -d
 ```
 
-## Images format support
+## Image formats support
 
-*wpaperd* relies on the `image` crate for loading and dislaying images. By default it
-supports for the following formats:
+loading and dislaying images. Have a look on its
+[documentation](https://github.com/image-rs/image/blob/main/README.md#supported-image-formats)
+for the supported formats.
 
-- `jpeg`
-- `png`
-- `webp`
+## Cycling images
 
-Optionally, support for `avif` images can be enabled by adding its respective feature:
+When `path` is set to a directory, you can cycle the images by running the commands `next` and
+`previous` using _wpaperctl_:
 
 ```bash
-$ cargo build --release --features avif
+$ wpaperctl next
+$ wpaperctl previous
 ```
 
+When `sorting` is set to `asceding` and `desceding`, _wpaperd_ will use the wallpaper name to
+calculate the next wallpaper accordingly. When `sorting` is set to `random`, it will store
+all the wallpapers shown in a queue, so that the commands `next` and `previous` can work
+as intended.
+
 ## Wallpaper Configuration
 
-The wallpaper configuration file for *wpaperd* is located in `XDG_CONFIG_HOME/wpaperd/wallpaper.toml`
-(which defaults to `$HOME/.config/wpaperd/wallpaper.toml`) and is a TOML file. Each section
-represents a different output and contains the following keys:
+The configuration file for *wpaperd* is located in `XDG_CONFIG_HOME/wpaperd/config.toml`
+(which defaults to `~/.config/wpaperd/config.toml`). Each section
+represents a different output and can contain the following keys:
 
-- `path`, path to the image/directory
+- `path`, path to the image to use as wallpaper or to a directory to pick the wallpaper from
 - `duration`, how much time the image should be displayed until it is changed with a new one.
+  It supports a human format for declaring the duration (e.g. `30s` or `10m`), described
+  [here](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html).
   This is only valid when path points to a directory. (_Optional_)
-- `apply-shadow`, apply a shadow on the top part of the image, to work as a shadow effect
-  of the status bar. This is particularly suited for window managers like sway. (_Optional_)
 - `sorting`, choose the sorting order. Valid options are `ascending`, `descending`, and `random`,
-  with the unspecified or default being `random` (_Optional_)
+  with the default being `random`. This is only valid when path points to a directory. (_Optional_)
+- `mode`, choose how to display the wallpaper when the size is different than the display
+  resolution:
+  - `fit` shows the entire image with black corners covering the empty space left
+  - `center` centers the image on the screen, leaving out the corners of the image that couldn't fit
+  - `stretch` shows the entire image stretching it to fit the entire screen without leaving any
+    black corner, changing the aspect ratio
+  - `tile` shows the image multiple times horizontally and vertically to fill the screen
+- `transition_time`, how many milliseconds should the transition run. (_Optional_, `300` by default).
+- `queue_size`, decide how big the queue should be when `path` is set a directory and `sorting` is
+   set to `random`. (_Optional_, `10` by default)
+
+The section `default` will be used as base for the all the display configuration; the section
+`any` will be used for all the displays that are not explictly listed. This allows to have a
+flexible configuration without repeating any settings. _wpaperd_ will check the configuration at
+startup and each time it changes and provide help when it is incorrect.
+
+This is the simplest configuration:
+
+```toml
+[DP-3]
+path = "/home/danyspin97/github_octupus.png"
+
+[DP-4]
+path = "/home/danyspin97/Wallpapers"
+duration = "30m"
+```
 
-The section `default` will be used as fallback for the all the outputs that aren't listed in
-the config file. This is an example configuration:
+This is a more complex configuration:
 
 ```toml
 [default]
-path = "/home/danyspin97/Pictures/Wallpapers/"
 duration = "30m"
+mode = "center"
 sorting = "ascending"
 
-[eDP-1]
-path = "/home/danyspin97/Pictures/Wallpapers/github_octupus.png"
-apply-shadow = true
+[any]
+path = "/home/danyspin97/default_wallpaper.png"
 
-[DP-2]
-path = "/home/danyspin97/Pictures/Landscapes/"
-sorting = "descending"
+[DP-3]
+path = "/home/danyspin97/Wallpapers"
 ```
 
 If you're running sway, you can look for the available outputs and their ID by running:
@@ -126,17 +160,11 @@ If you're running sway, you can look for the available outputs and their ID by r
 $ swaymsg -t get_outputs
 ```
 
-Every time you update the configuration while the program is running, the changes will
-be applied automatically.
-
-## TODO
-
-**wpaperd** is still a work in progress. The next things to do, in order, are:
+On Hyprland you can run:
 
-- [ ] Configurable upscaling algorithm, right now Lanzcos3 is always used
-- [ ] Add different modes to apply the wallpaper, i.e. `center`, `fit`, `original`
-- [ ] Add IPC and a client to control wpaperd
-- [ ] Update smithay-client-toolkit to next version (still unreleased)
+```bash
+$ hyprctl monitors
+```
 
 ## License