GLSL Transitions & Shaders

Relevant source files

The following files were used as context for generating this wiki page:

• kaleidux-daemon/src/shaders.rs
• kaleidux-daemon/src/renderer.rs
• kaleidux-daemon/src/main.rs
• kaleidux-daemon/src/metrics.rs
• config.example.toml
• README.md

Kaleidux utilizes a hardware-accelerated rendering pipeline powered by WGPU to deliver smooth, high-performance wallpaper transitions. The system supports over 50 built-in GLSL shaders, allowing for visually rich effects like cross-zooms, cubes, and ripples with near-zero CPU overhead.

The shader system is responsible for compiling GLSL code into WGSL (WebGPU Shading Language), mapping user-defined parameters from configuration files to shader uniforms, and managing the lifecycle of render pipelines and textures.

Sources: README.md:16-25, kaleidux-daemon/src/shaders.rs:1-10, kaleidux-daemon/src/renderer.rs:250-260

Shader Architecture & Compilation

The core of the shader system resides in the ShaderManager. It handles the transformation of standard GLSL transition code into a format compatible with the WGPU backend. This involves prepending a standard GLSL prelude, defining uniforms, and converting the final module to WGSL using the naga crate.

Compilation Pipeline

When a transition is requested, the system performs the following steps:

1. Prelude Injection: Attaches GLSL_PRELUDE, which defines common inputs like v_uv, t_prev, t_next, and the TransitionUniforms block.
2. Parameter Mapping: Converts configuration parameters into #define statements or variable assignments.
3. Uniform Stripping: Removes standard GLSL uniform declarations from user code to prevent binding conflicts during Naga parsing.
4. Validation & Translation: Uses naga to parse the GLSL, validate it against hardware capabilities, and emit the final WGSL code.

The diagram shows the transformation flow from a raw GLSL source to the validated WGSL used by the WGPU renderer.
Sources: kaleidux-daemon/src/shaders.rs:43-118, kaleidux-daemon/src/renderer.rs:400-450

Renderer Integration

The Renderer struct manages the active transition state, including progress tracking and texture swapping. It uses a composition texture to render the transition effect before blitting the final result to the screen surface.

Transition Data Flow

Transitions are triggered by a switch_content call, which moves the current wallpaper texture to a "previous" slot and prepares a new "current" slot. The renderer then increments a progress value from 0.0 to 1.0 over the configured duration.

Component	Description
TransitionUniforms	C-compatible struct containing progress, aspect ratios, and 28 float parameters.
PipelineLRU	A Least Recently Used cache for wgpu::RenderPipeline objects to avoid re-compilation stalls.
Composition Texture	An intermediate texture where the shader effect is rendered.
Texture Pool	A mechanism to reuse textures of the same dimensions, reducing allocation overhead.

Sources: kaleidux-daemon/src/renderer.rs:13-25, kaleidux-daemon/src/renderer.rs:55-80, kaleidux-daemon/src/renderer.rs:1050-1080

Rendering Sequence

The following sequence diagram illustrates how the daemon coordinates with the renderer to execute a transition.

This diagram depicts the lifecycle of a transition from content switching to final cleanup.
Sources: kaleidux-daemon/src/renderer.rs:520-560, kaleidux-daemon/src/renderer.rs:1050-1090, kaleidux-daemon/src/main.rs:120-150

Built-in Transitions & Parameters

Kaleidux supports a wide variety of parametric transitions. These are defined in the Transition enum (shared via kaleidux-common) and mapped to GLSL uniforms in shaders.rs.

Supported Transition Examples

Type	Key Parameters	Source Logic
cube	persp, unzoom, reflection, floating	shaders.rs:205
doom	bars, amplitude, noise, frequency	shaders.rs:214
cross-zoom	strength	shaders.rs:203
grid-flip	size (ivec2), pause, divider_width	shaders.rs:220
directional	direction (vec2)	shaders.rs:206

Custom shaders can also be loaded from ~/.config/kaleidux/shaders/ and provided with arbitrary parameters via the Transition::Custom variant.

Sources: kaleidux-daemon/src/shaders.rs:188-255, config.example.toml:132-160

Performance & Metrics

The shader system is monitored for efficiency using the PerformanceMetrics module. Key metrics include shader compilation time, texture pool hit rates, and transition duration drift.

• Shader Precompilation: To prevent frame drops, the renderer can pre-compile common or configured shaders in the background.
• Pipeline Caching: The MAX_PIPELINE_CACHE_SIZE is set to 50 to store frequently used transition pipelines.
• CPU Tracking: The system records shader_compile_cpu_time to identify expensive shader modules.

// From kaleidux-daemon/src/renderer.rs:360
pub fn apply_config(&mut self, config: &crate::orchestration::OutputConfig) {
    self.active_transition = config.transition.clone();
    self.transition_duration = (config.transition_time as f32 / 1000.0).max(0.001);
    // ... spawns background precompilation ...
}

Sources: kaleidux-daemon/src/metrics.rs:40-60, kaleidux-daemon/src/renderer.rs:90-110, kaleidux-daemon/src/renderer.rs:360-385

Conclusion

The GLSL Transition and Shader system in Kaleidux is a robust, modular architecture that bridges high-level user configuration with low-level GPU execution. By combining a flexible GLSL-to-WGSL compilation pipeline with aggressive caching and intermediate composition rendering, the project achieves smooth, aesthetically pleasing wallpaper changes with minimal resource impact.