Rendering Effects
These effects are not forbidden. Investigate, then act only on evidence.
1. Locate the cost
- Profile mode, DevTools performance view: is the janky time in raster rather than UI?
- Use the raster/layer diagnostics available in DevTools (e.g. save-layer and repaint tooling) to find which widgets trigger offscreen layers.
- Static scan for:
Opacity, BackdropFilter, ImageFiltered, ClipRRect, ClipPath, large blurRadius in BoxShadow, transparency stacked over transparency, always-running animations.
saveLayer() allocates an offscreen buffer and can force a render target switch, which is costly on mobile GPUs. Widgets and packages can call it without your code doing so. Besides Opacity and the effects above, check ShaderMask, ColorFilter, Chip (when disabledColorAlpha != 0xff) and Text (when it has an overflowShader). To see where it happens, use the PerformanceOverlayLayer.checkerboardOffscreenLayers switch in the DevTools Performance view. If a package you do not own causes it, ask the owner why before replacing it.
If the raster thread is fine, leave the effect alone and record it under <not_changed>.
2. Targeted remedies (apply only to a confirmed hotspot)
| Cost |
Lower-cost option to evaluate |
Opacity over a subtree |
Apply opacity to a single leaf, use AnimatedOpacity/FadeTransition for animation, or fold alpha into the colour (Color.withValues(alpha:)/withOpacity) on a plain box or text |
BackdropFilter |
Limit to the smallest area; avoid inside scrolling lists; avoid animating its sigma; consider a static blurred or tinted alternative only if a visual compromise is acceptable |
| Clipping |
Avoid clipping where borderRadius on a DecoratedBox/Container gives the same result; use the cheapest clipBehavior that is visually correct. Clipping defaults to Clip.none, and only Clip.antiAliasWithSaveLayer calls saveLayer() |
| Clipping inside an animation |
Avoid it; pre-clip the image before animating it |
| Fading an image in |
FadeInImage, or apply opacity directly to the image, rather than wrapping it in an Opacity widget |
| Two overlapping semi-transparent shapes |
If they always overlap the same way, precalculate and cache the combined result, or repaint to avoid the overlap |
| Large shadows |
Reduce blur radius or layer count, or pre-render only if profiling justifies it |
| Looping animations |
Stop when off-screen; scope repaint with RepaintBoundary where profiling shows a benefit |
RepaintBoundary is a tool, not a default: add it only where repaint tracing shows an isolated subtree repainting needlessly.
3. Design preservation
Visual design must remain materially unchanged. If a compromise is truly required (e.g. dropping blur on low-end devices), state it explicitly in the report as a visual trade-off and get it noted, never slip it in silently.
4. Verify
Compare raster frame times before/after on a representative physical device in profile mode, and a visual comparison of the affected screen. Method: flutter-perf-profiling-and-validation.
Hard rules
- Act only on what the user asked. Before answering or changing anything, open the relevant files and check what is already done; report only what you checked, never guess, and do not redo finished work. Reason: guesses and repeated work waste the user's credit.
1---2name: flutter-perf-rendering-effects3description: >4 Use when DevTools shows high raster time or janky raster frames. Optimises5 only where profiling or implementation evidence shows real cost, and keeps the6 visual design materially unchanged. Investigates expensive Flutter visual7 effects and raster cost: Opacity, BackdropFilter, blur, clipping (ClipRRect,8 ClipPath), large or layered shadows, overlapping transparency, saveLayer, and9 continuously animated effects. Do not use for UI-thread rebuild problems10 (flutter-perf-build-and-rebuild).11metadata:12 source: https://skillmd.com/skills/kinwisenz-devops/flutter-perf-rendering-effects13---1415# Rendering Effects1617These effects are not forbidden. Investigate, then act only on evidence.1819## 1. Locate the cost2021- Profile mode, DevTools performance view: is the janky time in **raster** rather than UI?22- Use the raster/layer diagnostics available in DevTools (e.g. save-layer and repaint tooling) to find which widgets trigger offscreen layers.23- Static scan for: `Opacity`, `BackdropFilter`, `ImageFiltered`, `ClipRRect`, `ClipPath`, large `blurRadius` in `BoxShadow`, transparency stacked over transparency, always-running animations.2425`saveLayer()` allocates an offscreen buffer and can force a render target switch, which is costly on mobile GPUs. Widgets and packages can call it without your code doing so. Besides `Opacity` and the effects above, check `ShaderMask`, `ColorFilter`, `Chip` (when `disabledColorAlpha != 0xff`) and `Text` (when it has an `overflowShader`). To see where it happens, use the `PerformanceOverlayLayer.checkerboardOffscreenLayers` switch in the DevTools Performance view. If a package you do not own causes it, ask the owner why before replacing it.2627If the raster thread is fine, leave the effect alone and record it under `<not_changed>`.2829## 2. Targeted remedies (apply only to a confirmed hotspot)3031| Cost | Lower-cost option to evaluate |32|---|---|33| `Opacity` over a subtree | Apply opacity to a single leaf, use `AnimatedOpacity`/`FadeTransition` for animation, or fold alpha into the colour (`Color.withValues(alpha:)`/`withOpacity`) on a plain box or text |34| `BackdropFilter` | Limit to the smallest area; avoid inside scrolling lists; avoid animating its sigma; consider a static blurred or tinted alternative only if a visual compromise is acceptable |35| Clipping | Avoid clipping where `borderRadius` on a `DecoratedBox`/`Container` gives the same result; use the cheapest `clipBehavior` that is visually correct. Clipping defaults to `Clip.none`, and only `Clip.antiAliasWithSaveLayer` calls `saveLayer()` |36| Clipping inside an animation | Avoid it; pre-clip the image before animating it |37| Fading an image in | `FadeInImage`, or apply opacity directly to the image, rather than wrapping it in an `Opacity` widget |38| Two overlapping semi-transparent shapes | If they always overlap the same way, precalculate and cache the combined result, or repaint to avoid the overlap |39| Large shadows | Reduce blur radius or layer count, or pre-render only if profiling justifies it |40| Looping animations | Stop when off-screen; scope repaint with `RepaintBoundary` where profiling shows a benefit |4142`RepaintBoundary` is a tool, not a default: add it only where repaint tracing shows an isolated subtree repainting needlessly.4344## 3. Design preservation4546Visual design must remain materially unchanged. If a compromise is truly required (e.g. dropping blur on low-end devices), state it explicitly in the report as a visual trade-off and get it noted, never slip it in silently.4748## 4. Verify4950Compare raster frame times before/after on a representative physical device in profile mode, and a visual comparison of the affected screen. Method: [flutter-perf-profiling-and-validation](../flutter-perf-profiling-and-validation/SKILL.md).5152## Hard rules5354- Act only on what the user asked. Before answering or changing anything, open the relevant files and check what is already done; report only what you checked, never guess, and do not redo finished work. Reason: guesses and repeated work waste the user's credit.