enricobuehler
76791e53e9
Split the docs' single distro×desktop axis (ubuntu-gnome / ubuntu-kde / fedora-kde) into two,
which deduplicates the shared mechanics and scales to distros that run several desktops (Arch):
- Install the host — per distro/OS (ubuntu, fedora, arch, bazzite, steamos-host, windows-host):
GPU driver + package + input group, then a canonical "Configure your desktop" funnel.
- Configure your desktop — per compositor (kde, gnome, gamescope, sway): host.env, compositor
quirks, the headless session, and starting the host.
New shared web-console page (enable · login password · arm pairing) removes the console/password
block that was copy-pasted across all seven host pages. Merged ubuntu-gnome + ubuntu-kde into
ubuntu; renamed fedora-kde to fedora; kept bazzite and steamos-host as dedicated appliance guides
(trimmed of duplication). Moved the KWin headless session, the GNOME EGL/lock traps, and the
gamescope attach/managed model out of the distro pages onto their compositor pages.
Fixed while restructuring: distro-specific paths on kde (kde-desktop-setup.sh is Fedora/Bazzite-only;
the .deb ships host.env.kde under /usr/share/punktfunk-host), the interactive "start the host" step
that was lost in the merge, sway over-claiming Hyprland, and a pre-existing broken anchor in
how-it-works.
Removal of the three old pages was captured by the preceding commit b28ddfc (a concurrent commit
swept up the staged git-rm); the net docs tree is correct. Fumadocs build + internal link/anchor
check green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
72 lines
3.6 KiB
Markdown
72 lines
3.6 KiB
Markdown
---
|
|
title: How It Works
|
|
description: The ideas behind punktfunk — per-client virtual displays, the two protocols, and trust.
|
|
---
|
|
|
|
You don't need to know any of this to use punktfunk, but it helps to understand what's happening
|
|
when you connect.
|
|
|
|
## A virtual display, sized to your device
|
|
|
|
When a client connects, the host asks your desktop to create a **new virtual display** at exactly the
|
|
client's resolution and refresh rate, captures that display, and streams it. The virtual display is
|
|
real to your desktop — apps can be moved onto it, games open on it — but it isn't tied to any physical
|
|
monitor. When the client disconnects, the virtual display goes away.
|
|
|
|
That's why a 1080p60 laptop and a 1440p120 desktop can stream from the same host **at the same time**,
|
|
each at its own mode — they each get their own virtual display.
|
|
|
|
How the virtual display is created depends on your host:
|
|
|
|
| Host | How |
|
|
|---|---|
|
|
| **GNOME** (Mutter) | A virtual monitor via the screen-cast API |
|
|
| **KDE Plasma** (KWin) | A virtual output via KWin's screencast |
|
|
| **Bazzite / Steam** (gamescope) | A nested gamescope session launched at the client's mode |
|
|
| **Sway** (wlroots) | A headless output added to the running session |
|
|
| **Windows** | A virtual-display driver — including punktfunk's own **indirect display driver** the host pushes frames straight into — a real virtual display, no physical monitor, even on the secure desktop |
|
|
|
|
That last one is the distinctive part on Windows: rather than only capturing an existing screen,
|
|
punktfunk has **its own indirect display driver (IDD)**, and the host can push finished frames
|
|
**straight into the driver**. You get the same on-the-fly virtual display the Linux compositors give
|
|
you — at the client's exact mode, with no physical monitor or dummy HDMI dongle, and even on the
|
|
secure desktop (UAC / lock screen). That tight, push-based integration is unusual among Windows
|
|
streaming hosts.
|
|
|
|
## From screen to GPU to wire
|
|
|
|
Captured frames never touch the CPU on their way to the encoder. They go straight from the
|
|
compositor to the GPU's NVENC hardware encoder (HEVC/H.264/AV1) and out to the network — a **zero-copy
|
|
GPU path** that keeps latency low even at high resolutions and frame rates.
|
|
|
|
## Two protocols
|
|
|
|
punktfunk speaks two protocols over the same host:
|
|
|
|
- **GameStream** — the protocol Moonlight uses. Any [Moonlight](/docs/moonlight) client connects with
|
|
no special software. This is the most compatible way in.
|
|
- **punktfunk/1 (native)** — a purpose-built protocol with a QUIC control channel and a UDP data
|
|
channel hardened with forward error correction and encryption. It's lower-latency and more resilient
|
|
on imperfect networks, and it's what the [native clients](/docs/clients) (Apple, Linux, Windows,
|
|
Android) use.
|
|
|
|
Both run from a single host process, so you don't choose up front — Moonlight clients use GameStream,
|
|
the native clients use punktfunk/1.
|
|
|
|
## Pairing and trust
|
|
|
|
The first time a device connects, you pair it: the host shows a short **PIN**, you type it into the
|
|
client, and the two remember each other. After that the device reconnects automatically on a pinned
|
|
cryptographic identity — no PIN, no account, no cloud. See [Pairing & Trust](/docs/pairing).
|
|
|
|
## Finding hosts
|
|
|
|
Hosts advertise themselves on your local network, so clients can **discover** them automatically
|
|
instead of needing an IP address. The native clients and Moonlight both list hosts they find on the
|
|
LAN.
|
|
|
|
## Multiple devices at once
|
|
|
|
A host can stream to several clients simultaneously — your laptop and your TV both viewing (and
|
|
controlling) the desktop, each at its own resolution. See [Multiple devices](/docs/configuration#multiple-devices-at-once).
|