This directory contains the implementation of display lists and display list-based painting, except for code which requires knowledge of core/ concepts, such as DOM elements and layout objects.
This code is owned by the paint team.
Slimming Paint v2 is currently being implemented. Unlike Slimming Paint v1, SPv2 represents its paint artifact not as a flat display list, but as a list of drawings, and a list of paint chunks, stored together.
This document explains the SPv2 world as it develops, not the SPv1 world it replaces.
The SPv2 paint artifact consists of a list of display items in paint order (ideally mostly or all drawings), partitioned into paint chunks which define certain paint properties which affect how the content should be drawn or composited.
Paint properties define characteristics of how a paint chunk should be drawn, such as the transform it should be drawn with. To enable efficient updates, a chunk's paint properties are described hierarchically. For instance, each chunk is associated with a transform node, whose matrix should be multiplied by its ancestor transform nodes in order to compute the final transformation matrix to the screen.
Each paint chunk is associated with a transform node, which defines the coordinate space in which the content should be painted.
Each transform node has:
TransformationMatrixThe parent node pointers link the transform nodes in a hierarchy (the transform tree), which defines how the transform for any painted content can be determined.
Note that, even though CSS does not permit it in the DOM, the transform tree can have nodes whose children do not flatten their inherited transform and participate in no 3D rendering context. For example, not flattening is necessary to preserve the 3D character of the perspective transform, but this does not imply any 3D sorting.
Each paint chunk is associated with a clip node, which defines the raster region that will be applied on the canvas when the chunk is rastered.
Each clip node has:
The raster region defined by a node is the rounded rect transformed to the root space, intersects with the raster region defined by its parent clip node (if not root).
Each paint chunk is associated with a scroll node which defines information about how a subtree scrolls so threads other than the main thread can perform scrolling. Scroll information includes:
To ensure geometry operations are simple and only deal with transforms, the scroll offset is stored as a 2d transform in the transform tree.
Each paint chunk is associated with an effect node, which defines the effect (opacity, transfer mode, filter, mask, etc.) that should be applied to the content before or as it is composited into the content below.
Each effect node has:
The paret node pointers link the effect nodes in a hierarchy (the effect tree), which defines the dependencies between rasterization of different contents.
One can imagine each effect node as corresponding roughly to a bitmap that is drawn before being composited into another bitmap, though for implementation reasons this may not be how it is actually implemented.
A display item is the smallest unit of a display list in Blink. Each display item is identified by an ID consisting of:
DisplayItem::Type enum)In practice, display item clients are generally subclasses of LayoutObject, but can be other Blink objects which get painted, such as inline boxes and drag images.
Generally, clients of this code should use stack-allocated recorder classes to emit display items to a PaintController (using GraphicsContext).
Holds a PaintRecord which contains the paint operations required to draw some atom of content.
Draws an atom of content, but using a cc::Layer produced by some agent outside of the normal Blink paint system (for example, a plugin). Since they always map to a cc::Layer, they are always the only display item in their paint chunk, and are ineligible for squashing with other layers.
Placeholder for creating a cc::Layer for scrolling in paint order. Hit testing in the compositor requires both property trees (scroll nodes) and a scrollable cc::layer in paint order. This should be associated with the scroll translation paint property node as well as any overflow clip nodes.
Callers use GraphicsContext (via its drawing methods, and its paintController() accessor) and scoped recorder classes, which emit items into a PaintController.
PaintController is responsible for producing the paint artifact. It contains the current paint artifact, and new display items and paint chunks, which are added as content is painted.
Painters should call PaintController::useCachedDrawingIfPossible() or PaintController::useCachedSubsequenceIfPossible() and if the function returns true, existing display items that are still valid in the current paint artifact will be reused and the painter should skip real painting of the drawing or subsequence.
When the new display items have been populated, clients call commitNewDisplayItems, which replaces the previous artifact with the new data, producing a new paint artifact.
At this point, the paint artifact is ready to be drawn or composited.
See Display item caching and Paint invalidation for more details about how caching and invalidation are handled in blink core module using PaintController API.
We use ‘cache generation’ which is a unique id of cache status in each DisplayItemClient and PaintController to determine if the client is validly cached by a PaintController.
A paint controller sets its cache generation to DisplayItemCacheGeneration::next() at the end of each commitNewDisplayItems(), and updates the cache generation of each client with cached drawings by calling DisplayItemClient::setDisplayItemsCached(). A display item is treated as validly cached in a paint controller if its cache generation matches the paint controller's cache generation.
A cache generation value smaller than kFirstValidGeneration matches no other cache generations thus is always treated as invalid. When a DisplayItemClient is invalidated, we set its cache generation to one of PaintInvalidationReason values which are smaller than kFirstValidGeneration. When a PaintController is cleared (e.g. when the corresponding GraphicsLayer is fully invalidated), we also invalidate its cache generation.
For now we use a uint32_t variable to store cache generation. Assuming there is an animation in 60fps needing main-thread repaint, the cache generation will overflow after 2^32/86400/60 = 828 days. The time may be shorter if there are multiple animating PaintControllers in the same process. When it overflows, we may treat some object that is not cached as cached if the following conditions are all met:
SPv1 only: If a display item is painted on multiple paint controllers, because cache generations are unique, the client‘s cache generation matches the last paint controller only. The client will be treated as invalid on other paint controllers regardless if it’s validly cached by these paint controllers. The situation is very rare (about 0.07% clients were painted on multiple paint controllers in a Cluster Telemetry run (run 803) so the performance penalty is trivial.
The PaintArtifactCompositor is responsible for consuming the PaintArtifact produced by the PaintController, and converting it into a form suitable for the compositor to consume.
At present, PaintArtifactCompositor creates a cc layer tree, with one layer for each paint chunk. In the future, it is expected that we will use heuristics to combine paint chunks into a smaller number of layers.
The owner of the PaintArtifactCompositor (e.g. WebView) can then attach its root layer to the overall layer hierarchy to be displayed to the user.
In the future we would like to explore moving to a single shared property tree representation across both cc and Blink. See Web Page Geometries for more.
The GeometryMapper is responsible for efficiently computing visual and transformed rects of display items in the coordinate space of ancestor PropertyTreeStates.
The transformed rect of a display item in an ancestor PropertyTreeState is that rect, multiplied by the transforms between the display item's PropertyTreeState and the ancestors, then flattened into 2D.
The visual rect of a display item in an ancestor PropertyTreeState is the intersection of all of the intermediate clips (transformed in to the ancestor state), with the display item's transformed rect.