ShaderEffect.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <PhosphorRendering/ShaderNodeLiveness.h>
#include <PhosphorRendering/phosphorrendering_export.h>
 
#include <PhosphorShaders/ShaderEntryPoint.h>
 
#include <QColor>
#include <QImage>
#include <QMutex>
#include <QPointF>
#include <QQuickItem>
#include <QSizeF>
#include <QStringList>
#include <QUrl>
#include <QVariantMap>
#include <QVector4D>
 
#include <QPointer>
#include <array>
#include <atomic>
#include <functional>
#include <memory>
#include <mutex>
 
QT_BEGIN_NAMESPACE
class QSGNode;
QT_END_NAMESPACE
 
namespace PhosphorShaders {
class IUniformExtension;
}
 
namespace PhosphorRendering {
 
class ShaderNodeRhi;
 
inline constexpr int kMaxUserTextureSlots = 4;
 
inline constexpr int kDefaultUserTextureSvgSize = 1024;
 
PHOSPHORRENDERING_EXPORT QVariant peelQmlVariant(const QVariant& value);
 
class PHOSPHORRENDERING_EXPORT ShaderEffect : public QQuickItem
{
    Q_OBJECT
 
    // ── Shadertoy-compatible animation uniforms ──────────────────────
    Q_PROPERTY(qreal iTime READ iTime WRITE setITime NOTIFY iTimeChanged FINAL)
    Q_PROPERTY(qreal iTimeDelta READ iTimeDelta WRITE setITimeDelta NOTIFY iTimeDeltaChanged FINAL)
    Q_PROPERTY(int iFrame READ iFrame WRITE setIFrame NOTIFY iFrameChanged FINAL)
    Q_PROPERTY(QSizeF iResolution READ iResolution WRITE setIResolution NOTIFY iResolutionChanged FINAL)
    Q_PROPERTY(QPointF iMouse READ iMouse WRITE setIMouse NOTIFY iMouseChanged FINAL)
    Q_PROPERTY(bool isReversed READ isReversed WRITE setIsReversed NOTIFY isReversedChanged FINAL)
 
    
    Q_PROPERTY(bool playing READ isPlaying WRITE setPlaying NOTIFY playingChanged FINAL)
 
    // ── Shader source ────────────────────────────────────────────────
    Q_PROPERTY(QUrl shaderSource READ shaderSource WRITE setShaderSource NOTIFY shaderSourceChanged FINAL)
    Q_PROPERTY(QUrl vertexShaderUrl READ vertexShaderUrl WRITE setVertexShaderUrl NOTIFY vertexShaderUrlChanged FINAL)
    Q_PROPERTY(QVariantMap shaderParams READ shaderParams WRITE setShaderParams NOTIFY shaderParamsChanged)
    Q_PROPERTY(QString paramPreamble READ paramPreamble WRITE setParamPreamble NOTIFY paramPreambleChanged)
    Q_PROPERTY(QQuickItem* sourceItem READ sourceItem WRITE setSourceItem NOTIFY sourceItemChanged FINAL)
 
    // ── Multipass ────────────────────────────────────────────────────
    Q_PROPERTY(
        QString bufferShaderPath READ bufferShaderPath WRITE setBufferShaderPath NOTIFY bufferShaderPathChanged FINAL)
    Q_PROPERTY(QStringList bufferShaderPaths READ bufferShaderPaths WRITE setBufferShaderPaths NOTIFY
                   bufferShaderPathsChanged FINAL)
    Q_PROPERTY(bool bufferFeedback READ bufferFeedback WRITE setBufferFeedback NOTIFY bufferFeedbackChanged FINAL)
    Q_PROPERTY(qreal bufferScale READ bufferScale WRITE setBufferScale NOTIFY bufferScaleChanged FINAL)
    Q_PROPERTY(
        bool halfFloatBuffers READ halfFloatBuffers WRITE setHalfFloatBuffers NOTIFY halfFloatBuffersChanged FINAL)
    Q_PROPERTY(QString bufferWrap READ bufferWrap WRITE setBufferWrap NOTIFY bufferWrapChanged FINAL)
    Q_PROPERTY(QStringList bufferWraps READ bufferWraps WRITE setBufferWraps NOTIFY bufferWrapsChanged FINAL)
    Q_PROPERTY(QString bufferFilter READ bufferFilter WRITE setBufferFilter NOTIFY bufferFilterChanged FINAL)
    Q_PROPERTY(QStringList bufferFilters READ bufferFilters WRITE setBufferFilters NOTIFY bufferFiltersChanged FINAL)
 
    // ── Custom parameters (32 floats in 8 vec4s) ────────────────────
    Q_PROPERTY(QVector4D customParams1 READ customParams1 WRITE setCustomParams1 NOTIFY customParamsChanged FINAL)
    Q_PROPERTY(QVector4D customParams2 READ customParams2 WRITE setCustomParams2 NOTIFY customParamsChanged FINAL)
    Q_PROPERTY(QVector4D customParams3 READ customParams3 WRITE setCustomParams3 NOTIFY customParamsChanged FINAL)
    Q_PROPERTY(QVector4D customParams4 READ customParams4 WRITE setCustomParams4 NOTIFY customParamsChanged FINAL)
    Q_PROPERTY(QVector4D customParams5 READ customParams5 WRITE setCustomParams5 NOTIFY customParamsChanged FINAL)
    Q_PROPERTY(QVector4D customParams6 READ customParams6 WRITE setCustomParams6 NOTIFY customParamsChanged FINAL)
    Q_PROPERTY(QVector4D customParams7 READ customParams7 WRITE setCustomParams7 NOTIFY customParamsChanged FINAL)
    Q_PROPERTY(QVector4D customParams8 READ customParams8 WRITE setCustomParams8 NOTIFY customParamsChanged FINAL)
 
    // ── Custom colors (16 color slots) ───────────────────────────────
    Q_PROPERTY(QColor customColor1 READ customColor1 WRITE setCustomColor1 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor2 READ customColor2 WRITE setCustomColor2 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor3 READ customColor3 WRITE setCustomColor3 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor4 READ customColor4 WRITE setCustomColor4 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor5 READ customColor5 WRITE setCustomColor5 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor6 READ customColor6 WRITE setCustomColor6 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor7 READ customColor7 WRITE setCustomColor7 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor8 READ customColor8 WRITE setCustomColor8 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor9 READ customColor9 WRITE setCustomColor9 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor10 READ customColor10 WRITE setCustomColor10 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor11 READ customColor11 WRITE setCustomColor11 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor12 READ customColor12 WRITE setCustomColor12 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor13 READ customColor13 WRITE setCustomColor13 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor14 READ customColor14 WRITE setCustomColor14 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor15 READ customColor15 WRITE setCustomColor15 NOTIFY customColorsChanged FINAL)
    Q_PROPERTY(QColor customColor16 READ customColor16 WRITE setCustomColor16 NOTIFY customColorsChanged FINAL)
 
    // ── Textures ─────────────────────────────────────────────────────
    Q_PROPERTY(QVariant audioSpectrum READ audioSpectrumVariant WRITE setAudioSpectrumVariant NOTIFY
                   audioSpectrumChanged FINAL)
    Q_PROPERTY(QVariant wallpaperTexture READ wallpaperTextureVariant WRITE setWallpaperTextureVariant NOTIFY
                   wallpaperTextureChanged FINAL)
    Q_PROPERTY(bool useWallpaper READ useWallpaper WRITE setUseWallpaper NOTIFY useWallpaperChanged FINAL)
    Q_PROPERTY(bool useDepthBuffer READ useDepthBuffer WRITE setUseDepthBuffer NOTIFY useDepthBufferChanged FINAL)
 
    // ── Status ───────────────────────────────────────────────────────
    Q_PROPERTY(Status status READ status NOTIFY statusChanged FINAL)
    Q_PROPERTY(QString errorLog READ errorLog NOTIFY errorLogChanged FINAL)
 
public:
    enum class Status {
        Null, 
        Loading, 
        Ready, 
        Error, 
    };
    Q_ENUM(Status)
 
    
    static constexpr int kMaxSvgDimension = 2048;
 
    static constexpr int kMinSvgDimension = 64;
 
    static constexpr qint64 kMaxSvgPixelBytes = 16LL * 1024 * 1024;
 
    explicit ShaderEffect(QQuickItem* parent = nullptr);
    ~ShaderEffect() override;
 
    // ── Uniform extension ────────────────────────────────────────────
 
    virtual void setUniformExtension(std::shared_ptr<PhosphorShaders::IUniformExtension> extension);
    std::shared_ptr<PhosphorShaders::IUniformExtension> uniformExtension() const;
 
    // ── Shadertoy uniforms ───────────────────────────────────────────
 
    qreal iTime() const
    {
        return m_iTime;
    }
    void setITime(qreal time);
 
    qreal iTimeDelta() const
    {
        return m_iTimeDelta;
    }
    void setITimeDelta(qreal delta);
 
    int iFrame() const
    {
        return m_iFrame;
    }
    void setIFrame(int frame);
 
    bool isPlaying() const
    {
        return m_playing;
    }
    void setPlaying(bool playing);
 
    bool isReversed() const
    {
        return m_isReversed;
    }
    void setIsReversed(bool reverse);
 
    QSizeF iResolution() const
    {
        return m_iResolution;
    }
    void setIResolution(const QSizeF& resolution);
 
    QPointF iMouse() const
    {
        return m_iMouse;
    }
    void setIMouse(const QPointF& mouse);
 
    // ── Shader source ────────────────────────────────────────────────
 
    QUrl shaderSource() const
    {
        return m_shaderSource;
    }
    void setShaderSource(const QUrl& source);
 
    QUrl vertexShaderUrl() const
    {
        return m_vertexShaderUrl;
    }
    void setVertexShaderUrl(const QUrl& source);
 
    QVariantMap shaderParams() const
    {
        return m_shaderParams;
    }
    virtual void setShaderParams(const QVariantMap& params);
 
    static QImage loadUserTextureFile(const QString& path, int svgMaxDim);
 
    QQuickItem* sourceItem() const
    {
        return m_sourceItem.data();
    }
    void setSourceItem(QQuickItem* item);
 
    // ── Multipass ────────────────────────────────────────────────────
 
    QString bufferShaderPath() const
    {
        return m_bufferShaderPath;
    }
    void setBufferShaderPath(const QString& path);
 
    QStringList bufferShaderPaths() const
    {
        return m_bufferShaderPaths;
    }
    void setBufferShaderPaths(const QStringList& paths);
 
    bool bufferFeedback() const
    {
        return m_bufferFeedback;
    }
    void setBufferFeedback(bool enable);
 
    qreal bufferScale() const
    {
        return m_bufferScale;
    }
    void setBufferScale(qreal scale);
 
    bool halfFloatBuffers() const
    {
        return m_halfFloatBuffers;
    }
    void setHalfFloatBuffers(bool enable);
 
    QString bufferWrap() const
    {
        return m_bufferWrap;
    }
    void setBufferWrap(const QString& wrap);
 
    QStringList bufferWraps() const
    {
        return m_bufferWraps;
    }
    void setBufferWraps(const QStringList& wraps);
 
    QString bufferFilter() const
    {
        return m_bufferFilter;
    }
    void setBufferFilter(const QString& filter);
 
    QStringList bufferFilters() const
    {
        return m_bufferFilters;
    }
    void setBufferFilters(const QStringList& filters);
 
    // ── Custom parameters (32 float slots in 8 vec4s) ────────────────
 
    QVector4D customParams1() const
    {
        return m_customParams[0];
    }
    void setCustomParams1(const QVector4D& params);
    QVector4D customParams2() const
    {
        return m_customParams[1];
    }
    void setCustomParams2(const QVector4D& params);
    QVector4D customParams3() const
    {
        return m_customParams[2];
    }
    void setCustomParams3(const QVector4D& params);
    QVector4D customParams4() const
    {
        return m_customParams[3];
    }
    void setCustomParams4(const QVector4D& params);
    QVector4D customParams5() const
    {
        return m_customParams[4];
    }
    void setCustomParams5(const QVector4D& params);
    QVector4D customParams6() const
    {
        return m_customParams[5];
    }
    void setCustomParams6(const QVector4D& params);
    QVector4D customParams7() const
    {
        return m_customParams[6];
    }
    void setCustomParams7(const QVector4D& params);
    QVector4D customParams8() const
    {
        return m_customParams[7];
    }
    void setCustomParams8(const QVector4D& params);
 
    // ── Custom colors (16 color slots) ───────────────────────────────
 
    QColor customColor1() const
    {
        return m_customColors[0];
    }
    void setCustomColor1(const QColor& color);
    QColor customColor2() const
    {
        return m_customColors[1];
    }
    void setCustomColor2(const QColor& color);
    QColor customColor3() const
    {
        return m_customColors[2];
    }
    void setCustomColor3(const QColor& color);
    QColor customColor4() const
    {
        return m_customColors[3];
    }
    void setCustomColor4(const QColor& color);
    QColor customColor5() const
    {
        return m_customColors[4];
    }
    void setCustomColor5(const QColor& color);
    QColor customColor6() const
    {
        return m_customColors[5];
    }
    void setCustomColor6(const QColor& color);
    QColor customColor7() const
    {
        return m_customColors[6];
    }
    void setCustomColor7(const QColor& color);
    QColor customColor8() const
    {
        return m_customColors[7];
    }
    void setCustomColor8(const QColor& color);
    QColor customColor9() const
    {
        return m_customColors[8];
    }
    void setCustomColor9(const QColor& color);
    QColor customColor10() const
    {
        return m_customColors[9];
    }
    void setCustomColor10(const QColor& color);
    QColor customColor11() const
    {
        return m_customColors[10];
    }
    void setCustomColor11(const QColor& color);
    QColor customColor12() const
    {
        return m_customColors[11];
    }
    void setCustomColor12(const QColor& color);
    QColor customColor13() const
    {
        return m_customColors[12];
    }
    void setCustomColor13(const QColor& color);
    QColor customColor14() const
    {
        return m_customColors[13];
    }
    void setCustomColor14(const QColor& color);
    QColor customColor15() const
    {
        return m_customColors[14];
    }
    void setCustomColor15(const QColor& color);
    QColor customColor16() const
    {
        return m_customColors[15];
    }
    void setCustomColor16(const QColor& color);
 
    // ── Indexed accessors (avoid per-slot function-pointer tables at call sites) ──
    QVector4D customParamAt(int index) const;
    void setCustomParamAt(int index, const QVector4D& params);
 
    QColor customColorAt(int index) const;
    void setCustomColorAt(int index, const QColor& color);
 
    // ── Textures ─────────────────────────────────────────────────────
 
    QVariant audioSpectrumVariant() const;
    void setAudioSpectrumVariant(const QVariant& spectrum);
    void setAudioSpectrum(const QVector<float>& spectrum);
 
    void setUserTexture(int slot, const QImage& image);
    void setUserTextureWrap(int slot, const QString& wrap);
 
    QImage wallpaperTexture() const;
 
    QVariant wallpaperTextureVariant() const;
    void setWallpaperTexture(const QImage& image);
    void setWallpaperTextureVariant(const QVariant& texture);
 
    bool useWallpaper() const
    {
        return m_useWallpaper;
    }
    void setUseWallpaper(bool use);
 
    bool useDepthBuffer() const
    {
        return m_useDepthBuffer;
    }
    void setUseDepthBuffer(bool use);
 
    // ── Shader include paths ─────────────────────────────────────────
 
    void setShaderIncludePaths(const QStringList& paths);
    QStringList shaderIncludePaths() const
    {
        return m_shaderIncludePaths;
    }
 
    // ── Parameter preamble (T1.1: generated `#define p_<id> ...`) ─────
 
    void setParamPreamble(const QString& preamble);
    QString paramPreamble() const
    {
        return m_paramPreamble;
    }
 
    // ── Entry-point scaffold (T1.4: harness-generated `main()`) ────────
 
    void setEntryScaffold(const QString& prologue, const QList<PhosphorShaders::EntryCandidate>& candidates);
 
    // ── Status ───────────────────────────────────────────────────────
 
    Status status() const
    {
        return m_status.load(std::memory_order_acquire);
    }
    QString errorLog() const
    {
        QMutexLocker lock(&m_errorLogMutex);
        return m_errorLog;
    }
 
    // ── Actions ──────────────────────────────────────────────────────
 
    Q_INVOKABLE void reloadShader();
 
    Q_INVOKABLE void releaseIdleGraphicsResources();
 
Q_SIGNALS:
    void iTimeChanged();
    void iTimeDeltaChanged();
    void iFrameChanged();
    void iResolutionChanged();
    void iMouseChanged();
    void isReversedChanged();
    void playingChanged();
    void shaderSourceChanged();
    void vertexShaderUrlChanged();
    void shaderParamsChanged();
    void paramPreambleChanged();
    void sourceItemChanged();
    void bufferShaderPathChanged();
    void bufferShaderPathsChanged();
    void bufferFeedbackChanged();
    void bufferScaleChanged();
    void halfFloatBuffersChanged();
    void bufferWrapChanged();
    void bufferWrapsChanged();
    void bufferFilterChanged();
    void bufferFiltersChanged();
    void customParamsChanged();
    void customColorsChanged();
    void audioSpectrumChanged();
    void wallpaperTextureChanged();
    void useWallpaperChanged();
    void useDepthBufferChanged();
    void statusChanged();
    void errorLogChanged();
 
protected:
    QSGNode* updatePaintNode(QSGNode* oldNode, UpdatePaintNodeData* data) override;
    void geometryChange(const QRectF& newGeometry, const QRectF& oldGeometry) override;
    void componentComplete() override;
    void itemChange(ItemChange change, const ItemChangeData& value) override;
 
    qreal effectiveResolutionScale() const;
 
    void syncBasePropertiesToNode(ShaderNodeRhi* node);
 
    bool consumeShaderDirty()
    {
        return m_shaderDirty.exchange(false);
    }
 
    virtual ShaderNodeRhi* createShaderNode();
 
    void registerRenderNode(ShaderNodeRhi* node);
 
    void setError(const QString& error);
    void setStatus(Status newStatus);
 
private:
    // ── Auto-tick (playing=true) plumbing ────────────────────────────
    void updatePlayingConnection();
    void onPlayingTick();
 
    // ── Output-scale plumbing ────────────────────────────────────────
    void updateScaleConnections();
 
    // ── Animation state ──────────────────────────────────────────────
    // Field order minimises padding: 8-byte (qreal/QSizeF/QPointF) members
    // grouped together, followed by 4-byte (int), trailing 1-byte bool.
    // qreal-bool-int interleaving wastes 7 bytes via alignment padding.
    qreal m_iTime = 0.0;
    qreal m_iTimeDelta = 0.0;
    qreal m_playingLastFrameSeconds = 0.0; 
    QSizeF m_iResolution;
    QPointF m_iMouse;
    int m_iFrame = 0;
    bool m_isReversed = false;
    bool m_playing = false;
    QMetaObject::Connection m_playingConnection;
    QMetaObject::Connection m_scaleConnection;
    QMetaObject::Connection m_screenDprConnection;
 
    // ── Shader source ────────────────────────────────────────────────
    QUrl m_shaderSource;
    QUrl m_vertexShaderUrl;
    QVariantMap m_shaderParams;
    QStringList m_shaderIncludePaths;
    QString m_paramPreamble; 
    QString m_entryPrologue; 
    QList<PhosphorShaders::EntryCandidate> m_entryCandidates; 
 
    // QPointer because the source item is owned by the QML scene, not
    // the ShaderEffect — a torn-down source must auto-null rather than
    // leave a dangling pointer that the per-frame textureProvider()
    // lookup would dereference.
    QPointer<QQuickItem> m_sourceItem;
    bool m_warnedSelfSourceItem = false;
 
    // ── Multipass ────────────────────────────────────────────────────
    QString m_bufferShaderPath;
    QStringList m_bufferShaderPaths;
    bool m_bufferFeedback = false;
    qreal m_bufferScale = 1.0;
    bool m_halfFloatBuffers = true;
    QString m_bufferWrap = QStringLiteral("clamp");
    QStringList m_bufferWraps;
    QString m_bufferFilter = QStringLiteral("linear");
    QStringList m_bufferFilters;
 
    // ── Custom parameters (8 vec4s, initialized to -1.0 "unset" sentinel) ──
    std::array<QVector4D, 8> m_customParams = {{
        QVector4D(-1.0f, -1.0f, -1.0f, -1.0f),
        QVector4D(-1.0f, -1.0f, -1.0f, -1.0f),
        QVector4D(-1.0f, -1.0f, -1.0f, -1.0f),
        QVector4D(-1.0f, -1.0f, -1.0f, -1.0f),
        QVector4D(-1.0f, -1.0f, -1.0f, -1.0f),
        QVector4D(-1.0f, -1.0f, -1.0f, -1.0f),
        QVector4D(-1.0f, -1.0f, -1.0f, -1.0f),
        QVector4D(-1.0f, -1.0f, -1.0f, -1.0f),
    }};
 
    // ── Custom colors (16 colors) ────────────────────────────────────
    std::array<QColor, 16> m_customColors = {{
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
        QColor::fromRgbF(0.0f, 0.0f, 0.0f, 0.0f),
    }};
 
    // ── Textures ─────────────────────────────────────────────────────
    QVector<float> m_audioSpectrum;
    std::array<QImage, kMaxUserTextureSlots> m_userTextureImages;
    // Spelled out rather than default-constructed, matching the node's array of
    // the same name. setShaderParams string-compares against these to decide
    // whether a wrap actually changed, so a null default made the first
    // assignment of the effective default ("clamp") look like a change.
    std::array<QString, kMaxUserTextureSlots> m_userTextureWraps = {QStringLiteral("clamp"), QStringLiteral("clamp"),
                                                                    QStringLiteral("clamp"), QStringLiteral("clamp")};
    std::array<QString, kMaxUserTextureSlots> m_userTexturePaths;
    // Filled with kDefaultUserTextureSvgSize by the constructor rather than a
    // brace list, so bumping kMaxUserTextureSlots cannot silently zero-fill the
    // new slots (qBound would then rasterise them at the 64 px floor).
    std::array<int, kMaxUserTextureSlots> m_userTextureSvgSizes{};
    bool m_userTexturesDirectlyOverridden = false;
    QImage m_wallpaperTexture;
    mutable QMutex m_wallpaperTextureMutex;
    bool m_useWallpaper = false;
    bool m_useDepthBuffer = false;
 
    // ── Uniform extension ────────────────────────────────────────────
    std::shared_ptr<PhosphorShaders::IUniformExtension> m_uniformExtension;
 
    // ── Status ───────────────────────────────────────────────────────
    // Atomic because setStatus is called from updatePaintNode (render
    // thread under threaded render loop) while onPlayingTick reads it on
    // the GUI thread. A torn read would only matter at status
    // transitions, but the gate at `m_status != Status::Ready` would
    // skip-or-tick spuriously around the boundary. Acquire/release
    // semantics suffice — there's no associated data we need to publish
    // alongside.
    std::atomic<Status> m_status{Status::Null};
    mutable QMutex m_errorLogMutex;
    QString m_errorLog;
 
    // ── Render node tracking ─────────────────────────────────────────
    std::shared_ptr<ShaderNodeLiveness> m_renderNodeLink;
    mutable std::mutex m_renderNodeMutex;
    std::shared_ptr<ShaderNodeLiveness> trackedNodeLink() const;
    void withTrackedNode(const std::function<void(ShaderNodeRhi*)>& fn) const;
    // QPointer defends against reparent/teardown storms where the window is
    // destroyed out from under us before windowChanged(nullptr) fires.
    QPointer<QQuickWindow> m_connectedWindow;
    struct SelfToken
    {
        std::mutex mutex;
        ShaderEffect* effect = nullptr;
    };
    std::shared_ptr<SelfToken> m_selfToken = std::make_shared<SelfToken>();
 
    void notifyOnGuiThread(void (ShaderEffect::*signal)());
 
    // ── Thread-safe dirty flags for main -> render thread sync ───────
    std::atomic<bool> m_shaderDirty{false};
};
 
} // namespace PhosphorRendering