Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorSurfaceQuick::SurfaceShaderItem Class Reference

QQuickItem for rendering a per-window surface-decoration layer with a custom shader (border / rounded corners / focus tint / glow). More...

#include <PhosphorSurfaceQuick/SurfaceShaderItem.h>

Inheritance diagram for PhosphorSurfaceQuick::SurfaceShaderItem:
[legend]

Signals

void surfaceOpacityChanged ()
void surfaceScaleChanged ()
void surfaceFocusedChanged ()
void surfaceSizeChanged ()
void surfaceFrameTopLeftChanged ()
void surfaceFrameSizeChanged ()
void backdropScreenRectChanged ()
void backdropSurfaceRectChanged ()
Signals inherited from PhosphorRendering::ShaderEffect
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 bufferScalesChanged ()
void halfFloatBuffersChanged ()
void bufferWrapChanged ()
void bufferWrapsChanged ()
void bufferFilterChanged ()
void bufferFiltersChanged ()
void customParamsChanged ()
void customColorsChanged ()
void audioSpectrumChanged ()
void wallpaperTextureChanged ()
void useWallpaperChanged ()
void useDepthBufferChanged ()
void gridSubdivisionsChanged ()
void statusChanged ()
 Emitted when status() transitions.
void errorLogChanged ()
 Emitted from setError().

Public Member Functions

 SurfaceShaderItem (QQuickItem *parent=nullptr)
 Host fade factor for the decoration's output, 0..1.
 ~SurfaceShaderItem () override
qreal surfaceOpacity () const
void setSurfaceOpacity (qreal opacity)
qreal surfaceScale () const
void setSurfaceScale (qreal scale)
bool surfaceFocused () const
void setSurfaceFocused (bool focused)
QSizeF surfaceSize () const
void setSurfaceSize (const QSizeF &size)
QPointF surfaceFrameTopLeft () const
void setSurfaceFrameTopLeft (const QPointF &topLeft)
QSizeF surfaceFrameSize () const
void setSurfaceFrameSize (const QSizeF &size)
QRectF backdropScreenRect () const
void setBackdropScreenRect (const QRectF &rect)
QRectF backdropSurfaceRect () const
void setBackdropSurfaceRect (const QRectF &rect)
Public Member Functions inherited from PhosphorRendering::ShaderEffect
 ShaderEffect (QQuickItem *parent=nullptr)
 ~ShaderEffect () override
virtual void setUniformExtension (std::shared_ptr< PhosphorShaders::IUniformExtension > extension)
 Attach a uniform extension that appends custom data after BaseUniforms.
std::shared_ptr< PhosphorShaders::IUniformExtension > uniformExtension () const
qreal iTime () const
void setITime (qreal time)
qreal iTimeDelta () const
void setITimeDelta (qreal delta)
int iFrame () const
void setIFrame (int frame)
bool isPlaying () const
void setPlaying (bool playing)
bool isReversed () const
void setIsReversed (bool reverse)
 Direction signal forwarded to ShaderNodeRhi → BaseUniforms::iIsReversed.
QSizeF iResolution () const
void setIResolution (const QSizeF &resolution)
QPointF iMouse () const
void setIMouse (const QPointF &mouse)
QUrl shaderSource () const
void setShaderSource (const QUrl &source)
QUrl vertexShaderUrl () const
void setVertexShaderUrl (const QUrl &source)
QVariantMap shaderParams () const
virtual void setShaderParams (const QVariantMap &params)
 Push a parameter map onto the shader.
QQuickItem * sourceItem () const
 Live texture-provider source bound to SRB binding 11 (uTexture0).
void setSourceItem (QQuickItem *item)
QString bufferShaderPath () const
void setBufferShaderPath (const QString &path)
QStringList bufferShaderPaths () const
void setBufferShaderPaths (const QStringList &paths)
bool bufferFeedback () const
void setBufferFeedback (bool enable)
qreal bufferScale () const
void setBufferScale (qreal scale)
QVariantList bufferScales () const
 Per-pass render-target scales, positionally aligned with bufferShaderPaths (a pack's bufferScales), fed by surface packs alone today.
void setBufferScales (const QVariantList &scales)
bool halfFloatBuffers () const
void setHalfFloatBuffers (bool enable)
QString bufferWrap () const
void setBufferWrap (const QString &wrap)
QStringList bufferWraps () const
void setBufferWraps (const QStringList &wraps)
QString bufferFilter () const
void setBufferFilter (const QString &filter)
QStringList bufferFilters () const
void setBufferFilters (const QStringList &filters)
QVector4D customParams1 () const
void setCustomParams1 (const QVector4D &params)
QVector4D customParams2 () const
void setCustomParams2 (const QVector4D &params)
QVector4D customParams3 () const
void setCustomParams3 (const QVector4D &params)
QVector4D customParams4 () const
void setCustomParams4 (const QVector4D &params)
QVector4D customParams5 () const
void setCustomParams5 (const QVector4D &params)
QVector4D customParams6 () const
void setCustomParams6 (const QVector4D &params)
QVector4D customParams7 () const
void setCustomParams7 (const QVector4D &params)
QVector4D customParams8 () const
void setCustomParams8 (const QVector4D &params)
QColor customColor1 () const
void setCustomColor1 (const QColor &color)
QColor customColor2 () const
void setCustomColor2 (const QColor &color)
QColor customColor3 () const
void setCustomColor3 (const QColor &color)
QColor customColor4 () const
void setCustomColor4 (const QColor &color)
QColor customColor5 () const
void setCustomColor5 (const QColor &color)
QColor customColor6 () const
void setCustomColor6 (const QColor &color)
QColor customColor7 () const
void setCustomColor7 (const QColor &color)
QColor customColor8 () const
void setCustomColor8 (const QColor &color)
QColor customColor9 () const
void setCustomColor9 (const QColor &color)
QColor customColor10 () const
void setCustomColor10 (const QColor &color)
QColor customColor11 () const
void setCustomColor11 (const QColor &color)
QColor customColor12 () const
void setCustomColor12 (const QColor &color)
QColor customColor13 () const
void setCustomColor13 (const QColor &color)
QColor customColor14 () const
void setCustomColor14 (const QColor &color)
QColor customColor15 () const
void setCustomColor15 (const QColor &color)
QColor customColor16 () const
void setCustomColor16 (const QColor &color)
QVector4D customParamAt (int index) const
 Read a customParams slot by index.
void setCustomParamAt (int index, const QVector4D &params)
 Write a customParams slot by index.
QColor customColorAt (int index) const
 Read a customColor slot by index.
void setCustomColorAt (int index, const QColor &color)
 Write a customColor slot by index.
QVariant audioSpectrumVariant () const
void setAudioSpectrumVariant (const QVariant &spectrum)
void setAudioSpectrum (const QVector< float > &spectrum)
 Direct setter from C++ avoiding QVariantList round-trip.
void setUserTexture (int slot, const QImage &image)
 Set a user texture (slots 0-3, bindings 11-14) directly from a QImage, bypassing the path-driven loader.
void setUserTextureWrap (int slot, const QString &wrap)
 Set user texture wrap mode (slots 0-3).
QImage wallpaperTexture () const
QVariant wallpaperTextureVariant () const
 QML-facing form of wallpaperTexture, and the reason the Q_PROPERTY is a QVariant rather than a QImage.
void setWallpaperTexture (const QImage &image)
void setWallpaperTextureVariant (const QVariant &texture)
 Accepts a QImage, a null, an undefined, an absent key, or an invalid QVariant — a host with nothing behind its surface passes one of the latter four, which is the ordinary no-backdrop state rather than an error, and resolves to a null QImage without a warning.
bool useWallpaper () const
void setUseWallpaper (bool use)
bool useDepthBuffer () const
void setUseDepthBuffer (bool use)
int gridSubdivisions () const
void setGridSubdivisions (int subdivisions)
void setShaderIncludePaths (const QStringList &paths)
 Set directories to search for #include directives in shaders.
QStringList shaderIncludePaths () const
void setParamPreamble (const QString &preamble)
 Set the generated named-parameter preamble spliced after #version into the fragment source at load time, so authors read a parameter by name (p_speed) instead of a customParams[N].xyzw lane.
QString paramPreamble () const
void setEntryScaffold (const QString &prologue, const QList< PhosphorShaders::EntryCandidate > &candidates)
 Install the entry-point scaffold forwarded to the render node: when the fragment source defines no main(), the node prepends prologue and appends the generated main() of the first candidates entry function the source defines.
Status status () const
QString errorLog () const
void reloadShader ()
 Force reload of shader from source (callable from QML).
void releaseIdleGraphicsResources ()
 Release the render node's RHI resources (buffer FBOs, pipelines, uploaded textures) while the item sits idle, without destroying the node, the item, or the window.

Static Public Member Functions

static QStringList surfaceIncludePaths ()
 The canonical surface-shader include-path list, highest priority first: every XDG data dir's copy of the subdir the app set with PhosphorSurfaceShaders::setSurfacePackDataSubdir() (user first, system descending, via locateAll), each contributing its shared subdir then itself.
Static Public Member Functions inherited from PhosphorRendering::ShaderEffect
static QImage loadUserTextureFile (const QString &path, int svgMaxDim)
 Static helper that loads a user-texture file (PNG/JPG/etc.

Protected Member Functions

PhosphorRendering::ShaderNodeRhi * createShaderNode () override
 Create the render node with the surface UBO profile.
QSGNode * updatePaintNode (QSGNode *oldNode, UpdatePaintNodeData *data) override
 Create or update the scene graph node for rendering.
Protected Member Functions inherited from PhosphorRendering::ShaderEffect
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
 The factor the GPU-bound iResolution is multiplied by.
void syncBasePropertiesToNode (ShaderNodeRhi *node)
 Sync base properties (time, params, colors, audio, multipass, depth, wallpaper, user textures, uniform extension) to a render node.
bool consumeShaderDirty ()
 Atomically read-and-clear the shader-dirty flag.
void registerRenderNode (ShaderNodeRhi *node)
 Register the live render node for base-class teardown coverage.
void setError (const QString &error)
void setStatus (Status newStatus)

Additional Inherited Members

Public Types inherited from PhosphorRendering::ShaderEffect
enum class  Status { Null , Loading , Ready , Error }
 Auto-tick mode. More...
Static Public Attributes inherited from PhosphorRendering::ShaderEffect
static constexpr int kMaxSvgDimension = 2048
 Hard ceiling on the per-axis SVG rasterisation dimension applied by setShaderParams to the uTexture<N>_svgSize parameter.
static constexpr int kMinSvgDimension = 64
 Floor of the same clamp.
static constexpr qint64 kMaxSvgPixelBytes = 16LL * 1024 * 1024
 Hard cap on the byte budget for a single rasterised SVG (16 MiB — matches RGBA8 at kMaxSvgDimension × kMaxSvgDimension).
Static Protected Member Functions inherited from PhosphorRendering::ShaderEffect
static QString localShaderPath (const QUrl &url)
 URL to loader path; see the definition.

Detailed Description

QQuickItem for rendering a per-window surface-decoration layer with a custom shader (border / rounded corners / focus tint / glow).

The Qt Quick consumer for the surface shader-pack category, one of four beside overlays, animations and pointer, and sibling to PlasmaZones' ZoneShaderItem (overlay zone backgrounds). Like ZoneShaderItem it inherits from PhosphorRendering::ShaderEffect, which provides all base shader rendering: Shadertoy uniforms, custom params/colors, user textures, multipass, status, and the createShaderNode() / syncBasePropertiesToNode() seam.

Where ZoneShaderItem layers zone-array machinery on top of the base (a zone data snapshot, a labels texture at binding 1, zone counts in appField0/1, and an owned ZoneUniformExtension), SurfaceShaderItem layers NONE of that. A surface pack is a single-pass-or-multipass fragment shader composited over one live window surface; it has no zones, no per-zone glyph labels, and no consumer escape-hatch int slots. The ONLY thing that differs from the base render path is the UBO: the node is created with a PhosphorSurfaceShaders::SurfaceUniformProfile so it uploads the DISTINCT 672-byte surface UBO instead of the overlay one. Distinct, not smaller: both layouts static_assert to 672 bytes, and past the shared qt_Matrix / qt_Opacity lead (offsets 0 and 64, plus iTextureResolution at 592) the members do not line up. createShaderNode() supplies that profile to a stock PhosphorRendering::ShaderNodeRhi — there is no SurfaceShaderItem-specific node subclass.

The surface-state inputs below (scale / focus / geometry) map to the surface-only fields of PhosphorShaders::UboFrameState that SurfaceUniformProfile::fill() reads. They are the binding surface a QML surface host will drive. qml/SurfaceDecoration.qml in this library is that host and drives all of them per stage; the UboFrameState defaults (scale 1.0, unfocused, zero geometry) are the safe identity a host that binds nothing gets.

Registered as SurfaceShaderItem in the org.phosphor.surface QML module (QML_NAMED_ELEMENT below), the same module that ships SurfaceDecoration.qml, so any process that links the module's plugin resolves both together.

Constructor & Destructor Documentation

◆ SurfaceShaderItem()

PhosphorSurfaceQuick::SurfaceShaderItem::SurfaceShaderItem ( QQuickItem * parent = nullptr)
explicit

Host fade factor for the decoration's output, 0..1.

Multiplied with the scene graph's inherited opacity into the shader's qt_Opacity, which the generated surface entry point applies to the final premultiplied colour. Use this rather than QQuickItem::opacity for a fade the host drives: a stage that a hide-source ShaderEffectSource captures (every decoration stage but the last, and the last one too while SurfaceAnimator runs a shader leg) loses its own item opacity in the capture, while this factor is baked into what the capture samples. Logical→device pixel scale for the decorated surface. Maps to UboFrameState::surfaceScale (the shader's uSurfaceScale). Whether the decorated window is focused. Maps to UboFrameState::surfaceFocused (1.0 focused / 0.0 not) — the shader mixes active vs inactive appearance on it. Decorated surface size in device px. Maps to UboFrameState::surfaceSize. Frame (content) top-left in device px. Maps to UboFrameState::surfaceFrameTopLeft. Frame (content) size in device px. Maps to UboFrameState::surfaceFrameSize. The screen area the bound wallpaper covers, in the same space as backdropSurfaceRect. Empty disables backdrop placement. This surface's rect within backdropScreenRect. Empty disables backdrop placement, which falls back to sampling the wallpaper whole.

◆ ~SurfaceShaderItem()

PhosphorSurfaceQuick::SurfaceShaderItem::~SurfaceShaderItem ( )
override

Member Function Documentation

◆ backdropScreenRect()

QRectF PhosphorSurfaceQuick::SurfaceShaderItem::backdropScreenRect ( ) const
inline

◆ backdropScreenRectChanged

void PhosphorSurfaceQuick::SurfaceShaderItem::backdropScreenRectChanged ( )
signal

◆ backdropSurfaceRect()

QRectF PhosphorSurfaceQuick::SurfaceShaderItem::backdropSurfaceRect ( ) const
inline

◆ backdropSurfaceRectChanged

void PhosphorSurfaceQuick::SurfaceShaderItem::backdropSurfaceRectChanged ( )
signal

◆ createShaderNode()

PhosphorRendering::ShaderNodeRhi * PhosphorSurfaceQuick::SurfaceShaderItem::createShaderNode ( )
overrideprotectedvirtual

Create the render node with the surface UBO profile.

Returns a stock PhosphorRendering::ShaderNodeRhi constructed with a PhosphorSurfaceShaders::SurfaceUniformProfile, so the shared render engine uploads the 672-byte surface UBO. No node subclass — the profile is the only difference from the base/overlay path.

Reimplemented from PhosphorRendering::ShaderEffect.

◆ setBackdropScreenRect()

void PhosphorSurfaceQuick::SurfaceShaderItem::setBackdropScreenRect ( const QRectF & rect)

◆ setBackdropSurfaceRect()

void PhosphorSurfaceQuick::SurfaceShaderItem::setBackdropSurfaceRect ( const QRectF & rect)

◆ setSurfaceFocused()

void PhosphorSurfaceQuick::SurfaceShaderItem::setSurfaceFocused ( bool focused)

◆ setSurfaceFrameSize()

void PhosphorSurfaceQuick::SurfaceShaderItem::setSurfaceFrameSize ( const QSizeF & size)

◆ setSurfaceFrameTopLeft()

void PhosphorSurfaceQuick::SurfaceShaderItem::setSurfaceFrameTopLeft ( const QPointF & topLeft)

◆ setSurfaceOpacity()

void PhosphorSurfaceQuick::SurfaceShaderItem::setSurfaceOpacity ( qreal opacity)

◆ setSurfaceScale()

void PhosphorSurfaceQuick::SurfaceShaderItem::setSurfaceScale ( qreal scale)

◆ setSurfaceSize()

void PhosphorSurfaceQuick::SurfaceShaderItem::setSurfaceSize ( const QSizeF & size)

◆ surfaceFocused()

bool PhosphorSurfaceQuick::SurfaceShaderItem::surfaceFocused ( ) const
inline

◆ surfaceFocusedChanged

void PhosphorSurfaceQuick::SurfaceShaderItem::surfaceFocusedChanged ( )
signal

◆ surfaceFrameSize()

QSizeF PhosphorSurfaceQuick::SurfaceShaderItem::surfaceFrameSize ( ) const
inline

◆ surfaceFrameSizeChanged

void PhosphorSurfaceQuick::SurfaceShaderItem::surfaceFrameSizeChanged ( )
signal

◆ surfaceFrameTopLeft()

QPointF PhosphorSurfaceQuick::SurfaceShaderItem::surfaceFrameTopLeft ( ) const
inline

◆ surfaceFrameTopLeftChanged

void PhosphorSurfaceQuick::SurfaceShaderItem::surfaceFrameTopLeftChanged ( )
signal

◆ surfaceIncludePaths()

QStringList PhosphorSurfaceQuick::SurfaceShaderItem::surfaceIncludePaths ( )
static

The canonical surface-shader include-path list, highest priority first: every XDG data dir's copy of the subdir the app set with PhosphorSurfaceShaders::setSurfacePackDataSubdir() (user first, system descending, via locateAll), each contributing its shared subdir then itself.

Empty while the app has set no subdir. Shared by this item's constructor AND an app's warm-bake (PlasmaZones' daemon) so the bake-cache key the warm compile writes is guaranteed to be the one the first live paint looks up — the two paths cannot silently diverge.

The LIVE node is handed one more entry than this returns: updatePaintNode prepends the pack's own sibling shared dir (withPackSiblingShared). That is a no-op for every XDG-installed pack, which is all the warm bake sees, and surfaceshaderitem.cpp documents why at that call.

◆ surfaceOpacity()

qreal PhosphorSurfaceQuick::SurfaceShaderItem::surfaceOpacity ( ) const
inline

◆ surfaceOpacityChanged

void PhosphorSurfaceQuick::SurfaceShaderItem::surfaceOpacityChanged ( )
signal

◆ surfaceScale()

qreal PhosphorSurfaceQuick::SurfaceShaderItem::surfaceScale ( ) const
inline

◆ surfaceScaleChanged

void PhosphorSurfaceQuick::SurfaceShaderItem::surfaceScaleChanged ( )
signal

◆ surfaceSize()

QSizeF PhosphorSurfaceQuick::SurfaceShaderItem::surfaceSize ( ) const
inline

◆ surfaceSizeChanged

void PhosphorSurfaceQuick::SurfaceShaderItem::surfaceSizeChanged ( )
signal

◆ updatePaintNode()

QSGNode * PhosphorSurfaceQuick::SurfaceShaderItem::updatePaintNode ( QSGNode * oldNode,
UpdatePaintNodeData * data )
overrideprotected

Create or update the scene graph node for rendering.

Mirrors ZoneShaderItem's load semantics (vertex shader resolved + loaded before the fragment, include paths + param preamble pushed) minus all the zone-specific sync. A fragment entry-point scaffold IS installed, so a surface pack may define only vec4 pSurface(vec2 uv) and omit main() (a traditional main() pack passes through unchanged). The vertex stage has no scaffold and relies on a shared surface.vert for its main().


The documentation for this class was generated from the following file: