linux-wallpaperengine

What the renderer does

Linux Wallpaper Engine is a Linux renderer for Wallpaper Engine projects. The README states it is a Linux renderer for Wallpaper Engine projects, which are animated desktop backgrounds created by the original Windows application. The goal is to play those projects on Linux using a native engine rather than running the Windows client through compatibility layers. The current feature table shows where support stands. Video wallpapers are marked as supported, and the renderer handles MP4, WebM, MKV, AVI, MOV, and WMV files with FFmpeg software decoding and VA-API hardware decoding, plus an automatic software decode fallback. Scene wallpapers are only partially supported, with image layers, layer visibility, position, scale, rotation, and camera parallax working, while particle systems, text layers, and 3D model layers are not yet supported. Web and application wallpapers are not supported yet. On the effects side, water waves and depth parallax are supported, effect chains and multiple passes work, but most blur, colorization, and distortion effects are still missing. The project is therefore most useful today for video wallpapers and for simple scene projects, and the README is honest about the partial status of richer features. A runtime command line control and a debug sandbox exist, and GPU enumeration and selection are available.

System requirements

The README lists the build and runtime requirements up front. The system must be Linux, with a C plus plus 20 capable compiler such as GCC or Clang. The build system is xmake, and the renderer needs Vulkan development libraries plus a working Vulkan GPU driver. The Slang compiler and runtime libraries are required for shader work. X11 development libraries are needed, specifically libX11, libXcursor, and libXi. FFmpeg development libraries (libavformat, libavcodec, libavutil, libswscale) provide decoding, and VA-API development libraries (libva, libva-drm) provide hardware acceleration, along with libdrm. A local Wallpaper Engine installation with its original assets directory is required at runtime. The README says to set WALLPAPER_ENGINE_PATH or engine_path in config.json so the renderer can find that data. Some dependencies are fetched by xmake and do not need manual install: Sokol, linmath.h, Vulkan-Headers, LZ4, cJSON, stb, and Dear ImGui for debug builds only. On Arch Linux or CachyOS, the README gives a pacman command that installs xmake, gcc, vulkan-icd-loader, shader-slang, libx11, libxcursor, libxi, ffmpeg, libva, and libdrm, plus a Vulkan driver for the GPU such as vulkan-radeon, vulkan-intel, or the NVIDIA driver. Development checks add clang and cppcheck. The README presents these as the minimum to build and check the renderer, and a working Vulkan driver for the specific GPU remains a hard requirement that the package lists cannot satisfy on their own.

Building and running

The build is driven by xmake. Running xmake with no arguments builds the default configuration, and build outputs are written to bin slash mode slash linux-wallpaperengine. To run a wallpaper project directory or a dot pkg file, the command is xmake run linux-wallpaperengine with the path in quotes. A video wallpaper is run the same way with a dot mp4 path. Debug and release builds are selected with xmake f minus m debug or xmake f minus m release before the run command. The renderer can list available GPUs with bin slash debug slash linux-wallpaperengine minus minus list-gpus, and select one with minus minus gpu and an index or name. A package can be extracted with minus minus extract-only. Source formatting and static analysis use xmake check, and xmake format reformats files. The command xmake sandbox validates, builds, and launches the debug effect sandbox. Render diagnostics are opt in and available in debug builds through minus minus diagnose or minus minus diagnostics, capturing pipeline state such as pass images, scene stages, render graphs, shader code, and uniforms. The README's command table also covers xmake clean for build outputs. Because the project is a renderer rather than a full desktop wallpaper service, it plays a chosen project on demand rather than managing the desktop background automatically.

Editorial conclusion

The renderer requires a local Wallpaper Engine installation with its assets directory, set through WALLPAPER_ENGINE_PATH or engine_path in config.json. Builds are produced with xmake and written to bin slash mode slash linux-wallpaperengine, and video wallpapers support MP4, WebM, MKV, AVI, MOV, and WMV with FFmpeg decoding and VA-API hardware decoding.