Lumen Wallpaper

Procedural GLSL wallpapers for KDE Plasma 6, rendered natively with Rust and Vulkan.

Lumen is a native Plasma wallpaper package. A small C++/QML bridge connects it to Qt Quick, while shader compilation and Vulkan rendering live in Rust. Frames are recorded directly into Qt's Vulkan command buffer; there is no video, browser, OpenGL fallback, or per-frame CPU copy.

Features

• Native wallpaper type and settings in KDE System Settings.
• Independent rendering at each monitor's native resolution and device pixel ratio.
• Runtime GLSL-to-SPIR-V compilation with Naga.
• Shadertoy-style mainImage() fragment shaders.
• Mouse interaction, animation speed, frame-rate limit, and pause.
• Hot reload with debouncing and the last working shader preserved after errors.
• Correct per-frame resources for Qt's frames in flight and configurable MSAA.

Requirements

• Linux with KDE Plasma 6 and Qt Quick 6.6 or newer; Wayland is the tested configuration.
• A working Vulkan driver. Qt Quick must use its Vulkan backend.
• CMake 3.22+, Ninja, a C++20 compiler, and Rust/Cargo 1.87+ to build from source.
• Qt 6 development files, Extra CMake Modules, Vulkan headers, Kirigami, and Plasma Workspace.

The installer can offer to install these packages on Fedora, Debian/Ubuntu, and Arch Linux. System packages are changed only after confirmation. The wallpaper itself installs into ~/.local and does not require sudo.

One-file installer

Download lumen-wallpaper-0.1.0-installer.run and its checksum from Releases, then run:

chmod +x lumen-wallpaper-0.1.0-installer.run
./lumen-wallpaper-0.1.0-installer.run

The installer extracts the included source into a temporary directory, checks dependencies, builds the plugin for the laptop's Qt version, installs it, and activates it in the running Plasma session.

A native Plasma plugin cannot be portable across arbitrary Qt versions as a prebuilt binary. Building on the target machine is intentional and avoids Qt/C++ ABI mismatches.

Useful options:

./lumen-wallpaper-0.1.0-installer.run --no-deps       # do not offer package installation
./lumen-wallpaper-0.1.0-installer.run --no-activate   # install only
./lumen-wallpaper-0.1.0-installer.run --yes           # non-interactive confirmation
./lumen-wallpaper-0.1.0-installer.run --help

PREFIX and BUILD_DIR can override the installation and build locations for an isolated installation.

From source

git clone https://git.shanaty.ru/Emil_Shanaty/Lumen-wallpaper.git
cd Lumen-wallpaper
./scripts/install.sh
./scripts/activate.sh

install.sh only builds and installs. activate.sh backs up the current wallpaper configuration, selects Lumen on all desktops, configures QSG_RHI_BACKEND=vulkan, and restarts plasmashell.

To enable it manually, open System Settings → Wallpaper, select Lumen Wallpaper, and click Apply. The Vulkan environment is loaded for new Plasma sessions from ~/.config/plasma-workspace/env/lumen-vulkan.sh; log out and back in if necessary.

To return to the previous wallpaper, select it in the same settings page. Activation backups are stored in PREFIX/share/lumen-wallpaper/ when installed through the installer, or in the source build directory when activate.sh is called directly. LUMEN_STATE_DIR overrides this location.

Custom shaders

Choose a .frag or .glsl file in the wallpaper settings, or leave the path empty to use the built-in Lumen shader. A minimal shader looks like this:

void mainImage(out vec4 fragColor, in vec2 fragCoord) {
    vec2 uv = fragCoord / iResolution.xy;
    float pulse = 0.5 + 0.5 * sin(iTime + uv.x);
    fragColor = vec4(0.05, 0.25 * pulse, 0.45 * pulse, 1.0);
}

Available values include iResolution, iTime, iTimeDelta, iFrameRate, iFrame, iMouse, iDate, iScreenIndex, and iScreenCount. Mouse coordinates use Shadertoy's bottom-left origin. On Wayland, pointer input is available while the pointer is over the desktop.

See examples/Gradient.frag for a complete example. Validate a file before selecting it:

cargo run --bin lumen-shader-check -- /absolute/path/to/shader.frag

The source directory is not scanned for shaders, and no shader is downloaded automatically.

Current limitations

• Only single-pass image shaders are supported.
• Feedback buffers A–D, iChannel*, textures, and audio input are not implemented yet.
• Layered Qt items and arbitrary offscreen Qt render targets are outside the supported wallpaper-surface path.
• OpenGL is not a rendering fallback; Lumen requires Qt Quick's Vulkan backend.

Development and release packaging

cargo fmt --check
cargo check
./scripts/install.sh
./scripts/package-release.sh

The packaging script uses git archive, so local build outputs, logs, screenshots, backups, credentials, and other untracked files cannot enter a release archive. Artifacts are written to dist/:

• lumen-wallpaper-0.1.0-source.tar.gz
• lumen-wallpaper-0.1.0-installer.run
• SHA256SUMS

Test the self-extracting installer without changing system packages or the active wallpaper:

PREFIX="$PWD/build/test-prefix" ./dist/lumen-wallpaper-0.1.0-installer.run \
    --no-deps --no-activate

License

Lumen Wallpaper is distributed under GPL-3.0-or-later.