Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
ShaderProfile.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
6#include <PhosphorAnimation/phosphoranimation_export.h>
7
8#include <QJsonObject>
9#include <QMutex>
10#include <QSet>
11#include <QString>
12// For qWarning / qUtf8Printable in effectiveParameters() below. Named explicitly
13// rather than relied on through QString: this header is pulled in by the unity
14// build everywhere, where a neighbour's include hides a missing one, and the
15// non-unity build is the only place it shows up.
16#include <QtGlobal>
17#include <QVariantMap>
18
19#include <optional>
20
21namespace PhosphorShaders {
23}
24
26
49class PHOSPHORANIMATION_EXPORT ShaderProfile
50{
51public:
55 std::optional<QString> effectId;
56
67 std::optional<QVariantMap> parameters;
68
81 std::optional<QString> presetId;
82
83 // ─────── Effective getters ───────
84
85 QString effectiveEffectId() const
86 {
87 return effectId.value_or(QString());
88 }
89
97 QVariantMap storedParameters() const
98 {
99 return parameters.value_or(QVariantMap());
100 }
101
122 QVariantMap effectiveParameters() const
123 {
124 // ONCE per (effectId, presetId), not per call. These getters are read from render
125 // and install paths, so a single genuinely-unflattened consumer would otherwise
126 // repeat the warning for the life of the session and bury everything around it.
127 // The decoration tree's own parser chose qCDebug over a warning for exactly that
128 // reason; latching keeps the louder level, which is right for a contract
129 // violation, without the flood.
130 if (presetId && !presetId->isEmpty()) {
131 // Guarded: this getter is const on a value type whose class doc says it is not
132 // internally synchronized, and contains()+insert() on a shared QSet is not
133 // atomic (only the static's INITIALISATION is). The set is bounded by the
134 // user's own config, so growth is not the concern; a torn read is.
135 //
136 // The latch is process-wide, which is why no test asserts "warns exactly
137 // once": a slot doing that would pass or fail on slot ORDER within the
138 // binary. A test that wants to see the warning has to use a (pack, preset)
139 // pair no earlier slot has touched, which the key makes possible.
140 static QMutex latchMutex;
141 static QSet<QString> reported;
142 const QMutexLocker latchLock(&latchMutex);
143 const QString key = effectId.value_or(QString()) + QLatin1Char('\x1f') + *presetId;
144 if (!reported.contains(key)) {
145 reported.insert(key);
146 qWarning(
147 "PhosphorAnimation: ShaderProfile::effectiveParameters() read on a profile whose preset is NOT "
148 "yet applied (effectId=%s presetId=%s). The preset's values are missing from the result — "
149 "flatten with withPresetsResolved() after the tree walk-up, never per node. Reported once per "
150 "pack and preset.",
151 qUtf8Printable(effectId.value_or(QString())), qUtf8Printable(*presetId));
152 }
153 }
154 return parameters.value_or(QVariantMap());
155 }
156
160 QString effectivePresetId() const
161 {
162 return presetId.value_or(QString());
163 }
164
166
167 // ─────── Serialization ───────
168
169 static constexpr auto JsonFieldEffectId = "effectId";
170 static constexpr auto JsonFieldParameters = "parameters";
171 static constexpr auto JsonFieldPresetId = "presetId";
172
173 QJsonObject toJson() const;
174 static ShaderProfile fromJson(const QJsonObject& obj);
175
176 // ─────── Overlay ───────
177
180 static void overlay(ShaderProfile& dst, const ShaderProfile& src);
181
182 // ─────── Equality ───────
183
184 bool operator==(const ShaderProfile& other) const;
185 bool operator!=(const ShaderProfile& other) const
186 {
187 return !(*this == other);
188 }
189};
190
213PHOSPHORANIMATION_EXPORT ShaderProfile withPresetsResolved(const ShaderProfile& profile,
215
216} // namespace PhosphorAnimationShaders
Per-event shader effect selection and configuration.
Definition ShaderProfile.h:50
static constexpr auto JsonFieldEffectId
Definition ShaderProfile.h:169
QString effectivePresetId() const
As with the decoration twin's presetIdFor, the callers are tests.
Definition ShaderProfile.h:160
std::optional< QString > presetId
The preset parameters are deltas against, resolved by id from PhosphorShaders::ShaderPresetRegistry a...
Definition ShaderProfile.h:81
QString effectiveEffectId() const
Definition ShaderProfile.h:85
static ShaderProfile fromJson(const QJsonObject &obj)
std::optional< QVariantMap > parameters
Per-event parameter overrides for the shader.
Definition ShaderProfile.h:67
static constexpr auto JsonFieldPresetId
Definition ShaderProfile.h:171
bool operator==(const ShaderProfile &other) const
QVariantMap storedParameters() const
The stored parameter map, without judgement.
Definition ShaderProfile.h:97
QVariantMap effectiveParameters() const
The parameter map a CONSUMER should render.
Definition ShaderProfile.h:122
std::optional< QString > effectId
Which animation shader effect to apply.
Definition ShaderProfile.h:55
static void overlay(ShaderProfile &dst, const ShaderProfile &src)
Overlay src onto dst: every engaged field in src replaces the corresponding field in dst.
bool operator!=(const ShaderProfile &other) const
Definition ShaderProfile.h:185
static constexpr auto JsonFieldParameters
Definition ShaderProfile.h:170
The one place a presetId on an assignment turns into parameters.
Definition ShaderPresetRegistry.h:51
Definition AnimationShaderContract.h:10
PHOSPHORANIMATION_EXPORT ShaderProfile withPresetsResolved(const ShaderProfile &profile, const PhosphorShaders::ShaderPresetRegistry &presets)
Flatten profile's preset reference into its parameters.
Definition ShaderProfile.h:21