Find cached display items directly during painting

third_party/WebKit/Source/platform/graphics/paint/README.md

 # Platform paint code
 
 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][paint-team-site].
 
 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
@@ skipping 116 matching lines @@
 It is illegal for there to be two drawings with the same ID in a display item
 list, except for drawings that are marked uncacheable
 (see [DisplayItemCacheSkipper](DisplayItemCacheSkipper.h)).
 ***
 
 Generally, clients of this code should use stack-allocated recorder classes to
 emit display items to a `PaintController` (using `GraphicsContext`).
 
 ### Standalone display items
 
-#### [CachedDisplayItem](CachedDisplayItem.h)
-
-See [Display item caching](../../../core/paint/README.md#paint-result-caching).
-
 #### [DrawingDisplayItem](DrawingDisplayItem.h)
 
 Holds an `SkPicture` which contains the Skia commands required to draw some atom
 of content.
 
 #### [ForeignLayerDisplayItem](ForeignLayerDisplayItem.h)
 
 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.
 
 ### Paired begin/end display items
 
 *** aside
 TODO(jbroman): Describe how these work, once we've worked out what happens to
 them in SPv2.
 ***
 
 ## Paint controller
 
 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, which is always complete (i.e. it has no
-`CachedDisplayItem` objects), and *new* display items and paint chunks, which
+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 merges the previous artifact with the new data,
-producing a new paint artifact, where `CachedDisplayItem` objects have been
-replaced with the cached content from the previous artifact.
+`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.
 
 ### Paint result caching and invalidation
 
 See [Display item caching](../../../core/paint/README.md#paint-result-caching)
 and [Paint invalidation](../../../core/paint/README.md#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.
 
-`kInvalidCacheGeneration` is a special cache generation value which matches no
-other cache generations. When a `DisplayItemClient` is invalidated, we set its
-cache generation to `kInvalidCacheGeneration`. When a `PaintController` is
-cleared (e.g. when the corresponding `GraphicsLayer` is fully invalidated), we
-also set its cache generation to `kInvalidCacheGeneration`.
+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 `PaintController`s 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:
 *   the object was painted when the cache generation was *n*;
 *   the object has been neither painted nor invalidated since cache generation
     *n*;
@@ skipping 30 matching lines @@
 visual and transformed rects of display items in the coordinate space of ancestor
 [`PropertyTreeState`](PropertyTreeState.h)s.
 
 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.