How valvesoftware/gamescope works
Purpose and Executables
Gamescope is a Linux micro-compositor that isolates a game in a virtual Xwayland/Wayland desktop, scales or post-processes its frames, and presents them with low latency through direct DRM/KMS scanout or Vulkan compositing. Main executable startup and option processing are rooted in src/main.cpp and src/main.hpp; the primary compositor is built from src/meson.build. Companion command-line tools include src/Apps/gamescopectl.cpp, src/Apps/gamescopestream.cpp, and src/Apps/gamescopereaper.cpp.
Session and Window-System Control
The compositor hosts a Wayland server and manages Xwayland-facing game surfaces, focus, input methods, protocol objects, and shell state. src/wlserver.cpp / src/wlserver.hpp are the server boundary; src/steamcompmgr.cpp / src/steamcompmgr.hpp own compositor/window-management behavior; src/xwayland_ctx.hpp captures Xwayland integration context. Wayland extension definitions are generated from XML in protocol/, notably protocol/gamescope-control.xml, protocol/gamescope-swapchain.xml, and protocol/gamescope-reshade.xml.
Presentation Backends and Display Boundary
Backend selection abstracts nested, embedded, VR, and headless deployment modes. src/backend.cpp and src/backends.h dispatch to concrete implementations: DRM/KMS (src/Backends/DRMBackend.cpp), nested Wayland (src/Backends/WaylandBackend.cpp), SDL (src/Backends/SDLBackend.cpp), OpenVR (src/Backends/OpenVRBackend.cpp), and headless (src/Backends/HeadlessBackend.cpp). DRM is the hardware presentation boundary, supporting direct flips when possible; wlroots and libliftoff are vendored subprojects supporting Wayland/DRM composition.
Frame Pipeline and Vulkan Compositing
Window buffers flow from Wayland/Xwayland into compositor commit state, then either direct scanout or Vulkan compute composition. Key stages are buffer tracking in src/BufferMemo.cpp, surface/commit handling in src/commit.cpp, Vulkan rendering in src/rendervulkan.cpp / src/rendervulkan.hpp, and scanout timing in src/vblankmanager.cpp. Compute shaders under src/shaders/, including src/shaders/cs_composite_blit.comp, src/shaders/cs_easu.comp, and src/shaders/cs_nis.comp, implement composition, FSR/NIS/SGSR scaling, blur, sharpening, color work, and NV12 conversion.
Input, Process, and Frame Governance
Gamescope launches and supervises the target game while controlling its input and pacing. Process lifecycle utilities are in src/Utils/Process.cpp; reaping has a dedicated executable at src/Apps/gamescopereaper.cpp. Input arrives through libinput and is routed/emulated through src/LibInputHandler.cpp and src/InputEmulation.cpp. Frame limits, focus behavior, and presentation sequencing are coordinated through src/Timeline.cpp, src/vblankmanager.cpp, and runtime console variables in src/convar.cpp.
Streaming, Color, and Effects Integrations
PipeWire provides capture/streaming integration via src/pipewire.cpp and the protocol/gamescope-pipewire.xml protocol. Color-management and display metadata handling live in src/color_helpers.cpp, src/edid.cpp, and protocol definitions such as protocol/color-management-v1.xml; prebuilt LUT looks are supplied in looks/. Optional ReShade effect loading and control are implemented by src/reshade_effect_manager.cpp and exposed through the ReShade Wayland protocol. A separate Vulkan implicit layer, layer/VkLayer_FROG_gamescope_wsi.cpp, intercepts WSI behavior for Gamescope-specific swapchain integration.
Runtime and Build Dependencies
The primary runtime is native C++ on Linux, using Vulkan, DRM/KMS, Wayland/Xwayland, SDL, libinput, PipeWire, LuaJIT, and optional OpenVR. Meson is the build entry point (meson.build, src/meson.build), with important bundled/subproject dependencies including wlroots, vkroots, libdisplay-info, libliftoff, GLM, and OpenVR under subprojects/. Device-specific embedded-session display setup is scripted in scripts/00-gamescope/, with Lua display profiles under scripts/00-gamescope/displays/.
Main entry points: wlserver.cpp Wayland server · rendervulkan.cpp Vulkan compositor · backend.cpp Backend dispatcher · main.cpp Gamescope executable
Components 20
Compositor Core
- Gamescope executable · Parses options and starts the compositor session.
src/main.cpp - Wayland server · Hosts clients, protocols, focus, and input-method objects.
src/wlserver.cpp - Window manager · Owns Xwayland-facing surfaces and shell behavior.
src/steamcompmgr.cpp - Xwayland context
src/xwayland_ctx.hpp - Wayland extensions · Generated control, swapchain, ReShade, PipeWire, and color interfaces.
- Input routing · Routes and emulates game input.
src/LibInputHandler.cpp - Game lifecycle · Launches and supervises the target game.
src/Utils/Process.cpp
Frame Pipeline
- Surface commits · Turns client surface updates into compositor state.
src/commit.cpp - Buffer tracking
src/BufferMemo.cpp - Vulkan compositor · Composites and post-processes frames when direct scanout is unavailable.
src/rendervulkan.cpp - Compute shaders · Composition, scaling, color, blur, sharpening, and conversion kernels.
- Frame pacing · Coordinates timeline limits and vblank sequencing.
src/vblankmanager.cpp
Presentation Backends
- Backend dispatcher · Selects nested, embedded, VR, or headless presentation.
src/backend.cpp - DRM/KMS backend · Performs display scanout and direct flips.
src/Backends/DRMBackend.cpp - Nested and alternate backends · Wayland, SDL, OpenVR, and headless implementations.
src/Backends/WaylandBackend.cpp
Runtime Integrations
- PipeWire streaming
src/pipewire.cpp - Color management · Handles color metadata, EDID, and LUT looks.
src/color_helpers.cpp - ReShade effects
src/reshade_effect_manager.cpp - Gamescope WSI layer · Intercepts WSI swapchain behavior for Gamescope integration.
layer/VkLayer_FROG_gamescope_wsi.cpp - Companion CLI tools · Control, streaming, and reaper executables.
src/Apps/gamescopectl.cpp
Connections 22
- Gamescope executable → Wayland server: starts
- Gamescope executable → Backend dispatcher: selects
- Gamescope executable → Game lifecycle: launches game
- Wayland server → Wayland extensions: serves
- Wayland server → Window manager: routes surfaces
- Xwayland context → Window manager: integrates X11 surfaces
- Input routing → Wayland server: delivers input
- Window manager → Surface commits: produces commit state
- Surface commits → Buffer tracking: tracks buffers
- Buffer tracking → Vulkan compositor: supplies frames
- Surface commits → DRM/KMS backend: direct scanout path
- Vulkan compositor → Backend dispatcher: presents composed frame
- Compute shaders → Vulkan compositor: implement effects
- Frame pacing → Vulkan compositor: paces presentation
- Frame pacing → DRM/KMS backend: uses vblank
- Backend dispatcher → DRM/KMS backend: embedded display
- Backend dispatcher → Nested and alternate backends: nested, VR, headless
- PipeWire streaming → Wayland server: capture protocol
- Color management → Vulkan compositor: color transforms
- ReShade effects → Vulkan compositor: loads effects
- Gamescope WSI layer → Wayland extensions: swapchain integration
- Companion CLI tools → Wayland server: controls session