Create PaintChunk and begin writing code to build paint chunks.

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

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
new file mode 100644
index 0000000000000000000000000000000000000000..4792885b77a5730c59522f02ac0838775f4054a6
--- /dev/null
+++ b/third_party/WebKit/Source/platform/graphics/paint/README.md
@@ -0,0 +1,110 @@
+# 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
+drawings, and a list of paint chunks, stored together.
+
+This document explains the SPv2 world as it develops, not the SPv1 world it
+replaces.
+
+[paint-team-site]: https://www.chromium.org/developers/paint-team
+
+## Paint artifact

[pdr., 2015/10/01 00:32:48]

Because the display item list will require intimate knowledge of the paint
chunks (for merge), I think we'll end up using DIL as the paint artifact. Is
that your thinking too, or do you think we can extract the merge logic out of
the list into a paint artifact class? Alternatively, rename DisplayItemList to
PaintArtifact and create a simple wrapper around a vector of display items?

[jbroman, 2015/10/01 18:04:20]

In my ideal world, DisplayItemList would become something like
PaintArtifactBuilder, to reflect that its role is the stateful work of
constructing new paint artifacts (including keeping around the old one), and one
would use PaintArtifactBuilder::paintArtifact() to get access to the latest
artifact, which would be a { chunks, drawings } class.

blink::DIL is currently much more than a single list, and the name suggests more
similarity to cc::DisplayItemList than there is (the latter is closer to
blink::DisplayItems).

I'm not upper-casing it here, because the current "artifact" is currently called
DisplayItemList::displayItems(), but this is how I think of it.

+
+The SPv2 paint artifact consists of a list of display items (ideally mostly or
+all drawings), partitioned into *paint chunks* which define certain certain

[pdr., 2015/10/01 00:32:48]

Nit: remove either the first or the second certain

[jbroman, 2015/10/01 18:04:20]

Done.

+*paint properties* which affect how the content should be drawn or composited.
+
+## Paint properties
+
+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.
+
+*** note
+Support for all paint properties has yet to be implemented in SPv2.
+***
+
+*** aside
+TODO(jbroman): Explain the semantics of transforms, clips, scrolls and effects
+as support for them is added to SPv2.
+***
+
+## Display items
+
+A display item is the smallest unit of a display list in Blink. Each display
+item is identified by an ID consisting of:
+
+* an opaque pointer to the *display item client* that produced it
+* a type (from the `DisplayItem::Type` enum)
+* a scope number
+
+*** aside
+TODO(jbroman): Explain scope numbers.
+***

[trchen, 2015/10/01 02:19:36]

I'm actually trying to eliminate scope. Basically scope used to make ID unique
when a layout object can generate nonpredetermined number of display items. One
notable case is multicol.

Fortunately for multicol and reflection the recording will be exactly the same
(with different interest rect though), so a better solution is to make a special
transform node to do the replication.

Another application is used by SVGShapePainter to paint markers. I don't
understand SVG that well, but I suspect we can let LayoutSVGResourceMarker to
own display items so scope won't be needed.

[pdr., 2015/10/01 02:29:03]

I didn't realize how rare scopes are. I can remove the SVGShapePainter one. If
you can remove the multicol/reflection one, we only have a painting case
remaining which seems simple. Simplicity++

+
+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.
+
+*** note
+It is illegal for there to be two display items with the same ID in a display
+item list.
+***

[trchen, 2015/10/01 02:19:36]

AFAIK the uniqueness is not enforced for metadata display items, but for drawing
display items they are required to be unique for caching to work.

[jbroman, 2015/10/01 18:04:20]

Changed to drawings.

+
+Generally, clients of this code should use stack-allocated recorder classes to
+emit display items to a `GraphicsContext`.

[pdr., 2015/10/01 00:32:48]

GraphicsContext -> DisplayItemList ?

[jbroman, 2015/10/01 18:04:20]

Well, it's a little weird, because you actually pass the GraphicsContext to the
recorder classes, which pull out the DisplayItemList. Reworded a little, though
I'm not sure it helps.

+
+### Standalone display items
+
+#### [CachedDisplayItem](CachedDisplayItem.h)
+
+If the type is `DisplayItem::CachedSubsequence`, indicates that the previous

[pdr., 2015/10/01 00:32:48]

Nit: "The type `DisplayItem::CachedSubsequence` indicates that the previous..."

[jbroman, 2015/10/01 18:04:20]

Done.

+frame's display item list contains a contiguous sequence of display items which
+should be reused in place of this `CachedDisplayItem`.
+
+*** note
+Support for cached subsequences for SPv2 is planned, but not yet implemented.
+***
+
+Otherwise, indicates that it contains a single `DrawingDisplayItem` with a

[pdr., 2015/10/01 00:32:48]

 Nit: "Other cached display items reference a single `DrawingDisplayIetm`
with..."

[jbroman, 2015/10/01 18:04:20]

Done.

+corresponding type which should be reused in place of this `CachedDisplayItem`.
+
+#### [DrawingDisplayItem](DrawingDisplayItem.h)
+
+Holds an `SkPicture` which contains the Skia commands required to draw some atom
+of content.
+
+### Paired begin/end display items
+
+*** aside
+TODO(jbroman): Describe how these work, once we've worked out what happens to
+them in SPv2.
+***
+
+## Display item list
+
+`GraphicsContext` is used to record into a `DisplayItemList`, which is

[pdr., 2015/10/01 00:32:48]

I don't quite follow the GraphicsContext reference here. Could you expand on
that a bit?

[jbroman, 2015/10/01 18:04:20]

Expanded a little.

+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 are added as content is painted.
+
+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.
+
+At this point, the paint artifact is ready to be drawn or composited.
+
+*** aside
+TODO(jbroman): Explain invalidation.
+***