Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorSurfaceShaders::SurfaceShaderRegistry Class Reference

Registry of available surface shader effects. More...

#include <PhosphorSurface/SurfaceShaderRegistry.h>

Inheritance diagram for PhosphorSurfaceShaders::SurfaceShaderRegistry:
[legend]

Classes

class  SurfacePack
 Registry entry: a discovered surface effect as a PhosphorRegistry factory. More...

Signals

void effectsChanged ()

Public Member Functions

 SurfaceShaderRegistry (QObject *parent=nullptr)
 ~SurfaceShaderRegistry () override
void addSearchPath (const QString &path, PhosphorFsLoader::LiveReload liveReload=PhosphorFsLoader::LiveReload::On)
void addSearchPaths (const QStringList &paths, PhosphorFsLoader::LiveReload liveReload=PhosphorFsLoader::LiveReload::On, PhosphorFsLoader::RegistrationOrder order=PhosphorFsLoader::RegistrationOrder::LowestPriorityFirst)
QStringList searchPaths () const
void setUserPath (const QString &path)
void refresh ()
QList< SurfaceShaderEffect > availableEffects () const
SurfaceShaderEffect effect (const QString &id) const
bool hasEffect (const QString &id) const
QStringList effectIds () const
QVariantMap translateSurfaceParams (const QString &effectId, const QVariantMap &friendlyParams) const
 Translate a friendly parameter map into the canonical slot keys consumed by both runtimes that drive surface shaders.

Static Public Member Functions

static QVariantMap translateSurfaceParams (const SurfaceShaderEffect &effect, const QVariantMap &friendlyParams)
 Static counterpart for callers that already hold the resolved SurfaceShaderEffect (e.g.
static QString paramPreamble (const SurfaceShaderEffect &effect)
 Build the generated #define p_<id> <glsl-accessor> preamble for effect's declared parameters so authors read a parameter by name (p_glow) instead of hand-decoding a customParams[N].xyzw lane.
static QString surfaceEntryPrologue ()
 Entry-point scaffold, matching the overlay (pZone/pImage) and animation (pTransition/pIn+pOut) categories.
static QList< PhosphorShaders::EntryCandidate > surfaceEntryCandidates ()
static bool isBuiltinBufferShader (const QString &token)
 Resolve a builtin: buffer-shader token (e.g.
static QString resolveBuiltinBufferShader (const QString &token, const QString &effectDir)
static QString compositorVertexSource ()
 The vertex stage the COMPOSITOR compiles for every surface pack that declares none of its own (the bundled border ships none).
static QString compositorBufferVertexSource ()
 The vertex stage of every surface BUFFER pass on the compositor: a unit quad already in clip space (no matrix), since a buffer pass is an FBO-to-FBO blit with no window quad to project.
static QString compositorPresentVertexSource ()
 The vertex stage of the decoration PRESENT shader, the passthrough that samples a decorated window's pre-composited final FBO.

Detailed Description

Registry of available surface shader effects.

Discovers shader packs from configured search paths. Each pack is a subdirectory containing a metadata.json describing the effect plus the shader source files it references.

Directory layout

<search-path>/
border/
metadata.json ← { "id": "border", "fragmentShader": "effect.frag", ... }
effect.frag
rounded-corners/
metadata.json
effect.frag
SurfaceShaderEffect effect(const QString &id) const

The subdirectory name is decorative — the id field in metadata.json is the registry key. This matches PhosphorShaders::ShaderRegistry's and AnimationShaderRegistry's convention.

Search paths and live reload

Storage + change-notify is the generic PhosphorRegistry::Registry<SurfacePack> (one SurfacePack wraps one discovered SurfaceShaderEffect); the on-disk scan + hot-reload is a PhosphorRegistry::MetadataPackLoader<SurfacePack>. Search-path management (addSearchPath, addSearchPaths, searchPaths, setUserPath, refresh) forwards to that loader. The first addSearchPath[s] call with LiveReload::On (the default) installs a QFileSystemWatcher with the standard 50 ms debounce, parent-watch promotion for missing user-data dirs, per-file watches re-armed on every rescan, and rescan-during-rescan race protection. Forbidden roots ($HOME, /, XDG data/config/cache/temp/runtime, Documents, Downloads) are refused.

effectsChanged fires on every committed rescan (the loader's coarse onCommitted hook) — i.e. whenever the discovered set or any watched-file fingerprint differs from the previous scan, including any metadata.json field edit or shader-source edit.

Thread safety

GUI-thread only for both reads and mutations. The pack map lives inside the registry and is rebuilt on the GUI thread inside the rescan; the public lookup methods read it without synchronisation.

searchPaths() is the one exception: it returns a by-value snapshot of an implicitly-shared QStringList, so a GUI-thread caller can snapshot it and propagate the result to worker threads. Calling it from a worker thread concurrently with a GUI-thread mutation is a data race; snapshot on the GUI thread first.

Constructor & Destructor Documentation

◆ SurfaceShaderRegistry()

PhosphorSurfaceShaders::SurfaceShaderRegistry::SurfaceShaderRegistry ( QObject * parent = nullptr)
explicit

◆ ~SurfaceShaderRegistry()

PhosphorSurfaceShaders::SurfaceShaderRegistry::~SurfaceShaderRegistry ( )
override

Member Function Documentation

◆ addSearchPath()

void PhosphorSurfaceShaders::SurfaceShaderRegistry::addSearchPath ( const QString & path,
PhosphorFsLoader::LiveReload liveReload = PhosphorFsLoader::LiveReload::On )

◆ addSearchPaths()

void PhosphorSurfaceShaders::SurfaceShaderRegistry::addSearchPaths ( const QStringList & paths,
PhosphorFsLoader::LiveReload liveReload = PhosphorFsLoader::LiveReload::On,
PhosphorFsLoader::RegistrationOrder order = PhosphorFsLoader::RegistrationOrder::LowestPriorityFirst )

◆ availableEffects()

QList< SurfaceShaderEffect > PhosphorSurfaceShaders::SurfaceShaderRegistry::availableEffects ( ) const

◆ compositorBufferVertexSource()

QString PhosphorSurfaceShaders::SurfaceShaderRegistry::compositorBufferVertexSource ( )
staticnodiscard

The vertex stage of every surface BUFFER pass on the compositor: a unit quad already in clip space (no matrix), since a buffer pass is an FBO-to-FBO blit with no window quad to project.

A pack's declared vertex stage is deliberately not used for buffer passes there, so a buffer fragment may read no varying beyond vTexCoord.

◆ compositorPresentVertexSource()

QString PhosphorSurfaceShaders::SurfaceShaderRegistry::compositorPresentVertexSource ( )
staticnodiscard

The vertex stage of the decoration PRESENT shader, the passthrough that samples a decorated window's pre-composited final FBO.

That FBO has GL's bottom-left origin, so where KWin supplies top-down texcoords (PZ_KWIN_OFFSCREEN_TEXCOORDS_TOP_DOWN, KWin 6.8) the stage flips them back, and passes them through on earlier versions.

◆ compositorVertexSource()

QString PhosphorSurfaceShaders::SurfaceShaderRegistry::compositorVertexSource ( )
staticnodiscard

The vertex stage the COMPOSITOR compiles for every surface pack that declares none of its own (the bundled border ships none).

Positions in screen-pixel space projected by KWin's modelViewProjectionMatrix, and a passthrough texcoord with NO Y-flip, because the fragment reconstructs the top-down device pixel itself for its rounded-rect SDF. Attribute slots match KWin::VA_Position (0) / VA_TexCoord (1).

The compositor's vertex stages live here rather than in the effect so the offline validator links every pack against the exact stage the compositor uses, which is how a varying a fragment reads but no stage writes gets caught.

◆ effect()

SurfaceShaderEffect PhosphorSurfaceShaders::SurfaceShaderRegistry::effect ( const QString & id) const

◆ effectIds()

QStringList PhosphorSurfaceShaders::SurfaceShaderRegistry::effectIds ( ) const

◆ effectsChanged

void PhosphorSurfaceShaders::SurfaceShaderRegistry::effectsChanged ( )
signal

◆ hasEffect()

bool PhosphorSurfaceShaders::SurfaceShaderRegistry::hasEffect ( const QString & id) const

◆ isBuiltinBufferShader()

bool PhosphorSurfaceShaders::SurfaceShaderRegistry::isBuiltinBufferShader ( const QString & token)
static

Resolve a builtin: buffer-shader token (e.g.

builtin:gaussian-h) to the absolute path of the standard pass shipped in the surface shared/ directory, probing effectDir's sibling shared/ dir first (both are children of the same search root) and falling back to <subdir>/shared under the XDG data dirs, where <subdir> is what the app passed to setSurfacePackDataSubdir() (so user packs outside the system tree can still opt in; no fallback while it is unset). The token vocabulary is a fixed whitelist — authors cannot smuggle arbitrary paths through it, which keeps the pack-dir traversal guard intact. Returns an empty string for an unknown token or when the shared file is absent (callers funnel that into the existing fail-closed missing-buffer path). Non-builtin: inputs also return empty; use isBuiltinBufferShader() to distinguish. Shared by the registry's metadata resolution and the shadervalidate tool so both resolve the identical file.

◆ paramPreamble()

QString PhosphorSurfaceShaders::SurfaceShaderRegistry::paramPreamble ( const SurfaceShaderEffect & effect)
static

Build the generated #define p_<id> <glsl-accessor> preamble for effect's declared parameters so authors read a parameter by name (p_glow) instead of hand-decoding a customParams[N].xyzw lane.

The slot allocation mirrors translateSurfaceParams exactly — color params fill customColors[N], everything else fills customParams[N].<xyzw>, both in metadata declaration order — so the macro a shader reads resolves to the same UBO lane the value is uploaded to. Both runtimes splice the result after the shader's #version line (via PhosphorShaders::spliceAfterVersion). Returns an empty string when the effect declares no parameters.

◆ refresh()

void PhosphorSurfaceShaders::SurfaceShaderRegistry::refresh ( )

◆ resolveBuiltinBufferShader()

QString PhosphorSurfaceShaders::SurfaceShaderRegistry::resolveBuiltinBufferShader ( const QString & token,
const QString & effectDir )
static

◆ searchPaths()

QStringList PhosphorSurfaceShaders::SurfaceShaderRegistry::searchPaths ( ) const
nodiscard

◆ setUserPath()

void PhosphorSurfaceShaders::SurfaceShaderRegistry::setUserPath ( const QString & path)

◆ surfaceEntryCandidates()

QList< PhosphorShaders::EntryCandidate > PhosphorSurfaceShaders::SurfaceShaderRegistry::surfaceEntryCandidates ( )
static

◆ surfaceEntryPrologue()

QString PhosphorSurfaceShaders::SurfaceShaderRegistry::surfaceEntryPrologue ( )
static

Entry-point scaffold, matching the overlay (pZone/pImage) and animation (pTransition/pIn+pOut) categories.

A pack may define vec4 pSurface(vec2 uv) and omit main(); the harness generates a main() that writes pSurface(vTexCoord) to fragColor, multiplied by qt_Opacity on the Qt RHI hosts and unmultiplied under PLASMAZONES_KWIN, and prepends the prologue (#version, #include <surface_lib.glsl>, the vertex-in / fragColor-out declarations). A pack that writes its own main() is passed through unchanged and therefore applies no host opacity. Shared by the daemon (via ShaderEffect::setEntryScaffold) and the kwin-effect / validator paths (via PhosphorShaders::assembleEntryPoint) so all three compile the identical source.

◆ translateSurfaceParams() [1/2]

QVariantMap PhosphorSurfaceShaders::SurfaceShaderRegistry::translateSurfaceParams ( const QString & effectId,
const QVariantMap & friendlyParams ) const

Translate a friendly parameter map into the canonical slot keys consumed by both runtimes that drive surface shaders.

Two independent allocators advance in metadata declaration order:

• Float / int / bool parameters fill customParams<N>_<x|y|z|w> — the first declared param lands in customParams1_x, the second in customParams1_y, …, the fifth in customParams2_x, up to 32 slots (SurfaceShaderContract::kMaxParameterSlots).

• Color parameters fill customColor<N> — the first declared color lands in customColor1, the second in customColor2, up to 16 slots (SurfaceShaderContract::kMaxCustomColors). Color values are coerced to QColor at this boundary — anything QColor::QColor(QString) accepts is accepted here too (the common cases are "#rgb", "#rrggbb", and "#aarrggbb" with alpha FIRST per Qt's convention) — alongside QColor instances. Everything else falls back to the declared default, then Qt::transparent. CSS-style "#rrggbbaa" (alpha LAST, 9 chars) is NOT accepted — any 9-char hex string is ambiguous between Qt-form and CSS-form, so a rewrite would silently corrupt configs that already use Qt's order; settings UI / config writers MUST emit Qt-form.

The two allocators advance independently — a color parameter does NOT consume a customParams sub-slot, so a [color, float] declaration produces customColor1 + customParams1_x, not customColor1 + customParams1_y.

Bool values become 0.0 or 1.0. Missing float keys fall back to the metadata-declared default, then to 0.0. Unknown parameter ids in friendlyParams are silently ignored. Slot-budget overflows log a warning and drop the offending parameter.

Returns an empty map when effect is invalid, or when a valid effect declares no parameters and no textures and friendlyParams supplies no texture overrides. Conversely a valid effect with no declared parameters can still return user-texture keys (uTextureN), so callers must not treat a non-empty result as proof the effect declares parameters.

◆ translateSurfaceParams() [2/2]

QVariantMap PhosphorSurfaceShaders::SurfaceShaderRegistry::translateSurfaceParams ( const SurfaceShaderEffect & effect,
const QVariantMap & friendlyParams )
static

Static counterpart for callers that already hold the resolved SurfaceShaderEffect (e.g.

the kwin-effect's per-frame translation). Same slot-allocation contract as the registry-keyed overload.


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