123 lines
4.7 KiB
Markdown
123 lines
4.7 KiB
Markdown
# gpupaper
|
|
|
|
Wayland layer-surface wallpaper runner powered by GLSL/WGSL fragment shaders, built on [wgpu](https://wgpu.rs).
|
|
|
|
Runs shaders full-screen on one or all monitors as a proper compositor layer surface (via `zwlr-layer-shell-v1`). Supports Vulkan and OpenGL backends, with automatic fallback for drivers that misbehave at device creation (e.g. Mesa V3DV on Raspberry Pi).
|
|
|
|
## Features
|
|
|
|
- **GLSL and WGSL shaders** — use `.frag`/`.glsl` for GLSL or `.wgsl` for WGSL
|
|
- **ShaderToy-compatible GLSL** — shaders using `mainImage(out vec4, in vec2)` work without modification
|
|
- **glpaper-compatible GLSL** — shaders using `void main()` and `gl_FragColor` work as-is
|
|
- **Multi-monitor support** — target a specific output by name or use `all` to run on every connected display simultaneously
|
|
- **Hotplug** — new outputs are picked up automatically when using `all`
|
|
- **Vulkan-first with GL fallback** — prefers discrete Vulkan, falls back gracefully to integrated or GL
|
|
- **Layer selection** — place the shader on any compositor layer: `background`, `bottom`, `top`, or `overlay`
|
|
- **FPS cap** — optionally limit frame rate; defaults to vsync
|
|
|
|
## Shader uniforms
|
|
|
|
The following uniforms are available in all shaders:
|
|
|
|
| Uniform | Type | Description |
|
|
|--------------|---------|------------------------------------|
|
|
| `time` | `float` | Seconds since program start |
|
|
| `resolution` | `vec2` | Output dimensions in pixels |
|
|
| `mouse` | `vec2` | Mouse position (currently `0,0`) |
|
|
|
|
**WGSL** shaders receive these via a uniform buffer:
|
|
|
|
```wgsl
|
|
struct Uniforms {
|
|
time: f32,
|
|
_pad: f32,
|
|
resolution: vec2<f32>,
|
|
mouse: vec2<f32>,
|
|
}
|
|
@group(0) @binding(0) var<uniform> u: Uniforms;
|
|
```
|
|
|
|
**GLSL** shaders can declare them as bare `uniform` variables — gpupaper strips those declarations and injects the UBO automatically, so existing ShaderToy-style shaders need no changes.
|
|
|
|
## Usage
|
|
|
|
```
|
|
gpupaper <output> <shader_file> [--fps <n>] [--layer <layer>]
|
|
```
|
|
|
|
| Argument | Description |
|
|
|-----------------|----------------------------------------------------------------|
|
|
| `<output>` | Wayland output name (e.g. `HDMI-A-1`) or `all` / `*` |
|
|
| `<shader_file>` | Path to a `.frag`, `.glsl`, or `.wgsl` shader file |
|
|
| `--fps <n>` | Target frame rate; `0` = vsync (default) |
|
|
| `--layer` | Compositor layer: `background` (default), `bottom`, `top`, `overlay` |
|
|
|
|
**Examples:**
|
|
|
|
```bash
|
|
# Run on all outputs, vsync
|
|
gpupaper all /usr/share/gpupaper/shaders/wave.frag
|
|
|
|
# Run on a specific monitor, capped at 30 fps
|
|
gpupaper DP-1 ~/shaders/my_shader.frag --fps 30
|
|
|
|
# Run on the bottom layer (above wallpaper managers that use background)
|
|
gpupaper all /usr/share/gpupaper/shaders/fireflies.frag --layer bottom
|
|
```
|
|
|
|
Output names can be found with `wlr-randr`, `hyprctl monitors`, or `wayland-info`.
|
|
|
|
## Bundled shaders
|
|
|
|
A collection of example shaders is installed to `/usr/share/gpupaper/shaders/`:
|
|
|
|
`black_hole` · `building` · `cloud` · `cloudninja` · `cubes` · `fireflies` · `firering` ·
|
|
`flags` · `fluid_spiral` · `green_lines` · `light_line` · `light_wave` · `matrix` · `mickey` ·
|
|
`rainbow_donut` · `rainbow_lights` · `rainbow_ring` · `rainbow_triangle` · `red_lines` ·
|
|
`slinky` · `snake_torus` · `space` · `spiral` · `torus` · `trippy_cube` · `tunnel` ·
|
|
`twisty` · `water` · `wave` · `white_hole` · `yellow_lines`
|
|
|
|
## Installation
|
|
|
|
### Arch Linux (AUR)
|
|
|
|
Binary package for `x86_64` and `aarch64` (no build dependencies required):
|
|
|
|
```bash
|
|
yay -S gpupaper
|
|
```
|
|
|
|
Or build from source:
|
|
|
|
```bash
|
|
yay -S gpupaper-git
|
|
```
|
|
|
|
### From source
|
|
|
|
Dependencies: Rust stable, `libwayland`, `libxkbcommon`, `pkg-config`
|
|
|
|
```bash
|
|
cargo build --release
|
|
./target/release/gpupaper --help
|
|
```
|
|
|
|
## Compatibility
|
|
|
|
| Platform | Backend | Notes |
|
|
|-----------------------|-----------------|-----------------------------------------|
|
|
| AMD / Intel (desktop) | Vulkan | |
|
|
| NVIDIA | Vulkan | Requires `nvidia-utils` |
|
|
| Raspberry Pi 4/5 | OpenGL (EGL) | V3DV Vulkan driver skipped automatically|
|
|
| Most other hardware | Vulkan or GL | Whichever wgpu can initialise first |
|
|
|
|
Requires a Wayland compositor that implements `zwlr-layer-shell-v1` (Sway, Hyprland, river, labwc, and most wlroots-based compositors).
|
|
|
|
## Acknowledgements
|
|
|
|
Inspired by [glpaper](https://hg.sr.ht/~scoopta/glpaper) by Scoopta. gpupaper extends the concept with multi-monitor support, WGSL, a wgpu backend, and compatibility with both glpaper-style and ShaderToy-style GLSL shaders.
|
|
|
|
## License
|
|
|
|
MIT
|