Registry of available surface shader effects. More...
#include <PhosphorSurface/SurfaceShaderRegistry.h>
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. | |
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.
The subdirectory name is decorative — the id field in metadata.json is the registry key. This matches PhosphorShaders::ShaderRegistry's and AnimationShaderRegistry's convention.
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.
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.
|
explicit |
|
override |
| void PhosphorSurfaceShaders::SurfaceShaderRegistry::addSearchPath | ( | const QString & | path, |
| PhosphorFsLoader::LiveReload | liveReload = PhosphorFsLoader::LiveReload::On ) |
| void PhosphorSurfaceShaders::SurfaceShaderRegistry::addSearchPaths | ( | const QStringList & | paths, |
| PhosphorFsLoader::LiveReload | liveReload = PhosphorFsLoader::LiveReload::On, | ||
| PhosphorFsLoader::RegistrationOrder | order = PhosphorFsLoader::RegistrationOrder::LowestPriorityFirst ) |
| QList< SurfaceShaderEffect > PhosphorSurfaceShaders::SurfaceShaderRegistry::availableEffects | ( | ) | const |
|
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.
|
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.
|
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.
| SurfaceShaderEffect PhosphorSurfaceShaders::SurfaceShaderRegistry::effect | ( | const QString & | id | ) | const |
| QStringList PhosphorSurfaceShaders::SurfaceShaderRegistry::effectIds | ( | ) | const |
|
signal |
| bool PhosphorSurfaceShaders::SurfaceShaderRegistry::hasEffect | ( | const QString & | id | ) | const |
|
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.
|
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.
| void PhosphorSurfaceShaders::SurfaceShaderRegistry::refresh | ( | ) |
|
static |
|
nodiscard |
| void PhosphorSurfaceShaders::SurfaceShaderRegistry::setUserPath | ( | const QString & | path | ) |
|
static |
|
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.
| 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.
|
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.