ShaderNodeRhi.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/BaseUniforms.h>
#include <PhosphorShaders/IUboProfile.h>
#include <PhosphorShaders/IUniformExtension.h>
#include <PhosphorShaders/ShaderEntryPoint.h>
 
#include <QColor>
#include <QImage>
#include <QMatrix4x4>
#include <QPointF>
#include <QPointer>
#include <QSizeF>
#include <QQuickItem>
#include <QSGRenderNode>
#include <QSGTextureProvider>
#include <QString>
#include <QStringList>
#include <QVector>
#include <QVector4D>
 
#include <array>
#include <atomic>
#include <map>
#include <memory>
#include <mutex>
#include <optional>
 
#include <rhi/qrhi.h>
 
namespace PhosphorRendering {
 
// Forward declare constants used in member declarations.
// `constexpr int` at namespace scope in a header is implicitly `inline` since
// C++17 — no `static` needed (and matches the existing `constexpr int` style
// used by kFirstFreeConsumerBinding / kMaxConsumerBinding below).
constexpr int kMaxBufferPasses = 4;
constexpr int kMaxUserTextures = 4;
constexpr int kMaxCustomParams = 8;
constexpr int kMaxCustomColors = 16;
 
// ── Consumer binding range (for setExtraBinding) ────────────────────────
// Library-managed bindings: 0 (UBO), 2-5 (multipass buffers), 6 (audio),
// 7-10 (user textures), 11 (wallpaper), 12 (depth). Assigning any of those
// via setExtraBinding() would duplicate SRB entries and is rejected at
// runtime. Binding 1 is the one "free-in-the-gap" slot; 13..31 are free as
// well.
//
// Phosphor uses binding 1 for its zone-labels texture by convention.
// Other consumers that interoperate with Phosphor should pick from
// 13..kMaxConsumerBinding to avoid a per-instance overwrite.
constexpr int kFirstFreeConsumerBinding = 1; 
constexpr int kMaxConsumerBinding = 31;
constexpr int kReservedBindingRangeStart = 2; 
constexpr int kReservedBindingRangeEnd = 12; 
 
constexpr int kUserTextureBaseBinding = 7;
 
constexpr bool isConsumerBinding(int binding) noexcept
{
    return binding >= kFirstFreeConsumerBinding && binding <= kMaxConsumerBinding
        && (binding < kReservedBindingRangeStart || binding > kReservedBindingRangeEnd);
}
 
class PHOSPHORRENDERING_EXPORT ShaderNodeRhi : public QSGRenderNode
{
public:
    explicit ShaderNodeRhi(QQuickItem* item, std::unique_ptr<PhosphorShaders::IUboProfile> profile = nullptr);
    ~ShaderNodeRhi() override;
 
    void invalidateItem();
 
    bool hasValidItem() const
    {
        return m_itemValid.load(std::memory_order_acquire);
    }
 
    const std::shared_ptr<ShaderNodeLiveness>& liveness() const
    {
        return m_liveness;
    }
 
    // QSGRenderNode
    QSGRenderNode::StateFlags changedStates() const override;
    QSGRenderNode::RenderingFlags flags() const override;
    QRectF rect() const override;
    void prepare() override;
    void render(const RenderState* state) override;
    void releaseResources() override;
    void preprocess() override;
 
    // ── Uniform Extension ──────────────────────────────────────────────
    void setUniformExtension(std::shared_ptr<PhosphorShaders::IUniformExtension> extension);
    std::shared_ptr<PhosphorShaders::IUniformExtension> uniformExtension() const
    {
        return m_uniformExtension;
    }
 
    // ── Timing ─────────────────────────────────────────────────────────
    void setTime(double time);
    void setTimeDelta(float delta);
    void setFrame(int frame);
    void setResolution(float width, float height);
    void setMousePosition(const QPointF& pos);
    void setIsReversed(bool reverse);
 
    // ── Custom Parameters (indexed API) ────────────────────────────────
    void setCustomParams(int index, const QVector4D& params);
    void setCustomColor(int index, const QColor& color);
 
    // ── Surface-only state ─────────────────────────────────────────────
    void setSurfaceOpacity(float opacity);
    void setSurfaceScale(float scale);
    void setSurfaceFocused(bool focused);
    void setSurfaceSize(float width, float height);
    void setBackdropRect(float x, float y, float w, float h);
    void setSurfaceFrameTopLeft(float x, float y);
    void setSurfaceFrameSize(float width, float height);
 
    // ── App Fields (consumer escape hatch in BaseUniforms) ─────────────
    void setAppField0(int value);
    void setAppField1(int value);
 
    // ── Extra Bindings (consumer-managed texture bindings) ─────────────
    bool setExtraBinding(int binding, QRhiTexture* texture, QRhiSampler* sampler);
    bool removeExtraBinding(int binding);
 
    // ── Textures ───────────────────────────────────────────────────────
    void setAudioSpectrum(const QVector<float>& spectrum);
    void setUserTexture(int slot, const QImage& image);
    void setUserTextureWrap(int slot, const QString& wrap);
    void setWallpaperTexture(const QImage& image);
    void setUseWallpaper(bool use);
    void setUseDepthBuffer(bool use);
 
    void setSourceTextureProvider(QSGTextureProvider* provider);
    QSGTextureProvider* sourceTextureProvider() const
    {
        return m_sourceTextureProvider.data();
    }
 
    // ── Multi-pass Buffers ─────────────────────────────────────────────
    void setBufferShaderPath(const QString& path);
    void setBufferShaderPaths(const QStringList& paths);
    void setBufferFeedback(bool enable);
    void setBufferScale(qreal scale);
    void setHalfFloatBuffers(bool enable);
    void setBufferWrap(const QString& wrap);
    void setBufferWraps(const QStringList& wraps);
    void setBufferFilter(const QString& filter);
    void setBufferFilters(const QStringList& filters);
 
    // ── Shader Loading ─────────────────────────────────────────────────
    bool loadVertexShader(const QString& path);
    bool loadFragmentShader(const QString& path);
    void setVertexShaderSource(const QString& source);
    void setFragmentShaderSource(const QString& source);
    bool isShaderReady() const;
    QString shaderError() const;
    void invalidateShader();
    void invalidateUniforms();
 
    // ── Include Paths ──────────────────────────────────────────────────
    void setShaderIncludePaths(const QStringList& paths);
 
    // ── Parameter preamble (T1.1: generated `#define p_<id> ...`) ─────
    void setParamPreamble(const QString& preamble);
 
    // ── Entry-point scaffold (T1.4: harness-generated `main()`) ────────
    void setEntryScaffold(const QString& prologue, const QList<PhosphorShaders::EntryCandidate>& candidates);
 
    static QString normalizeWrapMode(const QString& wrap);
    static QString normalizeFilterMode(const QString& filter);
 
    static QRhiSampler::AddressMode wrapModeToRhiAddress(const QString& wrap);
 
protected:
    QRhi* safeRhi() const;
 
    void retractLiveness() noexcept;
 
private:
    bool ensurePipeline();
    bool ensureBufferPipeline();
    bool ensureBufferTarget();
    bool ensureDummyChannelResources(QRhi* rhi);
    bool ensureBufferSampler(QRhi* rhi, int index);
    void resetBufferTargets();
    void syncBaseUniforms(QRhi* rhi);
    bool renderingIntoTexture() const;
    void uploadDirtyTextures(QRhi* rhi, QRhiCommandBuffer* cb);
    void uploadExtensionToUbo(QRhiResourceUpdateBatch* batch);
    void releaseRhiResources();
    void appendUserTextureBindings(QVector<QRhiShaderResourceBinding>& bindings) const;
    bool wallpaperBindingLive() const
    {
        return m_useWallpaper && m_wallpaperTexture && m_wallpaperSampler && !m_wallpaperImage.isNull();
    }
    void appendWallpaperBinding(QVector<QRhiShaderResourceBinding>& bindings) const;
    enum class DepthAccess {
        Sampled, 
        WrittenThisPass 
    };
    void appendDepthBinding(QVector<QRhiShaderResourceBinding>& bindings, DepthAccess access) const;
    void appendExtraBindings(QVector<QRhiShaderResourceBinding>& bindings) const;
    void appendAudioBinding(QVector<QRhiShaderResourceBinding>& bindings) const;
    void appendUboAndExtraBindings(QVector<QRhiShaderResourceBinding>& bindings) const;
    void appendCommonTrailerBindings(QVector<QRhiShaderResourceBinding>& bindings, DepthAccess depthAccess) const;
    void resetAllBindingsAndPipelines();
    void bakeBufferShaders();
    QString loadAndExpandShader(const QString& path, QString* outError);
    QString loadAndExpandShaderTracked(const QString& path, QStringList* outIncludedPaths, QString* outError);
 
    QQuickItem* m_item = nullptr;
    std::atomic<bool> m_itemValid{true};
 
    // Lock-ordering invariant: MUST NOT block on the GUI thread while holding
    // m_itemMutex (avoids deadlock during ~ShaderEffect → invalidateItem path).
    mutable std::mutex m_itemMutex;
 
    std::shared_ptr<ShaderNodeLiveness> m_liveness = std::make_shared<ShaderNodeLiveness>();
 
    // ── Uniform Extension ──────────────────────────────────────────────
    std::shared_ptr<PhosphorShaders::IUniformExtension> m_uniformExtension;
    QByteArray m_extensionStaging;
 
    // ── Shader Include Paths ───────────────────────────────────────────
    QStringList m_shaderIncludePaths;
 
    // ── Parameter preamble (generated `#define p_<id> ...`) ───────────
    QString m_paramPreamble;
 
    // ── Entry-point scaffold (T1.4) ────────────────────────────────────
    QString m_entryPrologue;
    QList<PhosphorShaders::EntryCandidate> m_entryCandidates;
 
    // ── RHI Core Resources ─────────────────────────────────────────────
    std::unique_ptr<QRhiBuffer> m_vbo;
    std::unique_ptr<QRhiBuffer> m_ubo;
    std::unique_ptr<QRhiShaderResourceBindings> m_srb;
    std::unique_ptr<QRhiGraphicsPipeline> m_pipeline;
    QShader m_vertexShader;
    QShader m_fragmentShader;
    QVector<quint32> m_renderPassFormat;
 
    // ── Multi-pass: buffer pass(es) (optional). Up to 4 paths. ────────
    QString m_bufferPath;
    QStringList m_bufferPaths;
    bool m_bufferFeedback = false;
    qreal m_bufferScale = 1.0;
    // Buffer-pass texel format. Half-float by default so packs that store HDR
    // radiance, signed data, or feedback accumulators keep full precision; a
    // pack whose buffers hold plain clamped [0,1] colour opts down to RGBA8
    // via metadata to halve buffer bandwidth (which is what integrated GPUs
    // are starved of).
    bool m_halfFloatBuffers = true;
    std::array<QString, kMaxBufferPasses> m_bufferWraps = {QStringLiteral("clamp"), QStringLiteral("clamp"),
                                                           QStringLiteral("clamp"), QStringLiteral("clamp")};
    QString m_bufferWrapDefault = QStringLiteral("clamp");
    std::array<QString, kMaxBufferPasses> m_bufferFilters = {QStringLiteral("linear"), QStringLiteral("linear"),
                                                             QStringLiteral("linear"), QStringLiteral("linear")};
    QString m_bufferFilterDefault = QStringLiteral("linear");
    QString m_bufferFragmentShaderSource;
    QShader m_bufferFragmentShader;
    bool m_bufferShaderReady = false;
    bool m_bufferShaderDirty = true;
    int m_bufferShaderRetries = 0;
    std::unique_ptr<QRhiTexture> m_bufferTexture;
    std::unique_ptr<QRhiRenderPassDescriptor> m_bufferRenderPassDescriptor;
    std::unique_ptr<QRhiTextureRenderTarget> m_bufferRenderTarget;
    std::array<std::unique_ptr<QRhiSampler>, kMaxBufferPasses> m_bufferSamplers;
    std::unique_ptr<QRhiShaderResourceBindings> m_bufferSrb;
    std::unique_ptr<QRhiGraphicsPipeline> m_bufferPipeline;
    QVector<quint32> m_bufferRenderPassFormat;
    // Ping-pong (bufferFeedback): second texture/RT/SRB for buffer pass; image pass has two SRBs
    std::unique_ptr<QRhiTexture> m_bufferTextureB;
    std::unique_ptr<QRhiRenderPassDescriptor> m_bufferRenderPassDescriptorB;
    std::unique_ptr<QRhiTextureRenderTarget> m_bufferRenderTargetB;
    std::unique_ptr<QRhiShaderResourceBindings> m_bufferSrbB;
    std::unique_ptr<QRhiShaderResourceBindings> m_srbB; // image pass SRB with binding 2 = texture B
    bool m_bufferFeedbackCleared = false;
 
    // Multi-buffer mode (2-4 passes): per-pass resources
    std::array<std::unique_ptr<QRhiTexture>, kMaxBufferPasses> m_multiBufferTextures = {};
    std::array<std::unique_ptr<QRhiTextureRenderTarget>, kMaxBufferPasses> m_multiBufferRenderTargets = {};
    std::array<std::unique_ptr<QRhiRenderPassDescriptor>, kMaxBufferPasses> m_multiBufferRenderPassDescriptors = {};
    std::array<std::unique_ptr<QRhiGraphicsPipeline>, kMaxBufferPasses> m_multiBufferPipelines = {};
    std::array<std::unique_ptr<QRhiShaderResourceBindings>, kMaxBufferPasses> m_multiBufferSrbs = {};
    std::array<QShader, kMaxBufferPasses> m_multiBufferFragmentShaders = {};
    std::array<QString, kMaxBufferPasses> m_multiBufferFragmentShaderSources = {};
    bool m_multiBufferShadersReady = false;
    bool m_multiBufferShaderDirty = true;
    int m_multiBufferShaderRetries = 0;
    // Dummy 1x1 texture for the multipass channel-0 buffer slot (SRB
    // binding 2, GLSL `iChannel0`) when multipass is configured but the
    // backing buffer hasn't been created yet. Distinct from the user-
    // texture slot 0 (SRB binding 7, GLSL `uTexture0`) — the iChannel0
    // name here refers to the buffer-channel binding, not the renamed
    // user-texture.
    std::unique_ptr<QRhiTexture> m_dummyChannelTexture;
    std::unique_ptr<QRhiSampler> m_dummyChannelSampler;
    bool m_dummyChannelTextureNeedsUpload = false;
 
    // ── Shader Sources ─────────────────────────────────────────────────
    QString m_vertexShaderSource;
    QString m_fragmentShaderSource;
    QString m_vertexPath;
    QString m_fragmentPath;
    qint64 m_vertexMtime = 0;
    qint64 m_fragmentMtime = 0;
    QStringList m_vertexIncludedPaths;
    QStringList m_fragmentIncludedPaths;
    QString m_shaderError;
    bool m_initialized = false;
    bool m_vboUploaded = false;
    bool m_shaderReady = false;
    bool m_shaderDirty = true;
    bool m_uniformsDirty = true;
    bool m_timeDirty = true;
    bool m_timeHiDirty = true; 
    bool m_sceneDataDirty = true; 
    bool m_appFieldsDirty = false; 
    bool m_didFullUploadOnce = false;
    std::optional<bool> m_lastTargetWasTexture;
 
    // ── UBO Profile (pluggable uniform buffer concern) ─────────────────
    std::unique_ptr<PhosphorShaders::IUboProfile> m_uboProfile;
 
    int m_appField0 = 0;
    int m_appField1 = 0;
 
    // Full-precision elapsed seconds (double). Split into iTime (wrapped lo) +
    // iTimeHi (wrap offset) at upload.
    double m_time = 0.0;
    float m_timeDelta = 0.0f;
    int m_frame = 0;
    bool m_isReversed = false;
    float m_timeHi = 0.0f; // Cached iTimeHi for wrap-offset change detection
    float m_width = 0.0f;
    float m_height = 0.0f;
    std::atomic<float> m_cachedWidth{0.0f};
    std::atomic<float> m_cachedHeight{0.0f};
    QPointF m_mousePosition;
 
    // ── Surface-only state (consumed by a SurfaceUniformProfile; ignored by
    //    the BaseUniformProfile). Defaults mirror UboFrameState so the overlay
    //    path is byte-identical whether or not these are ever touched. ──
    float m_surfaceOpacity = 1.0f;
    float m_surfaceScale = 1.0f;
    bool m_surfaceFocused = false;
    float m_surfaceSize[2] = {0.0f, 0.0f};
    float m_backdropRect[4] = {0.0f, 0.0f, 1.0f, 1.0f};
    float m_surfaceFrameTopLeft[2] = {0.0f, 0.0f};
    float m_surfaceFrameSize[2] = {0.0f, 0.0f};
 
    // ── Custom Parameters (indexed) ────────────────────────────────────
    std::array<QVector4D, kMaxCustomParams> m_customParams;
    std::array<QColor, kMaxCustomColors> m_customColors;
 
    // ── Extra Bindings (consumer-managed) ──────────────────────────────
    struct ExtraBinding
    {
        QRhiTexture* texture = nullptr;
        QRhiSampler* sampler = nullptr;
    };
    // std::map (ordered) so SRB construction produces a deterministic binding
    // order regardless of insertion/erasure history. An unordered_map can
    // produce different iteration orders after erasures, which Qt RHI
    // backends may hash into different pipeline layout signatures.
    std::map<int, ExtraBinding> m_extraBindings;
    bool m_extraBindingsDirty = false;
 
    // ── 1x1 Transparent Fallback ───────────────────────────────────────
    QImage m_transparentFallbackImage;
 
    // ── Audio spectrum texture (binding 6) ─────────────────────────────
    QVector<float> m_audioSpectrum;
    std::unique_ptr<QRhiTexture> m_audioSpectrumTexture;
    std::unique_ptr<QRhiSampler> m_audioSpectrumSampler;
    bool m_audioSpectrumDirty = false;
 
    // ── User texture slots (bindings 7-10) ─────────────────────────────
    std::array<QImage, kMaxUserTextures> m_userTextureImages;
    std::array<std::unique_ptr<QRhiTexture>, kMaxUserTextures> m_userTextures;
    std::array<std::unique_ptr<QRhiSampler>, kMaxUserTextures> m_userTextureSamplers;
    // Spelled out rather than default-constructed, matching m_bufferWraps
    // above. The only reader normalises an unknown token to ClampToEdge, so a
    // null QString behaves identically today, but leaving the two arrays with
    // different defaults means a future reader that string-compares gets a
    // different answer for a user texture than for a buffer.
    std::array<QString, kMaxUserTextures> m_userTextureWraps = {QStringLiteral("clamp"), QStringLiteral("clamp"),
                                                                QStringLiteral("clamp"), QStringLiteral("clamp")};
    std::array<bool, kMaxUserTextures> m_userTextureDirty = {};
 
    // ── Source texture override (slot 0 / binding 7) ───────────────────
    // Texture-provider source — typically a `QQuickItem::textureProvider()`
    // for a layer-enabled item. When non-null this supersedes
    // m_userTextures[0] in the SRB build, so the shader's uTexture0
    // samples a live QML render instead of a static QImage upload.
    // m_sourceSampler is owned here (not a user-texture sampler) so we
    // can keep slot 0's user-texture sampler available for callers that
    // mix the two paths. m_lastSourceRhiTexture caches the QRhiTexture*
    // we last bound; when the provider's underlying texture changes
    // (FBO recreation on resize / device-loss) we drop the SRB so the
    // next rebuild picks up the new pointer.
    QPointer<QSGTextureProvider> m_sourceTextureProvider;
    QMetaObject::Connection m_sourceTextureChangedConn;
    std::unique_ptr<QRhiSampler> m_sourceSampler;
    QRhiTexture* m_lastSourceRhiTexture = nullptr;
    bool m_sourceSamplerFailed = false;
    bool m_warnedForeignRhi = false;
    mutable bool m_warnedWallpaperBindingOmitted = false;
    bool m_warnedAudioTruncated = false;
    bool m_warnedAudioCreateFailed = false;
    std::unique_ptr<QRhiTexture> m_transparentFallbackTexture;
    bool m_transparentFallbackTextureNeedsUpload = false;
 
    // ── Depth buffer (binding 12) ──────────────────────────────────────
    bool m_useDepthBuffer = false;
    bool m_depthMultiBufferWarned = false;
    std::unique_ptr<QRhiTexture> m_depthTexture;
    std::unique_ptr<QRhiSampler> m_depthSampler;
 
    // ── Desktop wallpaper texture (binding 11) ─────────────────────────
    bool m_useWallpaper = false;
    QImage m_wallpaperImage;
    std::unique_ptr<QRhiTexture> m_wallpaperTexture;
    std::unique_ptr<QRhiSampler> m_wallpaperSampler;
    bool m_wallpaperDirty = false;
};
 
struct WarmShaderBakeResult
{
    bool success = false;
    QString errorMessage;
};
 
PHOSPHORRENDERING_EXPORT WarmShaderBakeResult warmShaderBakeCacheForPaths(
    const QString& vertexPath, const QString& fragmentPath, const QStringList& includePaths = {},
    const QString& paramPreamble = {}, const QString& entryPrologue = {},
    const QList<PhosphorShaders::EntryCandidate>& entryCandidates = {});
 
} // namespace PhosphorRendering