Engine & Frame Pipeline

shouldRepaint runs when a new painter instance replaces the old one, typically after a rebuild. Return true only if the new painter would draw something different, by comparing its fields with oldDelegate's. Always true wastes repaints; always false leaves stale drawings.

Keep the samples in a ChangeNotifier owned by the State and pass it to the painter's super(repaint: ...). Each notifyListeners makes RenderCustomPaint call markNeedsPaint, so only paint runs: no setState, no build, no layout.

Each frame, SchedulerBinding runs transient callbacks (animation ticks), then their microtasks, then persistent callbacks that rebuild dirty elements, lay out, paint into a layer tree and composite it, then post-frame callbacks. The raster thread draws the resulting scene.

The UI thread runs Dart (build, layout, paint) and produces a layer tree; the raster thread renders it through the GPU. Since Flutter 3.29 on iOS and Android, Dart runs on the platform main thread; rasterizing stays separate.

Impeller is the engine's rendering runtime. Skia compiled shaders just in time, so an effect's first use could stall a frame; Impeller precompiles a smaller shader set when the engine is built and creates pipelines upfront, ending that first-run jank.

Rebuilding only allocates small immutable widget objects. The long-lived elements are reused and handed the new widgets; an identical widget stops the walk, and render object setters mark layout or paint only for values that actually changed.

CustomPaint is the widget that sizes and hosts the drawing; a CustomPainter is the delegate that draws. A painter implements paint(Canvas, Size) to draw inside that size, and shouldRepaint(oldDelegate) to say whether a new instance needs a repaint.

setState only marks the widget dirty; the list is rebuilt and laid out in the next frame, so maxScrollExtent read immediately still describes the old list. Scroll inside WidgetsBinding.instance.addPostFrameCallback, which runs after that frame's layout.

The framework (Dart) turns widgets into a layer tree; the engine (C++) runs Dart, exposes dart:ui and rasterizes scenes with Impeller; the platform embedder hosts the engine in a native app, providing the surface, threads, input and lifecycle.

Without a child, CustomPaint asks for its size argument, Size.zero by default, so loose constraints give the painter an empty box. Drawing outside size is not reliably clipped, so clip to Offset.zero & size, and keep save and restore balanced.

iOS and macOS: Impeller on Metal. Android API 29+: Impeller on Vulkan, else Impeller's OpenGL ES backend; below API 29, Skia on OpenGL ES. Windows and Linux: Impeller since 3.47, over OpenGL. Web: Skia.

markNeedsLayout schedules layout and then paint, and can spread up to ancestors whose layout depends on this size. markNeedsPaint only repaints up to the nearest repaint boundary. Call markNeedsLayout when size or child positions change, markNeedsPaint when only pixels change.

A ComponentElement builds one child widget and owns no render object; stateless, stateful and inherited widgets create one. A RenderObjectElement owns a render object and keeps it in sync; Leaf, SingleChild and MultiChild RenderObjectWidgets create one.

An element is created and mounted when its widget first appears, updated in place when a compatible new widget arrives, deactivated into an inactive list when removed, and unmounted at the end of the frame unless something reclaims it.

addPostFrameCallback does not request a frame. On an idle screen, the callback waits until something else, such as a touch or an animation, schedules one. Request a frame too, with SchedulerBinding.instance.ensureVisualUpdate(), or await SchedulerBinding.instance.endOfFrame.

RepaintBoundary gives its subtree its own layer: a repaint inside no longer repaints ancestors, and an ancestor repaint reuses its recorded content. It helps where parent and child repaint at different times and only adds cost where they repaint together.

First-run-only stutter is the signature of just-in-time shader compilation, which Impeller removes. So check which renderer the affected devices use (Android below API 29 still runs Skia); on Impeller devices, hunt other one-time costs such as image decoding.

performLayout lays out children, positions them via parentData and sets a size within the constraints. Set sizedByParent only when size depends on constraints alone. Implement computeDryLayout whenever a parent may ask your size without laying you out; it must match performLayout.

Write a custom RenderBox only when composition, CustomPaint and layout delegates cannot express the layout, hit testing or performance you need. You then own layout, painting, hit testing, dry layout, intrinsics and semantics yourself.

createRenderObject builds the render object once, from every widget field and any context values. updateRenderObject must copy the same fields onto the existing object on every update; left empty, the UI keeps showing the first configuration after rebuilds.

A RenderBox lays out, paints and hit-tests. It sets its size from the parent's BoxConstraints in performLayout, draws in paint(PaintingContext, Offset), and answers pointer hits through hitTestSelf and hitTestChildren.

List the .frag file under flutter: shaders: in pubspec.yaml, load it once with FragmentProgram.fromAsset, create a FragmentShader, set uniforms with setFloat in declaration order, and draw with Paint()..shader = shader in paint. The tool compiles the shader at build time.

Use flutter run --no-enable-impeller for a debug session, or the per-platform build switch such as Android's EnableImpeller manifest entry. iOS has no opt-out and the others are slated for removal, so the switch only isolates the bug.

The parent installs a parentData object on each child in setupParentData, writes each child's position into it during performLayout, paints each child at offset plus that position, and hit-tests children in reverse paint order after subtracting it.