Linux Wallpaper Engine

Linux renderer for Wallpaper Engine projects.

Requirements

System requirements

• Linux
• GCC or Clang with C++20 support
• xmake
• Vulkan development libraries and a working Vulkan GPU driver
• Slang compiler/runtime libraries
• X11 development libraries (libX11, libXcursor, libXi)
• FFmpeg development libraries (libavformat, libavcodec, libavutil, libswscale)
• VA-API development libraries (libva, libva-drm)
• libdrm
• A local Wallpaper Engine installation with its original assets/ data (required at runtime; set WALLPAPER_ENGINE_PATH or engine_path in config.json)

Dependencies managed by xmake

The following dependencies are fetched by xmake and normally do not need to be installed manually:

• Sokol
• linmath.h
• Vulkan-Headers
• LZ4
• cJSON
• stb
• Dear ImGui (debug builds only)

Arch Linux / CachyOS

sudo pacman -S --needed \
    xmake \
    gcc \
    vulkan-icd-loader \
    shader-slang \
    libx11 \
    libxcursor \
    libxi \
    ffmpeg \
    libva \
    libdrm

A Vulkan driver for your GPU is also required, for example vulkan-radeon, vulkan-intel, or the appropriate NVIDIA driver.

For development checks:

sudo pacman -S --needed clang cppcheck

Build and run

Goal	Command
Build the default configuration	xmake
Run a wallpaper project directory or .pkg file	xmake run linux-wallpaperengine "/path/to/wallpaper"
Run a video wallpaper	xmake run linux-wallpaperengine "/path/to/video.mp4"
Configure and run a debug build	xmake f -m debug then xmake run linux-wallpaperengine
Configure and run a release build	xmake f -m release then xmake run linux-wallpaperengine
List available GPUs	bin/<mode>/linux-wallpaperengine --list-gpus
Select a GPU	bin/<mode>/linux-wallpaperengine --gpu <index-or-name> "/path"
Extract a package	bin/<mode>/linux-wallpaperengine --extract-only "/path/to/scene.pkg"
Clean build outputs	xmake clean
Validate formatting and static analysis	xmake check
Format source files	xmake format
Validate, build, and launch the debug effect sandbox	xmake sandbox

Build outputs are written to bin/<mode>/.

Render Diagnostics (Debug Mode)

Render diagnostics are available in debug builds and are opt-in. Enable them with --diagnose or --diagnostics:

bin/debug/linux-wallpaperengine --diagnose "/path/to/wallpaper"

Diagnostics can capture render-pipeline state including pass images, scene stages, render graphs, shader code, and uniforms.

FEATURE SUPPORT

Runtime compatibility with Wallpaper Engine wallpapers.

• Supported
• [-] Partial / Incomplete
• Not supported yet

Wallpaper Types

• [-] Scene wallpapers
• Video wallpapers
• Web wallpapers
• Application wallpapers

Scene Layers & Assets

• Image layers
• [-] Particle system layers
• Text layers
• Sound layers
• Light layers
• 3D model layers
• Composition layers
• Fullscreen / effect layers
• [-] Layer hierarchy
• Layer visibility
• Layer position
• Layer scale
• Layer rotation
• [-] Parent transforms
• [-] Layer blending
• Layer attachments

Camera & Parallax

• Orthographic scenes
• Perspective scenes
• Camera parallax
• Mouse influence
• Parallax amount
• Parallax delay
• Per-layer parallaxDepth
• Horizontal / vertical parallax depth
• Parent parallax propagation
• disablepropagation
• Shader g_ParallaxPosition
• Depth Parallax effect integration
• Camera assets
• Camera field of view
• Multiple cameras
• Camera paths
• Camera shake

Image Effects

Animation Effects

• Foliage Sway
• Iris Movement
• Pulse
• Cloud Motion
• Scroll
• Shake
• Spin
• Swing
• Twirl
• Water Flow
• Water Ripple
• Water Waves

Blur Effects

• Blur
• Blur Precise
• Motion Blur
• Radial Blur

Interactive Effects

• Cursor Ripple
• Advanced Fluid Simulation
• Depth Parallax
• X-Ray

Colorization Effects

• Blend
• Blend Gradient
• Chromatic Aberration
• Clouds
• Color Key
• Film Grain
• Glitter
• Shimmer
• Fire
• Light Shafts
• Nitro
• Opacity
• Reflection
• Tint
• VHS
• Water Caustics

Distortion Effects

• Fisheye
• Perspective
• Refraction
• Skew
• Transform

Enhancement Effects

• Edge Detection
• God Rays
• Local Contrast
• Shine

Effect Runtime

• [-] Generic Wallpaper Engine shader effects
• Effect chains
• Multiple effect passes
• Effect masks
• Effect texture inputs
• Constant shader values
• Shader combo defines
• [-] Wallpaper Engine material support
• Full built-in effect compatibility
• Custom effect compatibility

Bloom & HDR

• Bloom
• HDR rendering
• Ultra HDR
• HDR bloom / threshold
• Bloom iterations
• Bloom scatter

Particle Systems

• [-] Particle systems

General

• Maximum particle count
• Start-time warmup
• World-space particles
• Perspective particles
• [-] Sprite sheets
• Frame blending
• Material lighting
• [-] Refraction
• [-] Blend modes

Renderers

• [-] Particle sprite rendering
• [-] Particle trail rendering
• Full particle renderer set

Emitters

• [-] Emitters
• Multiple emitters
• Sphere random
• Box random
• Full emitter set

Initializers

• Lifetime
• Size
• Velocity
• Color
• Alpha
• Rotation
• Angular velocity
• Full initializer set

Operators

• Movement
• Gravity
• Drag
• Alpha fade
• Alpha oscillation
• Size oscillation
• Position oscillation
• Turbulence
• Full operator set

Advanced Particle Features

• Child particle systems
• Control points
• Mouse-interactive particles
• Audio-responsive particles
• [-] Particle sprite-sheet animations
• Particle instance modifiers
• [-] Particle instance overrides

Timeline Animations

• Timeline animations
• Property animations
• Keyframes
• Bézier interpolation
• Loop mode
• Mirror mode
• Single mode
• Animation playback rate
• Start paused
• Named animations
• Animation events
• SceneScript timeline control

Puppet Warp

• Puppet Warp
• Puppet geometry / mesh
• Custom topology / vertex editing
• Skeleton / bones
• Bone weights
• Puppet animations
• Multiple puppet animations
• Animation mixing
• Character sheets
• Texture channels
• Shape animations / blend shapes
• Bone constraints
• Spring simulation
• Rigid simulation
• Gravity
• Kinematic chains
• Inverse kinematics
• Bone blend rules
• Attachment points
• Interactive bones
• SceneScript puppet control
• 3D perspective extrusion

Lighting & Reflections

• 2D real-time lighting
• 2D reflections
• Normal maps
• Light sources
• Point lights
• Spot lights
• Directional lights
• Light animations
• Reflection maps

3D Scenes & Models

• 3D scenes
• FBX models
• OBJ models
• Perspective rendering
• Model hierarchy
• Multiple model materials

3D Materials

• Albedo maps
• Normal maps
• Metallic maps
• Roughness maps
• Reflection maps
• Emissive maps
• Lighting
• Reflections
• Rim lighting
• Toon / cel shading
• Tint masks

Model Animation

• Skeletal animation
• Animation clips
• Multiple animation layers
• Animation blending
• Root motion
• Additional animation files
• Bone physics simulations
• Model attachments

3D Rendering

• Shadows
• Point-light shadows
• Spot-light shadows
• Directional-light shadows
• Volumetric lighting
• Distance fog
• Height fog

Built-in 3D Shaders

• Fur shader
• Vegetation shader
• Chroma shader

User Properties

• User properties
• Color properties
• Slider properties
• Checkbox properties
• Combo properties
• Text input properties
• Texture replacement properties
• User Shortcut properties
• Property groups
• Property display conditions
• Property bindings
• SceneScript property access

Audio

• Sound layers
• Audio playback
• MP3 playback
• WAV playback
• Loop playback
• Single playback
• Volume control
• Play / pause / stop
• System audio capture
• Audio spectrum data
• Audio-responsive properties
• Audio-responsive effects
• Audio-responsive particles

Media Integration

• Currently-playing media integration
• Track title
• Artist
• Album metadata
• Media playback status
• Playback timeline
• Album artwork
• Album artwork color extraction

SceneScript

• SceneScript runtime
• ECMAScript-compatible scripting
• Property scripts
• init()
• update()
• Scene access
• Layer access
• Effect access
• Dynamic layer creation
• Dynamic asset registration
• Timeline control
• Puppet animation control
• 3D model animation control
• Particle control
• Sound control
• Cursor events
• Audio data
• User properties
• Time / date APIs
• Media integration
• Local persistent storage
• Shared script state
• Dynamic 2D / 3D model creation
• WEColor module
• WEMath module
• WEVector module

Interaction

• Mouse position
• Mouse-driven parallax
• Solid layer hit testing
• Cursor enter
• Cursor leave
• Cursor move events
• Cursor down
• Cursor up
• Cursor click
• Interactive effects
• Interactive particles
• Interactive Puppet Warp

RGB Hardware

• RGB hardware integration
• Corsair iCUE
• Razer Chroma
• RGB source layers
• Composition-layer RGB output
• Web wallpaper RGB API

Shader Programming

• [-] Wallpaper Engine shader loading
• [-] Wallpaper Engine GLSL compatibility
• [-] GLSL to SPIR-V translation
• Runtime Slang compilation
• [-] Built-in shader uniforms
• [-] Built-in texture bindings
• [-] Shader combo system
• Full vertex attribute support
• Custom shaders
• Full custom effect compatibility

Texture & Asset Formats

• Wallpaper Engine .tex
• RGBA8
• R8 grayscale
• BC1 / DXT1
• BC2 / DXT3
• BC3 / DXT5
• LZ4-compressed texture data
• Embedded PNG textures
• Multi-image .tex resources
• [-] Wallpaper Engine materials
• [-] Wallpaper Engine shaders
• [-] Wallpaper Engine particle definitions
• Wallpaper Engine model formats
• Full .tex format compatibility

Wallpaper Packages & Projects

• Wallpaper Engine project folders
• scene.pkg extraction
• Standalone package input
• scene.json parsing
• project.json video target detection
• Authored scene resolution
• Orthographic projection resolution
• Clear color

Web Wallpapers

• HTML
• CSS
• JavaScript
• Local web assets
• Web user properties
• File properties
• Directory properties
• Audio visualization API
• Media integration API
• RGB API
• User-configurable FPS API
• Web video playback

Video Wallpapers

• Video wallpaper playback
• MP4 wallpapers
• WebM wallpapers
• MKV wallpapers
• AVI wallpapers
• MOV wallpapers
• WMV wallpapers
• Looping
• Audio
• [-] Playback controls
• FFmpeg software decoding
• VA-API hardware decoding
• [-] GPU-native VA-API / DMA-BUF video textures
• Automatic software decode fallback
• Video user properties

Application Wallpapers

• Application wallpapers
• Native executable wallpaper processes
• Wallpaper process lifecycle
• Embedded / desktop window placement

Runtime / Desktop Integration

• Desktop wallpaper placement
• Multi-monitor rendering
• Per-monitor wallpapers
• Spanned wallpapers
• Cloned wallpapers
• Pause / resume runtime
• Mute / unmute
• FPS limits
• Fullscreen application detection
• Screensaver mode
• [-] Runtime command-line controls
• GPU enumeration
• GPU selection
• Package extraction CLI
• Debug sandbox
• Debug render diagnostics