verifying-rendering-changes
Proves that a change to a renderer did what was meant and nothing else, when a refactor or a speed-up must not change a pixel, a change is meant to change the rendered image, a history-dependent or temporal effect is added, a screenshot or golden-image test fails, or "did this change anything on screen?" is asked. Names the kind of change, captures the same views before it, compares decoded pixels byte for byte where frames are deterministic and elsewhere within a tolerance set from the build's own run-to-run variation, keys stored references by everything their pixels depend on, captures only paused, settled frames, and reports measured differences with crops. Use with three.js WebGPU renderers, or any renderer with screenshot tests, whenever rendering code, a shader, a pass, a material, lighting or a capture tool changes. It hands a build that disagrees with itself to diagnosing-nondeterministic-frames, a defect of unknown cause to diagnosing-visual-defects and frame time to measurin
HuberyLL · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add HuberyLL/ponlai --skill verifying-rendering-changes技能说明
name: verifying-rendering-changes description: Proves that a change to a renderer did what was meant and nothing else, when a refactor or a speed-up must not change a pixel, a change is meant to change the rendered image, a history-dependent or temporal effect is added, a screenshot or golden-image test fails, or "did this change anything on screen?" is asked. Names the kind of change, captures the same views before it, compares decoded pixels byte for byte where frames are deterministic and elsewhere within a tolerance set from the build's own run-to-run variation, keys stored references by everything their pixels depend on, captures only paused, settled frames, and reports measured differences with crops. Use with three.js WebGPU renderers, or any renderer with screenshot tests, whenever rendering code, a shader, a pass, a material, lighting or a capture tool changes. It hands a build that disagrees with itself to diagnosing-nondeterministic-frames, a defect of unknown cause to diagnosing-visual-defects and frame time to measuring-performance-changes.
Verifying rendering changes
The rendered image can change for many reasons besides the change under test: a frame that has not settled, another browser build, a tool that changed together with the code, or noise that the GPU adds. A comparison that cannot tell these apart either passes a regression or fails a correct change, and both end up waved through. This skill fixes what the comparison means before you make the change, so you can trust its answer.
Rules most often broken without notice
- Name the kind of change before you edit (step 1). The kind decides the comparison. If you choose the comparison after you see the result, you fit the test to the answer.
- Capture "before" from the commit that the change starts from. Use the same views, size, pixel ratio, quality, browser build and capture tools as "after". A capture taken later, on another build or with a changed tool, is not "before".
- A change that must not alter the rendered image is byte-exact wherever frames are deterministic. "Looks the same" or "only a few pixels" is a failure: either the change has a bug, or it changes the image and that part belongs in its own commit.
- Use a tolerance only for frames that cannot be deterministic by construction, such as temporal accumulation, or the GPU splitting work on its own. Set the tolerance by comparing the same build with itself, and prove that it fails planted regressions (step 4). Never widen a tolerance, or recapture until a run passes, to make a failure go away.
- Capture a frame only when the app reports that the frame is final (paused and settled). A fixed wait or frame count passes or fails by chance on a busy GPU.
- Compare decoded pixels, never image files: encoders differ.
- Read crops of the subjects as well as the whole frame. Report a mean over the frame (including a perceptual metric's mean), but never use it to pass a change: it hides a missing small object.
- A view proves nothing about what it does not show. Zero difference counts only in views that show what the change touches.
- Report numbers: the pixel count over each level, the largest difference, and where it lies, per view and per crop.
- If the same build disagrees with itself, this skill does not apply: stop and use
diagnosing-nondeterministic-frames.
The project's facts: the binding
Steps marked "(binding: X)" need facts about the project: which checks follow which kind of change,
its views and test scenes, its capture, comparison and reference tools, its test mode, how a
history-dependent effect is registered, and how results are reported. When you reach the step, read
section X of docs/bindings/verifying-rendering-changes.md. If the project's AGENTS.md or
CLAUDE.md names another file for this skill, that file wins.
If there is no binding, find each fact in the project: its screenshot or golden-image tests, a paused or test mode in its URL options or debug globals, its image-diff tool, and the checks its commit hooks run. Ask the user for what you cannot find, above all whether frames are deterministic and who accepts new reference images. When the work ends, offer to write what you found as the binding, one section per step.
Workflow
Copy this checklist and keep it up to date:
- [ ] 1. Name the kind of change
- [ ] 2. Choose the views and checks, cheapest first
- [ ] 3. Capture before
- [ ] 4. Compare
- [ ] 5. Judge a change meant to change the rendered image
- [ ] 6. A history-dependent or temporal effect
- [ ] 7. Run the regular checks and report
1. Name the kind of change (binding: Kinds)
| Kind | Examples | What proves it |
|---|---|---|
| Must not change a pixel | A refactor, a rename, a move between files, a speed-up, a tool change, a cleanup | Bit-identical frames in views that show the changed code; evidence that needs no GPU first (identical generated shader text, CPU checks) |
| Meant to change the rendered image | A new effect, a material, a light or look value, a defect fix | The intended difference, measured where it was meant; bit-identical frames elsewhere |
| Different content | New random seeds, a regenerated or grown world, other geometry | Pixels cannot line up: judge by eye and by region statistics, not by pixel difference |
| History-dependent or temporal | Accumulation over frames, exposure adaptation, temporal anti-aliasing, a simulation stepped per frame | Step 6, then the comparison of the kind above that it falls under |
If a change is of two kinds (a speed-up that also changes the image), split it into two commits and verify each as its kind. Some correct changes can alter a few pixels on some GPUs: a change to how work is split into draws, or to the order in which shaders are first built. The binding names these cases. Measure and report them; do not call them identical.