121 lines
5.2 KiB
Markdown
121 lines
5.2 KiB
Markdown
# 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](https://git.shanaty.ru/Emil_Shanaty/Lumen-wallpaper/releases), then run:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
./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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```glsl
|
||
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:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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](LICENSE).
|