High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Kaleidux is a high-performance, hardware-accelerated wallpaper daemon for Linux systems, supporting both Wayland and X11 backends. The architecture is designed to provide smooth visual transitions between image and video content with near-zero CPU overhead by leveraging modern graphics APIs and efficient asset pipelines.
The system follows a client-server model where a background daemon (kaleidux-daemon) manages the rendering and state, while a CLI utility (kldctl) communicates via a Unix domain socket to control behavior. The project is structured as a Rust workspace to maintain a clean separation between the daemon, the controller, and shared protocol definitions.
Sources: README.md:15-25, CONTRIBUTING.md:100-115
Core System Components
The project is divided into three primary crates within the workspace:
| Component | Crate Name | Purpose |
|---|---|---|
| Daemon | kaleidux-daemon | The background service responsible for WGPU rendering, video playback via GStreamer, and output management. |
| Controller | kldctl | A CLI tool that sends JSON-encoded requests to the daemon's IPC socket. |
| Common | kaleidux-common | Shared data structures, IPC request/response types, and transition definitions. |
Sources: Cargo.toml:1-6, CONTRIBUTING.md:110-120
Workspace Layout
This diagram illustrates the relationship between the workspace crates and the external interfaces used for control and rendering.
Sources: CONTRIBUTING.md:100-115, kaleidux-daemon/src/main.rs:430-450
Rendering Pipeline
Kaleidux utilizes WGPU for its rendering engine, ensuring hardware acceleration for all visual effects. The pipeline is designed to handle different content types (Images and Videos) and apply complex GLSL transitions between them.
- WGPU Integration: Uses
WGPUfor near-zero CPU overhead during transitions. - Shader Management: Compiles GLSL transitions into WGSL for cross-backend compatibility.
- Video Playback: Integrated GStreamer for seamless video looping and frame extraction.
- Memory Management: Implements a texture pool to reuse GPU resources and a semaphore to limit concurrent image decoding tasks.
Sources: README.md:30-40, kaleidux-daemon/src/main.rs:18-22, kaleidux-daemon/src/shaders.rs:85-110
Wallpaper Transition Logic
When a content switch occurs, the daemon offloads heavy tasks to background threads to keep the main event loop responsive.
The transition process ensures that decoding does not block the frame-critical rendering loop.
Sources: kaleidux-daemon/src/main.rs:60-120, kaleidux-daemon/src/shaders.rs:15-35
Orchestration and Multi-Monitor Support
The orchestration and monitor_manager modules coordinate behavior across multiple displays. Kaleidux supports three distinct monitor behaviors:
- Independent: Each monitor operates its own wallpaper queue and timing.
- Synchronized: All monitors switch wallpapers simultaneously.
- Grouped: Specified sets of monitors share the same wallpaper state.
Sources: kaleidux-daemon/src/orchestration.rs:10-16, README.md:43-46
Configuration Hierarchy
The daemon parses a TOML configuration (usually at ~/.config/kaleidux/config.toml) using a layered approach:
- Global: Sets default behaviors like sorting strategies and transition times.
- Any: Provides a fallback configuration for any output not explicitly named.
- Per-Output: Uses specific output names (e.g., "DP-1") or Regex matching (e.g., "re:Dell.*") to override settings.
Sources: kaleidux-daemon/src/orchestration.rs:90-115, config.example.toml:1-50
Inter-Process Communication (IPC)
The daemon listens on a Unix Domain Socket (path determined by XDG_RUNTIME_DIR or /tmp). The protocol is based on JSON-serialized Request and Response enums defined in kaleidux-common.
IPC Commands Summary
| Command | Request Type | Description |
|---|---|---|
next | Request::Next | Skips to the next wallpaper in the queue. |
query | Request::QueryOutputs | Returns a list of connected outputs and their current content. |
love | Request::Love | Increases the selection frequency of a specific file in the loveit sorting strategy. |
reload | Request::Reload | Forces the daemon to re-parse the configuration file. |
pause/resume | Request::Pause | Controls GStreamer video playback. |
Sources: kldctl/src/main.rs:200-250, kaleidux-daemon/src/main.rs:430-465, README.md:85-110
Metrics and Performance Monitoring
To maintain the "high-performance" requirement, Kaleidux includes a dedicated PerformanceMetrics system that tracks various telemetry data points:
- Frame Timing: Records p50, p95, and p99 frame times in milliseconds.
- Resource Tracking: Monitors texture pool hits/misses and active pipeline counts to detect resource leaks.
- Startup Benchmarking: Measures GStreamer and WGPU initialization times.
- Memory/GPU Profiling: Samples system resource usage to ensure the daemon remains lightweight over long runtimes.
Sources: kaleidux-daemon/src/metrics.rs:10-50, kaleidux-daemon/src/metrics.rs:370-400
Conclusion
The architecture of Kaleidux prioritizes aesthetic fluidity and system efficiency. By combining a Rust-based daemon for safety and speed, WGPU for hardware-accelerated transitions, and a robust IPC system for external control, the project provides a modern solution for dynamic desktop backgrounds on Linux. The modular design allows for easy expansion of transition effects and support for complex multi-monitor configurations.
Sources: CONTRIBUTING.md:280-290, README.md:10-15