Phosphor

Phosphor

Phosphor is a suite of focused Qt6 / Wayland libraries for building window-management tools. Each library owns a single responsibility; the suite is designed to be consumed à la carte, so you pull in only what you need.

The suite currently ships with PlasmaZones, the reference consumer, and the headers live under libs/phosphor-*/include/ in that repository. These docs are generated from those public headers, with each library's hand-written design notes coming from its README.md.

Libraries

The suite is organized into five categories — click a library name for its design + examples page, or a namespace for the auto-generated API surface.

Foundations Layout Engines Rendering Surfaces Shell

Foundations

Low-level shared infrastructure every other layer builds on.

Library	Namespace	Responsibility
`phosphor-identity`	PhosphorIdentity	Stable cross-process identity formats (WindowId, ScreenId, VirtualScreenId)
`phosphor-geometry`	PhosphorGeometry	Pure-function geometry helpers shared by both engines
`phosphor-dbus`	PhosphorDBus	Generic, service-agnostic D-Bus client utilities
`phosphor-protocol`	PhosphorProtocol	Shared D-Bus service names, wire types, helpers
`phosphor-config`	PhosphorConfig	Pluggable configuration backends with schema + migration
`phosphor-fsloader`	PhosphorFsLoader	Watched-directory + metadata-pack loader skeleton
`phosphor-shortcuts`	Phosphor::Shortcuts	Pluggable global-shortcut backends
`phosphor-workspaces`	PhosphorWorkspaces	Virtual desktop and activity tracking

Layout

Zone and tile data models — the what of placement.

Library	Namespace	Responsibility
`phosphor-layout-api`	PhosphorLayout	Layout description interfaces + provider registry
`phosphor-zones`	PhosphorZones	Manual zone data model, registry, and ILayoutSource
`phosphor-tiles`	PhosphorTiles	Tiling algorithms, sandboxed JS, and TilingState

Engines

Placement runtime — the how of placement.

Library	Namespace	Responsibility
`phosphor-engine`	PhosphorEngine	Unified placement-engine surface + shared service contracts
`phosphor-snap-engine`	PhosphorSnapEngine	Manual zone-based placement engine
`phosphor-tile-engine`	PhosphorTileEngine	Automatic-tiling placement engine
`phosphor-placement`	PhosphorPlacement	Window tracking, auto-snap, resnap, rotation, empty-zone queries

Rendering

Shader and animation pipeline.

Library	Namespace	Responsibility
`phosphor-shaders`	PhosphorShaders	Shader-effect registry, base UBO layout, uniform extension contract
`phosphor-rendering`	PhosphorRendering	ShaderEffect / ShaderNodeRhi / runtime GLSL → SPIR-V
`phosphor-animation`	PhosphorAnimation	Motion runtime + shader-transition runtime with JSON profiles
`phosphor-audio`	PhosphorAudio	Audio spectrum input for audio-reactive shaders

Surfaces

Wayland integration, layer-shell primitives, and screen topology.

Library	Namespace	Responsibility
`phosphor-wayland`	PhosphorWayland	Custom QPA plugin + LayerSurface wrapper
`phosphor-layer`	PhosphorLayer	Layer-shell surface primitives: factory, registry, coordinator
`phosphor-surfaces`	PhosphorSurfaces	Surface manager with QML loading and Vulkan wiring
`phosphor-screens`	Phosphor::Screens	Physical + virtual screen topology resolver
`phosphor-compositor`	PhosphorCompositor	Plugin SDK for hosting the daemon in non-KWin Wayland compositors

Shell

Higher-level shell infrastructure on top of the surface stack — panel windows, named UI-pattern recipes, system-tray and platform services.

Library	Namespace	Responsibility
`phosphor-shell`	PhosphorShell	Quickshell-style declarative QML framework for layer-shell shells
`phosphor-services`	PhosphorServices	D-Bus + platform integrations (system tray today; notifications, MPRIS, UPower next)
`phosphor-overlay`	PhosphorOverlay	Per-screen layer-shell shell hosts with named slot vocabulary
`phosphor-shell-patterns`	PhosphorShellPatterns	Named UI-pattern Role recipes (wallpaper, panel, modal, toast)

Where to start

• Browsing by name? → Classes — alphabetical class index across every library.
• Browsing by namespace? → Namespaces — one entry per Phosphor* library.
• Browsing by header? → Files — every header under libs/phosphor-*/include/ grouped by library directory.
• D-Bus interfaces? → D-Bus APIs — every interface PlasmaZones exposes on the session bus, generated from dbus/*.xml.
• Looking for a specific symbol? → use the search box in the upper corner (indexes class names, method names, and file names).

Conventions

All Phosphor libraries share a handful of cross-cutting conventions so anything you learn in one library transfers to the others:

• Namespaces mirror library names — libs/phosphor-identity/include/PhosphorIdentity/WindowId.h declares PhosphorIdentity::WindowId. The Phosphor prefix is elided when sorting the class index (you won't see a hundred classes starting with Phosphor...).
• Public API in include/, implementation in src/ — everything under libs/phosphor-*/include/ is the stable surface you can link against. src/ and any _p.h/internal/ headers are intentionally excluded from this reference.
• Per-library README is the design page — each library's README.md is the source of truth for its responsibility, key types, examples, and design notes; the build pipeline (scripts/readme-to-doxypage.py) stitches them in here.
• Qt idioms throughout — Q_OBJECT, Q_PROPERTY with READ/WRITE/NOTIFY, parent-based ownership, signals in past tense (layoutChanged), slots in imperative (saveLayout). Macros are stripped by the preprocessor before Doxygen parses, so class declarations read cleanly in the generated HTML.
• Interface-first for anything pluggable — config storage, shortcut backends, wallpaper providers, render backends are all declared as abstract I* interfaces with one or more concrete implementations. That makes it easy to drop in a different persistence layer or shortcut router without touching the consumers.

License

All Phosphor libraries: LGPL-2.1-or-later. Consumers (including PlasmaZones) link against them under that license.