Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
AnimationShaderContract.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
7
8#include <QString>
9
11
217
257inline constexpr const char* kITime = "iTime";
258
262inline constexpr const char* kIResolution = "iResolution";
263
269inline constexpr const char* kITimeDelta = "iTimeDelta";
270
277inline constexpr const char* kIFrame = "iFrame";
278
284inline constexpr const char* kIDate = "iDate";
285
300inline constexpr const char* kIIsReversed = "iIsReversed";
301
337inline constexpr const char* kISurfaceScreenPos = "iSurfaceScreenPos";
338
346inline constexpr const char* kIAnchorSize = "iAnchorSize";
347
368inline constexpr const char* kIAnchorPosInFbo = "iAnchorPosInFbo";
369
387inline constexpr const char* kIAnchorRectInTexture = "iAnchorRectInTexture";
388
407inline constexpr const char* kIFromRect = "iFromRect";
408inline constexpr const char* kIToRect = "iToRect";
409
430inline constexpr const char* kIIconRect = "iIconRect";
431
448inline constexpr const char* kUOldWindow = "uOldWindow";
449
460inline constexpr const char* kUSurfaceLayer = "uSurfaceLayer";
461
468inline constexpr const char* kIHasSurfaceLayer = "iHasSurfaceLayer";
469
478inline constexpr const char* kIHasOldWindow = "iHasOldWindow";
479
489inline constexpr const char* kIOldWindowOpacity = "iOldWindowOpacity";
490
499inline constexpr const char* kIMoveVelocity = "iMoveVelocity";
503inline constexpr const char* kIMoveOffset = "iMoveOffset";
510inline constexpr const char* kIMoveVelocity2 = "iMoveVelocity2";
519inline constexpr const char* kIMoveTrail = "iMoveTrail";
529inline constexpr const char* kIMoveMesh = "iMoveMesh";
536inline constexpr const char* kILayerRectInTexture = "iLayerRectInTexture";
537
551inline constexpr const char* kIWindowOpacity = "iWindowOpacity";
552
567inline constexpr int kMaxUserTextureSlots = 3;
568
577
584inline constexpr const char* kIAudioSpectrumSize = "iAudioSpectrumSize";
585
591inline constexpr const char* kUAudioSpectrum = "uAudioSpectrum";
592
612inline constexpr const char* kIMouse = "iMouse";
613
620inline constexpr const char* kCustomParamsArray = "customParams";
621
635
641
649inline QString slotKey(int vec, char comp)
650{
652}
653
655inline QString slotKey(int slot)
656{
658}
659
683inline constexpr const char* kCustomColorsArray = "customColors";
685
693inline QString colorKey(int slot)
694{
696}
697
698// These two paragraphs document the CONTRACT rather than any one
699// declaration, so they are plain comments: a /// block followed by a blank
700// line attaches to nothing and Doxygen discards it. Every @par that does
701// belong to a declaration lives in the namespace doc at the top of this file.
702//
703// MULTIPASS LIMITATION (compositor path)
704// Animation shaders may declare multipass buffer shaders, wallpaper,
705// and depth in their metadata. The daemon's SurfaceAnimator wires
706// these through to PhosphorRendering::ShaderEffect which has full
707// multipass support. However, the kwin-effect compositor path uses
708// KWin::GLShader via OffscreenEffect, which is single-pass with no
709// auxiliary FBOs. Multipass animation shaders degrade to single-pass
710// on the compositor with a diagnostic log.
711
712// STD140 OFFSET CONTRACT
713// The canonical `plasmazones/data/animations/shared/animation_uniforms.glsl` UBO
714// declares its fields at the same byte offsets as
715// `PhosphorShaders::BaseUniforms` (the daemon's `binding=0` upload
716// struct). That alignment is what lets a single `effect.frag` source
717// run on both runtimes without per-runtime overrides.
718//
719// The C++ side of the contract is pinned by `static_assert(offsetof(...))`
720// statements in `<PhosphorShaders/BaseUniforms.h>` for every BASE field
721// declared in the GLSL UBO (through iIsReversed at byte 660); the anchor
722// tail (iSurfaceScreenPos .. iMoveMesh, bytes 672-1343, 1344 total)
723// is supplied by AnimationUniformExtension and pinned by the size
724// static_asserts in `<PhosphorAnimation/AnimationUniformExtension.h>`.
725// If anyone reorders `BaseUniforms`, those asserts fail at compile time
726// and the canonical GLSL header has to be updated to match. The GLSL side
727// is exercised at build time by
728// `plasmazones/tests/unit/ui/shaders/test_animation_shader_bake.cpp`, which runs every
729// built-in animation shader through `qsb` (which in turn computes
730// std140 offsets) — a layout drift would surface there as a bake
731// failure.
732
746inline bool isValidWrapToken(const QString& wrap)
747{
748 // Thin forwarder onto the cross-library canonical predicate in
749 // <PhosphorShaders/CustomParamsKey.h> (already included above), so all
750 // FOUR shader families share one wrap vocabulary rather than each
751 // hand-rolling its own token list that can drift.
753}
754
763inline bool isValidFilterToken(const QString& filter)
764{
765 // Forwarder onto PhosphorShaders::isValidFilterToken, for the same reason
766 // as isValidWrapToken above.
768}
769
770} // namespace AnimationShaderContract
771
772} // namespace PhosphorAnimationShaders
773
774// The compile-time link between AnimationShaderContract::kMaxUserTextureSlots
775// and PhosphorRendering::kMaxUserTextures lives in
776// libs/phosphor-animation/src/contract_pins.cpp. It cannot live in this header
777// because translation units that only need contract definitions (notably the
778// kwin-effect, which already pulls in epoxy/gl.h via KWin) must not be forced
779// to also pull in <QtQuick/QSGTextureProvider> via ShaderNodeRhi.h — epoxy and
780// Qt's qopenglext.h declare overlapping GL function-pointer typedefs that
781// conflict when both end up in the same TU.
Cross-runtime named-uniform contract for animation/transition shaders.
Definition AnimationShaderContract.h:216
constexpr const char * kISurfaceScreenPos
vec4 iSurfaceScreenPos — the shader surface's position plus the host screen dimensions,...
Definition AnimationShaderContract.h:337
constexpr const char * kIMoveVelocity
vec2 iMoveVelocity — COMPOSITOR PATH ONLY.
Definition AnimationShaderContract.h:499
constexpr const char * kIAnchorPosInFbo
vec2 iAnchorPosInFbo is the anchor's top-left position inside the FBO, in logical pixels.
Definition AnimationShaderContract.h:368
constexpr const char * kIFromRect
vec4 iFromRect / vec4 iToRect — geometry-morph endpoints in logical screen pixels (x,...
Definition AnimationShaderContract.h:407
constexpr const char * kIMoveTrail
vec2 iMoveTrail[16] — COMPOSITOR PATH ONLY.
Definition AnimationShaderContract.h:519
constexpr const char * kIAnchorSize
vec2 iAnchorSize — captured anchor (card) pixel size in logical pixels.
Definition AnimationShaderContract.h:346
QString slotKey(int vec, char comp)
Format a customParams slot key — thin forwarder onto PhosphorShaders::CustomParams::slotKey,...
Definition AnimationShaderContract.h:649
constexpr const char * kUAudioSpectrum
sampler2D uAudioSpectrum — the CAVA spectrum texture (bars×1, R = bar value in 0.....
Definition AnimationShaderContract.h:591
constexpr const char * kIAnchorRectInTexture
vec4 iAnchorRectInTexture — the card's UV sub-rect within uTexture0, as (x, y, width,...
Definition AnimationShaderContract.h:387
constexpr const char * kIResolution
vec2 iResolution — surface size in logical pixels.
Definition AnimationShaderContract.h:262
constexpr const char * kCustomColorsArray
vec4 customColors[N] — per-effect declared color parameter slots.
Definition AnimationShaderContract.h:683
constexpr int kMaxCustomColors
Definition AnimationShaderContract.h:684
constexpr const char * kIAudioSpectrumSize
int iAudioSpectrumSize — CAVA bar count, 0 while the audio visualizer is off or cava is unavailable.
Definition AnimationShaderContract.h:584
constexpr int kMaxUserTextureSlots
Maximum number of user-declared textures per animation effect.
Definition AnimationShaderContract.h:567
constexpr const char * kIHasOldWindow
int iHasOldWindow — COMPOSITOR PATH ONLY.
Definition AnimationShaderContract.h:478
constexpr const char * kIDate
vec4 iDate — local-time (year, month, day, seconds-since-midnight).
Definition AnimationShaderContract.h:284
constexpr int kMaxParameterSlots
Number of float sub-slots (4 per vec4 × 8 vec4s = 32).
Definition AnimationShaderContract.h:640
constexpr const char * kIMoveVelocity2
vec2 iMoveVelocity2 — COMPOSITOR PATH ONLY.
Definition AnimationShaderContract.h:510
constexpr const char * kIMoveMesh
vec2 iMoveMesh[16] — COMPOSITOR PATH ONLY.
Definition AnimationShaderContract.h:529
bool isValidWrapToken(const QString &wrap)
The accepted texture wrap vocabulary, shared by every animation validation site (metadata parse in An...
Definition AnimationShaderContract.h:746
constexpr const char * kIToRect
Definition AnimationShaderContract.h:408
constexpr const char * kIOldWindowOpacity
float iOldWindowOpacity — COMPOSITOR PATH ONLY.
Definition AnimationShaderContract.h:489
bool isValidFilterToken(const QString &filter)
The accepted buffer filter vocabulary: linear / nearest / mipmap.
Definition AnimationShaderContract.h:763
constexpr const char * kIHasSurfaceLayer
int iHasSurfaceLayer — COMPOSITOR PATH ONLY.
Definition AnimationShaderContract.h:468
constexpr const char * kITimeDelta
float iTimeDelta — wall-clock seconds between consecutive paint ticks that fed this transition.
Definition AnimationShaderContract.h:269
constexpr const char * kIMouse
vec4 iMouse — cursor position in shader-local pixels.
Definition AnimationShaderContract.h:612
constexpr const char * kIIconRect
vec4 iIconRect — the window's task-manager icon rectangle in logical screen pixels (x,...
Definition AnimationShaderContract.h:430
constexpr const char * kIWindowOpacity
float iWindowOpacity — the window's effective rule-resolved opacity in [0.0, 1.0],...
Definition AnimationShaderContract.h:551
constexpr const char * kITime
float iTime — transition progress, normally in [0.0, 1.0].
Definition AnimationShaderContract.h:257
constexpr int kMaxCustomParams
Number of vec4 slots in the customParams array (8).
Definition AnimationShaderContract.h:634
constexpr const char * kUOldWindow
sampler2D uOldWindow — snapshot of the window's content captured at the old frame size just before th...
Definition AnimationShaderContract.h:448
constexpr const char * kILayerRectInTexture
Card/anchor-space [0,1] sub-rect of the animated surface WITHIN uSurfaceLayer's canvas (xy offset,...
Definition AnimationShaderContract.h:536
constexpr int kMaxBufferPasses
Multipass buffer-pass budget.
Definition AnimationShaderContract.h:576
QString colorKey(int slot)
Format a customColor slot key — thin forwarder onto PhosphorShaders::CustomColors::colorKey.
Definition AnimationShaderContract.h:693
constexpr const char * kIFrame
int iFrame — per-leg frame counter.
Definition AnimationShaderContract.h:277
constexpr const char * kIMoveOffset
vec2 iMoveOffset — COMPOSITOR PATH ONLY.
Definition AnimationShaderContract.h:503
constexpr const char * kCustomParamsArray
vec4 customParams[N] — per-effect declared parameter slots.
Definition AnimationShaderContract.h:620
constexpr const char * kIIsReversed
int iIsReversed — direction signal for asymmetric leg rendering.
Definition AnimationShaderContract.h:300
constexpr const char * kUSurfaceLayer
sampler2D uSurfaceLayer — COMPOSITOR PATH ONLY.
Definition AnimationShaderContract.h:460
Definition AnimationShaderContract.h:10
QString colorKey(int slot)
Format a customColor key from a 0-based slot index.
Definition CustomParamsKey.h:224
constexpr int kColorCount
Number of color slots in BaseUniforms::customColors[16].
Definition CustomParamsKey.h:218
QString slotKey(int vec, char comp)
Format a customParams slot key from explicit (vec, comp) pair.
Definition CustomParamsKey.h:140
constexpr int kVecCount
Number of vec4 slots in BaseUniforms::customParams[8].
Definition CustomParamsKey.h:127
constexpr int kFlatSlotCount
Number of float sub-slots across all vec4s (4 × kVecCount).
Definition CustomParamsKey.h:133
bool isValidFilterToken(const QString &filter)
The accepted buffer filter vocabulary: linear / nearest / mipmap.
Definition CustomParamsKey.h:94
constexpr int kMaxBufferPasses
Maximum number of multipass buffer passes a pack may declare.
Definition CustomParamsKey.h:68
bool isValidWrapToken(const QString &wrap)
The accepted texture / buffer wrap vocabulary, shared by every validation site across the shader regi...
Definition CustomParamsKey.h:84