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

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.

Detailed Description

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.

Identity

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.

Shader source

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.

Parameters

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.

Multipass buffer passes

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.

Trimmed vs AnimationShaderEffect

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.

Member Function Documentation

◆ findParameter()

const ParameterInfo * PhosphorSurfaceShaders::SurfaceShaderEffect::findParameter ( QAnyStringView id) const
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.

◆ fromJson()

SurfaceShaderEffect PhosphorSurfaceShaders::SurfaceShaderEffect::fromJson ( const QJsonObject & obj)
static

◆ isValid()

bool PhosphorSurfaceShaders::SurfaceShaderEffect::isValid ( ) const
inline

◆ operator!=()

bool PhosphorSurfaceShaders::SurfaceShaderEffect::operator!= ( const SurfaceShaderEffect & other) const
inline

◆ operator==()

bool PhosphorSurfaceShaders::SurfaceShaderEffect::operator== ( const SurfaceShaderEffect & other) const

◆ toJson()

QJsonObject PhosphorSurfaceShaders::SurfaceShaderEffect::toJson ( ) const

Member Data Documentation

◆ animated

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.

◆ audio

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.

◆ author

QString PhosphorSurfaceShaders::SurfaceShaderEffect::author

Author attribution.

◆ bufferFeedback

bool PhosphorSurfaceShaders::SurfaceShaderEffect::bufferFeedback = false

Enable per-pass feedback (last frame's buffer is sampleable as iChannel<N>).

Requires isMultipass. Daemon-only.

◆ bufferFilter

QString PhosphorSurfaceShaders::SurfaceShaderEffect::bufferFilter

Default filter mode for all buffer samplers.

Empty = runtime default. Daemon-only.

◆ bufferFilters

QStringList PhosphorSurfaceShaders::SurfaceShaderEffect::bufferFilters

Per-buffer filter-mode overrides; index aligns with bufferShaderPaths.

Daemon-only.

◆ bufferScale

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.

◆ bufferScales

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.

◆ bufferShaderPaths

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.

◆ bufferWrap

QString PhosphorSurfaceShaders::SurfaceShaderEffect::bufferWrap

Default wrap mode for all buffer samplers.

Sibling of bufferWraps (per-buffer overrides). Empty = runtime default. Daemon-only.

◆ bufferWraps

QStringList PhosphorSurfaceShaders::SurfaceShaderEffect::bufferWraps

Per-buffer wrap-mode overrides; index aligns with bufferShaderPaths.

Daemon-only.

◆ category

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.

◆ description

QString PhosphorSurfaceShaders::SurfaceShaderEffect::description

One-line description for settings UI tooltips.

◆ fragmentShaderPath

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.

◆ halfFloatBuffers

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.

◆ id

QString PhosphorSurfaceShaders::SurfaceShaderEffect::id

Stable identifier — lookup key in the registry.

◆ interiorOpaque

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.

◆ isMultipass

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).

◆ isUserEffect

bool PhosphorSurfaceShaders::SurfaceShaderEffect::isUserEffect = false

Whether this effect was loaded from a user-local directory.

◆ kMaxBufferPasses

int PhosphorSurfaceShaders::SurfaceShaderEffect::kMaxBufferPasses = PhosphorShaders::kMaxBufferPasses
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.

◆ kMaxBufferScale

qreal PhosphorSurfaceShaders::SurfaceShaderEffect::kMaxBufferScale = PhosphorShaders::kMaxBufferScale
staticconstexpr

◆ kMinBufferScale

qreal PhosphorSurfaceShaders::SurfaceShaderEffect::kMinBufferScale = PhosphorShaders::kMinBufferScale
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.

◆ name

QString PhosphorSurfaceShaders::SurfaceShaderEffect::name

Human-readable display name (localizable by the consumer).

◆ needsBackdrop

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.

◆ paddingParam

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).

◆ parameters

QList<ParameterInfo> PhosphorSurfaceShaders::SurfaceShaderEffect::parameters

◆ presets

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.

◆ previewPath

QString PhosphorSurfaceShaders::SurfaceShaderEffect::previewPath

Preview image path (relative to the effect dir). For settings UI.

◆ providesBorder

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.

◆ providesOpacityTint

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.

◆ sourceDir

QString PhosphorSurfaceShaders::SurfaceShaderEffect::sourceDir

Resolved absolute directory containing this effect's assets.

◆ textures

QList<TextureSlot> PhosphorSurfaceShaders::SurfaceShaderEffect::textures

◆ useDepthBuffer

bool PhosphorSurfaceShaders::SurfaceShaderEffect::useDepthBuffer = false

Allocate a depth buffer alongside the colour FBO so the shader can sample window depth.

Daemon-only.

◆ version

QString PhosphorSurfaceShaders::SurfaceShaderEffect::version

Semantic version of this effect pack.

◆ vertexShaderPath

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.


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