impr: Warn when schema is not uniform aligned by aleksanderkatan · Pull Request #2750 · software-mansion/TypeGPU

aleksanderkatan · 2026-07-22T11:06:00Z

I checked and all the fixes suggested indeed do silence the errors

github-actions · 2026-07-22T11:07:42Z

pkg.pr.new

packages
Ready to be installed by your favorite package manager ⬇️

https://pkg.pr.new/software-mansion/TypeGPU/eslint-plugin-typegpu@7d87abc251799c9df9ed1ee6a9e50e37dc182451

https://pkg.pr.new/software-mansion/TypeGPU/tgpu-gen@7d87abc251799c9df9ed1ee6a9e50e37dc182451

https://pkg.pr.new/software-mansion/TypeGPU/tinyest-for-wgsl@7d87abc251799c9df9ed1ee6a9e50e37dc182451

https://pkg.pr.new/software-mansion/TypeGPU/typegpu@7d87abc251799c9df9ed1ee6a9e50e37dc182451

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/cli@7d87abc251799c9df9ed1ee6a9e50e37dc182451

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/color@7d87abc251799c9df9ed1ee6a9e50e37dc182451

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/gl@7d87abc251799c9df9ed1ee6a9e50e37dc182451

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/noise@7d87abc251799c9df9ed1ee6a9e50e37dc182451

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/radiance-cascades@7d87abc251799c9df9ed1ee6a9e50e37dc182451

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/react@7d87abc251799c9df9ed1ee6a9e50e37dc182451

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/sdf@7d87abc251799c9df9ed1ee6a9e50e37dc182451

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/three@7d87abc251799c9df9ed1ee6a9e50e37dc182451

https://pkg.pr.new/software-mansion/TypeGPU/unplugin-typegpu@7d87abc251799c9df9ed1ee6a9e50e37dc182451

benchmark
view benchmark

commit
view commit

github-actions · 2026-07-22T11:09:01Z

Resolution Time Benchmark

---
config:
  themeVariables:
    xyChart:
      plotColorPalette: "#E63946, #3B82F6, #059669"
---
xychart
  title "Random Branching (🔴 PR | 🔵 main | 🟢 release)"
  x-axis "max depth" [1, 2, 3, 4, 5, 6, 7, 8]
  y-axis "time (ms)"
  line [0.82, 1.63, 3.56, 5.67, 6.56, 10.34, 19.29, 20.72]
  line [0.79, 1.64, 3.59, 5.41, 7.19, 9.84, 19.40, 21.42]
  line [0.85, 1.64, 3.74, 5.92, 7.20, 11.96, 20.39, 23.71]

---
config:
  themeVariables:
    xyChart:
      plotColorPalette: "#E63946, #3B82F6, #059669"
---
xychart
  title "Linear Recursion (🔴 PR | 🔵 main | 🟢 release)"
  x-axis "max depth" [1, 2, 3, 4, 5, 6, 7, 8]
  y-axis "time (ms)"
  line [0.27, 0.42, 0.59, 0.76, 1.01, 1.04, 1.21, 1.35]
  line [0.29, 0.79, 0.70, 0.70, 0.99, 1.01, 1.18, 1.27]
  line [0.28, 0.49, 0.60, 0.72, 0.99, 1.05, 1.23, 1.38]

---
config:
  themeVariables:
    xyChart:
      plotColorPalette: "#E63946, #3B82F6, #059669"
---
xychart
  title "Full Tree (🔴 PR | 🔵 main | 🟢 release)"
  x-axis "max depth" [1, 2, 3, 4, 5, 6, 7, 8]
  y-axis "time (ms)"
  line [0.76, 1.88, 4.09, 6.20, 11.69, 21.99, 47.39, 96.40]
  line [0.74, 1.84, 3.44, 5.83, 10.60, 22.63, 46.73, 96.57]
  line [0.91, 1.81, 3.38, 5.62, 11.01, 22.94, 49.36, 102.75]

github-actions · 2026-07-22T11:09:05Z

Bundle size comparison (`import * as ...` in PR vs `import * as ...` in target):

🟢 Decreased	➖ Unchanged	🔴 Increased (max 0.61%)	❔ Unknown
0	37	285	0

`import * as ...` in PR vs `import * as ...` in target (did bundle size increase?):

Test	tsdown
STATIC_tgpu.ts	269.67 kB ($${\color{red}+0.6\%}$$)
tgpu_fn.ts	269.67 kB ($${\color{red}+0.6\%}$$)
tgpu_init.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_lazy.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_slot.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_const.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_unroll.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_resolve.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_accessor.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_comptime.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_vertexFn.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_computeFn.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_fragmentFn.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_privateVar.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_vertexLayout.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_workgroupVar.ts	269.68 kB ($${\color{red}+0.6\%}$$)
tgpu_initFromDevice.ts	269.69 kB ($${\color{red}+0.6\%}$$)
tgpu_bindGroupLayout.ts	269.69 kB ($${\color{red}+0.6\%}$$)
tgpu_mutableAccessor.ts	269.69 kB ($${\color{red}+0.6\%}$$)
tgpu_resolveWithContext.ts	269.69 kB ($${\color{red}+0.6\%}$$)
STATIC_allImports.ts	295.44 kB ($${\color{red}+0.6\%}$$)

`import { ... }` in PR vs `import * as ...` in PR (is the library tree-Shakeable?):

Test	tsdown
tgpu_init.ts	261.16 kB ($${\color{green}-3.2\%}$$)
tgpu_initFromDevice.ts	260.62 kB ($${\color{green}-3.4\%}$$)
tgpu_resolve.ts	164.95 kB ($${\color{green}-38.8\%}$$)
tgpu_resolveWithContext.ts	164.88 kB ($${\color{green}-38.9\%}$$)
tgpu_bindGroupLayout.ts	69.29 kB ($${\color{green}-74.3\%}$$)
tgpu_mutableAccessor.ts	66.30 kB ($${\color{green}-75.4\%}$$)
tgpu_accessor.ts	66.29 kB ($${\color{green}-75.4\%}$$)
tgpu_privateVar.ts	65.63 kB ($${\color{green}-75.7\%}$$)
tgpu_workgroupVar.ts	65.63 kB ($${\color{green}-75.7\%}$$)
tgpu_const.ts	64.88 kB ($${\color{green}-75.9\%}$$)
tgpu_fn.ts	38.48 kB ($${\color{green}-85.7\%}$$)
tgpu_fragmentFn.ts	38.48 kB ($${\color{green}-85.7\%}$$)
tgpu_vertexFn.ts	38.29 kB ($${\color{green}-85.8\%}$$)
tgpu_computeFn.ts	38.00 kB ($${\color{green}-85.9\%}$$)
tgpu_vertexLayout.ts	27.11 kB ($${\color{green}-89.9\%}$$)
tgpu_comptime.ts	14.80 kB ($${\color{green}-94.5\%}$$)
tgpu_unroll.ts	1.66 kB ($${\color{green}-99.4\%}$$)
tgpu_slot.ts	1.54 kB ($${\color{green}-99.4\%}$$)
tgpu_lazy.ts	1.19 kB ($${\color{green}-99.6\%}$$)

If you wish to run a comparison for other, slower bundlers, run the 'Tree-shake test' from the GitHub Actions menu.

aleksanderkatan · 2026-07-22T11:25:08Z

@pullfrog review

pullfrog

ℹ️ No critical issues — one minor polish item inline.

Reviewed changes — the PR introduces runtime warnings for schemas that violate WGSL uniform-buffer layout constraints, moves buffer-count limit checks into a shared webgpuLimitations.ts module, removes now-misaligned uniform usage from two confetti examples, and adds tests for the new warnings.

Add warnIfNotUniformAligned — warns when a schema used as uniform has struct member offsets or array strides that are not compatible with the default WGSL uniform address space layout.
Move limitsOverflow.ts to webgpuLimitations.ts — consolidates WebGPU validation helpers; updates imports in applyPipelineState.ts and limitsOverflow.test.ts.
Clean up confetti examples — drops unused 'uniform' buffer usage for particle data that now triggers the new warning.
Add test coverage — snapshots legitimate schemas and several misalignment cases in buffer.test.ts.

^{｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

pullfrog · 2026-07-22T11:34:00Z

The newly added 'uniform-schema-misaligned' warning will share the malformed prefix [uniform-schema-misaligned}] because TgpuLogger.warn formats the type as `[${type}}]` (note the stray }). Consider fixing the logger format string while the warning plumbing is being touched, and regenerating the affected snapshots.

Referenced at packages/typegpu/src/tgpuLogger.ts:16 (new warning type); root cause at packages/typegpu/src/tgpuLogger.ts:72.

^{｜ View workflow run ｜ via Pullfrog ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

…aligned

pullfrog

Important

The new Uniform alignment tests are failing because their inline snapshots include an extra } in the warning prefix (e.g. [uniform-schema-misaligned}]). Fix the snapshots before merging.

Reviewed changes — added a runtime warning for schemas used as uniform that don't meet WebGPU's strict uniform-buffer layout constraints, plus tests and example updates.

Merge limitsOverflow.ts into webgpuLimitations.ts — consolidates WebGPU limit warnings in one file.
Add warnIfNotUniformAligned — checks array stride, struct member offset alignment, and spacing for nested structs in uniform buffers.
Wire warning into $usage('uniform') — catches both createUniform() and explicit $usage('uniform').
Update confetti examples — removes uniform usage from particle data buffers that are not uniform-aligned.
Add tests — covers legit schemas, misaligned structs, nested structs, and arrays.

⚠️ Consider enabling the warning in production

uniform-schema-misaligned is currently enabled only in dev/test, unlike webgpu-limits-exceeded which is also enabled in production. Since both are WebGPU-portability warnings that can cause runtime failure on some devices, consider adding the new type to the production subset in packages/typegpu/src/tgpuLogger.ts.

^{｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

pullfrog · 2026-07-22T12:06:55Z

Line-anchored details for the findings in my review above:

packages/typegpu/tests/buffer.test.ts:1763 (and throughout the Uniform alignment describe block): every inline snapshot expects [uniform-schema-misaligned}] but the logger emits [uniform-schema-misaligned]. Remove the stray } before ] in each toMatchInlineSnapshot.
packages/typegpu/src/core/pipeline/webgpuLimitations.ts:168 (and the other warning message strings in the same function): "uniform" begins with a consonant sound, so the messages should read "a uniform buffer" rather than "an uniform buffer".

^{｜ View workflow run ｜ via Pullfrog ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

cieplypolar · 2026-07-23T10:04:43Z

+    root.createUniform(d.struct({ p: d.size(32, d.struct({ p: d.u32 })), q: d.u32 }));
+    root.createUniform(d.arrayOf(d.vec4f, 3));
+    root.createUniform(d.arrayOf(d.vec3f, 3));
+    root.createUniform(d.arrayOf(d.align(16, d.u32), 3));


It is false negative, see #2754

error: uniform storage requires that array elements are aligned to 16 bytes, but array element of type u32 has a stride of 4 bytes. Consider using a vector or struct as the element type instead. var<uniform> a : array<u32, 3>; ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

cieplypolar · 2026-07-23T11:32:35Z

+        continue;
+      }
+
+      const minimumDifference = roundUp(16, sizeOf(thisValue));


Suggested change

const minimumDifference = roundUp(16, sizeOf(thisValue));

const minimumDifference = roundUp(sizeOf(thisValue), 16);

cieplypolar · 2026-07-23T11:33:39Z

+        `\
+Schema '${getName(schema.elementType) ?? '<unnamed>'}' is used in an array in an uniform buffer, and its stride (${stride}) is not a multiple of 16.
+This is not portable (see https://www.w3.org/TR/WGSL/#address-space-layout-constraints), and will break on some devices.
+To address this, wrap the element in 'd.align(16, ...)'.`,


You cannot wrap array element with d.align

aleksanderkatan added 17 commits July 20, 2026 10:52

Replace warn with throw

f7c6a76

Add logger, replace console.warns with logger warns

e2ce177

Rename warning types

c0a42d0

Split apis into two

1e567ec

Rename warning types again

b82d259

Add custom warn message, change log tests to snapshots

5cae02c

Change enable to reset, add tests

8a8d1ed

Pass prod mode to logger

7e1368b

Change warn to invariant

1c4bde9

Merge remote-tracking branch 'origin/main' into feat/logger

d7ce0dc

Change remaining calls to warns

b4b2ba7

Add docs

5932429

nr fix

24dfc22

Add tests

46fc32e

Finish warn implementation

bf5b386

Report when giving usage

90ff2ec

Remove 'uniform' usage from confetti examples

664d90f

aleksanderkatan added 4 commits July 22, 2026 13:14

Self review

742c695

Review fixes

7357da4

Unused import

521ca90

Merge branch 'main' into feat/logger

a4207b5

pullfrog Bot reviewed Jul 22, 2026

View reviewed changes

aleksanderkatan added 2 commits July 22, 2026 13:49

Review fixes

7b8f4d2

Merge branch 'feat/logger' into impr/warn-when-schema-is-not-uniform-…

25ed48e

…aligned

aleksanderkatan requested a review from iwoplaza July 22, 2026 11:52

aleksanderkatan requested review from cieplypolar and reczkok July 22, 2026 11:52

aleksanderkatan marked this pull request as ready for review July 22, 2026 11:52

pullfrog Bot reviewed Jul 22, 2026

View reviewed changes

cieplypolar reviewed Jul 23, 2026

View reviewed changes

Update snapshots

7d87abc

Base automatically changed from feat/logger to main July 29, 2026 10:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

impr: Warn when schema is not uniform aligned - #2750

impr: Warn when schema is not uniform aligned#2750
aleksanderkatan wants to merge 24 commits into
mainfrom
impr/warn-when-schema-is-not-uniform-aligned

aleksanderkatan commented Jul 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 22, 2026 •

edited

Loading

Uh oh!

aleksanderkatan commented Jul 22, 2026

Uh oh!

pullfrog Bot left a comment

Uh oh!

pullfrog Bot commented Jul 22, 2026

Uh oh!

pullfrog Bot left a comment

Uh oh!

pullfrog Bot commented Jul 22, 2026 •

edited

Loading

Uh oh!

cieplypolar Jul 23, 2026

Uh oh!

cieplypolar Jul 23, 2026

Uh oh!

cieplypolar Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	const minimumDifference = roundUp(16, sizeOf(thisValue));
	const minimumDifference = roundUp(sizeOf(thisValue), 16);

Uh oh!

Uh oh!

Conversation

aleksanderkatan commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Resolution Time Benchmark

Uh oh!

github-actions Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle size comparison (import * as ... in PR vs import * as ... in target):

import * as ... in PR vs import * as ... in target (did bundle size increase?):

import { ... } in PR vs import * as ... in PR (is the library tree-Shakeable?):

Uh oh!

aleksanderkatan commented Jul 22, 2026

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

pullfrog Bot commented Jul 22, 2026

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

⚠️ Consider enabling the warning in production

Uh oh!

pullfrog Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cieplypolar Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

cieplypolar Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

cieplypolar Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aleksanderkatan commented Jul 22, 2026 •

edited

Loading

github-actions Bot commented Jul 22, 2026 •

edited

Loading

github-actions Bot commented Jul 22, 2026 •

edited

Loading

github-actions Bot commented Jul 22, 2026 •

edited

Loading

Bundle size comparison (`import * as ...` in PR vs `import * as ...` in target):

`import * as ...` in PR vs `import * as ...` in target (did bundle size increase?):

`import { ... }` in PR vs `import * as ...` in PR (is the library tree-Shakeable?):

pullfrog Bot commented Jul 22, 2026 •

edited

Loading