Rendering Pipeline #

Every time you see a button transition fading, a page scrolling, or a custom animation running smoothly in a Flutter app, a series of coordinated graphics engineering processes is running in the background. This systematic process chain is called the Rendering Pipeline — the data assembly line traveled from the declarative Dart code you write to the physical colored pixel rows on the user’s hardware screen. Understanding every detail of the phases inside the rendering pipeline is the key to writing high-performance app code, avoiding bottlenecks, and precisely diagnosing the causes of frame drops (stuttering) on both 60Hz and 120Hz devices.

Pipeline Overview #

Flutter’s rendering pipeline is designed as a two-thread assembly line working synchronously and in parallel: the UI Thread (running Dart code and the Framework) and the Raster Thread (running the C++ Engine and the GPU graphics card).

Broadly, this assembly line is divided into five sequential main phases:

flowchart TD
    subgraph UI_Thread["UI Thread (Dart Framework Phase)"]
        direction LR
        Build["1. BUILD\n(Widget Tree)"] --> Layout["2. LAYOUT\n(Constraints & Size)"]
        Layout --> Paint["3. PAINT\n(Record Canvas Drawing)"]
        Paint --> Composite["4. COMPOSITE\n(Assemble Layer Tree)"]
    end
    subgraph Raster_Thread["Raster Thread (C++ Engine & GPU Phase)"]
        Rasterize["5. RASTERIZE\n(Pixels in GPU Buffer)"]
    end
    
    Composite -->|"Send Scene via dart:ui"| Rasterize
    
    style UI_Thread stroke:#0288d1,stroke-width:2px
    style Raster_Thread stroke:#388e3c,stroke-width:2px

Phases 1 through 4 are completed entirely on the UI Thread using Dart. After the Composite phase finishes assembling the app’s visual representation, it sends that binary data to the C++ Engine on the Raster Thread to execute phase 5 (Rasterize) directly on the graphics card hardware.

VSync: The Trigger of Every Frame #

Flutter’s entire rendering pipeline is passive and reactive. That means Flutter won’t waste device battery drawing new frames continuously if there are no state changes or interactions. The main trigger that wakes and runs this pipeline cycle is a hardware signal called VSync (Vertical Synchronization).

VSync is a heartbeat signal sent by the physical display unit to the operating system, telling it the screen is ready to present a new image.

• 60Hz screens: Send a VSync signal every 16.67 milliseconds.
• 120Hz screens: Send a VSync signal every 8.33 milliseconds.

flowchart LR
    subgraph Display_60Hz["Display Refresh Rate (60Hz)"]
        direction LR
        V1["VSync 1 (0ms)"] -->|"Frame 1 (16.6ms)"| V2["VSync 2 (16.6ms)"]
        V2 -->|"Frame 2 (16.6ms)"| V3["VSync 3 (33.3ms)"]
    end
    subgraph Display_120Hz["Display Refresh Rate (120Hz)"]
        direction LR
        W1["VSync 1 (0ms)"] -->|"Frame 1 (8.3ms)"| W2["VSync 2 (8.3ms)"]
        W2 -->|"Frame 2 (8.3ms)"| W3["VSync 3 (16.6ms)"]
        W3 -->|"Frame 3 (8.3ms)"| W4["VSync 4 (25.0ms)"]
    end
        
    style Display_60Hz stroke:#0288d1,stroke-width:2px
    style Display_120Hz stroke:#388e3c,stroke-width:2px

When you trigger a state change (e.g., calling setState), Flutter registers a request for the next frame with the native platform. When the next VSync signal is sent by the OS, the Platform Embedder immediately forwards it to the Engine, which then triggers the drawFrame() callback on the Framework binding library. From there, the rendering assembly cycle begins.

Build Phase — Building the Widget Tree #

The Build phase is the first stage where your Dart code is executed on the UI Thread. The main task of this phase is assembling the user interface structure configuration in the form of a widget tree (Widget Tree).

Build Trigger Workflow #

When you call setState(), Flutter marks the Element associated with that widget as dirty. These dirty Elements are put into the dirty list queue managed by the BuildOwner object.

When the frame cycle starts from a VSync heartbeat:

1. BuildOwner processes the dirty list queue top-down (avoiding duplicate processing).
2. BuildOwner calls the build() method on every widget registered as dirty.
3. The build() function executes the new declarative Dart code to produce a new widget configuration tree.

The Reconciliation Process (Tree Diffing) #

Building thousands of new widget objects every frame sounds very slow and memory-hungry, but Flutter solves this through the Reconciliation mechanism. The actual Elements that persist in memory are the Element Tree. When a new widget is finished being built in the Build phase, Flutter compares the new widget’s configuration with the old element in memory using an efficient rule:

flowchart TD
    NewWidget["New Widget"] --> Compare{"Same type & key as Old Widget?"}
    Compare -->|"Yes (canUpdate == true)"| Update["Update Existing Element (Retain State)"]
    Compare -->|"No (canUpdate == false)"| Replace["Destroy Old Element & RenderObject\nCreate New (Reset State)"]
        
    style Compare stroke:#0288d1,stroke-width:2px

If the widget class type and identity key (Key) are the same, the old element is kept in memory and only its configuration property references are updated. This diffing process has sublinear time complexity $O(N)$, where $N$ is the number of active widgets that changed.

Optimization Using the const Keyword When you wrap a widget instantiation with the const keyword (e.g., const Text('Static Label')), you instruct the Dart compiler to create that object permanently in compile-time memory. When the parent widget rebuilds, Flutter instantly detects the reference equality of that const instance and skips the entire build process for that widget and all its children, significantly saving CPU power.

Layout Phase — Calculating Size and Position #

After the visual tree structure is agreed upon in the Build phase, Flutter must determine the physical spatial dimensions of every visual element on screen. This calculation process runs on the RenderObject Tree (not the Widget Tree) under the management of PipelineOwner.

The Constraints Go Down, Sizes Go Up Cycle #

Layout calculation in Flutter runs in a very fast single-pass system from top to bottom to avoid duplicate recalculations (backtracking). This process follows a three-stage rule:

sequenceDiagram
    autonumber
    participant Parent as Screen (Parent)
    participant Padding as Padding RenderObject
    participant Text as Text RenderObject

    Parent->>Padding: Send Constraints (maxW: 360, maxH: 640)
    Note over Padding: Subtract padding (e.g. 16px on each side)
    Padding->>Text: Send new Constraints (maxW: 328, maxH: 608)
    Note over Text: Calculate text dimensions based on font & characters
    Text-->>Padding: Return Size (width: 120, height: 20)
    Note over Padding: Add padding size (120+32, 20+32)
    Padding-->>Parent: Return new Size (width: 152, height: 52)
    Parent->>Padding: Set Position Offset (0, 0)
    Padding->>Text: Set Position Offset (16, 16)

1. Constraints Go Down: The parent sends maximum and minimum size boundaries (BoxConstraints) to its child.
2. Sizes Go Up: The child calculates its own actual size based on the parent’s constraints (e.g., text measures its word lengths) and returns those dimension sizes (Size) back up to the parent.
3. Parent Sets Position: The parent determines the child’s coordinate position (Offset) on screen based on the available space geometry. The child is not allowed to place its own coordinates unilaterally.

Layout Isolation: Relayout Boundary #

Like build, Flutter minimizes relayout calculations using the Relayout Boundary concept. If a widget’s dimensions change (e.g., a text widget lengthens because it receives new characters), this change can trigger relayout up the parent tree.

To stop this relayout propagation, Flutter establishes a Relayout Boundary around certain widgets (like fixed-size SizedBox widgets or flexible Expanded widgets). This boundary locks the relayout propagation so it doesn’t escape its area, isolating the workload to only the dirty sub-tree.

Paint Phase — Recording Drawing Instructions #

The Paint phase is responsible for composing the graphics instructions that define each element’s visual appearance.

The Paint Myth: Paint Doesn’t Draw Pixels #

There’s a common misconception: many developers think Flutter’s Paint phase directly changes screen pixel colors. That’s wrong. The Paint phase never draws pixels.

This phase purely records graphics commands into a binary display list object called a Picture. Actual pixels are only produced by the GPU graphics card in the final phase (Rasterize).

For example, the output of the Paint phase is a series of binary instructions like:

• Instruction 1: Save the current canvas state.
• Instruction 2: Draw a rectangle at coordinates $(10, 10)$ with the color blue.
• Instruction 3: Draw the text “Hello” at position $(20, 20)$ using a custom font.
• Instruction 4: Restore the initial canvas state.

PaintingContext & Canvas #

During this phase, every RenderObject receives a controller object called PaintingContext, which exposes the Canvas object. You can write drawing instructions directly by overriding the paint method at the RenderObject or CustomPainter level:

class MyCustomRenderBox extends RenderBox {
  @override
  void paint(PaintingContext context, Offset offset) {
    // Canvas acts as a binary instruction recorder
    final canvas = context.canvas;
    final paint = Paint()
      ..color = const Color(0xFFE91E63)
      ..style = PaintingStyle.fill;

    // Recording the pink circle drawing command
    canvas.drawCircle(
      offset + Offset(size.width / 2, size.height / 2),
      size.width / 3,
      paint,
    );
  }
}

Repaint Boundary: Paint Isolation #

For smooth animation performance, you should use RepaintBoundary. When a widget undergoes a visual update, by default the entire page area gets redrawn by the system.

By wrapping that dynamic widget with RepaintBoundary, you establish a display boundary that triggers the creation of a separate visual layer in memory. When the widget inside the boundary is redrawn, other static widgets outside the boundary are ignored, saving CPU work from re-recording unchanged drawing instructions.

Composite Phase — Assembling the Layer Tree #

After the Paint phase finishes recording all visual instructions into Picture objects, Flutter collects all those drawing records alongside decorative information (like transparency, area clipping, and shadow effects) to assemble them into a Layer Tree.

Why Do We Need a Layer Tree? #

Separating visuals into several layers is crucial for supporting the Retained Rendering concept. When your app moves to the next frame, the GPU doesn’t need to reprocess the entire image from scratch.

• If a layer hasn’t changed visually (e.g., a static background area), the GPU can directly call the texture cache already in its memory.
• Only changed layers (like a blinking cursor area) get their instructions updated.

Final Composition via SceneBuilder #

After all visual layers (like PictureLayer, OpacityLayer, TransformLayer, and OffsetLayer) are hierarchically arranged, the SceneBuilder object is triggered to assemble that tree into a single unified object ready for the device’s graphics card, called Scene.

flowchart TD
    subgraph LayerTree["Layer Tree"]
        direction TB
        Root["OffsetLayer (Root)"]
        Transform["TransformLayer (Scroll/Animation)"]
        PictureBG["PictureLayer (Background)"]
        RepaintL["OffsetLayer (RepaintBoundary)"]
        PictureAnim["PictureLayer (Animation)"]
        PictureStatic["PictureLayer (Static Text)"]
        
        Root --> Transform
        Transform --> PictureBG
        Transform --> RepaintL
        RepaintL --> PictureAnim
        Transform --> PictureStatic
    end
        
    LayerTree -->|"SceneBuilder"| Scene["ui.Scene (Composited Binary)"]
    Scene -->|"window.render()"| Engine["C++ Engine (Flow Compositor)"]
        
    style LayerTree stroke:#f57c00,stroke-width:2px

Once the Scene object is finished being assembled by SceneBuilder, the Framework sends this scene binary to the Engine via the ui.Window.render(scene) method call. This step marks the end of all Dart UI Thread tasks for that frame.

Rasterize Phase — Producing Pixels #

This final phase moves entirely to the Raster Thread and is executed by the C++ Engine sub-system (using Impeller or Skia), which communicates directly with the device’s GPU graphics card.

Graphics Card Execution Flow #

Once the Raster Thread receives the Scene binary data from the UI Thread:

1. The Engine breaks the Layer Tree into a series of graphics card drawing operations.
2. The Engine takes the AOT shaders previously compiled by Impeller.
3. The Engine executes GPU draw call instructions using native platform drivers (like Vulkan for Android or Metal for iOS).
4. The GPU rasterizes the image into actual colored pixels in the Framebuffer.

Screen Safety Mechanism: Double Buffering #

To prevent screen tearing — the condition where the screen displays half an old image and half a new image simultaneously — Flutter applies the Double Buffering technique:

flowchart LR
    subgraph Buffers["Double Buffering Mechanism"]
        direction LR
        BufA["Buffer A (Displayed on Screen)"]
        BufB["Buffer B (Being Rasterized by GPU)"]
        VSync{"VSync Signal?"} -->|"Yes (Swap Buffers)"| Swap["Swap Buffers"]
        Swap -->|"B becomes the screen"| BufA_New["Buffer B (Displayed)"]
        Swap -->|"A cleared for new frame"| BufB_New["Buffer A (Being Rasterized)"]
    end
        
    style Buffers stroke:#0288d1,stroke-width:2px

• Buffer A (Front Buffer): Stores the visual frame currently being actively presented to the user’s eyes on the physical screen.
• Buffer B (Back Buffer): Stores the memory area where the GPU is rasterizing pixels for the next frame in parallel.

When the VSync signal is sent by the screen hardware, the system instantly swaps the roles of the two buffers (buffer swapping). The finished rasterized image in Buffer B is presented to the screen, while Buffer A is cleared to hold the next frame’s rasterization process.

Bottlenecks and How to Identify Them #

Each rendering pipeline phase has the potential for workload overhead that can trigger visual performance degradation. The table below summarizes the types of bottlenecks, visual symptoms, and solution steps:

Pipeline Analysis Using the DevTools Performance Tab #

You can track rendering pipeline performance precisely using the Performance panel in Flutter DevTools. DevTools shows a visual bar graph for every frame:

• The top bar shows UI Thread performance (covering Build, Layout, Paint, and Composite phases).
• The bottom bar shows Raster Thread performance (the Rasterize phase).

If either bar’s height exceeds the horizontal line limit of 16.6ms (on a 60Hz screen) or 8.3ms (on a 120Hz screen), you know exactly which thread the frame drop is happening on and can direct optimization steps in a focused way.

Summary #

• VSync as the Main Trigger — Flutter’s rendering pipeline cycle is reactively awakened by the VSync signal heartbeat from the device’s physical screen.
• Five Sequential Phases — The visual data processing is divided into: Build → Layout → Paint → Composite → Rasterize.
• Sublinear Reconciliation — The Build phase compares the new widget tree with old elements in memory to save rendering using $O(N)$ time complexity.
• Single-Pass Layout — The Layout phase determines RenderObject spatial dimensions using a one-way system: “constraints go down, sizes go up, parent sets position.”
• Paint Recording — The Paint phase purely records 2D graphics instruction commands into Picture binaries, not drawing visual pixels directly.
• Layer Tree Assembly — The Composite phase collects isolated visual pictures into a unified Layer Tree structure to support retained rendering.
• GPU Rasterization — The Rasterize phase runs in parallel on the async Raster Thread to rasterize the Layer Tree into pixels in GPU memory.
• Double Buffering & DevTools — Applies double buffers to prevent screen tearing and provides a visual Performance panel in DevTools for diagnosing jank.

← Previous: Platform Embedder   Next: Skia & Impeller →