Slightly refactor StickyPositionScrollingConstraints API and add documentation

third_party/WebKit/Source/core/page/scrolling/StickyPositionScrollingConstraints.h

 // Copyright 2016 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.
 
 #ifndef StickyPositionScrollingConstraints_h
 #define StickyPositionScrollingConstraints_h
 
 #include "platform/geometry/FloatRect.h"
 #include "platform/geometry/FloatSize.h"
 #include "platform/wtf/HashMap.h"
 
 namespace blink {
 
-class LayoutBoxModelObject;
 class PaintLayer;
 class StickyPositionScrollingConstraints;
 
 typedef WTF::HashMap<PaintLayer*, StickyPositionScrollingConstraints>
     StickyConstraintsMap;
 
-// TODO(smcgruer): Add detailed comment explaining how
-// StickyPositionScrollingConstraints works.
+// Encapsulates the constraint information for a position: sticky element and
+// does calculation of the sticky offset for a given overflow clip rectangle.
+//
+// To avoid slowing down scrolling we cannot make the offset calculation a
+// layout-inducing event. Instead constraint information is cached during layout
+// and used as the scroll position changes to determine the current offset. In
+// most cases the only information that is needed is the sticky element's layout
+// rectangle and it's containing block rectangle (both respective to the nearest
+// ancestor scroller which the element is sticking to), and the set of sticky
+// edge constraints (i.e. the distance from each edge the element should stick).
+//
+// For a given (non-cached) overflow clip rectangle, calculating the current
+// offset in most cases just requires sliding the (cached) sticky element
+// rectangle until it satisfies the (cached) sticky edge constraints for the
+// overflow clip rectangle, whilst not letting the sticky element rectangle
+// escape it's (cached) containing block rect.
+//
+// Unfortunately this approach breaks down in the presence of nested sticky
+// elements. For those we apply more complicated logic, which is explained in
+// the implementation of |ComputeStickyOffset|.
 class StickyPositionScrollingConstraints final {
  public:
   enum AnchorEdgeFlags {
     kAnchorEdgeLeft = 1 << 0,
     kAnchorEdgeRight = 1 << 1,
     kAnchorEdgeTop = 1 << 2,
     kAnchorEdgeBottom = 1 << 3
   };
   typedef unsigned AnchorEdges;
 
   StickyPositionScrollingConstraints()
       : anchor_edges_(0),
         left_offset_(0),
         right_offset_(0),
         top_offset_(0),
         bottom_offset_(0),
-        nearest_sticky_box_shifting_sticky_box_(nullptr),
-        nearest_sticky_box_shifting_containing_block_(nullptr) {}
+        nearest_sticky_layer_shifting_sticky_box_(nullptr),
+        nearest_sticky_layer_shifting_containing_block_(nullptr) {}
 
   StickyPositionScrollingConstraints(
       const StickyPositionScrollingConstraints& other)
       : anchor_edges_(other.anchor_edges_),
         left_offset_(other.left_offset_),
         right_offset_(other.right_offset_),
         top_offset_(other.top_offset_),
         bottom_offset_(other.bottom_offset_),
         scroll_container_relative_containing_block_rect_(
             other.scroll_container_relative_containing_block_rect_),
         scroll_container_relative_sticky_box_rect_(
             other.scroll_container_relative_sticky_box_rect_),
-        nearest_sticky_box_shifting_sticky_box_(
-            other.nearest_sticky_box_shifting_sticky_box_),
-        nearest_sticky_box_shifting_containing_block_(
-            other.nearest_sticky_box_shifting_containing_block_),
+        nearest_sticky_layer_shifting_sticky_box_(
+            other.nearest_sticky_layer_shifting_sticky_box_),
+        nearest_sticky_layer_shifting_containing_block_(
+            other.nearest_sticky_layer_shifting_containing_block_),
         total_sticky_box_sticky_offset_(other.total_sticky_box_sticky_offset_),
         total_containing_block_sticky_offset_(
             other.total_containing_block_sticky_offset_) {}
 
-  FloatSize ComputeStickyOffset(
-      const FloatRect& viewport_rect,
-      const StickyPositionScrollingConstraints* ancestor_sticky_box_constraints,
-      const StickyPositionScrollingConstraints*
-          ancestor_containing_block_constraints);
+  // Computes the sticky offset for a given overflow clip rect.
+  //
+  // This method is non-const as we cache internal state for performance; see
+  // documentation in the implementation for details.
+  FloatSize ComputeStickyOffset(const FloatRect& overflow_clip_rect,
+                                const StickyConstraintsMap&);
+
+  // Returns the last-computed offset of the sticky box from its original
+  // position before scroll.
+  //
+  // This method exists for performance (to avoid recomputing the sticky offset)
+  // and must only be called when compositing inputs are clean for the sticky
+  // element. (Or after prepaint for SlimmingPaintV2).

[yigu, 2017/07/05 19:13:56]

Do you need to mention that this method should be called after
ComputeStickyOffset being invoked?

[smcgruer, 2017/07/06 14:25:37]

In patchset 2, flackr asked me to relate this to lifecycle and explicitly not
the method call. Unless I misunderstood him - flackr?

[flackr, 2017/07/06 14:35:06]

That's correct, because the lifecycle is a global concept, whereas saying after
that method is invoked requires then figuring out when it is invoked. If you
feel like it should explicitly call that out though we could say both, e.g.
"must only be called after ComputeStickyOffset has been invoked (i.e. after
compositing inputs are updated or after prepaint when SlimmingPaintV2 is
enabled)."

+  FloatSize GetOffsetForStickyPosition(const StickyConstraintsMap&) const;
 
   bool HasAncestorStickyElement() const {
-    return nearest_sticky_box_shifting_sticky_box_ ||
-           nearest_sticky_box_shifting_containing_block_;
+    return nearest_sticky_layer_shifting_sticky_box_ ||
+           nearest_sticky_layer_shifting_containing_block_;
   }
 
   AnchorEdges GetAnchorEdges() const { return anchor_edges_; }
   bool HasAnchorEdge(AnchorEdgeFlags flag) const {
     return anchor_edges_ & flag;
   }
   void AddAnchorEdge(AnchorEdgeFlags edge_flag) { anchor_edges_ |= edge_flag; }
-  void SetAnchorEdges(AnchorEdges edges) { anchor_edges_ = edges; }
 
   float LeftOffset() const { return left_offset_; }
   float RightOffset() const { return right_offset_; }
   float TopOffset() const { return top_offset_; }
   float BottomOffset() const { return bottom_offset_; }
 
   void SetLeftOffset(float offset) { left_offset_ = offset; }
   void SetRightOffset(float offset) { right_offset_ = offset; }
   void SetTopOffset(float offset) { top_offset_ = offset; }
   void SetBottomOffset(float offset) { bottom_offset_ = offset; }
 
   void SetScrollContainerRelativeContainingBlockRect(const FloatRect& rect) {
     scroll_container_relative_containing_block_rect_ = rect;
   }
   const FloatRect& ScrollContainerRelativeContainingBlockRect() const {
     return scroll_container_relative_containing_block_rect_;
   }
 
   void SetScrollContainerRelativeStickyBoxRect(const FloatRect& rect) {
     scroll_container_relative_sticky_box_rect_ = rect;
   }
   const FloatRect& ScrollContainerRelativeStickyBoxRect() const {
     return scroll_container_relative_sticky_box_rect_;
   }
 
-  void SetNearestStickyBoxShiftingStickyBox(LayoutBoxModelObject* layer) {
-    nearest_sticky_box_shifting_sticky_box_ = layer;
+  void SetNearestStickyLayerShiftingStickyBox(PaintLayer* layer) {
+    nearest_sticky_layer_shifting_sticky_box_ = layer;
   }
-  LayoutBoxModelObject* NearestStickyBoxShiftingStickyBox() const {
-    return nearest_sticky_box_shifting_sticky_box_;
+  PaintLayer* NearestStickyLayerShiftingStickyBox() const {
+    return nearest_sticky_layer_shifting_sticky_box_;
   }
 
-  void SetNearestStickyBoxShiftingContainingBlock(LayoutBoxModelObject* layer) {
-    nearest_sticky_box_shifting_containing_block_ = layer;
+  void SetNearestStickyLayerShiftingContainingBlock(PaintLayer* layer) {
+    nearest_sticky_layer_shifting_containing_block_ = layer;
   }
-  LayoutBoxModelObject* NearestStickyBoxShiftingContainingBlock() const {
-    return nearest_sticky_box_shifting_containing_block_;
-  }
-
-  const FloatSize& GetTotalStickyBoxStickyOffset() const {
-    return total_sticky_box_sticky_offset_;
-  }
-  const FloatSize& GetTotalContainingBlockStickyOffset() const {
-    return total_containing_block_sticky_offset_;
-  }
-
-  // Returns the relative position of the sticky box and its original position
-  // before scroll. This method is only safe to call if ComputeStickyOffset has
-  // been invoked.
-  FloatSize GetOffsetForStickyPosition(const StickyConstraintsMap&) const;
-
-  const LayoutBoxModelObject* NearestStickyAncestor() const {
-    // If we have one or more sticky ancestor elements between ourselves and our
-    // containing block, |m_nearestStickyBoxShiftingStickyBox| points to the
-    // closest. Otherwise, |m_nearestStickyBoxShiftingContainingBlock| points
-    // to the the first sticky ancestor between our containing block (inclusive)
-    // and our scroll ancestor (exclusive). Therefore our nearest sticky
-    // ancestor is the former if it exists, or the latter otherwise.
-    //
-    // If both are null, then we have no sticky ancestors before our scroll
-    // ancestor, so the correct action is to return null.
-    return nearest_sticky_box_shifting_sticky_box_
-               ? nearest_sticky_box_shifting_sticky_box_
-               : nearest_sticky_box_shifting_containing_block_;
+  PaintLayer* NearestStickyLayerShiftingContainingBlock() const {
+    return nearest_sticky_layer_shifting_containing_block_;
   }
 
   bool operator==(const StickyPositionScrollingConstraints& other) const {
     return left_offset_ == other.left_offset_ &&
            right_offset_ == other.right_offset_ &&
            top_offset_ == other.top_offset_ &&
            bottom_offset_ == other.bottom_offset_ &&
            scroll_container_relative_containing_block_rect_ ==
                other.scroll_container_relative_containing_block_rect_ &&
            scroll_container_relative_sticky_box_rect_ ==
                other.scroll_container_relative_sticky_box_rect_ &&
-           nearest_sticky_box_shifting_sticky_box_ ==
-               other.nearest_sticky_box_shifting_sticky_box_ &&
-           nearest_sticky_box_shifting_containing_block_ ==
-               other.nearest_sticky_box_shifting_containing_block_ &&
+           nearest_sticky_layer_shifting_sticky_box_ ==
+               other.nearest_sticky_layer_shifting_sticky_box_ &&
+           nearest_sticky_layer_shifting_containing_block_ ==
+               other.nearest_sticky_layer_shifting_containing_block_ &&
            total_sticky_box_sticky_offset_ ==
                other.total_sticky_box_sticky_offset_ &&
            total_containing_block_sticky_offset_ ==
                other.total_containing_block_sticky_offset_;
   }
 
   bool operator!=(const StickyPositionScrollingConstraints& other) const {
     return !(*this == other);
   }
 
  private:
+  FloatSize AncestorStickyBoxOffset(const StickyConstraintsMap&);
+  FloatSize AncestorContainingBlockOffset(const StickyConstraintsMap&);
+
   AnchorEdges anchor_edges_;
   float left_offset_;
   float right_offset_;
   float top_offset_;
   float bottom_offset_;
+
+  // The layout position of the sticky element's containing block rectangle,
+  // relative to the scroll container. When calculating the sticky offset it is
+  // used to ensure the sticky element stays bounded by it's containing block.
   FloatRect scroll_container_relative_containing_block_rect_;
+
+  // The layout position of the sticky element. When calculating the sticky
+  // offset it is used to determine how large the offset needs to be to satisfy
+  // the sticky constraints.
   FloatRect scroll_container_relative_sticky_box_rect_;
 
-  // In order to properly compute the stickyOffset, we need to know if we have
-  // any sticky ancestors both between ourselves and our containing block and
-  // between our containing block and the viewport. These ancestors are needed
-  // to properly shift our constraining rects with regards to the containing
-  // block and viewport.
-  LayoutBoxModelObject* nearest_sticky_box_shifting_sticky_box_;
-  LayoutBoxModelObject* nearest_sticky_box_shifting_containing_block_;
+  // In the case of nested sticky elements the layout position of the sticky
+  // element and it's containing block are not accurate (as they are affected by
+  // ancestor sticky offsets). To ensure a correct sticky offset calculation in
+  // that case we must track any sticky ancestors between the sticky element and
+  // it's containing block, and between it's containing block and the overflow
+  // clip ancestor.
+  //
+  // See the implementation of |ComputeStickyOffset| for documentation on how
+  // these ancestors are used to correct the offset calculation.
+  PaintLayer* nearest_sticky_layer_shifting_sticky_box_;
+  PaintLayer* nearest_sticky_layer_shifting_containing_block_;
 
   // For performance we cache our accumulated sticky offset to allow descendant
   // sticky elements to offset their constraint rects. Because we can either
   // affect the sticky box constraint rect or the containing block constraint
   // rect, we need to accumulate both.
   //
   // The case where we can affect both the sticky box constraint rect and the
   // constraining block constriant rect for different sticky descendants is
   // quite complex. See the StickyPositionComplexTableNesting test in
   // LayoutBoxModelObjectTest.cpp.
   FloatSize total_sticky_box_sticky_offset_;
   FloatSize total_containing_block_sticky_offset_;
 };
 
 }  // namespace blink
 
 #endif  // StickyPositionScrollingConstraints_h