PhosphorAnimationShaders::AnimationShaderEffect Struct Reference

Metadata for a single animation shader effect (transition). More...

#include <phosphor-animation/include/PhosphorAnimation/AnimationShaderEffect.h>

Classes
struct	ParameterInfo
	Declared shader inputs beyond the standard set (iTime, iFrame, etc.). More...
struct	TextureSlot
	User texture slot. More...

Public Types
enum class	FboExtentKind { Anchor , Surface }
	How wide the shader effect's render target is — relative to its anchor (default), or filling the surface scene root. More...

Public Member Functions
bool	isValid () const
QJsonObject	toJson () const
bool	operator== (const AnimationShaderEffect &other) const
bool	operator!= (const AnimationShaderEffect &other) const

Static Public Member Functions
static AnimationShaderEffect	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 (e.g. "Fade", "Geometric", "Glitch").
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.
QStringList	bufferShaderPaths
	Buffer-pass shader paths (relative to effect dir).
bool	isMultipass = false
	Opt-in multipass mode.
bool	useWallpaper = false
	Bind the user's wallpaper as a sampler.
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.
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.
FboExtentKind	fboExtentKind = FboExtentKind::Anchor
QList< ParameterInfo >	parameters
QList< TextureSlot >	textures

Static Public Attributes
static constexpr qreal	kMinBufferScale = 0.125
	Lower / upper bounds on bufferScale (multipass FBO downscale factor).
static constexpr qreal	kMaxBufferScale = 1.0

Detailed Description

Metadata for a single animation shader effect (transition).

Distinct from PhosphorRendering::ShaderEffect which renders persistent zone backgrounds. An AnimationShaderEffect describes a transition — dissolve, slide, morph, etc. — applied between two visual states over a finite duration.

Identity

Each effect is keyed by a stable id string (e.g. "dissolve", "slide", "glitch"). Plugin-authored effects use reverse-domain or namespaced ids ("myplugin.sparkle") to avoid collisions with built-in effects.

Shader source

Each effect carries a single fragmentShaderPath — the same GLSL source is used on both the QtQuick and KWin compositor paint paths. PhosphorRendering::ShaderNodeRhi handles texture binding and coordinate conventions at the RHI level, so separate per-backend shader variants are not needed.

Parameters

Each effect declares named parameters with type, default, min/max. Per-event parameter overrides live on ShaderProfile, not here.

Member Enumeration Documentation

FboExtentKind

enum class PhosphorAnimationShaders::AnimationShaderEffect::FboExtentKind

strong

How wide the shader effect's render target is — relative to its anchor (default), or filling the surface scene root.

• Anchor (default): FBO covers the captured anchor 1:1. Used by fragment-only effects (dissolve, glitch, …) whose math stays inside vTexCoord ∈ [0, 1] over the anchor.

• Surface: FBO covers the anchor's enclosing surface scene root (the wl_surface size on the daemon path). Used by effects that need to render past the captured anchor (fly-in translates the card across the surface, broken-glass fires shards into the surrounding screen). Authors who pick Surface typically ship a custom vertex shader that uses iAnchorPosInFbo / iAnchorSize / iResolution to position the card within the FBO; the fragment shader then either reads vTexCoord directly (if the vert remaps the quad to the anchor's region — fly-in) or calls anchorRemap to convert surface-UV back to anchor-space (broken-glass, morph).

Mirrors the public fboExtent JSON grammar: "anchor" → Anchor, "surface" → Surface. No other forms are accepted.

Enumerator
Anchor
Surface

Member Function Documentation

fromJson()

static AnimationShaderEffect PhosphorAnimationShaders::AnimationShaderEffect::fromJson ( const QJsonObject &  obj )

static

isValid()

bool PhosphorAnimationShaders::AnimationShaderEffect::isValid ( ) const

inline

operator!=()

bool PhosphorAnimationShaders::AnimationShaderEffect::operator!= ( const AnimationShaderEffect &  other ) const

inline

operator==()

bool PhosphorAnimationShaders::AnimationShaderEffect::operator==

(

const AnimationShaderEffect &

other

)

const

toJson()

QJsonObject PhosphorAnimationShaders::AnimationShaderEffect::toJson

(

)

const

Member Data Documentation

author

QString PhosphorAnimationShaders::AnimationShaderEffect::author

Author attribution.

bufferFeedback

bool PhosphorAnimationShaders::AnimationShaderEffect::bufferFeedback = false

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

Requires isMultipass. Daemon-only.

bufferFilter

QString PhosphorAnimationShaders::AnimationShaderEffect::bufferFilter

Default filter mode for all buffer samplers.

Empty = ShaderEffect default. Daemon-only.

bufferFilters

QStringList PhosphorAnimationShaders::AnimationShaderEffect::bufferFilters

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

Daemon-only.

bufferScale

qreal PhosphorAnimationShaders::AnimationShaderEffect::bufferScale = 1.0

Render-target scale relative to the surface size.

Clamped to [0.125, 1.0] at fromJson time. Daemon-only — the compositor path doesn't allocate auxiliary FBOs.

bufferShaderPaths

QStringList PhosphorAnimationShaders::AnimationShaderEffect::bufferShaderPaths

Buffer-pass shader paths (relative to effect dir).

When non-empty and isMultipass is true, the daemon's ShaderEffect runs these as intermediate passes before the main fragment shader.

bufferWrap

QString PhosphorAnimationShaders::AnimationShaderEffect::bufferWrap

Default wrap mode for all buffer samplers.

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

bufferWraps

QStringList PhosphorAnimationShaders::AnimationShaderEffect::bufferWraps

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

Daemon-only.

category

QString PhosphorAnimationShaders::AnimationShaderEffect::category

Category for settings-UI grouping (e.g. "Fade", "Geometric", "Glitch").

description

QString PhosphorAnimationShaders::AnimationShaderEffect::description

One-line description for settings UI tooltips.

fboExtentKind

FboExtentKind PhosphorAnimationShaders::AnimationShaderEffect::fboExtentKind = FboExtentKind::Anchor

fragmentShaderPath

QString PhosphorAnimationShaders::AnimationShaderEffect::fragmentShaderPath

Path to the fragment shader (relative to the effect dir).

The same source is used on both QtQuick and KWin paths — ShaderNodeRhi handles backend differences at the RHI level.

id

QString PhosphorAnimationShaders::AnimationShaderEffect::id

Stable identifier — lookup key in the registry.

isMultipass

bool PhosphorAnimationShaders::AnimationShaderEffect::isMultipass = false

Opt-in multipass mode.

When true and bufferShaderPaths is non-empty, the daemon path runs those buffer passes before the main fragment. The kwin-effect compositor path is single-pass only; multipass effects degrade to single-pass there with a diagnostic log (see AnimationShaderContract.h).

isUserEffect

bool PhosphorAnimationShaders::AnimationShaderEffect::isUserEffect = false

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

kMaxBufferScale

constexpr qreal PhosphorAnimationShaders::AnimationShaderEffect::kMaxBufferScale = 1.0

staticconstexpr

kMinBufferScale

constexpr qreal PhosphorAnimationShaders::AnimationShaderEffect::kMinBufferScale = 0.125

staticconstexpr

Lower / upper bounds on bufferScale (multipass FBO downscale factor).

0.125 means a 1/8 downscale on each axis (1/64 area — the lowest cost-floor that still gives Shadertoy-style buffer effects something to work with). 1.0 means full-resolution FBOs (no downscale). Hosted here as the source-of-truth that fromJson's clamp + the round-trip stability comment in toJson reference; a future runtime that consumes bufferScale from a non-JSON source can read these constants directly.

name

QString PhosphorAnimationShaders::AnimationShaderEffect::name

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

parameters

QList<ParameterInfo> PhosphorAnimationShaders::AnimationShaderEffect::parameters

previewPath

QString PhosphorAnimationShaders::AnimationShaderEffect::previewPath

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

sourceDir

QString PhosphorAnimationShaders::AnimationShaderEffect::sourceDir

Resolved absolute directory containing this effect's assets.

textures

QList<TextureSlot> PhosphorAnimationShaders::AnimationShaderEffect::textures

useDepthBuffer

bool PhosphorAnimationShaders::AnimationShaderEffect::useDepthBuffer = false

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

Daemon-only.

useWallpaper

bool PhosphorAnimationShaders::AnimationShaderEffect::useWallpaper = false

Bind the user's wallpaper as a sampler.

Daemon-only — the compositor path has no wallpaper plumbing so the field is observed only by SurfaceAnimator::attachShaderToAnchor.

version

QString PhosphorAnimationShaders::AnimationShaderEffect::version

Semantic version of this effect pack.

vertexShaderPath

QString PhosphorAnimationShaders::AnimationShaderEffect::vertexShaderPath

Path to the vertex shader (relative to the effect dir).

Empty = use the library's built-in fullscreen-quad vertex shader.

---

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

• phosphor-animation/include/PhosphorAnimation/AnimationShaderEffect.h