runi-dist/docs/lossless-scaling.md

Lossless Scaling

Runi can configure lsfg-vk frame generation for each registered game. Lossless Scaling itself provides both upscaling and frame generation on Windows; the Linux Vulkan layer exposes the LSFG frame-generation path, not the application's scaling algorithms.

Ownership and dependencies

Runi never purchases or installs Lossless Scaling, and never copies or distributes Lossless.dll. That file is proprietary, paid, and shipped inside a Steam application: the player buys it, Runi finds it.

Runi does install the layer. The earlier rule said it would not, but that rule bundled two claims together and only one of them was about licensing; the other was consistency with how gamescope and mangohud are treated. lsfg-vk is free software published as a GitHub release, and core/install/installer.py already downloads and checksum-verifies third-party binaries - Runi had simply never installed this particular one. See "Installing the layer" below.

The Lossless Scaling game tab becomes editable only when Runi finds:

• a supported lsfg-vk 1.x or 2.x Vulkan layer and its shared library; and
• Steam AppID 993090 in a native, external, or Flatpak Steam library, with a readable Lossless.dll in that installation.

Use Recheck after installing either dependency externally. If a dependency disappears while a game is enabled, the enable switch remains available so the saved integration can be turned off; launches otherwise fail with an actionable missing-dependency error.

Installing the layer

runi lossless-scaling                 # what is present, what is missing
runi lossless-scaling install         # fetch and register the layer
runi lossless-scaling remove          # undo, if runi installed it

The desktop GUI's Lossless Scaling tab shows the same thing and offers an Install lsfg-vk button, which appears only when no layer is registered.

Runi installs the release's layer-only artifact - about 700 KB, against 74 MB for the bundle that also ships a configuration UI Runi has no use for, since it writes the layer's settings as environment variables itself. Two files are written, both user-level, neither needing root:

File	Destination
liblsfg-vk.so	~/.local/lib/
VkLayer_LS_frame_generation.json	$XDG_DATA_HOME/vulkan/implicit_layer.d/

Three details are not obvious:

• The manifest is rewritten on install. The shipped one names its library as the bare filename liblsfg-vk.so, which the Vulkan loader resolves against the system's shared-object search path - not against the manifest's own directory, and ~/.local/lib is not on that path. Runi substitutes the absolute path of the library it just installed. Left alone, the layer would register and then fail to load.
• The download is verified against the digest the GitHub API publishes for the asset, because this project ships no checksum file of its own - unlike every Proton source, which publishes a sibling .sha512sum. Verification is required rather than best-effort: this is a shared library that every Vulkan application on the machine will load. An asset with no published digest is refused.
• Runi refuses to register a second layer of the same name. If lsfg-vk is already installed - most often from your distribution's packages, in /usr/share/vulkan/implicit_layer.d/ - Runi reports where that one came from instead of adding its own. Two manifests claiming one layer name is a real failure mode, not untidiness. For the same reason remove only ever deletes what Runi itself installed; a package's copy belongs to the package manager.

Prereleases are skipped: the 2.x line is published only as one, and it drives a different set of environment variables. Pass --version <tag> to select a specific release.

Per-game behavior

The tab controls the displayed-frame multiplier, motion-estimation flow scale, performance model and the lsfg-vk 1.x experimental present-mode option. Native HDR is managed only in the dedicated HDR tab and is the source of truth for launch composition. lsfg-vk 1.x receives its HDR shader mode automatically; 2.x has no equivalent separate control and reports that limit instead. The legacy hdr_mode field remains only as a schema migration mirror.

For lsfg-vk 1.x, Runi uses its documented environment-only mode. This avoids editing ~/.config/lsfg-vk/conf.toml and avoids process-name matching. The equivalent environment interface is used for 2.x. Dedicated settings take precedence over duplicate LSFG values in the game's generic [env] section.

When the integration is disabled, Runi adds no enable or disable variable. Profiles maintained externally with lsfg-vk-ui can therefore continue to apply. Only the main Play action receives the per-game environment; settings tools and other auxiliary actions do not.

Compatibility notes

• The final graphics path must use Vulkan. DirectX 11/12 games normally reach Vulkan through DXVK or VKD3D-Proton, while native OpenGL-only games do not.
• Generated frames increase displayed frame rate, not game simulation or input sampling. Start with a stable base frame rate and evaluate latency and visual artifacts in motion.
• Gamescope may not honor the VSync behavior expected by lsfg-vk. Verify frame pacing and latency when both are enabled.
• Native HDR should only be enabled for an active HDR game and desktop pipeline.
• Vulkan-layer injection may be rejected by anti-cheat. Runi warns when anti-cheat evidence exists and never enables Lossless Scaling automatically.

The current installation state and warnings are advisory; the running game is the final compatibility test.