Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
Phosphor

Phosphor

Phosphor is the library layer of the Phosphor desktop: focused Qt6 / Wayland libraries for window placement, rendering, layer-shell surfaces and desktop shell services. Each library owns a single responsibility, so you pull in only what you need.

The libraries live in two repositories, core libraries in phosphor-libs and shell libraries in phosphor-shell-libs, each under libs/. These docs are generated from their public headers, with each library's hand-written design notes coming from its README.md where it has one.

Libraries

The libraries are organized into categories. Click a library name for its design and examples page, or a namespace for the generated API surface. This section is generated from the website's catalogue (src/data/libraries.ts) by scripts/mainpage-libraries.mjs.

Foundations Layout Engines Rendering Surfaces Shell Services

Foundations

Identity, configuration, D-Bus, IPC, scripting and registries. The plumbing everything else uses.

Library Namespace Responsibility
phosphor-config PhosphorConfig Pluggable configuration backends with schema + migration.
phosphor-context-resolver PhosphorContext Frozen-snapshot gate over the mode, desktop, and activity cascade.
phosphor-dbus PhosphorDBus Generic, service-agnostic D-Bus client utilities.
phosphor-fsloader PhosphorFsLoader Watched-directory + metadata-pack loader skeleton.
phosphor-geometry PhosphorGeometry Pure-function geometry helpers shared by both engines.
phosphor-identity PhosphorIdentity Stable cross-process identity formats.
phosphor-ipc PhosphorIpc Typed JSON-over-Unix-socket invocation channel for the shell.
phosphor-protocol PhosphorProtocol Shared D-Bus service names, wire types, and client helpers.
phosphor-registry PhosphorRegistry Factory-by-name registry and plugin loader for shell extension seams.
phosphor-scripting PhosphorScripting Generic sandboxed Luau host with CPU and heap guards.
phosphor-shortcuts PhosphorShortcuts Pluggable global-shortcut backends.
phosphor-workspaces PhosphorWorkspaces Virtual desktop and activity tracking.

Layout

Data models for zones, tiling layouts and the sources that provide them.

Library Namespace Responsibility
phosphor-layout-api PhosphorLayout Layout description interfaces + provider registry.
phosphor-tiles PhosphorTiles Tiling algorithms (Luau via pluau), the registry, and TilingState.
phosphor-zones PhosphorZones Manual zone data model, registry, and ILayoutSource.

Engines

The snapping, tiling and scrolling engines, with shared placement policy and window rules.

Library Namespace Responsibility
phosphor-engine PhosphorEngine Unified placement-engine surface + shared service contracts.
phosphor-placement PhosphorPlacement Window-zone tracking, floating state, auto-snap, and resnap.
phosphor-rules PhosphorRules Unified window/context rule engine with one match language and cache.
phosphor-scroll-engine PhosphorScrollEngine Scrolling-strip placement engine.
phosphor-snap-engine PhosphorSnapEngine Manual zone-based placement engine.
phosphor-tile-engine PhosphorTileEngine Automatic-tiling placement engine.

Rendering

Shaders, animation, audio input and window decoration rendering.

Library Namespace Responsibility
phosphor-animation PhosphorAnimation Motion runtime + shader-transition runtime with JSON profiles.
phosphor-audio PhosphorAudio Audio spectrum input for audio-reactive shaders.
phosphor-pointer PhosphorPointerShaders Pointer shader packs: trails, halos, and click ripples around the cursor.
phosphor-rendering PhosphorRendering ShaderEffect / ShaderNodeRhi / runtime GLSL → SPIR-V.
phosphor-shaders PhosphorShaders Shader-effect registry, base UBO layout, uniform extension contract.
phosphor-surface PhosphorSurfaceShaders Per-window shader effects and window decoration profiles.
phosphor-surface-quick PhosphorSurfaceQuick Qt Quick host for surface shader packs.
phosphor-theme PhosphorTheme Active design-token store with hot reload and matugen retint.

Surfaces

Wayland and layer-shell surfaces, screens, and the bridge to the compositor.

Library Namespace Responsibility
phosphor-compositor PhosphorCompositor Compositor-plugin SDK — the plugin side of the daemon / plugin split.
phosphor-layer PhosphorLayer Layer-shell surface primitives: Surface, factory, registry, coordinator.
phosphor-popout PhosphorPopout Central arbiter for transient popout lifetime, focus, and exclusivity.
phosphor-screens PhosphorScreens Physical and virtual screen topology resolver.
phosphor-surfaces PhosphorSurfaces Surface manager with QML loading and Vulkan wiring.
phosphor-wayland PhosphorWayland Custom QPA plugin + LayerSurface wrapper.

Shell

Building blocks for a desktop shell: theme, popouts, widgets and the shell surfaces.

Library Namespace Responsibility
phosphor-control PhosphorControl Reusable Qt6/QML/Kirigami settings-app framework.
phosphor-overlay PhosphorOverlay Per-screen layer-shell shell hosts with named slot vocabulary.
phosphor-shell PhosphorShell Quickshell-style declarative QML framework for layer-shell desktop shells.
phosphor-shell-bar Phosphor.Bar (QML) The spectrum-rail bar surface and its built-in widgets.
phosphor-shell-control-center Phosphor.ControlCenter (QML) Quick-settings rails for Wi-Fi, Bluetooth, audio, brightness, and idle.
phosphor-shell-dashboard Phosphor.Dashboard (QML) Full-screen dashboard and keybind cheatsheet drawn on the placement map.
phosphor-shell-launcher PhosphorShellLauncher Spotlight-style launcher over apps, windows, clipboard, arithmetic, and commands.
phosphor-shell-lock PhosphorShellLock Lockscreen surface that draws the layout you left as outlines.
phosphor-shell-notifications Phosphor.Notifications (QML) Toast framework for notification popups.
phosphor-shell-osd Phosphor.OSD (QML) On-screen-display framework for volume, brightness, and friends.
phosphor-shell-patterns PhosphorShellPatterns Named UI-pattern recipes on top of phosphor-layer Role.
phosphor-shell-picker PhosphorShellPicker Wallpaper and theme strip that previews palettes on the live desktop.
phosphor-shell-polkit Phosphor.Polkit (QML) PolicyKit authentication prompt attached to the requesting window.
phosphor-shell-power Phosphor.Power (QML) Session menu for lock, suspend, hibernate, log out, restart, and shut down.
phosphor-shell-widgets Phosphor.Widgets (QML) Material 3 QML atoms every shell surface composes from.

Services

System services the shell binds to, from the tray and battery to polkit and the session.

Library Namespace Responsibility
phosphor-service-bluetooth PhosphorServiceBluetooth BlueZ adapter and device state with device pairing.
phosphor-service-brightness PhosphorServiceBrightness Display and keyboard backlight brightness control.
phosphor-service-clipboard PhosphorServiceClipboard De-duplicated, persistent clipboard history.
phosphor-service-icontheme PhosphorServiceIconTheme XDG icon-theme lookup and a QML image provider.
phosphor-service-idle PhosphorServiceIdle Multi-stage Wayland idle monitoring and inhibition.
phosphor-service-lock PhosphorServiceLock PAM authentication and Wayland session-lock lifecycle.
phosphor-service-mpris PhosphorServiceMpris MPRIS2 media-player discovery, status, and transport control.
phosphor-service-network PhosphorServiceNetwork NetworkManager device and connectivity state.
phosphor-service-notifications PhosphorServiceNotifications Freedesktop notification server and live history.
phosphor-service-pipewire PhosphorServicePipeWire Native PipeWire mixer for sinks, sources, and streams.
phosphor-service-polkit PhosphorServicePolkit PolicyKit authentication agent for the session.
phosphor-service-session PhosphorServiceSession logind session manager, power actions, and sleep inhibitors.
phosphor-service-sni PhosphorServiceSni StatusNotifierItem system-tray host with dbusmenu menus.
phosphor-service-upower PhosphorServiceUPower Battery and power-device status via UPower.

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 public header, grouped by library directory.
  • D-Bus interfaces? → D-Bus APIs — every interface PlasmaZones exposes on the session bus, generated from plasmazones/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 each library's 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.