From 8f1555cdcb559879abb357ae7cd945332ae21f5f Mon Sep 17 00:00:00 2001 From: Danilo Spinella Date: Mon, 15 Apr 2024 12:10:54 +0200 Subject: [PATCH] Update README.md --- README.md | 160 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 94 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 9309b92..3564e19 100644 --- a/README.md +++ b/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