# Flutter Perf Rendering Effects

> Use when DevTools shows high raster time or janky raster frames. Optimises only where profiling or implementation evidence shows real cost, and keeps the visual design materially unchanged. Investigates expensive Flutter visual effects and raster cost: Opacity, BackdropFilter, blur, clipping (ClipRRect, ClipPath), large or layered shadows, overlapping transparency, saveLayer, and continuously animated effects. Do not use for UI-thread rebuild problems (flutter-perf-build-and-rebuild).

- Skill: `kinwisenz-devops/flutter-perf-rendering-effects` (Agent Skill)
- Install (CLI): `npx get-skill add kinwisenz-devops/flutter-perf-rendering-effects`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kinwisenz-devops/flutter-perf-rendering-effects/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: KinwiseNZ-DevOps (https://skillmd.com/u/kinwisenz-devops)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/kinwisenz-devops/flutter-perf-rendering-effects

---


# 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](../flutter-perf-profiling-and-validation/SKILL.md).

## 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.

