NotAShelf
55012e16f9
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: Ic45f39e98b73a0ec2e2ec8cbdcc2f5d66a6a6964
228 lines
5 KiB
Markdown
228 lines
5 KiB
Markdown
# Chroma
|
|
|
|
Super-fast, lightweight and efficient wallpaper daemon for Wayland compositors
|
|
with multi-monitor & hotplugging support. Born from my woes with Hyprpaper,
|
|
swaybg and most ironically _SWWW_ (now called AWWW for some awful reason), which
|
|
turned out to be NOT a solution to my Wayland wallpaper woes. Smaller, faster,
|
|
cleaner and somehow still more feature-rich...
|
|
|
|
## Features
|
|
|
|
Chroma combines simplicity with powerful performance optimizations and
|
|
comprehensive monitor management. Here's what makes Chroma stand out:
|
|
|
|
### Core Functionality
|
|
|
|
- **Memory-efficient**: Smart caching and resource management
|
|
- **Optimized rendering**: VBO dirty flagging and reduced GPU overhead
|
|
- **Multi-monitor support**: Automatically detects and manages wallpapers for
|
|
all connected displays
|
|
- **Configurable scaling modes**: Fill, fit, stretch, and center options per
|
|
monitor
|
|
- **Hotplugging**: Dynamically handles monitor connection/disconnection events
|
|
- **Per-output configuration**: Set different wallpapers and settings for each
|
|
monitor
|
|
- **Global and per-output settings**: Override defaults for specific monitors
|
|
- **Performance tuning**: Adjustable downsampling limits and quality
|
|
thresholds
|
|
- **Multiple image formats**: Supports JPEG, PNG, BMP, TGA, PSD, GIF, HDR, PIC,
|
|
PPM, PGM
|
|
- **EGL/OpenGL rendering**: Hardware-accelerated wallpaper rendering
|
|
- **Configuration file support**: Easy setup with INI-style config files
|
|
- **Signal handling**: Graceful shutdown and configuration reload (SIGHUP)
|
|
- **Intelligent downsampling**: Automatically reduces large image resolution to
|
|
save memory (up to 94% memory savings for 8K images)
|
|
- **Advanced filtering**: Nearest, linear, bilinear, and trilinear filtering
|
|
options
|
|
|
|
## Usage
|
|
|
|
### Requirements
|
|
|
|
#### Dependencies
|
|
|
|
- **Wayland**: wayland-client, wayland-egl
|
|
- **Graphics**: EGL, OpenGL
|
|
- **System**: glibc, libm, libdl
|
|
|
|
#### Development Dependencies
|
|
|
|
- GCC or Clang compiler
|
|
- Make
|
|
- pkg-config
|
|
- Wayland development headers
|
|
- EGL/OpenGL development headers
|
|
|
|
### Building
|
|
|
|
#### Quick Build
|
|
|
|
```bash
|
|
# Check dependencies
|
|
make check-deps
|
|
|
|
# Build the daemon
|
|
make
|
|
|
|
# Or build debug version
|
|
make debug
|
|
```
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Install to /usr/local (default)
|
|
sudo make install
|
|
|
|
# Install to /usr
|
|
sudo make PREFIX=/usr install
|
|
|
|
# Create systemd service file
|
|
make systemd-service
|
|
|
|
# Create sample configuration
|
|
make sample-config
|
|
```
|
|
|
|
### Configuration
|
|
|
|
#### Configuration File
|
|
|
|
Chroma looks for configuration files in this order:
|
|
|
|
1. `~/.config/chroma/chroma.conf`
|
|
2. `$XDG_CONFIG_HOME/chroma/chroma.conf`
|
|
3. `./chroma.conf` (current directory)
|
|
|
|
#### Sample Configuration
|
|
|
|
```ini
|
|
# Default wallpaper for outputs without specific mapping
|
|
default_image = ~/.config/chroma/default.jpg
|
|
|
|
# Output-specific wallpapers
|
|
# Format: output.OUTPUT_NAME = /path/to/image.jpg
|
|
output.DP-1 = ~/Pictures/monitor1.jpg
|
|
output.DP-2 = ~/Pictures/monitor2.png
|
|
output.HDMI-A-1 = ~/Pictures/hdmi_wallpaper.jpg
|
|
```
|
|
|
|
### Finding Output Names
|
|
|
|
Use `wlr-randr` or similar tools to find your output names:
|
|
|
|
```bash
|
|
wlr-randr
|
|
```
|
|
|
|
### Command Line Options
|
|
|
|
```plaintext
|
|
Usage: chroma [OPTIONS]
|
|
|
|
Options:
|
|
-c, --config FILE Configuration file path
|
|
-d, --daemon Run as daemon
|
|
-v, --verbose Verbose logging
|
|
-h, --help Show help
|
|
--version Show version information
|
|
|
|
Examples:
|
|
chroma -c ~/.config/chroma/chroma.conf
|
|
chroma --daemon
|
|
```
|
|
|
|
### Running Manually
|
|
|
|
```bash
|
|
# Run in foreground
|
|
chroma
|
|
|
|
# Run as daemon
|
|
chroma --daemon
|
|
|
|
# Use custom config
|
|
chroma -c /path/to/config.conf
|
|
```
|
|
|
|
### Systemd Service
|
|
|
|
```bash
|
|
# Enable and start the service
|
|
systemctl --user enable chroma.service
|
|
systemctl --user start chroma.service
|
|
|
|
# Check status
|
|
systemctl --user status chroma.service
|
|
|
|
# View logs
|
|
journalctl --user -u chroma.service -f
|
|
|
|
# Reload configuration
|
|
systemctl --user reload chroma.service
|
|
```
|
|
|
|
### Auto-start with Desktop Session
|
|
|
|
```bash
|
|
# Enable the service for auto-start
|
|
systemctl --user enable chroma.service
|
|
|
|
# The service will start automatically with your graphical session
|
|
```
|
|
|
|
### Supported Wayland Compositors
|
|
|
|
Chroma works with any Wayland compositor that supports:
|
|
|
|
- `wl_compositor` interface
|
|
- `wl_output` interface
|
|
- EGL window surface creation
|
|
|
|
Tested only on Hyprland.
|
|
|
|
## Development
|
|
|
|
### Building Debug Version
|
|
|
|
```bash
|
|
make debug
|
|
```
|
|
|
|
### Code Formatting
|
|
|
|
```bash
|
|
make format # requires clang-format
|
|
```
|
|
|
|
### Static Analysis
|
|
|
|
```bash
|
|
make analyze # requires cppcheck
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Test thoroughly
|
|
5. Submit a pull request
|
|
|
|
### Code Style
|
|
|
|
- C11 standard
|
|
- 2-space indentation
|
|
- No tabs (except for the Makefile, obviously)
|
|
- Function names: `chroma_function_name`
|
|
- Constants: `CHROMA_CONSTANT_NAME`
|
|
|
|
## License
|
|
|
|
<!--markdownlint-disable MD059 -->
|
|
|
|
This project is made available under Mozilla Public License (MPL) version 2.0.
|
|
See [LICENSE](LICENSE) for more details on the exact conditions. An online copy
|
|
is provided [here](https://www.mozilla.org/en-US/MPL/2.0/).
|
|
|
|
<!--markdownlint-enable MD059 -->
|