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

Cross-runtime named-uniform contract for pointer shaders. More...

Functions

bool isValidWrapToken (const QString &wrap)
 The accepted texture wrap vocabulary (forwarder onto the canonical predicate in <PhosphorShaders/CustomParamsKey.h>).
QString paramKey (int vec, char comp)
 Format a customParams slot key (customParams<N>_<x|y|z|w>).
QString paramKey (int slot)
 Flat-slot overload: slot is 0..31 across the 8 vec4 slots.
QString colorKey (int slot)
 Format a customColor<N> slot key (1-based on the wire).

Variables

constexpr const char * kITime = "iTime"
 float iTime — seconds since the current burst of pointer activity began.
constexpr const char * kIResolution = "iResolution"
 vec2 iResolution — canvas size in device px.
constexpr const char * kIMouse = "iMouse"
 vec4 iMouse — .xy pointer position in canvas px, .zw = .xy / iResolution.
constexpr const char * kCustomParamsArray = "customParams"
 vec4 customParams[8] / vec4 customColors[16] — declared parameter slots.
constexpr const char * kCustomColorsArray = "customColors"
constexpr const char * kIChannelResolution = "iChannelResolution"
 vec4 iChannelResolution[4] — multipass buffer sizes (.xy).
constexpr const char * kITextureResolution = "iTextureResolution"
 vec4 iTextureResolution[4] — user texture sizes (.xy).
constexpr const char * kUPointerVelocity = "uPointerVelocity"
 vec4 uPointerVelocity — .xy device px/s, .z speed (length), .w the filtered speed over the current stroke (PointerFrameState::filteredSpeed, read by pointerFilteredSpeed()).
constexpr const char * kUPointerPress = "uPointerPress"
 vec4 uPointerPress — .xy canvas px of the last button press, .z seconds since it (kNeverSeconds when none this session), .w button (1 left, 2 right, 3 middle, 0 none).
constexpr const char * kUPointerRelease = "uPointerRelease"
 vec4 uPointerRelease — same shape as uPointerPress for the last release.
constexpr const char * kUPointerState = "uPointerState"
 vec4 uPointerState — .x pressed-button bitmask as float (1 left, 2 right, 4 middle), .y seconds since the last motion, .z logical-to-device scale, .w trail point count actually filled (0..32).
constexpr const char * kUCursorRect = "uCursorRect"
 vec4 uCursorRect — cursor sprite rect in canvas px (x, y, w, h) with the hotspot already applied, so it is where the sprite is drawn.
constexpr const char * kUPointerFlags = "uPointerFlags"
 vec4 uPointerFlags — .x = 1.0 when uCursorSprite is bound (needsCursor honoured), else 0.
constexpr const char * kUPointerTrail = "uPointerTrail"
 vec4 uPointerTrail[32] — newest first.
constexpr const char * kUCursorSprite = "uCursorSprite"
 sampler2D uCursorSprite — the cursor image, bound only for packs that declare needsCursor.
constexpr const char * kUTexture1 = "uTexture1"
 sampler2D uTexture1..3 — user-declared image textures (metadata textures).
constexpr const char * kUTexture2 = "uTexture2"
constexpr const char * kUTexture3 = "uTexture3"
constexpr const char * kIChannel0 = "iChannel0"
 sampler2D iChannel0..3 — multipass buffers, declared by the opt-in pointer_multipass.glsl include (bindings 2-5 on the UBO runtime, the FIRST FOUR of the shared table's eight-wide channel block).
constexpr const char * kIChannel1 = "iChannel1"
constexpr const char * kIChannel2 = "iChannel2"
constexpr const char * kIChannel3 = "iChannel3"
constexpr int kMaxTrailPoints = 32
 Ring capacity of uPointerTrail.
constexpr int kMaxCustomParams = PhosphorShaders::CustomParams::kVecCount
 Number of vec4 slots in customParams (8).
constexpr int kMaxCustomColors = PhosphorShaders::CustomColors::kColorCount
 Number of customColors slots (16).
constexpr int kMaxParameterSlots = PhosphorShaders::CustomParams::kFlatSlotCount
 Number of float sub-slots (4 × 8 = 32), the per-effect scalar budget.
constexpr int kMaxUserTextureSlots = 3
 Maximum number of user-declared textures per pointer effect.
constexpr int kMaxBufferPasses = 2
 Maximum number of buffer passes a pointer pack may declare.
constexpr int kMaxDeclaredParameters = 48
 Maximum number of declared parameters a pack may carry across both pools.
constexpr double kPointerCurveTension = 0.25
 Catmull-Rom tension used by every path pack's curve, mirroring kPointerCurveTension in data/pointer/shared/pointer_lib.glsl.
constexpr int kPointerCurveSteps = 4
 Straight pieces each path pack walks per curve span, mirroring kPointerCurveSteps in data/pointer/shared/pointer_lib.glsl.
constexpr double kNeverSeconds = 1.0e6
 The "none this session" sentinel for the seconds-since lanes of uPointerPress.z, uPointerRelease.z and uPointerState.y: what the tail carries before the first press, release or motion.
constexpr double kPreviewPeakSpeedPxPerSecond = 324.0
 Peak speed, in px per second, that the settings preview's simulated pointer ever reaches.

Detailed Description

Cross-runtime named-uniform contract for pointer shaders.

Pointer packs (data/pointer/<id>/) decorate the mouse pointer: trails, halos, click ripples, sparks. They are the fourth shader family beside the overlay, animation and surface categories and are modelled on the surface contract: one effect.frag runs on both runtimes.

• Compositor execution — the kwin-effect paints the chain as a screen-space pass over the composited scene of the output under the pointer. Classic GL, loose uniforms (the #ifdef PLASMAZONES_KWIN branch of data/pointer/shared/pointer_uniforms.glsl).

• Preview execution — the settings app drives the same source on the Qt-RHI ShaderEffect node. std140 UBO at binding 0 = PhosphorShaders::BaseUniforms followed by the pointer tail (PointerUniformsTail, see PointerShaderUniforms.h).

A pointer pack is a CONTINUOUS decoration: it ticks every frame while the pointer has recent motion or a recent button event, then the host stops repainting until the next event (PointerShaderEffect::trailSeconds). Click reactions are expressed through the press / release event uniforms inside that same continuous contract, so there is one family, not a decoration arm plus an animation arm.

Canvas
The canvas is the whole output in device px, top-down, origin at the output's top-left. Every position uniform is in that space and iResolution.xy is the output size in device px.
Per-effect declared parameters
Identical mechanism to the surface contract: float / int / bool parameters fill customParams[0].x … customParams[7].w (32 slots), colour parameters fill customColors[0] … customColors[15] (16 slots), both in metadata declaration order with independent allocators. PointerShaderRegistry::translatePointerParams converts a friendly map into the slot-keyed map both runtimes consume and PointerShaderRegistry::paramPreamble generates the #define p_<id> accessors packs read.

Function Documentation

◆ colorKey()

QString PhosphorPointerShaders::PointerShaderContract::colorKey ( int slot)
inline

Format a customColor<N> slot key (1-based on the wire).

◆ isValidWrapToken()

bool PhosphorPointerShaders::PointerShaderContract::isValidWrapToken ( const QString & wrap)
inline

The accepted texture wrap vocabulary (forwarder onto the canonical predicate in <PhosphorShaders/CustomParamsKey.h>).

◆ paramKey() [1/2]

QString PhosphorPointerShaders::PointerShaderContract::paramKey ( int slot)
inline

Flat-slot overload: slot is 0..31 across the 8 vec4 slots.

◆ paramKey() [2/2]

QString PhosphorPointerShaders::PointerShaderContract::paramKey ( int vec,
char comp )
inline

Format a customParams slot key (customParams<N>_<x|y|z|w>).

Variable Documentation

◆ kCustomColorsArray

const char* PhosphorPointerShaders::PointerShaderContract::kCustomColorsArray = "customColors"
inlineconstexpr

◆ kCustomParamsArray

const char* PhosphorPointerShaders::PointerShaderContract::kCustomParamsArray = "customParams"
inlineconstexpr

vec4 customParams[8] / vec4 customColors[16] — declared parameter slots.

Cross-runtime element-name lookup constants, mirrored by the kwin-effect's glGetUniformLocation("customParams[N]") calls.

◆ kIChannel0

const char* PhosphorPointerShaders::PointerShaderContract::kIChannel0 = "iChannel0"
inlineconstexpr

sampler2D iChannel0..3 — multipass buffers, declared by the opt-in pointer_multipass.glsl include (bindings 2-5 on the UBO runtime, the FIRST FOUR of the shared table's eight-wide channel block).

Two of the four are headroom: this family caps a chain at kMaxBufferPasses, which is 2.

◆ kIChannel1

const char* PhosphorPointerShaders::PointerShaderContract::kIChannel1 = "iChannel1"
inlineconstexpr

◆ kIChannel2

const char* PhosphorPointerShaders::PointerShaderContract::kIChannel2 = "iChannel2"
inlineconstexpr

◆ kIChannel3

const char* PhosphorPointerShaders::PointerShaderContract::kIChannel3 = "iChannel3"
inlineconstexpr

◆ kIChannelResolution

const char* PhosphorPointerShaders::PointerShaderContract::kIChannelResolution = "iChannelResolution"
inlineconstexpr

vec4 iChannelResolution[4] — multipass buffer sizes (.xy).

DOCUMENTATION ONLY, unlike every other name constant here. These two name ARRAYS, and a GL uniform lookup needs the per-element spelling (iChannelResolution[0]), so the compositor builds those from its own string-literal tables and never reads these. They are kept because the contract is the list of names a pack may use.

◆ kIMouse

const char* PhosphorPointerShaders::PointerShaderContract::kIMouse = "iMouse"
inlineconstexpr

vec4 iMouse — .xy pointer position in canvas px, .zw = .xy / iResolution.

◆ kIResolution

const char* PhosphorPointerShaders::PointerShaderContract::kIResolution = "iResolution"
inlineconstexpr

vec2 iResolution — canvas size in device px.

◆ kITextureResolution

const char* PhosphorPointerShaders::PointerShaderContract::kITextureResolution = "iTextureResolution"
inlineconstexpr

vec4 iTextureResolution[4] — user texture sizes (.xy).

Documentation only, for the same reason as kIChannelResolution above.

◆ kITime

const char* PhosphorPointerShaders::PointerShaderContract::kITime = "iTime"
inlineconstexpr

float iTime — seconds since the current burst of pointer activity began.

The compositor restarts it at 0 per burst and never wraps it; the preview wraps it at 1024 s like every family (iTimeHi is unused on this contract on either runtime).

◆ kMaxBufferPasses

int PhosphorPointerShaders::PointerShaderContract::kMaxBufferPasses = 2
inlineconstexpr

Maximum number of buffer passes a pointer pack may declare.

Two, against the eight the shared budget grants every other family: a pointer chain runs on every output frame while live, and each pass costs a canvas-sized draw.

◆ kMaxCustomColors

int PhosphorPointerShaders::PointerShaderContract::kMaxCustomColors = PhosphorShaders::CustomColors::kColorCount
inlineconstexpr

Number of customColors slots (16).

◆ kMaxCustomParams

int PhosphorPointerShaders::PointerShaderContract::kMaxCustomParams = PhosphorShaders::CustomParams::kVecCount
inlineconstexpr

Number of vec4 slots in customParams (8).

Forwards to the canonical constant so a single source of truth governs every shader family.

◆ kMaxDeclaredParameters

int PhosphorPointerShaders::PointerShaderContract::kMaxDeclaredParameters = 48
inlineconstexpr

Maximum number of declared parameters a pack may carry across both pools.

◆ kMaxParameterSlots

int PhosphorPointerShaders::PointerShaderContract::kMaxParameterSlots = PhosphorShaders::CustomParams::kFlatSlotCount
inlineconstexpr

Number of float sub-slots (4 × 8 = 32), the per-effect scalar budget.

◆ kMaxTrailPoints

int PhosphorPointerShaders::PointerShaderContract::kMaxTrailPoints = 32
inlineconstexpr

Ring capacity of uPointerTrail.

◆ kMaxUserTextureSlots

int PhosphorPointerShaders::PointerShaderContract::kMaxUserTextureSlots = 3
inlineconstexpr

Maximum number of user-declared textures per pointer effect.

◆ kNeverSeconds

double PhosphorPointerShaders::PointerShaderContract::kNeverSeconds = 1.0e6
inlineconstexpr

The "none this session" sentinel for the seconds-since lanes of uPointerPress.z, uPointerRelease.z and uPointerState.y: what the tail carries before the first press, release or motion.

Large enough that any fade or gate a pack writes against an age has long expired, so a click pack does not fire a ring at session start because an elapsed time read as zero. Both hosts' frame state and the UBO extension's initial tail use this one constant.

◆ kPointerCurveSteps

int PhosphorPointerShaders::PointerShaderContract::kPointerCurveSteps = 4
inlineconstexpr

Straight pieces each path pack walks per curve span, mirroring kPointerCurveSteps in data/pointer/shared/pointer_lib.glsl.

◆ kPointerCurveTension

double PhosphorPointerShaders::PointerShaderContract::kPointerCurveTension = 0.25
inlineconstexpr

Catmull-Rom tension used by every path pack's curve, mirroring kPointerCurveTension in data/pointer/shared/pointer_lib.glsl.

The textbook value is 0.5; the packs use half of it, which halves how far the curve can bulge outside the box of its span's endpoints while still visibly rounding the corners.

It lives here for the reason kMaxTrailPoints does: the host has to know it too. PointerHistory sizes its damage rect for the overshoot the curve is allowed, and the unit tests reconstruct the drawn path to pin it. Both would otherwise carry their own retyped copy of a number that lives in a GLSL file neither of them compiles, and a retune of the curve would leave them silently measuring the old one.

◆ kPreviewPeakSpeedPxPerSecond

double PhosphorPointerShaders::PointerShaderContract::kPreviewPeakSpeedPxPerSecond = 324.0
inlineconstexpr

Peak speed, in px per second, that the settings preview's simulated pointer ever reaches.

The preview stage is PreviewCanvas.size (420x236) and its pointer traces a Lissajous figure eight over a 4 second lap, so the two axes have amplitude 158.1 px at 1.571 rad/s and 66.1 px at 3.142 rad/s. Both terms peak together at the start of the lap, giving hypot(158.1 * 1.571, 66.1 * 3.142) which is a little under 324.

It lives here because it is a fact about how every pointer pack is judged, and the validator lints a pack's speed-gate default against it: a default above this means the gate never opens on the lap, so the pack previews as a blank stage however well it behaves on a real desktop. That is how the windtrail pack shipped invisible.

PointerPreviewCanvas.qml owns the lap this is derived from. Changing the stage size, the lap duration or the inset changes this number too.

◆ kUCursorRect

const char* PhosphorPointerShaders::PointerShaderContract::kUCursorRect = "uCursorRect"
inlineconstexpr

vec4 uCursorRect — cursor sprite rect in canvas px (x, y, w, h) with the hotspot already applied, so it is where the sprite is drawn.

(0, 0, 0, 0) when unknown. UBO offset 736.

◆ kUCursorSprite

const char* PhosphorPointerShaders::PointerShaderContract::kUCursorSprite = "uCursorSprite"
inlineconstexpr

sampler2D uCursorSprite — the cursor image, bound only for packs that declare needsCursor.

Loose sampler on KWin, binding 11 on the UBO runtime. Gate every read on uPointerFlags.x.

A shader that samples this without declaring needsCursor reads whatever texture unit 0 holds on the compositor at that point of the frame, which is undefined content rather than a black or transparent texel. The same holds for a uTexture<N> slot the metadata textures list does not declare. The static gate for both lives in the pack validator (plasmazones-shader-validate), not in this contract or its runtimes.

◆ kUPointerFlags

const char* PhosphorPointerShaders::PointerShaderContract::kUPointerFlags = "uPointerFlags"
inlineconstexpr

vec4 uPointerFlags — .x = 1.0 when uCursorSprite is bound (needsCursor honoured), else 0.

.y = the pack's resolved reach in DEVICE px (metadata reach / reachParam after resolution and scaling), the radius the host inflates the damage rect by; packs read it through pointerReach() so their extents and the host's rect cannot drift apart. .z .w reserved 0. UBO offset 752.

◆ kUPointerPress

const char* PhosphorPointerShaders::PointerShaderContract::kUPointerPress = "uPointerPress"
inlineconstexpr

vec4 uPointerPress — .xy canvas px of the last button press, .z seconds since it (kNeverSeconds when none this session), .w button (1 left, 2 right, 3 middle, 0 none).

UBO offset 688.

◆ kUPointerRelease

const char* PhosphorPointerShaders::PointerShaderContract::kUPointerRelease = "uPointerRelease"
inlineconstexpr

vec4 uPointerRelease — same shape as uPointerPress for the last release.

UBO offset 704.

◆ kUPointerState

const char* PhosphorPointerShaders::PointerShaderContract::kUPointerState = "uPointerState"
inlineconstexpr

vec4 uPointerState — .x pressed-button bitmask as float (1 left, 2 right, 4 middle), .y seconds since the last motion, .z logical-to-device scale, .w trail point count actually filled (0..32).

UBO offset 720.

◆ kUPointerTrail

const char* PhosphorPointerShaders::PointerShaderContract::kUPointerTrail = "uPointerTrail"
inlineconstexpr

vec4 uPointerTrail[32] — newest first.

.xy canvas px, .z age in seconds (0 = this frame), .w speed at that sample (device px/s). Entries at or past uPointerState.w are zero. UBO offset 768, 512 bytes.

◆ kUPointerVelocity

const char* PhosphorPointerShaders::PointerShaderContract::kUPointerVelocity = "uPointerVelocity"
inlineconstexpr

vec4 uPointerVelocity — .xy device px/s, .z speed (length), .w the filtered speed over the current stroke (PointerFrameState::filteredSpeed, read by pointerFilteredSpeed()).

UBO offset 672.

◆ kUTexture1

const char* PhosphorPointerShaders::PointerShaderContract::kUTexture1 = "uTexture1"
inlineconstexpr

sampler2D uTexture1..3 — user-declared image textures (metadata textures).

Slot N of the metadata list feeds uTexture<N+1> (bindings 12-14 on the UBO runtime) and iTextureResolution[N+1].xy carries its size. The array is indexed by GLSL slot, as in every family: iTextureResolution[i] is the size of uTexture<i>. This family has no uTexture0, because binding 11 carries uCursorSprite, so index 0 is unused here rather than being the first declared texture. An undeclared slot is unbound and reads texture unit 0 on the compositor (see kUCursorSprite).

◆ kUTexture2

const char* PhosphorPointerShaders::PointerShaderContract::kUTexture2 = "uTexture2"
inlineconstexpr

◆ kUTexture3

const char* PhosphorPointerShaders::PointerShaderContract::kUTexture3 = "uTexture3"
inlineconstexpr