From 3d962811e35ab11b4eca798600995b6798955405 Mon Sep 17 00:00:00 2001 From: Matthew Schwartz Date: Wed, 18 Sep 2024 16:07:10 -0700 Subject: [PATCH] readme: document utilities and post-Wayland backend refactor cleanup --- README.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 131 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 97dea45b3e..b941eee485 100644 --- a/README.md +++ b/README.md @@ -16,20 +16,68 @@ It runs on Mesa + AMD or Intel, and could be made to run on other Mesa/DRM drive If running RadeonSI clients with older cards (GFX8 and below), currently have to set `R600_DEBUG=nodcc`, or corruption will be observed until the stack picks up DRM modifiers support. ## Building +**Build Dependencies**: +- [Git](https://git-scm.com/) +- [Meson](https://mesonbuild.com/) - (version 0.58 or newer) +- [Ninja](https://github.com/ninja-build/ninja) +- [CMake](https://cmake.org/) +- [glslang](https://github.com/KhronosGroup/glslang) +- [wayland-protocols](https://gitlab.freedesktop.org/wayland/wayland-protocols) - (version 1.17 or newer) +- [vulkan-headers](https://github.com/KhronosGroup/Vulkan-Headers) +- [benchmark](https://github.com/google/benchmark) + +**Requirements**: +- [libei](https://gitlab.freedesktop.org/libinput/libei) +- [libcap](https://sites.google.com/site/fullycapable/) +- [SDL2](https://github.com/libsdl-org/SDL) +- [libx11](https://gitlab.freedesktop.org/xorg/lib/libx11) +- [libxmu](https://gitlab.freedesktop.org/xorg/lib/libxmu) +- [libxdamage](https://gitlab.freedesktop.org/xorg/lib/libxdamage) +- [libxcomposite](https://gitlab.freedesktop.org/xorg/lib/libxcomposite) +- [libxrender](https://gitlab.freedesktop.org/xorg/lib/libxrender) +- [libxres](https://gitlab.freedesktop.org/xorg/lib/libxres) +- [libxtst](https://gitlab.freedesktop.org/xorg/lib/libxtst) +- [libxkbcommon](https://github.com/xkbcommon/libxkbcommon) +- [libdrm](https://gitlab.freedesktop.org/mesa/drm) - (version 2.4.113 or newer) +- [libinput](https://gitlab.freedesktop.org/libinput/libinput) +- [pipewire](https://pipewire.org/) +- [libavif](https://github.com/AOMediaCodec/libavif) - (version 1.0.0 or newer) +- [libheif](https://github.com/strukturag/libheif) +- [aom](https://aomedia.org/) +- [rav1e](https://github.com/xiph/rav1e) +- [libdecor](https://gitlab.freedesktop.org/libdecor/libdecor) +- [xorg-xwayland](https://gitlab.freedesktop.org/xorg/xserver) +- [wayland](https://gitlab.freedesktop.org/wayland/wayland) - (version 1.23.0 or newer) +- [luajit](https://luajit.org/) + +Clone the repository with all submodules: +```sh +git clone https://github.com/ValveSoftware/gamescope.git --recurse-submodules ``` + +Set up your build for native architecture: + +```sh git submodule update --init meson setup build/ ninja -C build/ -build/gamescope -- ``` Install with: -``` +```sh meson install -C build/ --skip-subprojects ``` +By default, meson will install to `/usr/local`. If you want to install to your system directory, you can set the prefix to `--prefix=/usr` during meson build configuration. + +Uninstall with: + +```sh +sudo ninja -C build/ uninstall +``` + ## Keyboard shortcuts * **Super + F** : Toggle fullscreen @@ -42,6 +90,7 @@ meson install -C build/ --skip-subprojects * **Super + G** : Toggle keyboard grab ## Examples +**Nested** On any X11 or Wayland desktop, you can set the Steam launch arguments of your game as follows: @@ -56,6 +105,17 @@ gamescope -r 30 -- %command% gamescope -w 1920 -h 1080 -W 3440 -H 1440 -b -- %command% ``` +**Embedded** + +When launching from a Virtual Terminal, gamescope's DRM backend can act as a standalone session. The easiest way to run games with this backend is by running the entire Steam client within gamescope. + +To enable Steam client integration in gamescope, add `-e` or `--steam` to your launch arguments for gamescope while launching the Steam client. Running gamescope from a VT will default to your monitor's native resolution and refresh rate unless otherwise specified. + +```sh +# Run Steam embedded within gamescope at 7680x2160p with adaptive sync, mangoapp, and HDR enabled while using GamepadUI +gamescope -e -w 7680 -h 2160 --adaptive-sync --hdr-enabled --mangoapp -- steam -gamepadui +``` + ## Options See `gamescope --help` for a full list of options. @@ -64,12 +124,79 @@ See `gamescope --help` for a full list of options. * `-w`, `-h`: set the resolution used by the game. If `-h` is specified but `-w` isn't, a 16:9 aspect ratio is assumed. Defaults to the values specified in `-W` and `-H`. * `-r`: set a frame-rate limit for the game. Specified in frames per second. Defaults to unlimited. * `-o`: set a frame-rate limit for the game when unfocused. Specified in frames per second. Defaults to unlimited. -* `-F fsr`: use AMD FidelityFX™ Super Resolution 1.0 for upscaling -* `-F nis`: use NVIDIA Image Scaling v1.0.3 for upscaling +* `-F fsr`: use AMD FidelityFX™ Super Resolution 1.0 for upscaling. +* `-F nis`: use NVIDIA Image Scaling v1.0.3 for upscaling. * `-S integer`: use integer scaling. * `-S stretch`: use stretch scaling, the game will fill the window. (e.g. 4:3 to 16:9) * `-b`: create a border-less window. * `-f`: create a full-screen window. +* `-e`: enable Steam client integration when running Steam embedded within gamescope. + +## High Dynamic Range (HDR) + +Gamescope offers a wide range of configuration options for HDR support in both a nested usecase with the Wayland backend or an embedded usecase with the DRM backend. If your setup supports HDR, enabling HDR support within gamescope is as simple as adding `--hdr-enabled` to your gamescope launch options. + +Gamescope's logging reports the metadata of the HDR content it presents with [Gamescope WSI], and some MangoHud overlay presets include HDR status. The Steam Deck UI will also show an HDR badge on the right-side menu, next to the volume slider, when HDR is working both in-game and in gamescope. + +## Utilities + +Several utilities are built and installed along with the gamescope binary. Two binaries, gamescopestream and gamescopectl, are designed to be user-interactive while a third binary, gamescopereaper, is used for child process cleanup. + +**gamescopestream**: + +Gamescopestream is used to capture a Pipewire stream from a gamescope window and export it into a new window. It can be run alongside gamescope as `gamescopestream` in a separate terminal, which will capture the most recent window launched within gamescope. + +In embedded gamescope with Steam integration, you can pass along a Steam AppID to capture a specific window when multiple applications are launched. For example: Counter-Strike 2 has a Steam AppID of 730 and Portal 2 has a Steam AppID of 620. If both games are running simultaneeously within the same gamescope-session, you can use `gamescopestream 730` to capture only the Counter-Strike 2 window and export it into a new gamescopestream window. + +**gamescopectl**: + +Gamescopectl is a debugging utility that can be used to set convars, execute debugging commands, and list information about active gamescope instances. + +To print your current gamescope version and display panel information when filing an issue, you can run `gamescopectl` without any arguments while gamescope is running. + +```sh +gamescopectl version 3.15.9 (gcc 13.2.1) +gamescope_control info: + - Connector Name: eDP-1 + - Display Make: Valve Corporation + - Display Model: ANX7530 U + - Display Flags: 0x3 + - ValidRefreshRates: 45, 47, 48, 49, 50, 51, 53, 55, 56, 59, 60, 62, 64, 65, 66, 68, 72, 73, 76, 77, 78, 80, 81, 82, 84, 85, 86, 87, 88, 90 + Features: + - Reshade Shaders (1) - Version: 1 - Flags: 0x0 + - Display Info (2) - Version: 1 - Flags: 0x0 + - Pixel Filter (3) - Version: 1 - Flags: 0x0 + - Refresh Cycle Only Change Refresh Rate (4) - Version: 1 - Flags: 0x0 + - Mura Correction (5) - Version: 1 - Flags: 0x0 +You can execute any debug command in Gamescope using this tool. +For a list of commands and convars, use 'gamescopectl help' +``` + +Generally, convars can be set with 0 or false for disabled, and 1 or true for enabled. + +```sh +# Force gamescope to always composite (i.e. never use direct scan-out) +gamescopectl composite_force 1 + +# Stop forcing gamescope to always composite (i.e. go back to using direct scan-out when possible) +gamescopectl composite_force false + +# Print an output of gamescope backend information for debugging purposes +gamescopectl backend_info +``` + +Some convars, like logging levels, have additional values noted in `gamescopectl help`. + +**mangoapp**: + +This is not a binary that is included with gamescope, but [--mangoapp](https://github.com/flightlessmango/MangoHud?tab=readme-ov-file#gamescope) is the only officially supported method of adding MangoHud overlays to gamescope. It is designed to integrate MangoHud and gamescope in a way that does not adversely affect gamescope's presentation capabilities. Any other method of using MangoHud overlays are not supported as they can cause Vulkan errors or swapchain issues. + +## Scripts +> ⚠️ Experimental Feature ⚠️ + +Gamescope supports adding per-display configurations for display panels in `.lua` format. These configurations are used by the DRM backend as display profiles for known panels. Chromaticity coordinates can provide custom colorimetry to be used at scan-out, and custom refresh rate timings can be defined to customize the frame limiter within `gamescope-session`. + +Details about scripts can be found inside of the [`README.md`](https://github.com/ValveSoftware/gamescope/tree/master/scripts#readme) within the scripts subdirectory. ## Reshade support