# man33li/wayland-shader-kde architecture

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

- Interactive diagram: https://gitdiagram.com/man33li/wayland-shader-kde
- Repository: https://github.com/man33li/wayland-shader-kde

## Overview

WaylandShader is a native KWin desktop effect that applies RetroArch Slang presets and per-monitor color adjustments during composition. The main workflow is settings UI or CLI → asynchronous session-D-Bus control → KWin effect → preset compilation and per-output rendering → KWin presentation. The graph includes documented parameter editing, output controls, persistence, and hotplug handling. Some branches are documented in the README but not shown in sampled implementation excerpts, so their wiring is omitted where uncertain.

Main entry points: [`src/effect.cpp`](https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.cpp) (Desktop effect), [`src/shader_runtime.cpp`](https://github.com/man33li/wayland-shader-kde/blob/main/src/shader_runtime.cpp) (Shader runtime), [`src/controller_client.cpp`](https://github.com/man33li/wayland-shader-kde/blob/main/src/controller_client.cpp) (D-Bus client), [`src/controller_main.cpp`](https://github.com/man33li/wayland-shader-kde/blob/main/src/controller_main.cpp) (Settings window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control clients"]
  node_settings["Settings window"]
  node_cli["Control CLI<br/>[ctl_main.cpp]"]
  node_client["D-Bus client"]
end

subgraph group_effect["KWin effect"]
  node_plugin["Effect plugin<br/>[plugin.cpp]"]
  node_effect["Desktop effect<br/>[effect.cpp]"]
  node_outputstate["Output profiles<br/>[effect.cpp]"]
  node_config["Persistent settings<br/>[effect.cpp]"]
  node_loader["Preset loader<br/>[effect.cpp]"]
end

subgraph group_render["Shader rendering"]
  node_runtime["Shader runtime<br/>[shader_runtime.cpp]"]
  node_composition["Per-output composition<br/>[effect.cpp]"]
  node_color["Color adjustments<br/>[effect.cpp]"]
end

node_user(("Desktop user"))
node_bus(("Session D-Bus"))
node_kwin(("KWin compositor"))
node_preset["Slang preset"]
node_librashader["librashader"]
node_gpu["KWin render target"]

node_user -->|"controls"| node_settings
node_user -->|"runs commands"| node_cli
node_settings -->|"requests"| node_client
node_cli -->|"requests"| node_client
node_client -->|"calls asynchronously"| node_bus
node_bus -->|"dispatches control"| node_effect
node_effect -->|"publishes status"| node_bus
node_kwin -->|"loads effect"| node_plugin
node_plugin -->|"creates"| node_effect
node_kwin -->|"invokes render hooks"| node_effect
node_effect -->|"tracks outputs"| node_outputstate
node_effect -->|"reads and writes"| node_config
node_effect -->|"starts compilation"| node_loader
node_loader -->|"loads"| node_preset
node_loader -->|"creates runtime"| node_runtime
node_runtime -->|"uses API"| node_librashader
node_effect -->|"renders frames"| node_runtime
node_effect -->|"captures per output"| node_composition
node_composition -->|"shader frame"| node_runtime
node_composition -->|"applies adjustments"| node_color
node_color -->|"presents"| node_gpu
node_runtime -->|"renders shader output"| node_gpu

click node_settings "https://github.com/man33li/wayland-shader-kde/blob/main/src/controller_main.cpp"
click node_cli "https://github.com/man33li/wayland-shader-kde/blob/main/src/ctl_main.cpp"
click node_client "https://github.com/man33li/wayland-shader-kde/blob/main/src/controller_client.cpp"
click node_plugin "https://github.com/man33li/wayland-shader-kde/blob/main/src/plugin.cpp"
click node_effect "https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.cpp"
click node_outputstate "https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.cpp"
click node_config "https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.cpp"
click node_loader "https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.cpp"
click node_runtime "https://github.com/man33li/wayland-shader-kde/blob/main/src/shader_runtime.cpp"
click node_composition "https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.cpp"
click node_color "https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.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_settings,node_cli,node_client,node_user toneBlue
class node_plugin,node_effect,node_outputstate,node_config,node_loader toneAmber
class node_runtime,node_composition,node_color toneMint
class node_bus,node_kwin,node_preset,node_librashader,node_gpu toneIndigo
```

## Components

### Control clients

- [Settings window](https://github.com/man33li/wayland-shader-kde/blob/main/src/controller_main.cpp): `src/controller_main.cpp`
- [Control CLI](https://github.com/man33li/wayland-shader-kde/blob/main/src/ctl_main.cpp): `src/ctl_main.cpp`
- [D-Bus client](https://github.com/man33li/wayland-shader-kde/blob/main/src/controller_client.cpp): `src/controller_client.cpp`

### KWin effect

- [Effect plugin](https://github.com/man33li/wayland-shader-kde/blob/main/src/plugin.cpp): `src/plugin.cpp`
- [Desktop effect](https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.cpp): `src/effect.cpp`
- [Output profiles](https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.cpp): `src/effect.cpp`
- [Persistent settings](https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.cpp): `src/effect.cpp`
- [Preset loader](https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.cpp): `src/effect.cpp`

### Shader rendering

- [Shader runtime](https://github.com/man33li/wayland-shader-kde/blob/main/src/shader_runtime.cpp): `src/shader_runtime.cpp`
- [Per-output composition](https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.cpp): `src/effect.cpp`
- [Color adjustments](https://github.com/man33li/wayland-shader-kde/blob/main/src/effect.cpp): `src/effect.cpp`

### Other components

- **Desktop user**
- **Session D-Bus**
- **KWin compositor**
- **Slang preset**
- **librashader**
- **KWin render target**

## Connections

- Desktop user → Settings window: controls
- Desktop user → Control CLI: runs commands
- Settings window → D-Bus client: requests
- Control CLI → D-Bus client: requests
- D-Bus client → Session D-Bus: calls asynchronously
- Session D-Bus → Desktop effect: dispatches control
- Desktop effect → Session D-Bus: publishes status
- KWin compositor → Effect plugin: loads effect
- Effect plugin → Desktop effect: creates
- KWin compositor → Desktop effect: invokes render hooks
- Desktop effect → Output profiles: tracks outputs
- Desktop effect → Persistent settings: reads and writes
- Desktop effect → Preset loader: starts compilation
- Preset loader → Slang preset: loads
- Preset loader → Shader runtime: creates runtime
- Shader runtime → librashader: uses API
- Desktop effect → Shader runtime: renders frames
- Desktop effect → Per-output composition: captures per output
- Per-output composition → Shader runtime: shader frame
- Per-output composition → Color adjustments: applies adjustments
- Color adjustments → KWin render target: presents
- Shader runtime → KWin render target: renders shader output