Gamescope

From ArchWiki

Gamescope is a microcompositor from Valve that is used on the Steam Deck. Its goal is to provide an isolated compositor that is tailored towards gaming and supports many gaming-centric features such as:

  • Spoofing resolutions.
  • Upscaling using AMD FidelityFX™ Super Resolution or NVIDIA Image Scaling.
  • Limiting framerates.

As a microcompositor it is designed to run as a nested session on top of your existing desktop environment though it is also possible to use it as an embedded compositor as well.

Installation

Gamescope can be installed with the gamescope package (or the gamescope-gitAUR package). Additionally there is also gamescope-plusAUR which includes extra patches not present in the mainline build.

Requirements

  • AMD: Mesa 20.3 or above
  • Intel: Mesa 21.2 or above
  • NVIDIA: proprietary drivers 515.43.04 or above, and the nvidia-drm.modeset=1 kernel parameter

Usage

Gamescope offers many options, far too many to cover here. For a full list use the gamescope --help command from a terminal.

From a desktop session

The following command will run supertuxkart using Gamescope and force a 1920x1080 resolution at 60 FPS

$ gamescope -W 1920 -H 1080 -r 60 -- supertuxkart

From Steam

You can force Steam to run using Gamescope by using the following command:

$ gamescope -e -- steam
Note: The -e flag tells Gamescope to enable Steam Integration.

You can also run games from Steam using Gamescope by adding the following to the games launch options

gamescope -- %command%
Note: It is still required that you set flags such as resolution, FPS etc when launching from Steam otherwise Gamescope will launch at an incorrect resolution. You can do this in the same way as from a terminal, for example
gamescope -W 1920 -H 1080 -r 60 -- %command%

From Wine

To run programs using Gamescope through Wine, simply append wine followed by the executable.

$ gamescope -W 1920 -H 1080 -r 60 -- wine supertuxkart

Almost all the popular Wine managers such as Lutris, Bottles, and PlayOnLinux have support for Gamescope. Using them is as simple as installing the desired Gamescope package and checking the Use Gamescope (or similar) option.

Note: Wine managers also tend to have a GUI interface to configure basic Gamescope options making them, in general, the easiest way to use Gamescope.

From Flatpak

You can also use Gamescope from Flatpak versions of Wine managers and Steam in the same way as you would from a package install. It does however require that you first install Gamescope from Flathub with the following command:

$ flatpak install gamescope

Upscaling

The -F fsr and -F nis flags can be used to upscale games using AMD FidelityFX™ Super Resolution 1.0 (FSR) or NVIDIA Image Scaling v1.0.3 (NIS) respectively. You can also use -S integer for integer upscaling or -S stretch for stretch scaling.

To upscale a 720p game to 1440p using FSR:

$ gamescope -h 720 -H 1440 -F fsr -- supertuxkart

To run a game at 1080p internal resolution but display it at 4K using NIS:

$ gamescope -w 1920 -h 1080 -W 3840 -H 2160 -F nis -- supertuxkart

Games with low resolutions typically use linear filtering on fullscreen by default and sometimes get stretched. This is specially noticeable in classic JRPG. To have a pixelated look and keep aspect ratio:

$ gamescope -F nearest -S fit -- tecnoballz

Filters can be changed while the game is running:

  • Super+n toggle nearest filtering.
  • Super+u toggle FSR upscaling.
  • Super+y toggle NIS upscaling.
  • Super+i increase FSR sharpness by 1.
  • Super+o decrease FSR sharpness by 1.

HDR support

Gamescope is a requirement for HDR10 support when playing games, to make use of this feature you must launch your Gamescope session using the --hdr-enabled flag.

Note: HDR support on Linux is still in its infancy and has many caveats. See HDR monitor support for details.

Wayland support

Gamescope does not support Wayland clients by default. To enable support for Wayland clients, add the --expose-wayland flag to Gamescope's parameters.

SDR Gamut Wideness

Since SteamOS 3.5.5, Valve has changed the the default color rendering for the Steam Deck LCD. The effect is achieved through Gamescope by changing the "wideness" of the gamut for SDR content, which can result in a warmer and more vibrant color appearance depending on the adjustment.

In a Steam game's launch options, simply add --sdr-gamut-wideness followed by a value that's equal or between 0-1:

gamescope --sdr-gamut-wideness 1 -- %command%

Troubleshooting

Switching to fullscreen causes low performance

This is a known bug when using Gamescopes fullscreen hotkey Meta+f, if you encounter this issue it can be worked around by using the fullscreen flag -f when launching the game.

Setting Gamescopes priority

Another known cause of low performance and/or stuttering is not having Gamescope's priority set correctly. You can tell this is the case if you see an error like this in the terminal while Gamescope is running:

No CAP_SYS_NICE, falling back to regular-priority compute and threads.
Performance will be affected.

The following command will fix this:

# setcap 'CAP_SYS_NICE=eip' $(which gamescope)

Window does not appear in Flatpak on NVIDIA

This is because Flatpak Gamescope fails to access the NVIDIA DRM's GBM backend. It can be solved by simply setting an environment variable with the following command:

$ flatpak override --env=GBM_BACKENDS_PATH=/usr/lib/x86_64-linux-gnu/GL/nvidia-XXX-YY-ZZ/extra/gbm packageid

where packageid is the Flatpak package identifier of Gamescope or the app you want to use Gamescope with, such as Bottles. Replace nvidia-XXX-YY-ZZ with the currently installed NVIDIA driver version; inside Flatpak, it can be queried with this command:

$ flatpak run --command=ls packageid /usr/lib/x86_64-linux-gnu/GL

where packageid is any Flatpak package identifier; do note that the directory only exists inside Flatpak.

Note:

This article or section needs expansion.

Reason: This step can probably be automated by a pacman hook. (Discuss in Talk:Gamescope)

The command must be reran, and modified accordingly, on every driver update.

Image corruption on Intel graphics

If gamescope outputs corrupted image colors on Intel graphics disabling lossless color compression can be a work-around at the cost of increased memory bandwidth utilization. [1] To disable it pass INTEL_DEBUG=noccs environment variable.

VRR stutters when HDR is enabled

If VRR and HDR work independently, but the framerate is unstable when they're both enabled, then you may be hitting issues with long HDR compositing times. See https://github.com/ValveSoftware/gamescope/issues/1006. This only applies to using Gamescope in embedded mode, and not when using gamescope within an existing wayland or X session.

When using AMD graphics this can be fixed by using experimental AMD color management, which uses hardware planes to composite the final image. This requires one of two setups:

Steam Deck kernel

Linux kernel with experimental AMD color management enabled

See also