Flutter Performance Overlay

WHY IT EXISTS: Flutter renders frames by running two pipelines in parallel. The UI thread executes your Dart code to build widgets, perform layout, and record drawing commands. The raster thread takes those commands and turns them into actual pixels on the GPU. If either thread takes longer than the frame budget, the display skips, producing jank. Because the two threads are completely separate bottlenecks, guessing which one is slow wastes time. The Performance Overlay exists to eliminate that guesswork by showing you the exact cost of each frame on both threads at a glance.

THE MENTAL MODEL: Think of it as a pair of speedometers for a two-lane assembly line. The top gauge measures how fast the factory packs the box, and the bottom gauge measures how fast the truck delivers it. If deliveries are late, you do not send more packers; you fix the truck route. The overlay lets you see which lane is backed up so you tune the right stage.

HOW IT WORKS: Enabling the overlay paints two horizontal bar charts on top of your running app. Each vertical bar represents one frame. The height of the bar is the time that frame spent on its thread. A horizontal reference line marks the target budget, roughly 16 milliseconds for 60 Hz displays. Bars that stay below the line are smooth frames; bars that spike above it are jank. The top graph is the UI thread, covering widget builds, layouts, and paint records. The bottom graph is the raster thread, covering shader compilation, texture uploads, and GPU command execution. In profile mode, the data is accurate; in debug mode, Dart assertions and checks distort the timings, so the overlay is only trustworthy when running a profile build.

WHEN TO USE IT: Enable it during interactive work like list scrolling, page transitions, or hero animations. It is most valuable on physical devices, since emulators and simulators use the host machine's GPU and do not reproduce real raster thread behavior. Use it after you apply a performance fix to get immediate visual confirmation that frame times dropped. It is also the fastest way to triage a stutter before you open the full DevTools timeline.

WHEN NOT TO USE IT: Do not ship it in production; it is a development and profile-mode diagnostic. Do not rely on it for sub-method profiling, because it only shows aggregate frame time, not which function is slow. Avoid drawing conclusions from debug builds, where the JIT compiler and extra assertions inflate UI thread times. And do not test GPU-bound performance on an iOS simulator or Android emulator, because the raster numbers will mislead you.

ONE CANONICAL EXAMPLE: Imagine a vertically scrolling list of high-resolution network images. You notice stuttering and enable the Performance Overlay. The top UI graph stays low, but the bottom raster graph repeatedly spikes above the 16 ms line. This tells you the GPU is drowning in texture work, not that your list builder is inefficient. The fix is to resize images to the display size and use a caching strategy, which drops the raster bars back under the budget without changing a single widget.