Adding comments to cc pipeline around scheduling Commit/PrepareTiles

Change-Id: Idbe1d20fd14dfbbcf8810dee3c5a393f460b7f29
Reviewed-on: https://chromium-review.googlesource.com/c/1336509
Commit-Queue: Yi Xu <yiyix@chromium.org>
Reviewed-by: danakj <danakj@chromium.org>
Cr-Commit-Position: refs/heads/master@{#611449}

cc/scheduler/scheduler.h

@@ -40,6 +40,12 @@ class SchedulerClient {
       const viz::BeginFrameArgs& args) = 0;
   virtual DrawResult ScheduledActionDrawIfPossible() = 0;
   virtual DrawResult ScheduledActionDrawForced() = 0;
+
+  // The Commit step occurs when the client received the BeginFrame from the
+  // source and we perform at most one commit per BeginFrame. In this step the
+  // main thread collects all updates then blocks and gives control to the
+  // compositor thread, which allows Compositor thread to update its layer tree
+  // to match the state of the layer tree on the main thread.
   virtual void ScheduledActionCommit() = 0;
   virtual void ScheduledActionActivateSyncTree() = 0;
   virtual void ScheduledActionBeginLayerTreeFrameSinkCreation() = 0;
@@ -90,10 +96,19 @@ class CC_EXPORT Scheduler : public viz::BeginFrameObserverBase {
   void SetVisible(bool visible);
   bool visible() { return state_machine_.visible(); }
   void SetCanDraw(bool can_draw);
+
+  // We have 2 copies of the layer trees on the compositor thread: pending_tree
+  // and active_tree. When we finish asynchronously rastering all tiles on
+  // pending_tree, call this method to notify that this pending tree is ready to
+  // be activated, that is to be copied to the active tree.
   void NotifyReadyToActivate();
   void NotifyReadyToDraw();
   void SetBeginFrameSource(viz::BeginFrameSource* source);
 
+  // Set |needs_begin_main_frame_| to true, which will cause the BeginFrame
+  // source to be told to send BeginFrames to this client so that this client
+  // can send a CompositorFrame to the display compositor with appropriate
+  // timing.
   void SetNeedsBeginMainFrame();
   // Requests a single impl frame (after the current frame if there is one
   // active).
@@ -125,12 +140,24 @@ class CC_EXPORT Scheduler : public viz::BeginFrameObserverBase {
   void SetTreePrioritiesAndScrollState(TreePriority tree_priority,
                                        ScrollHandlerState scroll_handler_state);
 
+  // Commit step happens after the main thread has completed updating for a
+  // BeginMainFrame request from the compositor, and blocks the main thread
+  // to copy the layer tree to the compositor thread. Call this method when the
+  // main thread updates are completed to signal it is ready for the commmit.
   void NotifyReadyToCommit();
   void BeginMainFrameAborted(CommitEarlyOutReason reason);
   void DidCommit();
 
+  // In the PrepareTiles step, compositor thread divides the layers into tiles
+  // to reduce cost of raster large layers. Then, each tile is rastered by a
+  // dedicated thread.
+  // |WillPrepareTiles| is called before PrepareTiles step to have the scheduler
+  // track when PrepareTiles starts.
   void WillPrepareTiles();
+  // |DidPrepareTiles| is called after PrepareTiles step to have the scheduler
+  // track how long PrepareTiles takes.
   void DidPrepareTiles();
+
   void DidLoseLayerTreeFrameSink();
   void DidCreateAndInitializeLayerTreeFrameSink();
 

cc/tiles/tile_manager.h

@@ -139,6 +139,9 @@ class CC_EXPORT TileManager : CheckerImageTrackerClient {
   ~TileManager() override;
 
   // Assigns tile memory and schedules work to prepare tiles for drawing.
+  // This step occurs after Commit and at most once per BeginFrame. It can be
+  // called on its own, that is, outside of Commit.
+  //
   // - Runs client_->NotifyReadyToActivate() when all tiles required for
   // activation are prepared, or failed to prepare due to OOM.
   // - Runs client_->NotifyReadyToDraw() when all tiles required draw are

cc/trees/proxy.h

@@ -36,6 +36,9 @@ class CC_EXPORT Proxy {
   virtual ~Proxy() {}
 
   virtual bool IsStarted() const = 0;
+
+  // This function retruns true if the commits go directly to active tree by
+  // skipping commit to pending tree.
   virtual bool CommitToActiveTree() const = 0;
 
   virtual void SetLayerTreeFrameSink(