Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorPointerShaders::PointerShaderEffect Struct Reference

Metadata for a single pointer shader effect. More...

#include <PhosphorPointer/PointerShaderEffect.h>

Classes

struct  ParameterInfo
 Declared parameter. More...
struct  TextureSlot
 User texture slot. More...

Public Types

enum class  Layer { Below , Above }
 Where the chain paints relative to the cursor. More...

Public Member Functions

bool isValid () const
double resolvedTrailWindow (const QVariantMap &params) const
 How far back this pack reads the trail, in seconds, for the given friendly parameter map: the trailWindowParam value when declared and present (falling back to that parameter's default), else trailWindowSeconds, else trailSeconds.
double resolvedReach (const QVariantMap &params) const
 The pack's reach in logical px for the given friendly parameter map: the reachParam value when declared and present (falling back to that parameter's default), else reach.

Static Public Member Functions

static QString layerToken (Layer layer)
 The metadata spelling of layer, the inverse of what fromJson parses.
static PointerShaderEffect fromJson (const QJsonObject &obj, const QString &sourceDir=QString(), bool isUser=false)
 Parse a pack's metadata.json root.

Public Attributes

QString id
 Stable identifier, the registry lookup key.
QString name
 Human-readable display name.
QString description
 One-line description for settings UI.
QString author
 Author attribution.
QString version
 Semantic version of this pack.
QString category
 Category for settings-UI grouping ("Trail", "Glow", "Click", ...).
QString fragmentShaderPath
 Fragment shader path.
QString vertexShaderPath
 Optional vertex shader path (same resolution rules).
QString sourceDir
 Resolved absolute directory containing this pack's assets.
bool isUserEffect = false
 Whether this pack was loaded from the user-local directory.
QString previewPath
 Preview image path (absolute once resolved). Empty when none.
Layer layer = Layer::Below
 Paint layer relative to the cursor. Default Below.
double reach = 64.0
 How far, in logical px, from any trail point or press point the pack may paint.
QString reachParam
 Optional name of an int/float parameter whose resolved value replaces reach (same idea as the surface family's paddingParam).
double trailSeconds = 1.0
 How long, in seconds, after the last motion or button event the pack still needs frames.
bool samplesTrail = true
 Whether any of the pack's stages actually reads uPointerTrail.
double trailWindowSeconds = 0.0
 How far back, in seconds, the pack's stages actually READ the trail.
QString trailWindowParam
 Optional name of an int/float parameter whose resolved value replaces trailWindowSeconds, the same shape as reachParam over reach.
bool needsCursor = false
 Bind the cursor sprite as uCursorSprite. Default false.
bool isMultipass = false
 Opt-in multipass.
QStringList bufferShaderPaths
 Buffer-pass shader paths (max kMaxBufferPasses), resolved like fragmentShaderPath.
bool bufferFeedback = false
 Last frame's buffer is sampleable as iChannel<N>.
double bufferScale = 1.0
 Render-target scale relative to the canvas, clamped to [kMinBufferScale, kMaxBufferScale] at parse time.
QList< ParameterInfo > parameters
QList< TextureSlot > textures
PhosphorShaders::PackPresets presets
 Pack-declared named parameter presets: preset name -> { paramId -> value }.

Static Public Attributes

static constexpr double kMinBufferScale = PhosphorShaders::kMinBufferScale
static constexpr double kMaxBufferScale = PhosphorShaders::kMaxBufferScale
static constexpr double kMinReach = 1.0
 Bounds on resolvedReach, in logical px.
static constexpr double kMaxReach = 1024.0

Detailed Description

Metadata for a single pointer shader effect.

A pointer effect decorates the mouse pointer (trail, halo, click ripple, sparks). It is a continuous decoration: the host ticks it every frame while the pointer has recent motion or a recent button event, for trailSeconds after the last one, then goes quiet.

Field names of ParameterInfo and TextureSlot mirror the surface and animation families so the settings app's ParameterEditor works unchanged.

Where this type deliberately does NOT mirror its siblings

No operator== and no toJson, unlike the animation and surface effects, and neither absence is a gap:

  • Nothing compares two pointer effects. Reload change-detection is file-stat based, through effectContentSignature, and the preset-change edge is decided by ShaderPreset::operator== inside ShaderPresetRegistry::setPackPresets — neither path needs effect equality.
  • Nothing serializes one. The animation effect's toJson resolves image parameters to ABSOLUTE paths while its fromJson re-reads them under AbsolutePathPolicy::Reject, an asymmetry a pointer pack cannot hit because it never makes the round trip.

Adding either for symmetry alone would be churn with no consumer. Written down because a three-way asymmetry across otherwise parallel families reads as an omission until someone checks, and this is the record of that check.

Member Enumeration Documentation

◆ Layer

Where the chain paints relative to the cursor.

Enumerator
Below 

The chain paints under KWin's cursor (or the hardware cursor plane) and never touches cursor visibility.

Above 

The host hides KWin's cursor while the pack is live on the output under the pointer and paints the cursor sprite itself after the chain.

Member Function Documentation

◆ fromJson()

PointerShaderEffect PhosphorPointerShaders::PointerShaderEffect::fromJson ( const QJsonObject & obj,
const QString & sourceDir = QString(),
bool isUser = false )
static

Parse a pack's metadata.json root.

When sourceDir is non-empty every shader / texture / preview path is resolved against it and confined to it (a .. traversal or symlink escape clears the path, which fail-closes the pack). When empty the paths are kept verbatim for an in-memory effect.

◆ isValid()

bool PhosphorPointerShaders::PointerShaderEffect::isValid ( ) const
inline

◆ layerToken()

QString PhosphorPointerShaders::PointerShaderEffect::layerToken ( Layer layer)
static

The metadata spelling of layer, the inverse of what fromJson parses.

A consumer that shows the value to a user or hands it to QML reads back the word the pack author wrote rather than an integer it would have to decode. Lives here, beside the enum and the parser, so the two spellings cannot drift apart and so no consumer has to keep a private copy of the mapping.

◆ resolvedReach()

double PhosphorPointerShaders::PointerShaderEffect::resolvedReach ( const QVariantMap & params) const
nodiscard

The pack's reach in logical px for the given friendly parameter map: the reachParam value when declared and present (falling back to that parameter's default), else reach.

Clamped to kMinReach..kMaxReach.

◆ resolvedTrailWindow()

double PhosphorPointerShaders::PointerShaderEffect::resolvedTrailWindow ( const QVariantMap & params) const
nodiscard

How far back this pack reads the trail, in seconds, for the given friendly parameter map: the trailWindowParam value when declared and present (falling back to that parameter's default), else trailWindowSeconds, else trailSeconds.

Clamped to trailSeconds, since a pack cannot read further back than the host keeps it alive, and to a non-negative value.

Returns 0 when samplesTrail is false: such a pack reads nothing and has no business setting the spacing at all.

Member Data Documentation

◆ author

QString PhosphorPointerShaders::PointerShaderEffect::author

Author attribution.

◆ bufferFeedback

bool PhosphorPointerShaders::PointerShaderEffect::bufferFeedback = false

Last frame's buffer is sampleable as iChannel<N>.

Requires isMultipass.

◆ bufferScale

double PhosphorPointerShaders::PointerShaderEffect::bufferScale = 1.0

Render-target scale relative to the canvas, clamped to [kMinBufferScale, kMaxBufferScale] at parse time.

◆ bufferShaderPaths

QStringList PhosphorPointerShaders::PointerShaderEffect::bufferShaderPaths

Buffer-pass shader paths (max kMaxBufferPasses), resolved like fragmentShaderPath.

◆ category

QString PhosphorPointerShaders::PointerShaderEffect::category

Category for settings-UI grouping ("Trail", "Glow", "Click", ...).

◆ description

QString PhosphorPointerShaders::PointerShaderEffect::description

One-line description for settings UI.

◆ fragmentShaderPath

QString PhosphorPointerShaders::PointerShaderEffect::fragmentShaderPath

Fragment shader path.

Relative to the pack dir as authored; resolved to an absolute path confined to sourceDir by fromJson when a source dir is supplied.

◆ id

QString PhosphorPointerShaders::PointerShaderEffect::id

Stable identifier, the registry lookup key.

◆ isMultipass

bool PhosphorPointerShaders::PointerShaderEffect::isMultipass = false

Opt-in multipass.

Normalised to false when no buffer shader survives resolution.

◆ isUserEffect

bool PhosphorPointerShaders::PointerShaderEffect::isUserEffect = false

Whether this pack was loaded from the user-local directory.

◆ kMaxBufferScale

double PhosphorPointerShaders::PointerShaderEffect::kMaxBufferScale = PhosphorShaders::kMaxBufferScale
staticconstexpr

◆ kMaxReach

double PhosphorPointerShaders::PointerShaderEffect::kMaxReach = 1024.0
staticconstexpr

◆ kMinBufferScale

double PhosphorPointerShaders::PointerShaderEffect::kMinBufferScale = PhosphorShaders::kMinBufferScale
staticconstexpr

◆ kMinReach

double PhosphorPointerShaders::PointerShaderEffect::kMinReach = 1.0
staticconstexpr

Bounds on resolvedReach, in logical px.

The floor exists because a reach of 0 is never what a pack means: the damage rect is the trail's bounding box inflated by the reach, so at 0 a single-sample burst (one event, no motion since) gives a rect with no area, the pass stays live for trailSeconds and paints nothing into it. One logical px is the smallest reach that still turns a point into a region.

◆ layer

Layer PhosphorPointerShaders::PointerShaderEffect::layer = Layer::Below

Paint layer relative to the cursor. Default Below.

◆ name

QString PhosphorPointerShaders::PointerShaderEffect::name

Human-readable display name.

◆ needsCursor

bool PhosphorPointerShaders::PointerShaderEffect::needsCursor = false

Bind the cursor sprite as uCursorSprite. Default false.

◆ parameters

QList<ParameterInfo> PhosphorPointerShaders::PointerShaderEffect::parameters

◆ presets

PhosphorShaders::PackPresets PhosphorPointerShaders::PointerShaderEffect::presets

Pack-declared named parameter presets: preset name -> { paramId -> value }.

Read-only tunings the pack author ships, offered in the same picker as the user's own presets and resolved through the shared preset registry. A preset names a subset of parameters; ids this effect does not declare are inert at resolve time, so parsing keeps them and the offline pack validator is where an author hears about a typo. That holds for a typo'd id specifically — the validator lints this already-parsed struct, so it can only report what parsing kept. A preset parsing drops outright (every value a refused texture path) is reported in the runtime log instead.

◆ previewPath

QString PhosphorPointerShaders::PointerShaderEffect::previewPath

Preview image path (absolute once resolved). Empty when none.

◆ reach

double PhosphorPointerShaders::PointerShaderEffect::reach = 64.0

How far, in logical px, from any trail point or press point the pack may paint.

The host derives the damage rect from it, so a pack that paints outside its reach gets clipped. Default 64.

◆ reachParam

QString PhosphorPointerShaders::PointerShaderEffect::reachParam

Optional name of an int/float parameter whose resolved value replaces reach (same idea as the surface family's paddingParam).

◆ samplesTrail

bool PhosphorPointerShaders::PointerShaderEffect::samplesTrail = true

Whether any of the pack's stages actually reads uPointerTrail.

The host spreads the history's fixed number of slots over the longest WINDOW in the chain (see resolvedTrailWindow), so one pack's answer sets the spacing for every pack sharing the ring. A click pack that draws only at the press point still needs a long trailSeconds to keep its animation running, and would otherwise coarsen the stroke of every trail pack beside it while reading no samples of its own. Declaring this false keeps such a pack out of the sampling decision without shortening the frames it gets.

Defaults TRUE, which is the conservative answer: a pack that says nothing is assumed to read the trail and still has a say in the spacing. The validator cross-checks the declaration against the stage sources, so it cannot quietly drift away from what the shaders do.

◆ sourceDir

QString PhosphorPointerShaders::PointerShaderEffect::sourceDir

Resolved absolute directory containing this pack's assets.

◆ textures

QList<TextureSlot> PhosphorPointerShaders::PointerShaderEffect::textures

◆ trailSeconds

double PhosphorPointerShaders::PointerShaderEffect::trailSeconds = 1.0

How long, in seconds, after the last motion or button event the pack still needs frames.

Default 1.0.

This is a LIVENESS figure and nothing else. It says how long the host keeps painting, not how the sampler spaces its slots — see samplesTrail for why the two have to stay apart.

◆ trailWindowParam

QString PhosphorPointerShaders::PointerShaderEffect::trailWindowParam

Optional name of an int/float parameter whose resolved value replaces trailWindowSeconds, the same shape as reachParam over reach.

This is the form most packs want, because how far back they read is usually a slider: a trail's lifetime, a comet's length. Following the resolved value means a user who shortens the tail gets a finer stroke for it, instead of paying the spacing for a length they are not using.

◆ trailWindowSeconds

double PhosphorPointerShaders::PointerShaderEffect::trailWindowSeconds = 0.0

How far back, in seconds, the pack's stages actually READ the trail.

Zero means "not declared", and the window falls back to trailSeconds.

samplesTrail says WHETHER a pack reads the ring; this says HOW MUCH of it. The two are different questions and the second one is what should set the spacing, because the host spreads a fixed number of slots across the window it is given. Taking that window from trailSeconds charges every pack for its LIVENESS: a pack that must keep drawing for two seconds after the pointer stops, but only ever looks at the last half second of path, was getting its stroke sampled four times more coarsely than it needed.

◆ version

QString PhosphorPointerShaders::PointerShaderEffect::version

Semantic version of this pack.

◆ vertexShaderPath

QString PhosphorPointerShaders::PointerShaderEffect::vertexShaderPath

Optional vertex shader path (same resolution rules).

Empty = the runtime's built-in fullscreen-quad vertex stage.


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