ScreenAnimation
GPU-accelerated screen animations and wallpaper engine for Windows, built with Rust/WGPU. Features a novel .flow plugin system for portable, self-contained animations.
What makes this different: Unlike closed-source wallpaper engines, ScreenAnimation lets you write WGSL shaders and package them as portable .flow files that run anywhere without recompilation.
Features
- ๐จ GPU-accelerated rendering (WGPU + DXGI)
- ๐ฅ๏ธ Multi-monitor support with per-monitor animations
- ๐ Live Wallpaper: Mouse-reactive desktop background with wave distortion
- ๐ฌ Screen Transitions: Capture, detach, move, and land screen content with 3D effects
- ๐ Audio Sync: WAV sound effects triggered by animation events
- โป๏ธ Hot Reload: Shaders reloaded automatically on file changes (live development)
- ๐ฆ Plugin System:
.flow format packages animations (config + shader + assets) as portable ZIP files
- โก Performance: <16ms per frame (60+ FPS), ~50MB memory footprint
Quick Start
Build
cargo build --release
Binaries in target/release/:
animationengine.exe โ Runtime engine
builder.exe โ Package builder
Run Examples
# Live wallpaper: mouse-reactive wave distortion
./target/release/animationengine Wallpaper my_animation.flow
# Screen transition: capture โ detach โ move โ land
./target/release/animationengine Animation my_animation.flow
# Plasma / kaleidoscope / wave: procedural wallpapers
./target/release/animationengine Wallpaper my_wave.flow
Example animations are distributed as downloadable .flow assets (Releases), not committed to the repo.
The .flow Plugin System
The core innovation of ScreenAnimation is the .flow format โ a portable animation package.
What is .flow?
A .flow file is a ZIP archive containing:
animation.flow (ZIP)
โโโ config.toml # Parameters, metadata, timing
โโโ shader.wgsl # GPU shader code
โโโ background.png # Optional: background image
โโโ *.wav # Optional: audio files
โโโ *.png/*.jpg # Optional: textures
How it Works
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 1: Create your animation โ
โ - Write config.toml (parameters) โ
โ - Write shader.wgsl (GPU code) โ
โ - Add assets (images, audio) โ
โโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โ
โโโโโโโโโโโโโโโโโโโโ
โ builder.exe โ
โ (Packager) โ
โโโโโโโโโโฌโโโโโโโโโโ
โ
โ
โโโโโโโโโโโโโโโโโโโโ
โ animation.flow โ โ Self-contained package
โ (ZIP Archive) โ
โโโโโโโโโโฌโโโโโโโโโโ
โ
โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 2: Run anywhere โ
โ animationengine Wallpaper animation โ
โ โ Works on any ScreenAnimation install โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Example: Create Your First Animation
# 1. Create directory
mkdir my_wave_effect
cd my_wave_effect
# 2. Write config.toml
cat > config.toml << 'EOF'
[animation]
name = "Wave Effect"
description = "Mouse-reactive wave distortion"
[parameters]
speed = 1.5
amplitude = 0.05
frequency = 3.0
brightness = 1.0
mouse_influence = true
EOF
# 3. Write shader.wgsl (see TUTORIAL.md for full example)
cat > shader.wgsl << 'EOF'
@fragment
fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
let wave_offset = sin(input.uv.x * params.z + time * params.x) * params.y;
let distorted_uv = vec2<f32>(input.uv.x + wave_offset, input.uv.y);
return textureSample(screen_texture, screen_sampler, distorted_uv);
}
EOF
# 4. Package it
../target/release/builder --input . --output ../my_wave.flow
# 5. Run it!
../target/release/animationengine Wallpaper ../my_wave.flow
๐ Full tutorial: See TUTORIAL.md for step-by-step guide with shader examples.
Creating Custom Animations
Directory Structure
my_animation/
โโโ config.toml # Configuration and parameters
โโโ shader.wgsl # WGSL shader code
โโโ background.png # (Optional) Background image
โโโ *.wav # (Optional) Audio files
โโโ *.png/*.jpg # (Optional) Textures
Step 1: config.toml
[animation]
name = "My Animation"
version = "1.0.0"
description = "Description here"
[parameters]
speed = 1.0
amplitude = 0.05
frequency = 2.0
brightness = 1.0
mouse_influence = true
[rendering]
target_fps = 60
background_image = "background.png"
[audio]
enabled = false
# audio_file = "soundtrack.wav"
# beat_detection = true
Step 2: shader.wgsl
WSGL shader code. See example animations in Releases.
@fragment
fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
// Your shader code here
return textureSample(screen_texture, screen_sampler, input.uv);
}
Step 3: Package & Run
# Package
./target/release/builder --input my_animation --output my_animation.flow
# Run as wallpaper
./target/release/animationengine Wallpaper my_animation.flow
# Run as transition
./target/release/animationengine Animation my_animation.flow
Example Animations
Example animations (live wallpapers, screen transitions, plasma/kaleidoscope/wave) are distributed as .flow release assets to keep the repository lean. Grab them from the Releases page.
| Animation |
Type |
Purpose |
livewallpaper.flow |
Wallpaper |
Mouse-reactive wave on live desktop |
screentransition.flow |
Animation |
Multi-step screen transition (captureโdetachโmoveโland) |
plasma.flow / kaleidoscope.flow / wave.flow |
Wallpaper |
Small procedural effects (no assets) |
monitorswitch.flow |
Animation |
Display switching animation |
Architecture
Engine Components
| Component |
Purpose |
engine/ |
WGPU core (device, pipelines, bind groups) |
loader/ |
.flow package parsing (ZIP deserialization) |
logic/ |
Uniform buffer calculations per frame |
windows/ |
Windows API integration (DXGI, window management) |
Data Flow
config.toml + shader.wgsl + assets
โ (builder.exe)
package.flow (ZIP)
โ (animationengine.exe)
FlowPackage โ GpuCore โ MonitorWindows โ Render Loop
Performance
- Startup: ~1s (GPU init + shader compilation)
- Memory: ~50MB base
- Frametime: <16ms (60 FPS on modern GPUs)
- Multi-monitor: Linear scaling per monitor
Platform Support
| OS |
Status |
Requirements |
| Windows 10/11 |
โ
Full support |
DXGI + WGPU |
| Linux (Wayland) |
โ
Full support |
WGPU + Wayland |
| Linux (X11) |
โณ Partial |
WGPU (no window management) |
| macOS |
โณ Planned |
WGPU + Metal |
Building
Requirements
- Rust 1.70+ (Install)
- Windows: MSVC build tools + Windows SDK
- Linux:
libwayland-dev, libdrm-dev
Compile
# Full release build
cargo build --release
# Build specific binary
cargo build -p screen_animation --release
# Run tests
cargo test --all
Customization
Shader Development
Edit shader.wgsl while animationengine is running โ changes reload automatically (hot reload).
Parameter Tuning
Modify config.toml values without rebuilding:
speed โ Animation playback speed
amplitude โ Effect distortion strength
frequency โ Effect pattern density
brightness โ Output brightness
Audio Integration
Enable in config:
[audio]
enabled = true
audio_file = "soundtrack.wav"
beat_detection = true
Access frequency spectrum in shader (0-256 bands):
@group(0) @binding(4) var<storage, read> audio_spectrum: array<f32, 256>;
Documentation
Comparison: ScreenAnimation vs Alternatives
| Feature |
ScreenAnimation |
Wallpaper Engine |
OBS |
Blender |
| Open Source |
โ
Yes |
โ No |
โ
Yes |
โ
Yes |
| User Shaders |
โ
WGSL |
โ No |
โ ๏ธ Limited |
โ
Yes |
| Portable Format |
โ
.flow |
โ Proprietary |
โ No |
โ ๏ธ .blend files |
| Desktop Wallpaper |
โ
Yes |
โ
Yes |
โ No |
โ No |
| Screen Transitions |
โ
Yes |
โ ๏ธ Limited |
โ
Yes |
โ
Yes |
| Performance |
โก 60+ FPS |
โก 60+ FPS |
โ ๏ธ CPU-heavy |
โ ๏ธ Variable |
| Learning Curve |
๐ Medium |
โ N/A |
๐ Medium |
๐ Steep |
License
MIT License โ see LICENSE
Contributing
Contributions welcome! See CONTRIBUTING.md for guidelines.
Ideas for Enhancement
- macOS/Linux native window management
- Animation marketplace (publish/share
.flow files)
- Web-based shader editor + preview
- Performance profiler for shaders
- Multi-shader sequence editor (UI)
- Blender export plugin
Author
piot5 โ https://github.com/piot5
Quick Links
ScreenAnimation โ GPU-accelerated wallpapers with shader plugins
Made with โค๏ธ in Rust/WGPU