Add documentation on cc/Blink nodes, ids, and indices.

third_party/WebKit/Source/platform/graphics/compositing/PaintArtifactCompositor.cpp

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "platform/graphics/compositing/PaintArtifactCompositor.h"
 
 #include "cc/layers/content_layer_client.h"
 #include "cc/layers/layer.h"
 #include "cc/layers/picture_layer.h"
 #include "cc/playback/compositing_display_item.h"
@@ skipping 585 matching lines @@
     setupRootClipNode();
     setupRootEffectNode();
     setupRootScrollNode();
   }
 
   void setupRootTransformNode();
   void setupRootClipNode();
   void setupRootEffectNode();
   void setupRootScrollNode();
 
+  // A brief discourse on cc property tree nodes, identifiers, and current and
+  // future design evolution envisioned:
+  //
+  // cc property trees identify nodes by their |id|, which implementation-wise
+  // is actually its index in the property tree's vector of its node type. More
+  // recent cc code now refers to these as 'node indexes', or 'property tree

[chrishtr, 2017/01/04 20:54:28]

Could you land a patch that changes them to only have one naming scheme, rather
than both "node indexes" and "property tree indexes"?

[wkorman, 2017/01/04 21:22:55]

Sure, I'll look at that in a separate change and can update this comment
as part of that.

+  // indexes'. |parent_id| and |owner_id| in the cc property tree nodes are the
+  // same sort of node ids, all of which are stitched together to produce a tree
+  // representation.
+  //
+  // Note there are two other primary types of 'ids' referenced in cc property
+  // tree related logic: (1) ElementId, also known Blink-side as
+  // CompositorElementId, used by the animation system to allow tying an element
+  // to its respective layer, and (2) layer ids. There are other ancillary ids
+  // not relevant to any of the above, such as
+  // cc::TransformNode::sorting_context_id
+  // (a.k.a. blink::TransformPaintPropertyNode::renderingContextId()).
+  //
+  // There is a vision to move toward every layer having a |stable_id| instead
+  // of its current |id|. This could be represented by the layer's ElementId,

[ajuma, 2017/01/04 20:57:52]

"current |owner_id|"

[wkorman, 2017/01/04 21:22:55]

Rephrased this and next paragraph, let me know how it is now.

[ajuma, 2017/01/04 22:00:48]

Looks great, thanks!

+  // excepting that currently for performance reasons these are only assigned to
+  // layers with a composited animation. Once all layers have one, this could
+  // become the |stable_id| and the |owner_id| in each cc property tree node
+  // could then be the |stable_id| of its associated layer.

[ajuma, 2017/01/04 20:57:52]

The plan is that there won't be an associated layer, and the ElementId will come
from something like the layout object responsible for creating the property tree
node.

[wkorman, 2017/01/04 21:22:55]

See above comment.

+  //
+  // So, eventually cc property trees should not have to know anything about
+  // layer ids (once it is not assumed that each node is owned by a layer). That
+  // is, property tree nodes will have a |stable_id| and an index, but neither
+  // will correspond to a layer id. We would also like to explore moving to use
+  // a single shared property tree representation across both cc and Blink. See
+  // platform/graphics/paint/README.md for more.
+  //
+  // With the above as background, we can now state more clearly a description
+  // of the below set of compositor id generation methods: they take Blink paint
+  // property tree nodes as input and produce a corresponding cc 'node id',
+  // a.k.a., 'node index', for use as we build out the corresponding cc property
+  // tree representation.
+
   int compositorIdForTransformNode(const TransformPaintPropertyNode*);
   int compositorIdForClipNode(const ClipPaintPropertyNode*);
   int switchToEffectNode(const EffectPaintPropertyNode& nextEffect);
   int compositorIdForCurrentEffectNode() const {
     return m_effectStack.back().id;
   }
   int compositorIdForScrollNode(const ScrollPaintPropertyNode*);
 
   // Scroll offset has special treatment in the transform and scroll trees.
   void updateScrollOffset(int layerId, int scrollId);
@@ skipping 17 matching lines @@
   // have any actual children, but at present must exist in the tree.
   cc::Layer* m_rootLayer;
 
   // Maps from Blink-side property tree nodes to cc property node indices.
   HashMap<const TransformPaintPropertyNode*, int> m_transformNodeMap;
   HashMap<const ClipPaintPropertyNode*, int> m_clipNodeMap;
   HashMap<const ScrollPaintPropertyNode*, int> m_scrollNodeMap;
 
   struct BlinkEffectAndCcIdPair {
     const EffectPaintPropertyNode* effect;
+    // The cc property tree effect node id, or 'node index', for the cc effect
+    // node corresponding to the above Blink effect paint property node.
     int id;
   };
   Vector<BlinkEffectAndCcIdPair> m_effectStack;
 
 #if DCHECK_IS_ON()
   HashSet<const EffectPaintPropertyNode*> m_effectNodesConverted;
 #endif
 };
 
 void PropertyTreeManager::setupRootTransformNode() {
   // cc is hardcoded to use transform node index 1 for device scale and
   // transform.
   cc::TransformTree& transformTree = m_propertyTrees.transform_tree;
   transformTree.clear();
   cc::TransformNode& transformNode = *transformTree.Node(
       transformTree.Insert(cc::TransformNode(), kRealRootNodeId));
   DCHECK_EQ(transformNode.id, kSecondaryRootNodeId);
   transformNode.source_node_id = transformNode.parent_id;
   transformTree.SetTargetId(transformNode.id, kRealRootNodeId);
   transformTree.SetContentTargetId(transformNode.id, kRealRootNodeId);
 
-  // TODO(jaydasika): We shouldn't set ToScreeen and FromScreen of root
+  // TODO(jaydasika): We shouldn't set ToScreen and FromScreen of root
   // transform node here. They should be set while updating transform tree in
   // cc.
   float deviceScaleFactor = m_rootLayer->GetLayerTree()->device_scale_factor();
   gfx::Transform toScreen;
   toScreen.Scale(deviceScaleFactor, deviceScaleFactor);
   transformTree.SetToScreen(kRealRootNodeId, toScreen);
   gfx::Transform fromScreen;
   bool invertible = toScreen.GetInverse(&fromScreen);
   DCHECK(invertible);
   transformTree.SetFromScreen(kRealRootNodeId, fromScreen);
@@ skipping 522 matching lines @@
 #ifndef NDEBUG
 void PaintArtifactCompositor::showDebugData() {
   LOG(ERROR) << layersAsJSON(LayerTreeIncludesDebugInfo)
                     ->toPrettyJSONString()
                     .utf8()
                     .data();
 }
 #endif
 
 }  // namespace blink