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 indices', or 'property tree
+  // indices'. |parent_id| is the same sort of 'node index' of that node's
+  // parent, whereas |owner_id| is the layer id of the layer owning that node.
+  //
+  // 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 a world where cc property nodes have no
+  // association with layers and instead have a |stable_id|. The id could come
+  // from an ElementId in turn derived from the layout object responsible for
+  // creating the property node.
+  //
+  // 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