PhosphorLayout Namespace Reference

Namespaces
namespace	GapKeys
	Canonical JSON key strings for per-side outer-gap fields.
namespace	LayoutId
	LayoutPreview::id namespace utilities.
namespace	ScreenClassification
	Screen classification thresholds and utilities.

Classes
struct	AlgorithmMetadata
	Capability + display metadata for a single autotile algorithm. More...
class	CompositeLayoutSource
	Aggregates multiple ILayoutSource implementations behind one ILayoutSource interface. More...
struct	EdgeGaps
	Per-side edge gap values (resolved, non-negative pixel values) More...
class	FactoryContext
	Service registry passed to a layout-source-provider builder so it can pull whatever registries / dependencies its factory needs. More...
class	ILayoutSource
	Abstract producer of LayoutPreview values. More...
class	ILayoutSourceFactory
	Abstract factory for an ILayoutSource implementation. More...
class	ILayoutSourceRegistry
	Abstract notifier surface for every registry that feeds an ILayoutSource. More...
struct	LayoutPreview
	Renderer-ready snapshot of one layout entry (manual zone layout OR autotile algorithm result). More...
class	LayoutSourceBundle
	Owning bundle that assembles a list of ILayoutSourceFactory instances into a single CompositeLayoutSource. More...
class	LayoutSourceProviderRegistrar
	Static-init self-registration helper for provider libraries. More...
struct	PendingLayoutSourceProvider
	One pending layout-source-provider registration. More...

Enumerations
enum class	ZoneNumberDisplay {   RendererDecides , All , Last , FirstAndLast ,   None }
	How zone numbers are displayed in algorithm previews. More...
enum class	AspectRatioClass {   Any = 0 , Standard = 1 , Ultrawide = 2 , SuperUltrawide = 3 ,   Portrait = 4 }
	Screen aspect-ratio classification. More...

Functions
QString	zoneNumberDisplayToString (ZoneNumberDisplay value)
	Encode a ZoneNumberDisplay as its canonical wire string.
ZoneNumberDisplay	zoneNumberDisplayFromString (QStringView text)
	Decode a wire string back into a ZoneNumberDisplay.
PHOSPHORLAYOUTAPI_EXPORT QList< PendingLayoutSourceProvider > &	pendingLayoutSourceProviders ()
	Process-global list of pending provider registrations.
PHOSPHORLAYOUTAPI_EXPORT QMutex &	pendingLayoutSourceProvidersMutex ()
	Mutex protecting pendingLayoutSourceProviders().
template<typename Registry , typename Factory >
std::unique_ptr< ILayoutSourceFactory >	makeProviderFactory (const FactoryContext &ctx)
	Standard provider builder: pull Registry from ctx, return a new Factory bound to it, or nullptr if the composition root didn't surface that registry.

Variables
constexpr int	DefaultPreviewWindowCount = 4
	Reference window count used by ILayoutSource::previewAt when the caller doesn't specify one.

Enumeration Type Documentation

AspectRatioClass

enum class PhosphorLayout::AspectRatioClass

strong

Screen aspect-ratio classification.

Used to tag layouts with their intended monitor type and to classify physical screens at runtime so the layout picker can recommend matching layouts. The same enum is the type of LayoutPreview::aspectRatioClass so consumers can group/filter previews uniformly regardless of which provider produced them.

Enumerator
Any	Suitable for all aspect ratios (default)
Standard	~16:10 to ~16:9 (1.5 - 1.9)
Ultrawide	~21:9 (1.9 - 2.8)
SuperUltrawide	~32:9 (2.8+)
Portrait	Rotated/vertical monitors (< 1.0)

ZoneNumberDisplay

enum class PhosphorLayout::ZoneNumberDisplay

strong

How zone numbers are displayed in algorithm previews.

Internal typed enumeration used throughout the C++ codebase. String encodings are still used at the wire/parse boundaries (JS script front-matter, D-Bus AlgorithmInfoEntry, JSON serialisation, QML property strings) — convert via zoneNumberDisplayToString and zoneNumberDisplayFromString at those boundaries.

Enumerator
RendererDecides	Empty on the wire — algorithm defers to renderer default.
All	Every zone shows its number.
Last	Only the trailing zone is numbered.
FirstAndLast	First and last zones are numbered.
None	No zones are numbered.

Function Documentation

makeProviderFactory()

template<typename Registry , typename Factory >

std::unique_ptr< ILayoutSourceFactory > PhosphorLayout::makeProviderFactory ( const FactoryContext &  ctx )

inline

Standard provider builder: pull Registry from ctx, return a new Factory bound to it, or nullptr if the composition root didn't surface that registry.

Lets the per-provider factory .cpp boil down to a one-liner:

PhosphorLayout::LayoutSourceProviderRegistrar registrar(
    QStringLiteral("autotile"), /*priority=*/100,
    &PhosphorLayout::makeProviderFactory<ITileAlgorithmRegistry, AutotileLayoutSourceFactory>);

Forces every provider into the same null-bail-out discipline so a future engine can't accidentally crash the bundle by skipping the guard.

pendingLayoutSourceProviders()

PHOSPHORLAYOUTAPI_EXPORT QList< PendingLayoutSourceProvider > & PhosphorLayout::pendingLayoutSourceProviders

(

)

Process-global list of pending provider registrations.

Populated at static-init time by LayoutSourceProviderRegistrar instances in each provider library. Snapshotted (copied locally, never mutated) by LayoutSourceBundle::buildFromRegistered, so multiple bundles (daemon, editor, settings) each iterate the same list and create their own factory instances. A free function (rather than nested in a templated class) so every translation unit appends to the same QList regardless of template instantiation.

Warning

**Callers MUST hold pendingLayoutSourceProvidersMutex() across every access (read or write).** The reference returned here is the bare list; thread-safety lives in the mutex, not the container. In tree this matters when (a) a Qt plugin loader triggers dlopen of a provider on a worker thread (a LayoutSourceProviderRegistrar ctor running concurrently with a buildFromRegistered snapshot), and (b) two composition roots (e.g. daemon + KCM in the same process) run their bundle builds in parallel. The Meyer's-singleton QList is otherwise safe to reference but not safe to mutate without external sync.

Note

Plugin-loading constraint: this list is intended for static-init-time population. Bundles snapshot it at buildFromRegistered time, so providers introduced via a later dlopen are not picked up by bundles already built. Symmetrically, dlclose on a provider library leaves a dangling std::function closure in the list — safe as long as no bundle calls buildFromRegistered afterwards.

Todo:

(plugin-compositor) When runtime plugin loading lands, this contract must be revisited. Likely shape: explicit per-plugin handles, removal on dlclose, and a bundle rebuild API for composition roots that want to pick up a newly-loaded provider. The plugin-discovery pattern described above is the static-init-only variant; do not assume it will survive the switch to a dynamic plugin loader without a redesign.

pendingLayoutSourceProvidersMutex()

PHOSPHORLAYOUTAPI_EXPORT QMutex & PhosphorLayout::pendingLayoutSourceProvidersMutex

(

)

Mutex protecting pendingLayoutSourceProviders().

Same Meyer's- singleton lifetime as the list itself.

zoneNumberDisplayFromString()

ZoneNumberDisplay PhosphorLayout::zoneNumberDisplayFromString ( QStringView  text )

inline

Decode a wire string back into a ZoneNumberDisplay.

Forgiving: unknown or empty strings map to RendererDecides so callers need not pre-validate JSON / D-Bus input.

zoneNumberDisplayToString()

QString PhosphorLayout::zoneNumberDisplayToString ( ZoneNumberDisplay  value )

inline

Encode a ZoneNumberDisplay as its canonical wire string.

RendererDecides maps to an empty string so callers can check QString::isEmpty() before emitting the field.

Variable Documentation

DefaultPreviewWindowCount

constexpr int PhosphorLayout::DefaultPreviewWindowCount = 4

inlineconstexpr

Reference window count used by ILayoutSource::previewAt when the caller doesn't specify one.

Picked so most picker thumbnails render a visually representative layout without visiting the algorithm's empty state.