Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
BaseUniforms.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
6#include <cstddef>
7
8namespace PhosphorShaders {
9
11constexpr double kShaderTimeWrap = 1024.0;
12
36struct alignas(16) BaseUniforms
37{
38 // Transform and opacity from Qt scene graph (offset 0)
39 float qt_Matrix[16]; // mat4: 64 bytes at offset 0
40 float qt_Opacity; // float: 4 bytes at offset 64
41
42 // Shader timing (Shadertoy-compatible)
43 float iTime; // float: 4 bytes at offset 68 (wrapped)
44 float iTimeDelta; // float: 4 bytes at offset 72
45 int iFrame; // int: 4 bytes at offset 76
46
47 // Resolution
48 float iResolution[2]; // vec2: 8 bytes at offset 80
49
50 // Consumer-defined int slots — see class doc above for the escape-hatch
51 // design rationale. Written via ShaderNodeRhi::setAppField0/1.
52 int appField0; // offset 88
53 int appField1; // offset 92
54
55 // Mouse position
56 float iMouse[4]; // vec4: 16 bytes at offset 96
57
58 // Date/time: year, month (1-12), day (1-31), seconds since midnight
59 float iDate[4]; // vec4: 16 bytes at offset 112
60
61 // Custom shader parameters (32 float slots in 8 vec4s)
62 float customParams[8][4]; // vec4[8]: 128 bytes at offset 128
63
64 // Custom colors (16 color slots)
65 float customColors[16][4]; // vec4[16]: 256 bytes at offset 256
66
67 // Multi-pass: iChannelResolution[i] = buffer texture size.
68 // The FIRST FOUR channels only, deliberately. The channel budget is eight
69 // (Bindings::kChannelCount) but widening this array would move every
70 // offset below it and break the 672-byte base layout the shared GLSL
71 // headers pin. A pass reading iChannel4..7 sizes it with textureSize(),
72 // which is what the builtin Kawase passes do.
73 float iChannelResolution[4][4]; // vec4[4]: 64 bytes at offset 512
74
75 // Audio spectrum
76 int iAudioSpectrumSize; // offset 576
77 int iFlipBufferY; // offset 580 — always 1 for Y-flip
78 // The two pad ints at offsets 584 and 588 are explicitly written as zero
79 // by the C-side upload path (see BaseUniformProfile::fill in
80 // baseuniformprofile.cpp) — readers should not assume the bytes are
81 // skipped on the wire. On the GLSL side they are absorbed by std140's
82 // vec4 alignment of the following `iTextureResolution` (vec4[4]) member,
83 // which forces the next field onto a 16-byte boundary at offset 592.
84 // Removing the pad would shift the GLSL view of `iTextureResolution` and
85 // break the `data/animations/shared/animation_uniforms.glsl`
86 // byte-for-byte contract pinned by the static_asserts below.
87 int _pad_after_audioSpectrum[2]; // offset 584
88
89 // User texture resolutions (bindings 11-14)
90 float iTextureResolution[4][4]; // vec4[4]: 64 bytes at offset 592
91
92 // Wrap-offset counterpart of iTime
93 float iTimeHi; // offset 656
94
95 // Direction signal for asymmetric leg rendering. 1 when the runtime
96 // is driving this leg in the "reverse" direction (window.close /
97 // going-to-minimized / unmaximize on the kwin path; hide leg on
98 // the daemon path), 0 otherwise. Symmetric shaders ignore this and
99 // rely on the runtime's iTime flip to auto-mirror; asymmetric
100 // shaders (matrix's directional rain, rain windowAlpha trajectory,
101 // anything where open and close differ in more than time direction)
102 // branch on it. Carved out of the trailing std140 pad so total
103 // struct size stays 672 bytes.
104 int iIsReversed; // offset 660
105 // Ditto: trailing pad zeroed by value-init (BaseUniformProfile's `m_u = {}`)
106 // and covered by K_SCENE_HEADER. See the expanded `_pad_after_audioSpectrum`
107 // comment above for the full std140 / upload-region rationale.
108 int _pad_after_iIsReversed[2]; // std140 struct alignment, total 672 bytes
109};
110
111static_assert(sizeof(BaseUniforms) == 672, "BaseUniforms must be exactly 672 bytes");
112
113// Per-field std140 offset asserts. These pin the layout the
114// `data/animations/shared/animation_uniforms.glsl` canonical UBO branch
115// depends on — that GLSL declaration is a byte-for-byte std140 prefix of
116// `BaseUniforms`, which is what lets a single animation `effect.frag`
117// source produce identical visuals on both runtimes (compositor classic
118// GL via the canonical header's `#ifdef PLASMAZONES_KWIN` default-block
119// branch, daemon Qt RHI via the `binding=0` UBO upload). If anyone
120// reorders or inserts a field above any of these, the corresponding
121// assert fails at compile time and the canonical GLSL header MUST be
122// updated to match (and all in-tree `effect.frag` files re-baked, since
123// their `customParams[N]` `#define` macros encode the slot positions).
124//
125// Every field declared in `animation_uniforms.glsl` is pinned here. A
126// previous revision asserted only iTime / iResolution / customParams /
127// customColors, which left the door open to a reorder that swapped
128// {iTimeDelta, iFrame, appField0, appField1, iMouse, iDate} amongst
129// themselves while preserving the four asserted offsets — silent
130// miscompile for any future animation shader that reads the in-between
131// fields. The full coverage below catches that.
132static_assert(offsetof(BaseUniforms, qt_Matrix) == 0,
133 "BaseUniforms::qt_Matrix must remain at std140 offset 0 (animation UBO contract)");
134static_assert(offsetof(BaseUniforms, qt_Opacity) == 64,
135 "BaseUniforms::qt_Opacity must remain at std140 offset 64 (animation UBO contract)");
136static_assert(offsetof(BaseUniforms, iTime) == 68,
137 "BaseUniforms::iTime must remain at std140 offset 68 (animation UBO contract)");
138static_assert(offsetof(BaseUniforms, iTimeDelta) == 72,
139 "BaseUniforms::iTimeDelta must remain at std140 offset 72 (animation UBO contract)");
140static_assert(offsetof(BaseUniforms, iFrame) == 76,
141 "BaseUniforms::iFrame must remain at std140 offset 76 (animation UBO contract)");
142static_assert(offsetof(BaseUniforms, iResolution) == 80,
143 "BaseUniforms::iResolution must remain at std140 offset 80 (animation UBO contract)");
144static_assert(offsetof(BaseUniforms, appField0) == 88,
145 "BaseUniforms::appField0 must remain at std140 offset 88 (animation UBO contract)");
146static_assert(offsetof(BaseUniforms, appField1) == 92,
147 "BaseUniforms::appField1 must remain at std140 offset 92 (animation UBO contract)");
148static_assert(offsetof(BaseUniforms, iMouse) == 96,
149 "BaseUniforms::iMouse must remain at std140 offset 96 (animation UBO contract)");
150static_assert(offsetof(BaseUniforms, iDate) == 112,
151 "BaseUniforms::iDate must remain at std140 offset 112 (animation UBO contract)");
152static_assert(offsetof(BaseUniforms, customParams) == 128,
153 "BaseUniforms::customParams must remain at std140 offset 128 (animation UBO contract)");
154static_assert(offsetof(BaseUniforms, customColors) == 256,
155 "BaseUniforms::customColors must remain at std140 offset 256 (animation UBO contract)");
156static_assert(offsetof(BaseUniforms, iChannelResolution) == 512,
157 "BaseUniforms::iChannelResolution must remain at std140 offset 512 (animation UBO contract)");
158static_assert(offsetof(BaseUniforms, iAudioSpectrumSize) == 576,
159 "BaseUniforms::iAudioSpectrumSize must remain at std140 offset 576 (animation UBO contract)");
160static_assert(offsetof(BaseUniforms, iFlipBufferY) == 580,
161 "BaseUniforms::iFlipBufferY must remain at std140 offset 580 (animation UBO contract)");
162static_assert(offsetof(BaseUniforms, iTextureResolution) == 592,
163 "BaseUniforms::iTextureResolution must remain at std140 offset 592 (animation UBO contract)");
164static_assert(offsetof(BaseUniforms, iTimeHi) == 656,
165 "BaseUniforms::iTimeHi must remain at std140 offset 656 (animation UBO contract)");
166static_assert(offsetof(BaseUniforms, iIsReversed) == 660,
167 "BaseUniforms::iIsReversed must remain at std140 offset 660 (animation UBO contract)");
168
170namespace UboRegions {
171
172// Transform and opacity from Qt scene graph (mat4 + float).
173//
174// REFERENCE ONLY. Nothing uploads this region: dirtyRegions() below emits
175// K_TIME_BLOCK, K_TIME_HI, K_SCENE_HEADER and K_APP_FIELDS and never this one,
176// so the base UBO's matrix and opacity bytes reach the GPU through
177// fullUploadRegions() alone, on the first upload and on any retarget that
178// forces another. Kept as public constants because this is an exported header
179// and an out-of-tree consumer may describe the region, not because the library
180// uses them. (SurfaceUniformProfile DOES push a matrix region of its own,
181// which is probably why this header used to read as though the base did too.)
182constexpr size_t K_MATRIX_OPACITY_OFFSET = 0;
183constexpr size_t K_MATRIX_OPACITY_SIZE = offsetof(BaseUniforms, iTime); // 68 bytes
184
185// Animation time block (iTime, iTimeDelta, iFrame)
186constexpr size_t K_TIME_BLOCK_OFFSET = offsetof(BaseUniforms, iTime);
187constexpr size_t K_TIME_BLOCK_SIZE = sizeof(float) + sizeof(float) + sizeof(int); // 12 bytes
188
189// App-fields block (appField0, appField1) — 8 bytes at offset 88.
190// Uploaded as a tiny standalone region when ONLY the consumer's escape-hatch
191// fields changed. Without this granular region, every appField update would
192// trigger a full scene-header re-upload (~592 bytes).
193constexpr size_t K_APP_FIELDS_OFFSET = offsetof(BaseUniforms, appField0);
194constexpr size_t K_APP_FIELDS_SIZE = sizeof(int) * 2;
195
196// Scene header: iResolution through end of struct.
197// Covers iResolution, appFields, iMouse, iDate, customParams, customColors,
198// iChannelResolution, iAudioSpectrumSize, iFlipBufferY, iTextureResolution,
199// iTimeHi, iIsReversed, and the trailing std140 pad. Sized to the
200// remainder of BaseUniforms so any field added at or after offset 80
201// (iResolution) is automatically covered by m_sceneDataDirty's upload
202// path without needing a per-field dirty flag.
203//
204// History: an earlier revision capped K_SCENE_HEADER_SIZE at offsetof(iTimeHi),
205// leaving the gap from offsetof(iTimeHi) + sizeof(iTimeHi) (660) to
206// sizeof(BaseUniforms) (672) un-uploaded by partial-update paths. The
207// new iIsReversed field at offset 660 landed exactly in that gap and
208// silently failed to propagate to the GPU after the first full upload —
209// asymmetric direction-aware shaders read stale values forever.
210//
211// WARNING: this range covers offsets [80, sizeof(BaseUniforms)) and nothing
212// below. A new field added BEFORE iResolution (offset < 80) therefore needs
213// its own region AND a dirty flag emitting it from dirtyRegions(). Widening
214// K_MATRIX_OPACITY would not be enough on its own, because nothing uploads
215// that region; it would reach the GPU only on a full upload, which is the
216// same silent-staleness shape as the iIsReversed gap above.
217constexpr size_t K_SCENE_HEADER_OFFSET = offsetof(BaseUniforms, iResolution);
219
220// iTimeHi block: a granular 4-byte upload region for the time-wrap-only
221// path. m_timeHiDirty fires when iTime crosses the wrap boundary, which is
222// every kShaderTimeWrap seconds, so roughly every 17 minutes rather than
223// often. Subsumed by K_SCENE_HEADER, so when m_sceneDataDirty also fires for
224// the same frame BaseUniformProfile::dirtyRegions skips this granular write
225// to avoid the duplicate 4-byte transfer.
226constexpr size_t K_TIME_HI_OFFSET = offsetof(BaseUniforms, iTimeHi);
227constexpr size_t K_TIME_HI_SIZE = sizeof(float);
228
229// Verify K_SCENE_HEADER reaches end of BaseUniforms — a new field added
230// at or after offset 80 must land inside this range. Without this assert,
231// adding a field beyond the previous K_SCENE_HEADER end (the iTimeHi-
232// based cap) would silently regress the gap-bug fixed by extending the
233// region. Pin via the actual LAST field's offset+size so a developer
234// who manually narrows K_SCENE_HEADER_SIZE (e.g. `= offsetof(iTimeHi) -
235// K_SCENE_HEADER_OFFSET`, which is exactly the original regression)
236// fails to build. The other formulation,
237// `K_SCENE_HEADER_OFFSET + K_SCENE_HEADER_SIZE == sizeof(BaseUniforms)`,
238// is an identity only while K_SCENE_HEADER_SIZE is defined as
239// `sizeof(BaseUniforms) - K_SCENE_HEADER_OFFSET`. Under the narrowing it is
240// meant to defend against it stops being one and fires, so it is kept below
241// as a companion rather than removed. The trailing-field form is the primary
242// because it stays meaningful whatever K_SCENE_HEADER_SIZE is written as.
243static_assert(offsetof(BaseUniforms, _pad_after_iIsReversed) + sizeof(BaseUniforms::_pad_after_iIsReversed)
245 "K_SCENE_HEADER must cover the trailing _pad_after_iIsReversed bytes — "
246 "narrowing K_SCENE_HEADER_SIZE leaves the iIsReversed gap unmapped");
248 "K_SCENE_HEADER must reach end-of-BaseUniforms — defensive companion to "
249 "the trailing-field assert above");
250// Verify K_TIME_HI is fully nested inside K_SCENE_HEADER so the upload
251// site can skip the granular write when both dirty flags fire.
254 "K_TIME_HI must be subsumed by K_SCENE_HEADER so a scene-data upload "
255 "covers iTimeHi too without needing the m_timeHiDirty granular path");
256// Verify K_APP_FIELDS is fully nested inside K_SCENE_HEADER for the
257// same reason: BaseUniformProfile::dirtyRegions uses an `else if` to skip
258// the granular app-fields write when scene-data is also dirty (the broader
259// upload already covers it). Pinning the nesting at compile time makes a
260// future field-shuffle that breaks containment a build failure rather
261// than a silent missed-upload regression.
264 "K_APP_FIELDS must be subsumed by K_SCENE_HEADER so the scene-data upload "
265 "covers appField0/appField1 too without needing the m_appFieldsDirty granular path");
266
267// Total base size. REFERENCE ONLY, like K_MATRIX_OPACITY above: the extension
268// offset an extended profile actually uses comes from
269// BaseUniformProfile::baseSize(), which is what ShaderNodeRhi reads. This is
270// the public mirror of the same number for an out-of-tree consumer laying out
271// its own tail.
272constexpr size_t K_BASE_SIZE = sizeof(BaseUniforms);
273
274} // namespace UboRegions
275
276} // namespace PhosphorShaders
UBO region offsets and sizes for partial updates (reduces GPU bandwidth).
Definition BaseUniforms.h:170
constexpr size_t K_TIME_HI_OFFSET
Definition BaseUniforms.h:226
constexpr size_t K_TIME_HI_SIZE
Definition BaseUniforms.h:227
constexpr size_t K_TIME_BLOCK_SIZE
Definition BaseUniforms.h:187
constexpr size_t K_MATRIX_OPACITY_SIZE
Definition BaseUniforms.h:183
constexpr size_t K_TIME_BLOCK_OFFSET
Definition BaseUniforms.h:186
constexpr size_t K_APP_FIELDS_OFFSET
Definition BaseUniforms.h:193
constexpr size_t K_MATRIX_OPACITY_OFFSET
Definition BaseUniforms.h:182
constexpr size_t K_SCENE_HEADER_SIZE
Definition BaseUniforms.h:218
constexpr size_t K_APP_FIELDS_SIZE
Definition BaseUniforms.h:194
constexpr size_t K_SCENE_HEADER_OFFSET
Definition BaseUniforms.h:217
constexpr size_t K_BASE_SIZE
Definition BaseUniforms.h:272
Definition ShaderProfile.h:21
constexpr double kShaderTimeWrap
Time wrap period for float32 precision preservation.
Definition BaseUniforms.h:11
GPU uniform buffer layout following std140 rules (base region).
Definition BaseUniforms.h:37
int iAudioSpectrumSize
Definition BaseUniforms.h:76
float iChannelResolution[4][4]
Definition BaseUniforms.h:73
float iTime
Definition BaseUniforms.h:43
int _pad_after_iIsReversed[2]
Definition BaseUniforms.h:108
float iResolution[2]
Definition BaseUniforms.h:48
float iTimeDelta
Definition BaseUniforms.h:44
int _pad_after_audioSpectrum[2]
Definition BaseUniforms.h:87
float iTextureResolution[4][4]
Definition BaseUniforms.h:90
int appField1
Definition BaseUniforms.h:53
int iFrame
Definition BaseUniforms.h:45
int iIsReversed
Definition BaseUniforms.h:104
float iTimeHi
Definition BaseUniforms.h:93
float qt_Opacity
Definition BaseUniforms.h:40
float customColors[16][4]
Definition BaseUniforms.h:65
int appField0
Definition BaseUniforms.h:52
float iDate[4]
Definition BaseUniforms.h:59
int iFlipBufferY
Definition BaseUniforms.h:77
float qt_Matrix[16]
Definition BaseUniforms.h:39
float customParams[8][4]
Definition BaseUniforms.h:62
float iMouse[4]
Definition BaseUniforms.h:56