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 ¶ms) 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 ¶ms) 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 |
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.
No operator== and no toJson, unlike the animation and surface effects, and neither absence is a gap:
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.
|
strong |
Where the chain paints relative to the cursor.
|
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.
|
inline |
|
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.
|
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.
|
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.
| QString PhosphorPointerShaders::PointerShaderEffect::author |
Author attribution.
| bool PhosphorPointerShaders::PointerShaderEffect::bufferFeedback = false |
Last frame's buffer is sampleable as iChannel<N>.
Requires isMultipass.
| double PhosphorPointerShaders::PointerShaderEffect::bufferScale = 1.0 |
Render-target scale relative to the canvas, clamped to [kMinBufferScale, kMaxBufferScale] at parse time.
| QStringList PhosphorPointerShaders::PointerShaderEffect::bufferShaderPaths |
Buffer-pass shader paths (max kMaxBufferPasses), resolved like fragmentShaderPath.
| QString PhosphorPointerShaders::PointerShaderEffect::category |
Category for settings-UI grouping ("Trail", "Glow", "Click", ...).
| QString PhosphorPointerShaders::PointerShaderEffect::description |
One-line description for settings UI.
| QString PhosphorPointerShaders::PointerShaderEffect::fragmentShaderPath |
| QString PhosphorPointerShaders::PointerShaderEffect::id |
Stable identifier, the registry lookup key.
| bool PhosphorPointerShaders::PointerShaderEffect::isMultipass = false |
Opt-in multipass.
Normalised to false when no buffer shader survives resolution.
| bool PhosphorPointerShaders::PointerShaderEffect::isUserEffect = false |
Whether this pack was loaded from the user-local directory.
|
staticconstexpr |
|
staticconstexpr |
|
staticconstexpr |
|
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 PhosphorPointerShaders::PointerShaderEffect::layer = Layer::Below |
Paint layer relative to the cursor. Default Below.
| QString PhosphorPointerShaders::PointerShaderEffect::name |
Human-readable display name.
| bool PhosphorPointerShaders::PointerShaderEffect::needsCursor = false |
Bind the cursor sprite as uCursorSprite. Default false.
| QList<ParameterInfo> PhosphorPointerShaders::PointerShaderEffect::parameters |
| 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.
| QString PhosphorPointerShaders::PointerShaderEffect::previewPath |
Preview image path (absolute once resolved). Empty when none.
| 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.
| QString PhosphorPointerShaders::PointerShaderEffect::reachParam |
Optional name of an int/float parameter whose resolved value replaces reach (same idea as the surface family's paddingParam).
| 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.
| QString PhosphorPointerShaders::PointerShaderEffect::sourceDir |
Resolved absolute directory containing this pack's assets.
| QList<TextureSlot> PhosphorPointerShaders::PointerShaderEffect::textures |
| 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.
| 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.
| 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.
| QString PhosphorPointerShaders::PointerShaderEffect::version |
Semantic version of this pack.
| QString PhosphorPointerShaders::PointerShaderEffect::vertexShaderPath |
Optional vertex shader path (same resolution rules).
Empty = the runtime's built-in fullscreen-quad vertex stage.