chroma/README.md

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

# Check dependencies
make check-deps

# Build the daemon
make

# Or build debug version
make debug

Installation

# 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

# 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:

wlr-randr

Command Line Options

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

# Run in foreground
chroma

# Run as daemon
chroma --daemon

# Use custom config
chroma -c /path/to/config.conf

Systemd Service

# 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

# 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

make debug

Code Formatting

make format  # requires clang-format

Static Analysis

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

This project is made available under Mozilla Public License (MPL) version 2.0. See LICENSE for more details on the exact conditions. An online copy is provided here.