Critical Rendering Path: Prepaint

Prepaint is the RenderingNG pipeline stage that performs an in-order traversal of Blink’s LayoutObject tree to build four property trees and compute paint invalidations¹. It is the architectural seam between layout geometry and visual rendering: it factors visual effect state (transforms, clips, filters, scroll offsets) out of the layer tree so the compositor can update an element’s on-screen position by mutating a single property tree node — without re-walking layout or paint.

Mental model

Prepaint does two independent jobs in one tree walk¹:

1. Build property trees. PaintPropertyTreeBuilder constructs four sparse trees — transform, clip, effect, scroll — where each node represents a CSS property that creates a new coordinate space, clip region, or visual effect. Every FragmentData ends up holding a PropertyTreeState: a 4-tuple (transform, clip, effect, scroll) of pointers to its nearest ancestor nodes in each tree².
2. Compute paint invalidation. PaintInvalidator compares each visited object’s current visual state against the cached state, marking any DisplayItemClient that needs to be re-recorded by the Paint stage¹.

The Layout stage already produced a LayoutObject tree and an immutable Fragment Tree of resolved geometry. The Paint stage cannot start until property trees exist (because every paint chunk is grouped by PropertyTreeState) and until it knows which display items are stale. Prepaint sits in that gap.

Why this matters: from O(layers) to O(affected nodes)

In pre-RenderingNG Chromium, visual properties were baked into a monolithic Layer Tree: each composited layer stored its own transform matrix, clip rect, and effect values. Computing the on-screen state of any element required multiplying matrices through every ancestor layer — an O(layers) operation on every commit.

The Slimming Paint project (2015–2021) incrementally replaced that model with the four property trees, in five named milestones³:

The aggregate result, per the Chromium project page³:

• 22,000 lines of C++ removed.
• −1.3% total Chrome CPU usage.
• +3.5% improvement to 99th percentile scroll-update latency.
• +2.2% improvement to 95th percentile input delay.

These numbers compound across every Chromium-based browser. Prepaint is what makes them possible: by the time the compositor needs to scroll, animate, or hit-test, the only thing it has to mutate is a property tree node, not a slab of layer state.

Property tree architecture

PaintPropertyTreeBuilder constructs four trees during the walk. Each tree is sparse — most elements share their parent’s nodes. A new node is created only when CSS forces one (a transform, an overflow clip, an opacity below 1, a scrollable container, etc.).

The tree topology mostly mirrors the DOM, but each tree has its own scoping rules. The split into four trees exists because scrolling and visual effects do not have the same containment semantics: position: fixed/absolute descendants escape ancestor scrollers but still inherit ancestor visual effects, so scroll containment cannot share a topology with effect containment².

Transform tree

Stores the 4×4 transformation matrices that move and reshape coordinate spaces. A node is created for any non-none transform, translate, rotate, scale, perspective, scroll offset, or fixed-position adjustment. Each node records the local transform matrix, transform origin, whether the inherited transform is flattened to 2D or preserved in 3D, and which 3D rendering context it joins².

Separating transforms into a dedicated tree is what makes off-main-thread compositor updates cheap: the compositor mutates a single node and re-multiplies lazily at draw time, instead of eagerly rebuilding inherited matrices on the main thread.

1.transformed-parent {2  transform: translateZ(0); /* any transform, even identity */3}45.supposedly-fixed {6  position: fixed; /* positioned relative to .transformed-parent, not the viewport */7  top: 0;8  left: 0;9}

Clip tree

Represents overflow clips — axis-aligned rectangles, optionally with rounded corners². New nodes are created by overflow: hidden|scroll|auto|clip and by border-radius rounding on a clipping container.

Keeping clip nodes separate from transform nodes lets the compositor change a scroll offset (a transform mutation) without recomputing the clip rect that defines the visible viewport of the scroller.

Effect tree

Represents every visual effect that is not a transform and not a simple overflow clip: opacity, CSS filter, backdrop-filter, blend modes, masks, and clip-path². Each node carries the alpha, filter list, blend mode, and an optional mask reference.

The effect tree is what enables transparency groups: an opacity < 1 requires that the entire descendant subtree be composited together before the alpha is applied, so the compositor needs an explicit “begin/end transparency group” boundary. Without a dedicated effect tree, the compositor could not distinguish “apply opacity to this subtree” from “apply opacity to each element individually.”

Scroll tree

Encodes scrollable regions, their offsets, and how scrolls chain together. Each node records which axes scroll, the container size vs. content size (which determines scrollbar presence), and the parent in the scroll-chain hierarchy².

Crucially, the scroll offset is not stored directly in the scroll node — it lives in a paired transform-tree node². That indirection is the unification trick: the compositor’s general-purpose transform pipeline applies scroll position the same way it applies any other 2D translation, which is what makes off-main-thread scrolling work even while the main thread is blocked.

PropertyTreeState: the per-element 4-tuple

After Prepaint, every FragmentData carries a PropertyTreeState:

1PropertyTreeState = (transform_node, clip_node, effect_node, scroll_node)

Each entry points at the nearest ancestor node in the corresponding tree². Because the trees are sparse, most elements share their parent’s tuple — a deeply nested <span> with no visual properties of its own simply inherits its block parent’s PropertyTreeState. Only elements whose CSS forces a node (transform, clip-path, opacity, filter, scroll, etc.) get a new entry in any tree.

Multi-column and paginated layouts complicate this slightly: a single LayoutObject can have multiple FragmentData instances (one per column), and each fragment gets its own PropertyTreeState¹.

This tuple is also what the Paint stage uses to group display items into paint chunks — the unit at which the compositor decides what becomes a cc::Layer¹.

PrePaintTreeWalk

PrePaintTreeWalk performs an in-order, depth-first traversal starting at the root FrameView and crossing iframe boundaries. The in-order ordering matters because property tree relationships depend on DOM ancestry — specifically, on the parent containing block — and that information is cheapest to compute as you descend¹.

For each visited LayoutObject:

1. Dirty bit gate. If NeedsPaintPropertyUpdate, SubtreeNeedsPaintPropertyUpdate, or DescendantNeedsPaintPropertyUpdate is unset, the subtree is skipped entirely¹.
2. Property tree update. PaintPropertyTreeBuilder creates or refreshes the nodes that this object owns. New nodes are created only when CSS demands them (e.g. transform, clip-path, opacity < 1, overflow: scroll).
3. FragmentData population. Each fragment receives an ObjectPaintProperties pointing at its newly resolved property tree nodes. Multi-column layouts produce multiple fragments per object¹.
4. Paint invalidation. PaintInvalidator compares current vs. cached visual state and marks any stale DisplayItemClient¹.

Dirty bits

Three flags on LayoutObject control how much of the tree the walk has to touch¹:

On a 10,000-element page where one element’s background colour changed, Prepaint only visits the dirty path from the root down to that element — the rest of the subtree is gated out by these flags. Topology-changing updates are more expensive: when a transform is added or removed, Prepaint sets SubtreeNeedsPaintPropertyUpdate, walks every descendant, and reparents their transform tuple to the new node¹. The same is true for any property that introduces or removes a property-tree node — opacity crossing 1.0, overflow changing to/from visible, clip-path toggling, etc. This is exactly what contain: paint mitigates (next subsection).

Isolation boundaries

contain: paint establishes an isolation boundary in all three of the transform/clip/effect trees by inserting alias nodes that act as descendant roots¹. The walk treats the boundary as a wall: changes outside the boundary cannot reparent nodes inside it, so a SubtreeNeedsPaintPropertyUpdate flag from above the boundary stops at the boundary. Large widget subtrees can be effectively excluded from most cross-document mutations this way.

The example below (adapted from the Blink paint README¹) walks a tree where element 3 gets a new transform and element 5 carries contain: paint:

Quick update path

For a small but very common class of style changes — pure transform or opacity mutations with no layout consequences — Prepaint skips the full property tree builder entirely. During PaintLayer::StyleDidChange, qualifying changes are added to a pending list; later, in PrePaintTreeWalk::WalkTree, those updates are applied directly to the existing nodes without re-running the builder¹.

The shortcut is one half of why CSS animations on transform and opacity are smooth even on a busy main thread; the other half is that those same two properties are exactly the ones the compositor can mutate on its own thread (covered below).

Paint invalidation

The second output of Prepaint is the set of dirty display item clients that the Paint stage will re-record. PaintInvalidator compares, for each visited LayoutObject, the current vs. cached versions of¹:

• computed style,
• geometry (paint offset, visual rect),
• property tree state.

Where they differ, the corresponding DisplayItemClient is marked dirty. Paint only re-records dirty items; everything else is reused from the PaintController’s cache.

Invalidation operates at two granularities¹:

1. Paint chunk level. A paint chunk groups consecutive display items that share a PropertyTreeState. If chunks no longer match in order, or the property tree state changed, the entire chunk is invalidated.
2. Display item level. When chunks still match in order and property trees are unchanged, individual display items are compared so background-only or text-only changes invalidate just the affected item.

A practical illustration: changing only an element’s background-color invalidates a single display item and reuses the rest of its chunk. Changing only its transform invalidates the chunk’s property tree state but typically allows the chunk’s display items themselves to be reused (the chunk simply moves under a different transform node).

Compositor-driven animations: bypassing the main thread

The architectural payoff of property trees is that animations affecting only transform or opacity can run entirely on the compositor thread, skipping layout, prepaint, and paint per frame⁷. The compositor’s AnimationHost produces output values from AnimationCurves and writes them directly into property tree nodes; the new transform/opacity is applied at draw time⁸.

Why only transform and opacity? Because they cannot affect layout geometry or paint order. Anything else (width, left, top, margin, …) requires re-running layout — and therefore the full main-thread pipeline — every frame.

1/* Compositor-driven: stays smooth even when the main thread is blocked */2.smooth {3  animation: slide 1s;4}5@keyframes slide {6  to {7    transform: translateX(100px);8  }9}1011/* Main-thread animation: janks whenever the main thread is busy */12.janky {13  animation: slide-left 1s;14}15@keyframes slide-left {16  to {17    left: 100px;18  }19}

Edge cases worth internalising

will-change is not free

will-change: transform (or any other compositor-promoting property) tells the engine to allocate a separate composited layer up-front, including texture memory and bookkeeping. Applying it to many elements simultaneously exhausts GPU memory and produces checkerboarding (white tiles during scroll)⁹.

1/* Memory explosion — promotes every list item to its own layer */2.list-item {3  will-change: transform;4}56/* Promote only while actually animating */7.list-item.animating {8  will-change: transform;9}

The general rule: add will-change immediately before an animation begins, remove it as soon as the animation ends.

contain: paint confines position: fixed

contain: paint clips painted content to the box and prevents position: fixed descendants from escaping⁴:

1.container {2  contain: paint;3}45.tooltip {6  position: fixed; /* still positioned relative to .container */7}

This is exactly the isolation-boundary behaviour described earlier — useful for widget isolation, surprising for “why won’t my modal escape?”.

filter: blur(0) still has side effects

A no-op filter value still creates a stacking context, a containing block, and an effect-tree node. Using filter: blur(0) as a “force GPU” trick has stopped helping years ago and now actively costs compositing memory and changes positioning semantics⁴.

Performance debugging

In Chrome DevTools’ Performance panel, Prepaint shows up as Pre-paint (older traces still call it “Update Layer Tree”). What to look for:

• Long pre-paint slices (>5 ms) — usually a deep dirty subtree, often caused by mutating a high-up element’s transform or by toggling contain on/off.
• Repeated pre-paint every frame — typically a requestAnimationFrame callback writing layout-affecting properties.

Practical levers:

• Apply contain: layout paint (or contain: strict / content) on widget roots. It both bounds dirty-bit propagation and creates an isolation boundary¹.
• Batch transform/opacity mutations inside requestAnimationFrame; the quick-update path applies once per frame instead of once per write.
• Avoid layout-triggering animation properties (width, height, top, left, margin). Use transform: translate() and opacity instead.
• Use the Layers panel in DevTools to inspect composited layers and their reasons; excessive layers usually means too aggressive will-change use.

Practical takeaways

• Prepaint is the bridge from layout geometry to paint and compositing. It is structural (build property trees) and bookkeeping (compute paint invalidation) at the same time, in one walk.
• The four trees exist because scrolling and visual effects have different containment rules. Knowing which property goes in which tree predicts which compositor optimisations apply.
• The dirty-bit system plus isolation boundaries is what keeps Prepaint cheap on real-world pages. contain: paint is your strongest lever for isolating widget subtrees.
• The quick-update path makes transform and opacity the only animation properties that consistently stay on the compositor thread. Design animations around that.
• Off-main-thread scrolling is a property of the scroll tree, not magic. Non-passive wheel/touch handlers throw it away.

Appendix

Prerequisites

• Critical Rendering Path: Overview — the full RenderingNG pipeline from HTML to pixels.
• Critical Rendering Path: Style Recalculation — how the LayoutObject tree and computed styles are produced.
• Critical Rendering Path: Layout — how the Fragment Tree is built.
• Familiarity with CSS visual effects: transform, opacity, filter, overflow, contain.

Next in the series

• Critical Rendering Path: Paint — display-item recording and paint chunks (the consumer of Prepaint’s outputs).
• Critical Rendering Path: Compositing — how cc mutates the property trees off the main thread to scroll and animate.

Terminology

Footnotes