Introduction to Kaleidux
Relevant source files
The following files were used as context for generating this wiki page:
Kaleidux is a high-performance, hardware-accelerated wallpaper daemon specifically designed for Linux environments. It supports both Wayland and X11 display protocols, leveraging the WGPU graphics API to provide smooth, near-zero CPU overhead during wallpaper transitions. The system is built to handle dynamic desktop backgrounds, including high-quality images and seamless video loops powered by the GStreamer framework.
The project follows a modular architecture divided into a background daemon (kaleidux-daemon), a command-line controller (kldctl), and a shared library for protocol definitions (kaleidux-common). Beyond simple wallpaper rotation, Kaleidux features an extensive library of over 50 GLSL transitions, a Rhai-based scripting engine for automation, and sophisticated multi-monitor management that allows for independent, synchronized, or grouped monitor behaviors.
Sources: README.md:20-35, CONTRIBUTING.md:120-140, kaleidux-daemon/src/main.rs:200-220
System Architecture
Kaleidux is structured as a Rust workspace containing three primary components that interact to manage the wallpaper lifecycle, from file discovery and caching to rendering and IPC control.
Component Overview
| Component | Responsibility | Key Technologies |
|---|---|---|
| kaleidux-daemon | Core service handling rendering, video playback, and monitor orchestration. | WGPU, GStreamer, Tokio, Wayland-client, X11rb |
| kldctl | CLI utility for sending commands (next, prev, love, reload) to the daemon. | Clap, Serde, UnixStream |
| kaleidux-common | Shared types, IPC protocol definitions, and common transition logic. | Serde, Bincode |
Sources: CONTRIBUTING.md:125-145, Cargo.toml:1-15
High-Level Architecture Diagram
The following diagram illustrates the relationship between the user, the control utility, and the core daemon subsystems.
This diagram shows the flow of commands from the user through the IPC layer into the core daemon logic.
Sources: CONTRIBUTING.md:120-135, kaleidux-daemon/src/main.rs:430-460, kaleidux-daemon/src/cache.rs:15-30
Core Subsystems
Rendering Pipeline
The renderer uses WGPU to manage hardware-accelerated drawing. It utilizes a transition system where two textures (previous and next wallpaper) are blended using specialized GLSL shaders. The system supports aspect ratio "cover" logic to ensure wallpapers fit various screen resolutions correctly without distortion.
- Shader Management: Shaders are compiled from GLSL to WGSL via the
nagacrate. The system includes aGLSL_PRELUDEthat defines uniform bindings for progress, aspect ratios, and parametric variables. - Asset Loading: Images are decoded using a thread-pool limited by a semaphore to prevent memory spikes, while video frames are uploaded directly to GPU textures from GStreamer appsinks.
Sources: kaleidux-daemon/src/main.rs:25-45, kaleidux-daemon/src/shaders.rs:3-50, kaleidux-daemon/src/main.rs:275-310
Monitor and Queue Management
Kaleidux supports three primary monitor behaviors:
- Independent: Each monitor maintains its own separate wallpaper queue.
- Synchronized: All monitors display the same content simultaneously.
- Grouped: Specific monitors are linked to share a single queue.
The Queue Manager utilizes a "Loveit" sorting strategy by default, which performs weighted random selection based on popularity (the love command) and recency.
Sources: config.example.toml:15-35, kldctl/src/main.rs:80-100
IPC and Control
The kldctl utility communicates with kaleidux-daemon via a Unix domain socket located at XDG_RUNTIME_DIR/kaleidux.sock (or /tmp/kaleidux-{USER}.sock). Communication involves JSON-encoded requests and responses.
Common IPC Requests:
Next { output }: Skips to the next wallpaper.Love { path, multiplier }: Increases the selection frequency of a specific file.QueryOutputs: Returns status, resolution, and current wallpaper for all connected screens.
Sources: kldctl/src/main.rs:170-220, kaleidux-daemon/src/main.rs:445-470
Data Flow: Content Switching
When a wallpaper change is triggered (either by a timer or user command), the daemon executes a complex sequence to ensure a smooth transition between different media types.
This sequence illustrates how the system handles the transition from selection to GPU presentation for both images and video.
Sources: kaleidux-daemon/src/main.rs:75-150, kaleidux-daemon/src/main.rs:315-340
Performance Monitoring
The system includes a dedicated PerformanceMetrics module that tracks the health and efficiency of the daemon. This data is logged periodically and can be queried to detect potential issues like resource leaks.
| Metric Type | Tracked Data |
|---|---|
| Frame Timing | Average, p50, p95, and p99 frame times in milliseconds. |
| Resource Counts | Active texture counts and compiled pipeline counts. |
| CPU Utilization | Time spent in rendering, video decoding, and file discovery. |
| Memory | Current MB usage, peak usage, and growth rate. |
Sources: kaleidux-daemon/src/metrics.rs:5-60, kaleidux-daemon/src/metrics.rs:480-510
Configuration and Scripting
The system is configured via a TOML file (default ~/.config/kaleidux/config.toml). It allows for global settings and specific per-output overrides using monitor names or regex patterns for monitor descriptions.
Additionally, Kaleidux integrates the Rhai scripting engine. Users can provide a .rhai script path in the configuration to automate wallpaper logic, such as changing backgrounds based on time of day, system load, or other external triggers.
Sources: config.example.toml:1-60, kaleidux-daemon/src/main.rs:415-430, Cargo.toml:18-20
Conclusion
Kaleidux represents a sophisticated approach to Linux desktop aesthetics, prioritizing hardware acceleration and extensibility. By combining a WGPU-based rendering pipeline with GStreamer and a flexible IPC control system, it provides a performant foundation for both simple and complex dynamic wallpaper setups. Its architecture ensures that even with intensive video loops and complex GLSL transitions, desktop responsiveness remains uncompromised.
Sources: README.md:130-140, PROJECT_STANDARDS.md:15-25