# Lumen Wallpaper

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

![Lumen Wallpaper](docs/images/lumen.jpg)

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 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:

```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).