Metadata for a single surface shader effect. More...
#include <PhosphorSurface/SurfaceShaderEffect.h>
Classes | |
| struct | ParameterInfo |
| Declared shader inputs beyond the standard surface set (uTexture0, uSurfaceSize, uSurfaceFocused, etc.). More... | |
| struct | TextureSlot |
| User texture slot. More... | |
Public Member Functions | |
| const ParameterInfo * | findParameter (QAnyStringView id) const |
The declared parameter with id id, or nullptr when the pack does not declare it. | |
| bool | isValid () const |
| QJsonObject | toJson () const |
| bool | operator== (const SurfaceShaderEffect &other) const |
| bool | operator!= (const SurfaceShaderEffect &other) const |
Static Public Member Functions | |
| static SurfaceShaderEffect | fromJson (const QJsonObject &obj) |
Public Attributes | |
| QString | id |
| Stable identifier — lookup key in the registry. | |
| QString | name |
| Human-readable display name (localizable by the consumer). | |
| QString | description |
| One-line description for settings UI tooltips. | |
| QString | author |
| Author attribution. | |
| QString | version |
| Semantic version of this effect pack. | |
| QString | category |
| Category for settings-UI grouping. | |
| QString | fragmentShaderPath |
| Path to the fragment shader (relative to the effect dir). | |
| QString | vertexShaderPath |
| Path to the vertex shader (relative to the effect dir). | |
| QString | sourceDir |
| Resolved absolute directory containing this effect's assets. | |
| bool | isUserEffect = false |
| Whether this effect was loaded from a user-local directory. | |
| QString | previewPath |
| Preview image path (relative to the effect dir). For settings UI. | |
| bool | isMultipass = false |
| Opt-in multipass mode. | |
| QString | paddingParam |
| Names the parameter (an int/float, logical px) whose resolved value is the transparent OUTER MARGIN the pack needs around the surface to draw into — e.g. | |
| bool | animated = false |
| Declares that the pack references iTime and needs a per-frame driver. | |
| bool | needsBackdrop = false |
| Declares that the pack samples the scene BEHIND the window (backdropTexel() / uBackdrop). | |
| bool | interiorOpaque = false |
| Declares that the pack never writes a texel with alpha below the input's alpha INSIDE the window's natural frame rect — its drawing is confined to the transparent outer margin (shadow, glow: their halo is gated on 1 - base.a), so the client's own opaque region remains truthful for the composited output. | |
| bool | providesBorder = false |
| Declares that the pack draws a window border of its own (the border family: border, border-sweep, border-rgb, ...). | |
| bool | providesOpacityTint = false |
| Declares that the pack fades/tints the window surface (the reserved opacity-tint pack). | |
| bool | audio = false |
| Declares that the pack reacts to the CAVA audio spectrum (it includes surface_audio.glsl and reads audioBar / getBass / …). | |
| QStringList | bufferShaderPaths |
| Buffer-pass shader paths (relative to effect dir). | |
| bool | bufferFeedback = false |
| Enable per-pass feedback (last frame's buffer is sampleable as iChannel<N>). | |
| qreal | bufferScale = 1.0 |
| Render-target scale relative to the surface size, for every buffer pass that bufferScales does not name. | |
| QList< qreal > | bufferScales |
| Per-pass render-target scales, positionally aligned with bufferShaderPaths (metadata bufferScales). | |
| QString | bufferWrap |
| Default wrap mode for all buffer samplers. | |
| QStringList | bufferWraps |
| Per-buffer wrap-mode overrides; index aligns with bufferShaderPaths. | |
| QString | bufferFilter |
| Default filter mode for all buffer samplers. | |
| QStringList | bufferFilters |
| Per-buffer filter-mode overrides; index aligns with bufferShaderPaths. | |
| bool | useDepthBuffer = false |
| Allocate a depth buffer alongside the colour FBO so the shader can sample window depth. | |
| bool | halfFloatBuffers = true |
| Whether the intermediate buffers hold half-float texels. | |
| QList< ParameterInfo > | parameters |
| QList< TextureSlot > | textures |
| PhosphorShaders::PackPresets | presets |
| Pack-declared named parameter presets: preset name -> { paramId -> value }. | |
Static Public Attributes | |
| static constexpr qreal | kMinBufferScale = PhosphorShaders::kMinBufferScale |
| Lower / upper bounds on bufferScale (multipass FBO downscale factor) — forwarders onto the cross-library canonical constants in <PhosphorShaders/CustomParamsKey.h> (see there for why the floor sits several steps below the deepest level any pack declares). | |
| static constexpr qreal | kMaxBufferScale = PhosphorShaders::kMaxBufferScale |
| static constexpr int | kMaxBufferPasses = PhosphorShaders::kMaxBufferPasses |
| Maximum number of buffer passes a pack may declare. | |
Metadata for a single surface shader effect.
Distinct from PhosphorAnimationShaders::AnimationShaderEffect (which describes a finite-duration transition driven by a 0..1 timeline) and from PhosphorRendering::ShaderEffect (which renders persistent zone backgrounds). A SurfaceShaderEffect describes a persistent per-window surface layer — the decoration band / border, rounded corners, focus tint, etc. — composited over the live window content for as long as the window is mapped.
Each effect is keyed by a stable id string (e.g. "border", "rounded-corners"). Plugin-authored effects use reverse-domain or namespaced ids ("myplugin.glow") to avoid collisions with built-in effects.
Each effect carries a single fragmentShaderPath — the same GLSL source runs on both the compositor (KWin) and daemon (Qt RHI) surface- layer paint paths; the runtime handles texture binding and coordinate conventions, so separate per-backend shader variants are not needed.
Each effect declares named parameters with type, default, min/max. Field names mirror AnimationShaderEffect::ParameterInfo so surface packs and animation packs can share QML editor components.
Surface shaders support opt-in multipass: when isMultipass is set and bufferShaderPaths is non-empty, both hosts run those buffer passes before the main fragment shader.
On the daemon side the fields below reach a SurfaceShaderItem, which inherits the whole multipass property set from PhosphorRendering::ShaderEffect. The hosts that forward them through composeStageMap are enumerated once, in SurfaceChainCompose.h beside the function itself, rather than a second time here. The layer.enabled policy for a multipass stage belongs to SurfaceDecoration.qml, which states it at length and records what an earlier theory about it cost.
The kwin-effect compositor compiles and runs the same buffer passes in its composite fold. It degrades to single-pass, with a diagnostic log, only when a buffer pass fails to compile. The two hosts differ in several places, each documented on the field it belongs to. An enumeration here kept going stale as fields were added, so the fields are the list.
Neither struct is a subset of the other. This one OMITS the event-class and fboExtent fields that only make sense for a finite-duration transition, and ADDS two buffer fields the animation twin does not carry: bufferScales (per-pass render scales, which is what lets a pyramid diverge its levels) and halfFloatBuffers (animation buffers are pinned RGBA16F). The identity, shader-path, preview, parameter and texture-slot shape are identical.
|
inline |
The declared parameter with id id, or nullptr when the pack does not declare it.
The one lookup the host-side resolvers use to ask whether a flag or value belongs to the pack before reading or writing it.
|
static |
|
inline |
|
inline |
| bool PhosphorSurfaceShaders::SurfaceShaderEffect::operator== | ( | const SurfaceShaderEffect & | other | ) | const |
| QJsonObject PhosphorSurfaceShaders::SurfaceShaderEffect::toJson | ( | ) | const |
| bool PhosphorSurfaceShaders::SurfaceShaderEffect::animated = false |
Declares that the pack references iTime and needs a per-frame driver.
The compositor detects this itself (a linked iTime uniform gates the repaint), but the daemon UBO always carries iTime, so its hosts read this flag to decide whether to tick the item (SurfaceShaderItem playing). Static packs omit it and pay nothing.
| bool PhosphorSurfaceShaders::SurfaceShaderEffect::audio = false |
Declares that the pack reacts to the CAVA audio spectrum (it includes surface_audio.glsl and reads audioBar / getBass / …).
Both runtimes feed it when the audio visualizer is on: the daemon pushes the live spectrum to a decorated OSD / popup carrying an audio pack, and the KWin effect runs its own CAVA provider to feed window decorations. Session-global like the overlay category. The flag is what lets each host gate CAVA on an audio pack being present, so a plain decoration never spins up audio capture.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::author |
Author attribution.
| bool PhosphorSurfaceShaders::SurfaceShaderEffect::bufferFeedback = false |
Enable per-pass feedback (last frame's buffer is sampleable as iChannel<N>).
Requires isMultipass. Daemon-only.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::bufferFilter |
Default filter mode for all buffer samplers.
Empty = runtime default. Daemon-only.
| QStringList PhosphorSurfaceShaders::SurfaceShaderEffect::bufferFilters |
Per-buffer filter-mode overrides; index aligns with bufferShaderPaths.
Daemon-only.
| qreal PhosphorSurfaceShaders::SurfaceShaderEffect::bufferScale = 1.0 |
Render-target scale relative to the surface size, for every buffer pass that bufferScales does not name.
Clamped to [kMinBufferScale, kMaxBufferScale] at fromJson time. Both hosts honour it: the daemon through the stage map, the compositor when it sizes the fold's per-pack buffer textures.
| QList<qreal> PhosphorSurfaceShaders::SurfaceShaderEffect::bufferScales |
Per-pass render-target scales, positionally aligned with bufferShaderPaths (metadata bufferScales).
A pass past the list's end renders at bufferScale. Each entry is clamped like bufferScale and the list is capped at kMaxBufferPasses. This is what lets one pack run a resolution pyramid (the builtin dual Kawase chain renders each level at its own scale).
DISCARDED ENTIRELY on the daemon when useDepthBuffer is set. Every pass shares the one depth attachment, and a render target's colour and depth attachments must agree in size, so a depth pack pins every pass to bufferScale. The compositor implements no depth buffer for surface packs at all and always honours these, so the two hosts diverge for such a pack by design. The validator lints the combination.
| QStringList PhosphorSurfaceShaders::SurfaceShaderEffect::bufferShaderPaths |
Buffer-pass shader paths (relative to effect dir).
When non-empty and isMultipass is true, the host runs these as intermediate passes before the main fragment shader.
The two hosts reach them differently, which is why some of the buffer fields below are daemon-only. The daemon's SurfaceDecoration.qml (via OverlayService::applyDecoration) receives them through composeStageMap(); the KWin effect reads this struct directly and never calls that helper, so a field added only to composeStageMap reaches the daemon and not the compositor.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::bufferWrap |
Default wrap mode for all buffer samplers.
Sibling of bufferWraps (per-buffer overrides). Empty = runtime default. Daemon-only.
| QStringList PhosphorSurfaceShaders::SurfaceShaderEffect::bufferWraps |
Per-buffer wrap-mode overrides; index aligns with bufferShaderPaths.
Daemon-only.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::category |
Category for settings-UI grouping.
The bundled packs use "Blur", "Borders", "Ambience" and "Focus"; the field is free-form, so a third-party pack may introduce its own.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::description |
One-line description for settings UI tooltips.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::fragmentShaderPath |
Path to the fragment shader (relative to the effect dir).
The same source is used on both the compositor and daemon paths — the runtime handles backend differences.
| bool PhosphorSurfaceShaders::SurfaceShaderEffect::halfFloatBuffers = true |
Whether the intermediate buffers hold half-float texels.
Daemon-only.
True keeps RGBA16F, which a buffer legitimately needs when it stores HDR radiance, signed data, or a feedback accumulator whose decay would quantise to a standstill at 8 bits. A pack whose buffers hold plain clamped colour sets "halfFloatBuffers": false and halves the bandwidth its passes cost, which is the scarce resource on an integrated GPU. Mirrors the overlay category's key of the same name.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::id |
Stable identifier — lookup key in the registry.
| bool PhosphorSurfaceShaders::SurfaceShaderEffect::interiorOpaque = false |
Declares that the pack never writes a texel with alpha below the input's alpha INSIDE the window's natural frame rect — its drawing is confined to the transparent outer margin (shadow, glow: their halo is gated on 1 - base.a), so the client's own opaque region remains truthful for the composited output.
When EVERY drawing pack in a window's chain declares this (and nothing else thins the interior: no live transition, no resolved opacity below 1), the kwin effect skips setTranslucent() on the window, which keeps KWin's occlusion culling alive — windows fully behind it are neither damage-tracked nor repainted. A pack that draws ANYWHERE inside the frame at partial alpha (every border pack: the outer-radius corner arc and the band feather both thin frame texels; glass/frost/opacity-tint: they dim content) must leave this false, or stale pixels ghost through its translucent texels. Default false — the safe direction.
| bool PhosphorSurfaceShaders::SurfaceShaderEffect::isMultipass = false |
Opt-in multipass mode.
When true and bufferShaderPaths is non-empty, both the daemon path and the kwin-effect compositor run those buffer passes before the main fragment. Either host degrades a pack to single-pass, with a diagnostic log, when one of its buffer passes fails to compile (see SurfaceShaderContract.h).
| bool PhosphorSurfaceShaders::SurfaceShaderEffect::isUserEffect = false |
Whether this effect was loaded from a user-local directory.
|
staticconstexpr |
Maximum number of buffer passes a pack may declare.
Bounded because every declared pass costs a texture at its scale and a fullscreen draw PER DECORATED WINDOW, PER FRAME, and the count comes from an installable pack's JSON — an unvalidated system boundary, and previously the one uncapped axis (bufferScale, outerPadding and the texture slots are all bounded). The value is the cross-family PhosphorShaders::kMaxBufferPasses: the fold binds exactly that many iChannelN samplers and a pass samples only the passes before it, so a buffer past the cap is structurally unreadable — allocated, cleared, drawn, and sampled by nothing.
PER PACK, not per window. A decoration CHAIN runs several packs, each with its own budget, so a window's worst case is this cap times the number of multipass packs in its chain. The bundled chains hold one.
|
staticconstexpr |
|
staticconstexpr |
Lower / upper bounds on bufferScale (multipass FBO downscale factor) — forwarders onto the cross-library canonical constants in <PhosphorShaders/CustomParamsKey.h> (see there for why the floor sits several steps below the deepest level any pack declares).
Kept as names on this class because fromJson's clamp + the round-trip stability comment in toJson reference them.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::name |
Human-readable display name (localizable by the consumer).
| bool PhosphorSurfaceShaders::SurfaceShaderEffect::needsBackdrop = false |
Declares that the pack samples the scene BEHIND the window (backdropTexel() / uBackdrop).
The kwin effect captures the backdrop under the window's (padded) canvas each frame, routes the pack through the composite fold, and drives the window to repaint continuously. Daemon and preview hosts have no scene to capture, but MAY bind the desktop wallpaper as a stand-in, in which case uHasBackdrop reads 1 there too. It is 0 only when nothing was bound, and backdropTexel() returns transparent then, so a pack must still style a fallback on that gate rather than assuming the sampler.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::paddingParam |
Names the parameter (an int/float, logical px) whose resolved value is the transparent OUTER MARGIN the pack needs around the surface to draw into — e.g.
the glow pack's glowSize. The compositor host inflates the window's capture canvas by the chain's largest declared margin (per-window, from the surface's resolved parameter overrides) and presents on a matching padded quad, so an outer effect renders even when the window has no decoration-shadow margin of its own. The daemon host resolves the PRIMARY pack's margin the same way and publishes it as decorationOuterPadding; SurfaceDecoration inflates its capture sourceRect + shader item by it (OverlayService::applyDecoration). Empty = the pack draws within the surface (no padding requested).
| QList<ParameterInfo> PhosphorSurfaceShaders::SurfaceShaderEffect::parameters |
| PhosphorShaders::PackPresets PhosphorSurfaceShaders::SurfaceShaderEffect::presets |
Pack-declared named parameter presets: preset name -> { paramId -> value }.
Read-only tunings the pack author ships, offered in the same picker as the user's own presets and resolved through the shared preset registry. A preset names a subset of parameters; ids this effect does not declare are inert at resolve time, so parsing keeps them and the offline pack validator is where an author hears about a typo. That holds for a typo'd id specifically — the validator lints this already-parsed struct, so it can only report what parsing kept. A preset parsing drops outright (every value a refused texture path) is reported in the runtime log instead.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::previewPath |
Preview image path (relative to the effect dir). For settings UI.
| bool PhosphorSurfaceShaders::SurfaceShaderEffect::providesBorder = false |
Declares that the pack draws a window border of its own (the border family: border, border-sweep, border-rgb, ...).
Semantic contract flag, deliberately NOT keyed off the browsing category: a providesBorder pack is expected to declare the shared border param ids borderWidth / cornerRadius (and activeColor / inactiveColor where it distinguishes focus), which the settings side seeds from the plain Windows border setting when the pack is added to a chain. Any user pack in a window's chain already suppresses the plain border layer wholesale (see the kwin effect's updateWindowDecoration), so this flag gates seeding and UI hints, not rendering.
| bool PhosphorSurfaceShaders::SurfaceShaderEffect::providesOpacityTint = false |
Declares that the pack fades/tints the window surface (the reserved opacity-tint pack).
Same contract idea as providesBorder: such a pack is expected to declare the shared param ids opacity / tintStrength / tintColor, which the settings side seeds from the plain Windows opacity+tint setting when the pack is added to a chain. Gates seeding, not rendering.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::sourceDir |
Resolved absolute directory containing this effect's assets.
| QList<TextureSlot> PhosphorSurfaceShaders::SurfaceShaderEffect::textures |
| bool PhosphorSurfaceShaders::SurfaceShaderEffect::useDepthBuffer = false |
Allocate a depth buffer alongside the colour FBO so the shader can sample window depth.
Daemon-only.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::version |
Semantic version of this effect pack.
| QString PhosphorSurfaceShaders::SurfaceShaderEffect::vertexShaderPath |
Path to the vertex shader (relative to the effect dir).
Empty = use the runtime's built-in fullscreen-quad vertex shader.
The declared stage applies to the MAIN pass. Buffer passes are handled differently by the two hosts: the daemon runs them through this stage with the matrix pinned to identity, while the compositor runs them through its own built-in fullscreen quad, which emits vTexCoord at location 0 and nothing else. A buffer fragment must therefore read no varying beyond vTexCoord. One that reads more links on the daemon and fails to link on the compositor, where the pack then drops to single-pass with a log line and no other symptom. The pack validator compiles the two stages independently, so it cannot catch a varying mismatch either.