Lumen-wallpaper/README.md

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 kept outside the source package in the build directory.

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.