PhosphorLayer::SurfaceConfig Struct Reference

Immutable per-surface configuration passed to SurfaceFactory::create(). More...

#include <phosphor-layer/include/PhosphorLayer/SurfaceConfig.h>

Public Member Functions
Layer	effectiveLayer () const noexcept
Anchors	effectiveAnchors () const noexcept
int	effectiveExclusiveZone () const noexcept
KeyboardInteractivity	effectiveKeyboard () const noexcept
QMargins	effectiveMargins () const noexcept
QString	effectiveDebugName () const
	SurfaceConfig ()
	~SurfaceConfig ()
	SurfaceConfig (const SurfaceConfig &)=delete
SurfaceConfig &	operator= (const SurfaceConfig &)=delete
	SurfaceConfig (SurfaceConfig &&) noexcept
SurfaceConfig &	operator= (SurfaceConfig &&) noexcept

Public Attributes
Role	role
	Protocol-level defaults. Required.
QUrl	contentUrl
	QML root component URL (qrc:/… or file://…).
std::unique_ptr< QQuickItem >	contentItem
	Pre-built QQuickItem.
QScreen *	screen = nullptr
	Target screen.
QVariantMap	contextProperties
	Injected into the surface's QML root context.
QVariantMap	windowProperties
	Applied to the QQuickWindow as dynamic properties (via QObject:: setProperty) BEFORE the QML content loads.
QQmlEngine *	sharedEngine = nullptr
	Opt-in shared QQmlEngine.
std::optional< Layer >	layerOverride
std::optional< Anchors >	anchorsOverride
std::optional< int >	exclusiveZoneOverride
std::optional< KeyboardInteractivity >	keyboardOverride
std::optional< QMargins >	marginsOverride
bool	keepMappedOnHide = false
	When true, Surface::hide() does NOT call QQuickWindow::hide(); the surface stays Qt-visible and the visual "hidden" state is driven by the injected ISurfaceAnimator (typically by animating the root QML item's opacity to 0).
QSize	initialSize = {}
	Initial size committed to the wl_surface during warm-up.
QString	debugName
	Logged in state transitions. Defaults to Role::scopePrefix when empty.

Detailed Description

Immutable per-surface configuration passed to SurfaceFactory::create().

Aggregates a Role (protocol-level defaults) with per-instance data: content source, target screen, per-instance overrides of role defaults, optional shared QML engine.

Reconfiguration = destroy + recreate. This matches wlr-layer-shell, which forbids most post-show property changes (layer, anchors, output, scope are all immutable per protocol).

Exactly one of contentUrl / contentItem must be non-empty.

Note

Pre-1.0 ABI. SurfaceConfig is a plain aggregate exposed across the DSO boundary. Adding or reordering fields between releases is a binary-incompatible change until the library reaches 1.0 (SOVERSION 0 signals this). Consumers that aggregate-init by position must rebuild against each release; use named-member init for forward compatibility.

Constructor & Destructor Documentation

SurfaceConfig() [1/3]

PhosphorLayer::SurfaceConfig::SurfaceConfig

(

)

~SurfaceConfig()

PhosphorLayer::SurfaceConfig::~SurfaceConfig

(

)

SurfaceConfig() [2/3]

PhosphorLayer::SurfaceConfig::SurfaceConfig ( const SurfaceConfig &  )

delete

SurfaceConfig() [3/3]

PhosphorLayer::SurfaceConfig::SurfaceConfig ( SurfaceConfig &&  )

noexcept

Member Function Documentation

effectiveAnchors()

Anchors PhosphorLayer::SurfaceConfig::effectiveAnchors ( ) const

inlinenoexcept

effectiveDebugName()

QString PhosphorLayer::SurfaceConfig::effectiveDebugName ( ) const

inline

effectiveExclusiveZone()

int PhosphorLayer::SurfaceConfig::effectiveExclusiveZone ( ) const

inlinenoexcept

effectiveKeyboard()

KeyboardInteractivity PhosphorLayer::SurfaceConfig::effectiveKeyboard ( ) const

inlinenoexcept

effectiveLayer()

Layer PhosphorLayer::SurfaceConfig::effectiveLayer ( ) const

inlinenoexcept

effectiveMargins()

QMargins PhosphorLayer::SurfaceConfig::effectiveMargins ( ) const

inlinenoexcept

operator=() [1/2]

SurfaceConfig & PhosphorLayer::SurfaceConfig::operator= ( const SurfaceConfig &  )

delete

operator=() [2/2]

SurfaceConfig & PhosphorLayer::SurfaceConfig::operator= ( SurfaceConfig &&  )

noexcept

Member Data Documentation

anchorsOverride

std::optional<Anchors> PhosphorLayer::SurfaceConfig::anchorsOverride

contentItem

std::unique_ptr<QQuickItem> PhosphorLayer::SurfaceConfig::contentItem

Pre-built QQuickItem.

Ownership is transferred to the Surface at construction. Mutually exclusive with contentUrl. Note: unique_ptr is intentionally non-copyable — SurfaceConfig containing a contentItem is move-only.

contentUrl

QUrl PhosphorLayer::SurfaceConfig::contentUrl

QML root component URL (qrc:/… or file://…).

Mutually exclusive with contentItem.

contextProperties

QVariantMap PhosphorLayer::SurfaceConfig::contextProperties

Injected into the surface's QML root context.

Keys become context properties visible to the loaded QML as global identifiers.

debugName

QString PhosphorLayer::SurfaceConfig::debugName

Logged in state transitions. Defaults to Role::scopePrefix when empty.

exclusiveZoneOverride

std::optional<int> PhosphorLayer::SurfaceConfig::exclusiveZoneOverride

initialSize

QSize PhosphorLayer::SurfaceConfig::initialSize = {}

Initial size committed to the wl_surface during warm-up.

Determines the size of the first Vulkan swapchain Qt allocates.

When isEmpty() (the default QSize{}), warm-up sizes the wrapper QQuickWindow to the target screen's full geometry. That guarantees a non-zero buffer for partial-anchor layer surfaces (see the "non-zero size BEFORE completeCreate" invariant in surface.cpp::instantiateFromComponent), but it costs a full-screen swapchain (~25 MB at 4K × 3 buffers on NVIDIA) even when the eventual visible content is a small toast.

When non-empty, surface.cpp uses this as the warm-up geometry instead. Subsequent imperative setWidth/setHeight calls still resize the surface; this only governs the size of the warm-up commit. Pass the largest size the surface is expected to grow to in practice — that way Qt avoids the "small swapchain → resize on first show" round trip on NVIDIA, where swapchain resize is destroy + recreate.

QSize::isEmpty() (any non-positive dimension) is the unset sentinel; partially-zero sizes are silently treated as "use the default" — pass a fully-positive size or leave it default.

keepMappedOnHide

bool PhosphorLayer::SurfaceConfig::keepMappedOnHide = false

When true, Surface::hide() does NOT call QQuickWindow::hide(); the surface stays Qt-visible and the visual "hidden" state is driven by the injected ISurfaceAnimator (typically by animating the root QML item's opacity to 0).

The library still flips the underlying QWindow's Qt::WindowTransparentForInput flag during the hide so the still-mapped layer surface stops intercepting clicks at its screen position.

Use this for overlays where reattaching the wl_surface (and its Vulkan swapchain) on every show/hide cycle is too expensive — the PlasmaZones layout picker, navigation OSD, and zone selector all fall into this category. The Phase-4 LayoutOsd "L3 v2" pattern pioneered this for OSDs; Phase 5 generalises it into the library.

Default false preserves the original lifecycle: hide() unmaps the window immediately and a future show() pays the reattach cost.

keyboardOverride

std::optional<KeyboardInteractivity> PhosphorLayer::SurfaceConfig::keyboardOverride

layerOverride

std::optional<Layer> PhosphorLayer::SurfaceConfig::layerOverride

marginsOverride

std::optional<QMargins> PhosphorLayer::SurfaceConfig::marginsOverride

role

Role PhosphorLayer::SurfaceConfig::role

Protocol-level defaults. Required.

screen

QScreen* PhosphorLayer::SurfaceConfig::screen = nullptr

Target screen.

Nullptr means "let the factory resolve to the screen provider's primary()". Consumers that want focus-follows-surface can pass IScreenProvider::focused() here.

sharedEngine

QQmlEngine* PhosphorLayer::SurfaceConfig::sharedEngine = nullptr

Opt-in shared QQmlEngine.

Nullptr (default) → Surface owns its own engine for full isolation. Non-null → Surface uses the provided engine; caller retains ownership.

windowProperties

QVariantMap PhosphorLayer::SurfaceConfig::windowProperties

Applied to the QQuickWindow as dynamic properties (via QObject:: setProperty) BEFORE the QML content loads.

Lets the QML access them via the implicit window.foo binding. Distinct from contextProperties: window properties are per-surface (won't leak between shared-engine surfaces) and are observable through Qt's property system (QVariant).

---

The documentation for this struct was generated from the following file:

• phosphor-layer/include/PhosphorLayer/SurfaceConfig.h