vkBasalt

vkBasalt-ng is a compatibility and image-quality fork of vkBasalt. It keeps the original layer small while making mixed-architecture installation safe, removing X11 from the default runtime, and adding independently tested anti-aliasing effects. The original project and its authors remain credited below; the fork continues under the original zlib license.

vkBasalt-ng changes

• The layer manifest declares library_arch; the 64-bit package never bundles a 32-bit implicit-layer manifest. An i686 build is available separately.
• X11 keyboard polling is optional and disabled in the default package.
• vkbasaltctl toggle, enable, disable, and status control a running instance through a user-private socket in $XDG_RUNTIME_DIR/vkbasalt. This works with native Wine-Wayland because it does not inspect keyboard input inside Wine or depend on an XWayland connection.
• cmaa2 adds Intel Conservative Morphological Anti-Aliasing 2 as a native Vulkan compute effect. It uses the high-quality preset, supports RGBA8, BGRA8, and RGBA16F/HDR swapchains, and preserves swapchain alpha.
• rcas adds AMD FidelityFX Robust Contrast Adaptive Sharpening for cleaning up soft presentation-resolution output from TAA and temporal upscalers.
• nvsharpen adds NVIDIA Image Scaling's adaptive directional sharpener as a standalone, native-resolution pass.
• restore is an experimental spatial cleanup pass for soft temporal reconstruction output.

The Nix flake exposes vkbasalt-ng, vkbasalt-ng-x11, and the opt-in vkbasalt-ng-i686 package. The layer and controller use separate out and bin outputs, so a compositor can put only vkbasaltctl on the host PATH without registering another Vulkan manifest. A hotkey can run vkbasaltctl toggle; without --pid, the command reaches every active instance owned by the user. The controller also discovers endpoints inside private Steam Pressure Vessel runtime mounts.

To use CMAA2:

effects = cmaa2

For a modern game that already uses TAA, DLSS, FSR, XeSS, or TSR, apply RCAS directly to the reconstructed frame:

effects = rcas
rcasSharpness = 0.3
rcasDenoise = true

RCAS uses AMD's clipping-aware five-tap filter and optional noise detection. Its sharpness control is normalized so 0.0 is the mildest setting and 1.0 is the strongest. RCAS expects normalized SDR/perceptual output; HDR-aware sharpening is a separate future track.

NVSharpen is the directional alternative for reconstructed or otherwise soft frames:

effects = nvsharpen
nvSharpenStrength = 0.35
nvSharpenHDRMode = sdr

The strength control is clamped from 0.0 through 1.0 and uses NVIDIA's original nonlinear slider mapping. nvSharpenHDRMode accepts sdr, linear, or pq; it defaults to display-referred SDR. Choose the mode which matches the game's presentation output.

The experimental reconstruction cleanup mode combines directional edge analysis, local variance, noise/impulse suppression, multi-scale luma detail, and local-range clipping:

effects = restore
restoreStrength = 0.5
restoreDetailRecovery = 0.7
restoreNoiseSuppression = 0.4
restoreAntiRinging = 0.8

All four controls are clamped from 0.0 through 1.0. restore processes normalized, display-referred SDR and changes luma without sharpening chroma. It has no access to motion vectors or frame history, so it is a conservative spatial restoration filter rather than a replacement for a game's temporal reconstruction.

For a balanced anti-aliased and sharpened image, run DLS after CMAA2:

effects = cmaa2:dls
dlsSharpness = 0.5
dlsDenoise = 0.17
dlsAntiRinging = 0.75

RCAS is another sharpening choice for spatial/no-AA games:

effects = cmaa2:rcas

Do not normally put CMAA2 after a game's temporal AA or reconstruction pass; that tends to smooth an image which has already been anti-aliased. Use the rcas-only pipeline for those games.

The DLS pass uses Rec.709 luminance, linear-light sampling for common 8-bit sRGB swapchains, conservative extended-range highlight handling, and configurable anti-ringing. All three DLS controls are clamped to the range 0 through 1.

The shader is adapted from Intel's Apache-2.0-licensed CMAA2 reference implementation. Unsupported swapchain formats fall back to SMAA with a warning.

RCAS is adapted from AMD's MIT-licensed FidelityFX SDK implementation, including its lower-limiter compensation for isolated dark pixels.

NVSharpen is adapted from NVIDIA's MIT-licensed Image Scaling SDK implementation, including its directional edge detector, luma-dependent strength curve, and ringing limiter.

vkBasalt is a Vulkan post processing layer to enhance the visual graphics of games.

Currently, the build in effects are:

• Contrast Adaptive Sharpening
• Robust Contrast Adaptive Sharpening
• NVIDIA Adaptive Directional Sharpening
• Experimental Reconstruction Cleanup
• Denoised Luma Sharpening
• Fast Approximate Anti-Aliasing
• Conservative Morphological Anti-Aliasing 2
• Enhanced Subpixel Morphological Anti-Aliasing
• 3D color LookUp Table

It is also possible to use Reshade Fx shaders.

Disclaimer

This is one of my first projects ever, so expect it to have bugs. Use it at your own risk.

Building from Source

Dependencies

Before building, you will need:

• GCC >= 9
• X11 development files (only for -Dx11=enabled)
• glslang
• SPIR-V Headers
• Vulkan Headers

Building

These instructions use --prefix=/usr, which is generally not recommened since vkBasalt will be installed in directories that are meant for the package manager. The alternative is not setting the prefix, it will then be installed in /usr/local. But you need to make sure that ld finds the library since /usr/local is very likely not in the default path.

In general, prefer using distro provided packages.

git clone https://github.com/DadSchoorse/vkBasalt.git
cd vkBasalt

64bit

meson setup --buildtype=release --prefix=/usr builddir
ninja -C builddir install

32bit

Make sure that PKG_CONFIG_PATH=/usr/lib32/pkgconfig and --libdir=lib32 are correct for your distro and change them if needed. On Debian based distros you need to replace lib32 with lib/i386-linux-gnu, for example.

ASFLAGS=--32 CFLAGS=-m32 CXXFLAGS=-m32 PKG_CONFIG_PATH=/usr/lib32/pkgconfig meson setup --prefix=/usr --buildtype=release --libdir=lib32 -Dwith_json=false builddir.32
ninja -C builddir.32 install

Packaging status

Debian sudo apt install vkbasalt

Fedora sudo dnf install vkBasalt

Void Linux sudo xbps-install vkBasalt

Usage

Enable the layer with the environment variable.

Standard

When using the terminal or an application (.desktop) file, execute:

ENABLE_VKBASALT=1 yourgame

Lutris

With Lutris, follow these steps below:

1. Right click on a game, and press configure.
2. Go to the System options tab and scroll down to Environment variables.
3. Press on Add, and add ENABLE_VKBASALT under Key, and add 1 under Value.

Steam

With Steam, edit your launch options and add:

ENABLE_VKBASALT=1 %command% 

Configure

Settings like the CAS sharpening strength can be changed in the config file. The config file will be searched for in the following locations:

• a file set with the environment variableVKBASALT_CONFIG_FILE=/path/to/vkBasalt.conf
• vkBasalt.conf in the working directory of the game
• $XDG_CONFIG_HOME/vkBasalt/vkBasalt.conf or ~/.config/vkBasalt/vkBasalt.conf if XDG_CONFIG_HOME is not set
• $XDG_DATA_HOME/vkBasalt/vkBasalt.conf or ~/.local/share/vkBasalt/vkBasalt.conf if XDG_DATA_HOME is not set
• /etc/vkBasalt.conf
• /etc/vkBasalt/vkBasalt.conf
• /usr/share/vkBasalt/vkBasalt.conf

If you want to make changes for one game only, you can create a file named vkBasalt.conf in the working directory of the game and change the values there.

Reshade Fx shaders

To run reshade fx shaders e.g. shaders from the reshade repo, you have to set reshadeTexturePath and reshadeIncludePath to the matching dirctories from the repo. To then use a specific shader you need to set a custom effect name to the shader path and then add that effect name to effects like every other effect.

effects = colorfulness:denoise

colorfulness = /home/user/reshade-shaders/Shaders/Colourfulness.fx
denoise = /home/user/reshade-shaders/Shaders/Denoise.fx
reshadeTexturePath = /home/user/reshade-shaders/Textures
reshadeIncludePath = /home/user/reshade-shaders/Shaders

Runtime control

The default build does not poll keyboard state. Bind vkbasaltctl toggle in your Wayland compositor to disable and re-enable effects. Use vkbasaltctl --pid PID toggle to target one game, or omit --pid to control all running instances owned by the current user.

The optional -Dx11=enabled build retains the original in-process HOME-key toggle for X11 users. It is disabled by default.

Debug Output

The amount of debug output can be set with the VKBASALT_LOG_LEVEL env var, e.g. VKBASALT_LOG_LEVEL=debug. Possible values are: trace, debug, info, warn, error, none.

By default the logger outputs to stderr, a file as output location can be set with the VKBASALT_LOG_FILE env var, e.g. VKBASALT_LOG_FILE="vkBasalt.log".

FAQ

Why is it called vkBasalt?

It's a joke: vulkan post processing → after vulcan → basalt

Does vkBasalt work with dxvk and vkd3d?

Yes.

Will vkBasalt get me banned?

Maybe. To my knowledge this hasn't happened yet but don't blame me if your frog dies.

Will there be a openGl version?

No. I don't know anything about openGl and I don't want to either. Also openGl has no layer system like vulkan.

Will there be a GUI in the future?

Maybe, but not soon.

So is vkBasalt just a reshade port for linux?

Not really, most of the code was written from scratch. vkBasalt directly uses reshade source code for the shader compiler (thanks @crosire), but that's about it.

Does every reshade shader work?

No. Shaders that need multiple techniques do not work, there might still be problems with stencil and blending and depth buffer access isn't ready yet.

You said that "depth buffer access isn't ready yet", what does this mean?

There is a wip version that you can enable with depthCapture = on. It will lead to many problems especially on non nvidia hardware. Also the selected depth buffer isn't always the one you would want.

Is there a way to change settings for reshade shaders?

There is some support for it #46. One easy way so to simply edit the shader file.