Layer-shell surface primitives. The Surface per-overlay wrapper, the SurfaceFactory that builds them with injected transport / engine / screen providers, the per-screen registry, and the topology coordinator that reconciles surfaces as monitors come and go.
`phosphor-wayland` owns the low-level zwlr_layer_shell_v1 plumbing: the QPA plugin and the raw LayerSurface. phosphor-layer sits one level up. It's the policy layer that says "we currently have these overlay surfaces, they belong to these screens, their per-surface animators look like this, and each has one of these well-known roles."
| Target | Holds | Links |
|---|---|---|
| PhosphorLayer::PhosphorLayer | Everything below except PhosphorWaylandTransport | Qt Core/Gui/Qml/Quick. No Wayland client code |
| PhosphorLayer::Wayland | PhosphorWaylandTransport | PhosphorLayer::PhosphorLayer, and phosphor-wayland privately |
Link PhosphorLayer::Wayland only where you construct a PhosphorWaylandTransport. A host that presents surfaces without a Wayland client connection, such as a compositor drawing them as scene nodes through its own ILayerShellTransport, links the core target alone. The Wayland target is built when PHOSPHORLAYER_WITH_PHOSPHORWAYLAND is ON (the default).
| Type | Purpose |
|---|---|
| PhosphorLayer::Surface | Per-surface wrapper around a layer-shell role |
| PhosphorLayer::SurfaceFactory | Stateless builder: SurfaceConfig → Surface |
| PhosphorLayer::SurfaceConfig | Per-surface descriptor: role, screen, QML source, properties |
| PhosphorLayer::Role | Value struct for wlr-layer-shell config (layer + anchors + kbd + zone + margins + scope prefix) |
| PhosphorLayer::ScreenSurfaceRegistry<T> | Per-screen surface tracking (template) |
| PhosphorLayer::TopologyCoordinator | Debounces screensChanged; reconciles registry |
| PhosphorLayer::ISurfaceStore | Persistence of per-surface state across restarts |
| PhosphorLayer::IScreenProvider | Enumerates screens with geometry and scale |
| PhosphorLayer::ISurfaceAnimator | Show / hide animator for layer surfaces |
| PhosphorLayer::ILayerShellTransport | Adapter into the Wayland binding |
| PhosphorLayer::IQmlEngineProvider | Shared QQmlEngine for surface QML instantiation |
| PhosphorLayer::JsonSurfaceStore | Bundled file-backed ISurfaceStore (QSaveFile-atomic) |
| PhosphorLayer::DefaultScreenProvider | Bundled IScreenProvider over QGuiApplication::screens() |
| PhosphorLayer::NoOpSurfaceAnimator | Animator that shows / hides instantly (default) |
| PhosphorLayer::PhosphorWaylandTransport | Default ILayerShellTransport over phosphor-wayland's LayerSurface (in PhosphorLayer::Wayland) |
| PhosphorLayer::XdgToplevelTransport | Fallback transport using xdg_toplevel (no layer-shell) |
#include <PhosphorLayer/SurfaceFactory.h>
#include <PhosphorLayer/SurfaceConfig.h>
#include <PhosphorLayer/Role.h>
#include <PhosphorLayer/defaults/PhosphorWaylandTransport.h>
#include <PhosphorLayer/defaults/DefaultScreenProvider.h>
using namespace PhosphorLayer;
auto transport = std::make_unique<PhosphorWaylandTransport>();
auto screens = std::make_unique<DefaultScreenProvider>();
SurfaceFactory factory(SurfaceFactory::Deps{.transport = transport.get(),
.screens = screens.get(),
.engineProvider = engineProvider,
.animator = animator});
SurfaceConfig cfg;
// Role is a plain value type. Construct one directly or use a recipe from
// the sibling phosphor-shell-patterns library if you prefer named UI
// patterns (Wallpaper, Hud, Modal, Floating, Panel, Toast).
cfg.role = Role{Layer::Overlay,
AnchorAll,
-1,
KeyboardInteractivity::None,
QMargins(),
QStringLiteral("zone-outline")};
cfg.screen = targetScreen; // QScreen*; nullptr resolves to the provider's primary()
cfg.contentUrl = QUrl(QStringLiteral("qrc:/overlays/ZoneOutline.qml"));
cfg.contextProperties.insert(QStringLiteral("zones"), QVariant::fromValue(zoneList));
Surface *s = factory.create(std::move(cfg), /*parent*/ this);
s->show();
// Later:
s->hide();