Index: third_party/WebKit/Source/platform/graphics/paint/README.md |
diff --git a/third_party/WebKit/Source/platform/graphics/paint/README.md b/third_party/WebKit/Source/platform/graphics/paint/README.md |
index 5e5fb62e611d3da49e2fc75fabbf30f04aef0a56..89b97695cd8cf3095032d155a2e654def63cd6aa 100644 |
--- a/third_party/WebKit/Source/platform/graphics/paint/README.md |
+++ b/third_party/WebKit/Source/platform/graphics/paint/README.md |
@@ -179,9 +179,48 @@ replaced with the cached content from the previous artifact. |
At this point, the paint artifact is ready to be drawn or composited. |
-*** aside |
-TODO(jbroman): Explain invalidation. |
-*** |
+### 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`. |
+ |
+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. When it overflows, we may treat some |
chrishtr
2016/04/29 15:55:17
This is only with one PaintController. Could be le
Xianzhu
2016/04/29 16:37:11
Yes. Added a sentence for this fact.
|
+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 not been painted since cache generation n; |
+* when the cache generation wraps back to exact n (after several years), the |
+ object happens to be painted again and treated as cached. |
+As the paint controller doesn't have cached display items for the object, there |
+will be corrupted painting or assertion failure. The chance is too low to be |
+concerned. |
+ |
+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) so the performance penalty is trivial. |
## Paint artifact compositor |