Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
SurfaceShaderEffect.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 <PhosphorSurface/phosphorsurface_export.h>
7
10
11#include <QAnyStringView>
12#include <QJsonObject>
13#include <QList>
14#include <QString>
15#include <QStringList>
16#include <QVariantMap>
17
18namespace PhosphorSurfaceShaders {
19
80struct PHOSPHORSURFACE_EXPORT SurfaceShaderEffect
81{
83 QString id;
84
86 QString name;
87
89 QString description;
90
92 QString author;
93
95 QString version;
96
100 QString category;
101
106
121
123 QString sourceDir;
124
126 bool isUserEffect = false;
127
129 QString previewPath;
130
131 // ── Multipass buffer passes (opt-in, matching overlay/animation packs) ──
132
138 bool isMultipass = false;
139
152
158 bool animated = false;
159
169 bool needsBackdrop = false;
170
185 bool interiorOpaque = false;
186
198 bool providesBorder = false;
199
207
215 bool audio = false;
216
227 QStringList bufferShaderPaths;
228
231 bool bufferFeedback = false;
232
238 qreal bufferScale = 1.0;
239
253 QList<qreal> bufferScales;
254
258 QString bufferWrap;
259
262 QStringList bufferWraps;
263
267
270 QStringList bufferFilters;
271
274 bool useDepthBuffer = false;
275
284 bool halfFloatBuffers = true;
285
294 static_assert(kMinBufferScale > 0.0 && kMinBufferScale < kMaxBufferScale,
295 "kMinBufferScale must be positive and strictly less than kMaxBufferScale");
296
312
331 {
332 QString id;
333 QString name;
334 QString type;
335 QString description;
336 QString group;
337 QVariant defaultValue;
338 QVariant minValue;
339 QVariant maxValue;
340 QVariant stepValue;
341 };
342 QList<ParameterInfo> parameters;
343
347 const ParameterInfo* findParameter(QAnyStringView id) const
348 {
349 for (const ParameterInfo& param : parameters) {
350 if (QAnyStringView::equal(param.id, id)) {
351 return &param;
352 }
353 }
354 return nullptr;
355 }
356
378 {
379 QString path;
380 QString
382
383 bool operator==(const TextureSlot& other) const
384 {
385 return path == other.path && wrap == other.wrap;
386 }
387 bool operator!=(const TextureSlot& other) const
388 {
389 return !(*this == other);
390 }
391 };
392 QList<TextureSlot> textures;
393
404
405 bool isValid() const
406 {
407 return !id.isEmpty() && !fragmentShaderPath.isEmpty();
408 }
409
410 QJsonObject toJson() const;
411 static SurfaceShaderEffect fromJson(const QJsonObject& obj);
412
413 bool operator==(const SurfaceShaderEffect& other) const;
414 bool operator!=(const SurfaceShaderEffect& other) const
415 {
416 return !(*this == other);
417 }
418};
419
420} // namespace PhosphorSurfaceShaders
421
422// Mark TextureSlot as relocatable so QList can move-construct entries
423// in-place during reallocation rather than running the copy/move ctor
424// per element. The struct is two QStrings; QString itself is already
425// Q_RELOCATABLE_TYPE, so the aggregate is safely bitwise-relocatable.
426// Must sit at file scope outside the namespace per Qt convention.
428// ParameterInfo is five QStrings + four QVariants; both QString and QVariant are
429// already Q_RELOCATABLE_TYPE, so the aggregate is safely bitwise-relocatable.
430// Declared for the same QList<ParameterInfo> reallocation benefit as TextureSlot.
Q_DECLARE_TYPEINFO(PhosphorSurfaceShaders::SurfaceShaderEffect::TextureSlot, Q_RELOCATABLE_TYPE)
constexpr double kMaxBufferScale
Definition CustomParamsKey.h:37
constexpr double kMinBufferScale
Lower / upper bounds on a multipass bufferScale (FBO downscale factor).
Definition CustomParamsKey.h:36
QMap< QString, QVariantMap > PackPresets
Pack-declared named parameter presets: preset name → { paramId → value }.
Definition ShaderPresetParse.h:32
constexpr int kMaxBufferPasses
Maximum number of multipass buffer passes a pack may declare.
Definition CustomParamsKey.h:68
Definition DecorationProfile.h:31
Declared shader inputs beyond the standard surface set (uTexture0, uSurfaceSize, uSurfaceFocused,...
Definition SurfaceShaderEffect.h:331
QString type
"float", "int", "bool", "color"
Definition SurfaceShaderEffect.h:334
QVariant minValue
JSON/QML key: min.
Definition SurfaceShaderEffect.h:338
QString id
Definition SurfaceShaderEffect.h:332
QVariant stepValue
Optional slider step; JSON/QML key: step. QML falls back to (max-min)/200.
Definition SurfaceShaderEffect.h:340
QString description
Optional one-line tooltip for the settings UI.
Definition SurfaceShaderEffect.h:335
QString group
Optional accordion group name for the settings UI.
Definition SurfaceShaderEffect.h:336
QString name
Definition SurfaceShaderEffect.h:333
QVariant maxValue
JSON/QML key: max.
Definition SurfaceShaderEffect.h:339
QVariant defaultValue
JSON/QML key: default.
Definition SurfaceShaderEffect.h:337
User texture slot.
Definition SurfaceShaderEffect.h:378
bool operator!=(const TextureSlot &other) const
Definition SurfaceShaderEffect.h:387
bool operator==(const TextureSlot &other) const
Definition SurfaceShaderEffect.h:383
QString wrap
"clamp" / "repeat" / "mirror"; empty = runtime default. Other values are rejected by fromJson.
Definition SurfaceShaderEffect.h:381
QString path
Filename relative to the effect's sourceDir.
Definition SurfaceShaderEffect.h:379
Metadata for a single surface shader effect.
Definition SurfaceShaderEffect.h:81
static constexpr qreal kMinBufferScale
Lower / upper bounds on bufferScale (multipass FBO downscale factor) — forwarders onto the cross-libr...
Definition SurfaceShaderEffect.h:292
PhosphorShaders::PackPresets presets
Pack-declared named parameter presets: preset name -> { paramId -> value }.
Definition SurfaceShaderEffect.h:403
static constexpr qreal kMaxBufferScale
Definition SurfaceShaderEffect.h:293
QList< TextureSlot > textures
Definition SurfaceShaderEffect.h:392
QString bufferFilter
Default filter mode for all buffer samplers.
Definition SurfaceShaderEffect.h:266
QStringList bufferWraps
Per-buffer wrap-mode overrides; index aligns with bufferShaderPaths.
Definition SurfaceShaderEffect.h:262
QList< ParameterInfo > parameters
Definition SurfaceShaderEffect.h:342
bool operator==(const SurfaceShaderEffect &other) const
QString version
Semantic version of this effect pack.
Definition SurfaceShaderEffect.h:95
QString category
Category for settings-UI grouping.
Definition SurfaceShaderEffect.h:100
const ParameterInfo * findParameter(QAnyStringView id) const
The declared parameter with id id, or nullptr when the pack does not declare it.
Definition SurfaceShaderEffect.h:347
bool useDepthBuffer
Allocate a depth buffer alongside the colour FBO so the shader can sample window depth.
Definition SurfaceShaderEffect.h:274
bool isValid() const
Definition SurfaceShaderEffect.h:405
bool isMultipass
Opt-in multipass mode.
Definition SurfaceShaderEffect.h:138
QString sourceDir
Resolved absolute directory containing this effect's assets.
Definition SurfaceShaderEffect.h:123
QStringList bufferFilters
Per-buffer filter-mode overrides; index aligns with bufferShaderPaths.
Definition SurfaceShaderEffect.h:270
QString previewPath
Preview image path (relative to the effect dir). For settings UI.
Definition SurfaceShaderEffect.h:129
bool isUserEffect
Whether this effect was loaded from a user-local directory.
Definition SurfaceShaderEffect.h:126
static SurfaceShaderEffect fromJson(const QJsonObject &obj)
QList< qreal > bufferScales
Per-pass render-target scales, positionally aligned with bufferShaderPaths (metadata bufferScales).
Definition SurfaceShaderEffect.h:253
bool providesBorder
Declares that the pack draws a window border of its own (the border family: border,...
Definition SurfaceShaderEffect.h:198
QString description
One-line description for settings UI tooltips.
Definition SurfaceShaderEffect.h:89
QStringList bufferShaderPaths
Buffer-pass shader paths (relative to effect dir).
Definition SurfaceShaderEffect.h:227
static constexpr int kMaxBufferPasses
Maximum number of buffer passes a pack may declare.
Definition SurfaceShaderEffect.h:311
bool needsBackdrop
Declares that the pack samples the scene BEHIND the window (backdropTexel() / uBackdrop).
Definition SurfaceShaderEffect.h:169
bool providesOpacityTint
Declares that the pack fades/tints the window surface (the reserved opacity-tint pack).
Definition SurfaceShaderEffect.h:206
bool interiorOpaque
Declares that the pack never writes a texel with alpha below the input's alpha INSIDE the window's na...
Definition SurfaceShaderEffect.h:185
qreal bufferScale
Render-target scale relative to the surface size, for every buffer pass that bufferScales does not na...
Definition SurfaceShaderEffect.h:238
QString bufferWrap
Default wrap mode for all buffer samplers.
Definition SurfaceShaderEffect.h:258
bool animated
Declares that the pack references iTime and needs a per-frame driver.
Definition SurfaceShaderEffect.h:158
QString vertexShaderPath
Path to the vertex shader (relative to the effect dir).
Definition SurfaceShaderEffect.h:120
bool audio
Declares that the pack reacts to the CAVA audio spectrum (it includes surface_audio....
Definition SurfaceShaderEffect.h:215
QString name
Human-readable display name (localizable by the consumer).
Definition SurfaceShaderEffect.h:86
QString author
Author attribution.
Definition SurfaceShaderEffect.h:92
bool bufferFeedback
Enable per-pass feedback (last frame's buffer is sampleable as iChannel<N>).
Definition SurfaceShaderEffect.h:231
bool halfFloatBuffers
Whether the intermediate buffers hold half-float texels.
Definition SurfaceShaderEffect.h:284
QString id
Stable identifier — lookup key in the registry.
Definition SurfaceShaderEffect.h:83
QString paddingParam
Names the parameter (an int/float, logical px) whose resolved value is the transparent OUTER MARGIN t...
Definition SurfaceShaderEffect.h:151
bool operator!=(const SurfaceShaderEffect &other) const
Definition SurfaceShaderEffect.h:414
QString fragmentShaderPath
Path to the fragment shader (relative to the effect dir).
Definition SurfaceShaderEffect.h:105