PhosphorAnimationShaders Namespace Reference

Namespaces
namespace	AnimationShaderContract
	Cross-runtime named-uniform contract for animation/transition shaders.

Classes
struct	AnimationShaderEffect
	Metadata for a single animation shader effect (transition). More...
class	AnimationShaderRegistry
	Registry of available animation shader transition effects. More...
class	ShaderProfile
	Per-event shader effect selection and configuration. More...
class	ShaderProfileTree
	Hierarchical ShaderProfile storage with walk-up inheritance. More...

Functions
PHOSPHORANIMATION_EXPORT bool	shaderEffectAppliesToEventPath (const AnimationShaderEffect &effect, const QString &path)
	True iff effect may meaningfully run on event path.
PHOSPHORANIMATION_EXPORT bool	shaderEffectIsCompositorOnly (const AnimationShaderEffect &effect)
	True iff effect can ONLY execute on the compositor (kwin-effect) runtime and never on the daemon's overlay-surface path.
PHOSPHORANIMATION_EXPORT bool	shaderPathResolvesInIsolation (const QString &path)
	True when path resolves its shader in ISOLATION: ShaderProfileTree:: resolve reads only the direct override at the path, so no ancestor or baseline shader ever applies there — and, symmetrically, an override AT the path can never shadow an ancestor's shader.
PHOSPHORANIMATION_EXPORT QString	shaderPathIsolationRoot (const QString &path)
	The subtree root path resolves WITHIN, or an empty string when it resolves the ordinary way (from the tree baseline, down the whole chain).
PHOSPHORANIMATION_EXPORT ShaderProfile	resolveShaderWithDefault (const ShaderProfileTree &tree, const QString &path)
	Resolve path against tree, applying the built-in per-event default shader (ProfilePaths::defaultShaderEffectIdForPath, e.g.

Function Documentation

resolveShaderWithDefault()

PHOSPHORANIMATION_EXPORT ShaderProfile PhosphorAnimationShaders::resolveShaderWithDefault	(	const ShaderProfileTree &	tree,
		const QString &	path
	)

Resolve path against tree, applying the built-in per-event default shader (ProfilePaths::defaultShaderEffectIdForPath, e.g.

"window-morph" for window snap events) when the path is TRULY UNSET — i.e. neither it nor any ancestor carries an override. An explicit "None" (an engaged-empty override) IS an override, so it is respected and the default is NOT applied.

SSOT for "what shader does this event use", shared by the kwin-effect resolution and the settings UI so the built-in default both plays at runtime and shows as the current value in settings — without persisting the default into the user's config (it's computed, not stored).

shaderEffectAppliesToEventPath()

PHOSPHORANIMATION_EXPORT bool PhosphorAnimationShaders::shaderEffectAppliesToEventPath	(	const AnimationShaderEffect &	effect,
		const QString &	path
	)

True iff effect may meaningfully run on event path.

An effect with an empty appliesTo is universal and always returns true on single-surface paths (the opt-in desktop, move and strip classes are excluded). Otherwise the predicate maps path to its event class via PhosphorAnimation::ProfilePaths::eventClassForPath and checks membership. A path with no determinable class (a mixed ancestor like window, or a non-window/overlay path) also returns true — the predicate only reports false when it can PROVE a mismatch, so it never over-restricts a row whose class is ambiguous. The one exception is a pack declaring NEITHER geometry NOR appearance — exclusively one of the three opt-in classes. For move-only that is a proof (the move leaf takes no inherited shader at all); for desktop-only and strip-only it is picker POLICY, since those leaves do inherit and would run it. A HYBRID such as ["strip", "appearance"] stays offered on ambiguous rows: its appearance leg is live under them.

This is the (effect × path) analogue of PlasmaZones::eventPathSupportsShaderLeg(path), which gates whether a path can run ANY shader. Both the settings picker (to dim incompatible effects) and any future runtime verification consult this one predicate so the policy has a single source of truth.

shaderEffectIsCompositorOnly()

PHOSPHORANIMATION_EXPORT bool PhosphorAnimationShaders::shaderEffectIsCompositorOnly

(

const AnimationShaderEffect &

effect

)

True iff effect can ONLY execute on the compositor (kwin-effect) runtime and never on the daemon's overlay-surface path.

Every daemon surface that can take a shader leg at all (the OSD and popup families — snap-assist, layout-picker, zone-selector, cheatsheet) is an appearance-class single-surface event, and a universal pack (empty appliesTo) runs there too; the remaining daemon-side families (editor / panel / widget) carry no shader leg in the first place (see eventPathSupportsShaderLeg). The desktop (two-texture switch/peek), geometry (iFromRect → iToRect morph), move (held-drag physics) and strip (the scrolling view spring's one-scene post-process) classes exist only inside the kwin-effect. So a pack whose declared appliesTo names classes but not appearance is provably compositor-only.

Consequences carried by this predicate (single source of truth): • such packs author their shaders against the classic-GL kwin dialect directly (default-block uniforms, unguarded — no #ifdef PLASMAZONES_KWIN branching); • the daemon never warm-bakes them and SurfaceAnimator refuses to attach them (their source no longer compiles on the strict SPIR-V qsb target); • daemon-target bake tests and plasmazones-shadervalidate skip them — kwin-path compile coverage lives in test_animation_shader_kwin_bake.

shaderPathIsolationRoot()

PHOSPHORANIMATION_EXPORT QString PhosphorAnimationShaders::shaderPathIsolationRoot

(

const QString &

path

)

The subtree root path resolves WITHIN, or an empty string when it resolves the ordinary way (from the tree baseline, down the whole chain).

The weaker sibling of the predicate above, and the shape a whole FAMILY of foreign surfaces needs rather than a lone leaf: inheritance still works normally between the root and the leaf, so a pack set on the root cascades to its legs, but nothing ABOVE the root reaches in — not the global node, not the baseline. Today that root is ProfilePaths::Shell, whose surfaces belong to plasmashell rather than to any application: what the user chose for their own windows must not start playing on the system tray, and engaging a pack inside the subtree is the whole opt-in. The decoration tree isolates its own shell subtree the same way and for the same reason (see PhosphorSurface's decorationPathIsBaselineIsolated).

Exported for the same reason the predicate above is: a second copy of "where does inheritance start" drifts from the resolver. Consumed by resolve() and by the kwin-effect's event resolution (shader_config_dbus.cpp), which gates THREE things on it: the window-filtering call (shouldAnimateWindow is SKIPPED for an isolated path — it would reject every plasmashell surface outright on its structural clause, and its Animations.WindowFiltering knobs and ExcludeAnimations rules are all authored about application windows), the rule tier (resolved windowless), and the cascade-coverage diagnostic. Anything reasoning about what a shell.* path inherits should call this rather than re-derive it from a path prefix.

shaderPathResolvesInIsolation()

PHOSPHORANIMATION_EXPORT bool PhosphorAnimationShaders::shaderPathResolvesInIsolation

(

const QString &

path

)

True when path resolves its shader in ISOLATION: ShaderProfileTree:: resolve reads only the direct override at the path, so no ancestor or baseline shader ever applies there — and, symmetrically, an override AT the path can never shadow an ancestor's shader.

Two members today, the interactive-drag leaf (ProfilePaths::WindowMove) and the tab-switch leaf (ProfilePaths::ScrollingTabSwitch); see EXCEPTION 1 in the walk-up inheritance note above. Exposed so shadowing-aware consumers (e.g. the settings "shadowing children" banner walk) share the resolver's definition instead of re-deriving it from a path prefix.