# valvesoftware/gamescope architecture

> Architecture diagram of the GitHub repository valvesoftware/gamescope, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/valvesoftware/gamescope
- Repository: https://github.com/valvesoftware/gamescope

## Overview

#### 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: [`src/wlserver.cpp`](https://github.com/valvesoftware/gamescope/blob/master/src/wlserver.cpp) (Wayland server), [`src/rendervulkan.cpp`](https://github.com/valvesoftware/gamescope/blob/master/src/rendervulkan.cpp) (Vulkan compositor), [`src/backend.cpp`](https://github.com/valvesoftware/gamescope/blob/master/src/backend.cpp) (Backend dispatcher), [`src/main.cpp`](https://github.com/valvesoftware/gamescope/blob/master/src/main.cpp) (Gamescope executable)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Compositor Core"]
  node_main["Gamescope executable<br/>startup<br/>[main.cpp]"]
  node_wlserver["Wayland server<br/>server boundary<br/>[wlserver.cpp]"]
  node_compmgr["Window manager<br/>compositor control<br/>[steamcompmgr.cpp]"]
  node_xwayland["Xwayland context<br/>X11 integration<br/>[xwayland_ctx.hpp]"]
  node_protocols["Wayland extensions<br/>protocol definitions"]
  node_input["Input routing<br/>libinput bridge"]
  node_process["Game lifecycle<br/>process supervisor<br/>[Process.cpp]"]
end

subgraph group_frame["Frame Pipeline"]
  node_commit["Surface commits<br/>commit state<br/>[commit.cpp]"]
  node_buffers["Buffer tracking<br/>buffer state<br/>[BufferMemo.cpp]"]
  node_renderer["Vulkan compositor<br/>compute renderer<br/>[rendervulkan.cpp]"]
  node_shaders["Compute shaders<br/>Vulkan shaders"]
  node_timing["Frame pacing<br/>presentation timing<br/>[vblankmanager.cpp]"]
end

subgraph group_backends["Presentation Backends"]
  node_backend["Backend dispatcher<br/>backend selection<br/>[backend.cpp]"]
  node_drm["DRM/KMS backend<br/>hardware presentation<br/>[DRMBackend.cpp]"]
  node_otherbackends["Nested and alternate backends<br/>presentation backends<br/>[WaylandBackend.cpp]"]
end

subgraph group_integrations["Runtime Integrations"]
  node_pipewire["PipeWire streaming<br/>capture integration<br/>[pipewire.cpp]"]
  node_color["Color management<br/>display metadata<br/>[color_helpers.cpp]"]
  node_reshade["ReShade effects<br/>effect integration"]
  node_wsi_layer["Gamescope WSI layer<br/>Vulkan implicit layer"]
  node_tools["Companion CLI tools<br/>utilities<br/>[gamescopectl.cpp]"]
end

node_main -->|"starts"| node_wlserver
node_main -->|"selects"| node_backend
node_main -->|"launches game"| node_process
node_wlserver -->|"serves"| node_protocols
node_wlserver -->|"routes surfaces"| node_compmgr
node_xwayland -->|"integrates X11 surfaces"| node_compmgr
node_input -->|"delivers input"| node_wlserver
node_compmgr -->|"produces commit state"| node_commit
node_commit -->|"tracks buffers"| node_buffers
node_buffers -->|"supplies frames"| node_renderer
node_commit -.->|"direct scanout path"| node_drm
node_renderer -->|"presents composed frame"| node_backend
node_shaders -->|"implement effects"| node_renderer
node_timing -->|"paces presentation"| node_renderer
node_timing -->|"uses vblank"| node_drm
node_backend -->|"embedded display"| node_drm
node_backend -->|"nested, VR, headless"| node_otherbackends
node_pipewire -->|"capture protocol"| node_wlserver
node_color -->|"color transforms"| node_renderer
node_reshade -->|"loads effects"| node_renderer
node_wsi_layer -->|"swapchain integration"| node_protocols
node_tools -->|"controls session"| node_wlserver

click node_main "https://github.com/valvesoftware/gamescope/blob/master/src/main.cpp"
click node_wlserver "https://github.com/valvesoftware/gamescope/blob/master/src/wlserver.cpp"
click node_compmgr "https://github.com/valvesoftware/gamescope/blob/master/src/steamcompmgr.cpp"
click node_xwayland "https://github.com/valvesoftware/gamescope/blob/master/src/xwayland_ctx.hpp"
click node_input "https://github.com/valvesoftware/gamescope/blob/master/src/LibInputHandler.cpp"
click node_process "https://github.com/valvesoftware/gamescope/blob/master/src/Utils/Process.cpp"
click node_commit "https://github.com/valvesoftware/gamescope/blob/master/src/commit.cpp"
click node_buffers "https://github.com/valvesoftware/gamescope/blob/master/src/BufferMemo.cpp"
click node_renderer "https://github.com/valvesoftware/gamescope/blob/master/src/rendervulkan.cpp"
click node_timing "https://github.com/valvesoftware/gamescope/blob/master/src/vblankmanager.cpp"
click node_backend "https://github.com/valvesoftware/gamescope/blob/master/src/backend.cpp"
click node_drm "https://github.com/valvesoftware/gamescope/blob/master/src/Backends/DRMBackend.cpp"
click node_otherbackends "https://github.com/valvesoftware/gamescope/blob/master/src/Backends/WaylandBackend.cpp"
click node_pipewire "https://github.com/valvesoftware/gamescope/blob/master/src/pipewire.cpp"
click node_color "https://github.com/valvesoftware/gamescope/blob/master/src/color_helpers.cpp"
click node_reshade "https://github.com/valvesoftware/gamescope/blob/master/src/reshade_effect_manager.cpp"
click node_wsi_layer "https://github.com/valvesoftware/gamescope/blob/master/layer/VkLayer_FROG_gamescope_wsi.cpp"
click node_tools "https://github.com/valvesoftware/gamescope/blob/master/src/Apps/gamescopectl.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_wlserver,node_compmgr,node_xwayland,node_protocols,node_input,node_process toneBlue
class node_commit,node_buffers,node_renderer,node_shaders,node_timing toneAmber
class node_backend,node_drm,node_otherbackends toneMint
class node_pipewire,node_color,node_reshade,node_wsi_layer,node_tools toneRose
```

## Components

### Compositor Core

- [Gamescope executable](https://github.com/valvesoftware/gamescope/blob/master/src/main.cpp): startup · Parses options and starts the compositor session. · `src/main.cpp`
- [Wayland server](https://github.com/valvesoftware/gamescope/blob/master/src/wlserver.cpp): server boundary · Hosts clients, protocols, focus, and input-method objects. · `src/wlserver.cpp`
- [Window manager](https://github.com/valvesoftware/gamescope/blob/master/src/steamcompmgr.cpp): compositor control · Owns Xwayland-facing surfaces and shell behavior. · `src/steamcompmgr.cpp`
- [Xwayland context](https://github.com/valvesoftware/gamescope/blob/master/src/xwayland_ctx.hpp): X11 integration · `src/xwayland_ctx.hpp`
- **Wayland extensions**: protocol definitions · Generated control, swapchain, ReShade, PipeWire, and color interfaces.
- [Input routing](https://github.com/valvesoftware/gamescope/blob/master/src/LibInputHandler.cpp): libinput bridge · Routes and emulates game input. · `src/LibInputHandler.cpp`
- [Game lifecycle](https://github.com/valvesoftware/gamescope/blob/master/src/Utils/Process.cpp): process supervisor · Launches and supervises the target game. · `src/Utils/Process.cpp`

### Frame Pipeline

- [Surface commits](https://github.com/valvesoftware/gamescope/blob/master/src/commit.cpp): commit state · Turns client surface updates into compositor state. · `src/commit.cpp`
- [Buffer tracking](https://github.com/valvesoftware/gamescope/blob/master/src/BufferMemo.cpp): buffer state · `src/BufferMemo.cpp`
- [Vulkan compositor](https://github.com/valvesoftware/gamescope/blob/master/src/rendervulkan.cpp): compute renderer · Composites and post-processes frames when direct scanout is unavailable. · `src/rendervulkan.cpp`
- **Compute shaders**: Vulkan shaders · Composition, scaling, color, blur, sharpening, and conversion kernels.
- [Frame pacing](https://github.com/valvesoftware/gamescope/blob/master/src/vblankmanager.cpp): presentation timing · Coordinates timeline limits and vblank sequencing. · `src/vblankmanager.cpp`

### Presentation Backends

- [Backend dispatcher](https://github.com/valvesoftware/gamescope/blob/master/src/backend.cpp): backend selection · Selects nested, embedded, VR, or headless presentation. · `src/backend.cpp`
- [DRM/KMS backend](https://github.com/valvesoftware/gamescope/blob/master/src/Backends/DRMBackend.cpp): hardware presentation · Performs display scanout and direct flips. · `src/Backends/DRMBackend.cpp`
- [Nested and alternate backends](https://github.com/valvesoftware/gamescope/blob/master/src/Backends/WaylandBackend.cpp): presentation backends · Wayland, SDL, OpenVR, and headless implementations. · `src/Backends/WaylandBackend.cpp`

### Runtime Integrations

- [PipeWire streaming](https://github.com/valvesoftware/gamescope/blob/master/src/pipewire.cpp): capture integration · `src/pipewire.cpp`
- [Color management](https://github.com/valvesoftware/gamescope/blob/master/src/color_helpers.cpp): display metadata · Handles color metadata, EDID, and LUT looks. · `src/color_helpers.cpp`
- [ReShade effects](https://github.com/valvesoftware/gamescope/blob/master/src/reshade_effect_manager.cpp): effect integration · `src/reshade_effect_manager.cpp`
- [Gamescope WSI layer](https://github.com/valvesoftware/gamescope/blob/master/layer/VkLayer_FROG_gamescope_wsi.cpp): Vulkan implicit layer · Intercepts WSI swapchain behavior for Gamescope integration. · `layer/VkLayer_FROG_gamescope_wsi.cpp`
- [Companion CLI tools](https://github.com/valvesoftware/gamescope/blob/master/src/Apps/gamescopectl.cpp): utilities · Control, streaming, and reaper executables. · `src/Apps/gamescopectl.cpp`

## Connections

- 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
