Bug 1518584 - Update out-of-date comments in FrameMetrics.h. r=kats

Differential Revision: https://phabricator.services.mozilla.com/D15970

--HG--
extra : moz-landing-system : lando

gfx/layers/FrameMetrics.h

@@ -45,10 +45,21 @@ struct ScrollUpdateInfo {
 };
 
 /**
- * The viewport and displayport metrics for the painted frame at the
+ * Metrics about a scroll frame that are sent to the compositor and used
- * time of a layer-tree transaction.  These metrics are especially
+ * by APZ.
- * useful for shadow layers, because the metrics values are updated
+ *
- * atomically with new pixels.
+ * This is used for two main purposes:
+ *
+ *   (1) Sending information about a scroll frame to the compositor and APZ
+ *       as part of a layers or WebRender transaction.
+ *   (2) Storing information about a scroll frame in APZ that persists
+ *       between transactions.
+ *
+ * TODO: Separate these two uses into two distinct structures.
+ *
+ * A related class, RepaintRequest, is used for sending information about a
+ * scroll frame back from the compositor to the main thread when requesting
+ * a repaint of the scroll frame's contents.
  */
 struct FrameMetrics {
   friend struct IPC::ParamTraits<mozilla::layers::FrameMetrics>;
@@ -492,46 +503,41 @@ struct FrameMetrics {
       const CSSRect& aVisualViewport, CSSRect& aLayoutViewport);
 
  private:
-  // A unique ID assigned to each scrollable frame.
+  // A ID assigned to each scrollable frame, unique within each LayersId..
   ViewID mScrollId;
 
   // The pres-shell resolution that has been induced on the document containing
   // this scroll frame as a result of zooming this scroll frame (whether via
   // user action, or choosing an initial zoom level on page load). This can
   // only be different from 1.0 for frames that are zoomable, which currently
-  // is just the root content document's root scroll frame (mIsRoot = true).
+  // is just the root content document's root scroll frame
+  // (mIsRootContent = true).
   // This is a plain float rather than a ScaleFactor because in and of itself
   // it does not convert between any coordinate spaces for which we have names.
   float mPresShellResolution;
 
   // This is the area within the widget that we're compositing to. It is in the
-  // same coordinate space as the reference frame for the scrolled frame.
+  // layer coordinates of the scrollable content's parent layer.
   //
-  // This is useful because, on mobile, the viewport and composition dimensions
+  // The size of the composition bounds corresponds to the size of the scroll
-  // are not always the same. In this case, we calculate the displayport using
+  // frame's scroll port (but in a coordinate system where the size does not
-  // an area bigger than the region we're compositing to. If we used the
+  // change during zooming).
-  // viewport dimensions to calculate the displayport, we'd run into situations
-  // where we're prerendering the wrong regions and the content may be clipped,
-  // or too much of it prerendered. If the composition dimensions are the same
-  // as the viewport dimensions, there is no need for this and we can just use
-  // the viewport instead.
   //
-  // This value is valid for nested scrollable layers as well, and is still
+  // The origin of the composition bounds is relative to the layer tree origin.
-  // relative to the layer tree origin. This value is provided by Gecko at
+  // Unlike the scroll port's origin, it does not change during scrolling.
-  // layout/paint time.
+  //
+  // This value is provided by Gecko at layout/paint time.
   ParentLayerRect mCompositionBounds;
 
-  // The area of a frame's contents that has been painted, relative to
+  // The area of a scroll frame's contents that has been painted, relative to
-  // mCompositionBounds.
+  // mScrollOffset.
   //
-  // Note that this is structured in such a way that it doesn't depend on the
+  // Should not be larger than GetExpandedScrollableRect().
-  // method layout uses to scroll content.
   //
-  // May be larger or smaller than |mScrollableRect|.
+  // To pre-render a margin of 100 CSS pixels around the scroll port,
-  //
-  // To pre-render a margin of 100 CSS pixels around the window,
   // { x = -100, y = - 100,
-  //   width = window.innerWidth + 200, height = window.innerHeight + 200 }
+  //   width = scrollPort.width + 200, height = scrollPort.height + 200 }
+  // where scrollPort = CalculateCompositedSizeInCssPixels().
   CSSRect mDisplayPort;
 
   // If non-empty, the area of a frame's contents that is considered critical
@@ -553,10 +559,8 @@ struct FrameMetrics {
   // the scrollable range to 0.
   //
   // This is in the same coordinate space as |mScrollOffset|, but a different
-  // coordinate space than |mViewport| and |mDisplayPort|. Note also that this
+  // coordinate space than |mDisplayPort|. Note also that this coordinate
-  // coordinate system is understood by window.scrollTo().
+  // system is understood by window.scrollTo().
-  //
-  // This is valid on any layer unless it has no content.
   CSSRect mScrollableRect;
 
   // The cumulative resolution that the current frame has been painted at.
@@ -564,41 +568,33 @@ struct FrameMetrics {
   // containing this scroll frame and its ancestors, and any css-driven
   // resolution. This information is provided by Gecko at layout/paint time.
   // Note that this is allowed to have different x- and y-scales, but only
-  // for subframes (mIsRoot = false). (The same applies to other scales that
+  // for subframes (mIsRootContent = false). (The same applies to other scales
-  // "inherit" the 2D-ness of this one, such as mZoom.)
+  // that "inherit" the 2D-ness of this one, such as mZoom.)
   LayoutDeviceToLayerScale2D mCumulativeResolution;
 
-  // New fields from now on should be made private and old fields should
-  // be refactored to be private.
-
   // The conversion factor between CSS pixels and device pixels for this frame.
-  // This can vary based on a variety of things, such as reflowing-zoom. The
+  // This can vary based on a variety of things, such as reflowing-zoom.
-  // conversion factor for device pixels to layers pixels is just the
-  // resolution.
   CSSToLayoutDeviceScale mDevPixelsPerCSSPixel;
 
-  // The position of the top-left of the CSS viewport, relative to the document
+  // The position of the top-left of the scroll frame's scroll port, relative
-  // (or the document relative to the viewport, if that helps understand it).
+  // to the scrollable content's origin.
   //
-  // Thus it is relative to the document. It is in the same coordinate space as
+  // This is in the same coordinate space as |mScrollableRect|, but a different
-  // |mScrollableRect|, but a different coordinate space than |mViewport| and
+  // coordinate space than |mDisplayPort|.
-  // |mDisplayPort|.
   //
   // It is required that the rect:
   // { x = mScrollOffset.x, y = mScrollOffset.y,
-  //   width = mCompositionBounds.x / mResolution.scale,
+  //   width = scrollPort.width,
-  //   height = mCompositionBounds.y / mResolution.scale }
+  //   height = scrollPort.height }
-  // Be within |mScrollableRect|.
+  // (where scrollPort = CalculateCompositedSizeInCssPixels())
-  //
+  // be within |mScrollableRect|.
-  // This is valid for any layer, but is always relative to this frame and
-  // not any parents, regardless of parent transforms.
   CSSPoint mScrollOffset;
 
   // The base scroll offset to use for calculating a relative update to a
   // scroll offset.
   CSSPoint mBaseScrollOffset;
 
-  // The "user zoom". Content is painted by gecko at mResolution *
+  // The "user zoom". Content is painted by gecko at mCumulativeResolution *
   // mDevPixelsPerCSSPixel, but will be drawn to the screen at mZoom. In the
   // steady state, the two will be the same, but during an async zoom action the
   // two may diverge. This information is initialized in Gecko but updated in
@@ -622,22 +618,28 @@ struct FrameMetrics {
 
   uint32_t mPresShellId;
 
-  // The CSS viewport, which is the dimensions we're using to constrain the
+  // For a root scroll frame (RSF), the document's layout viewport
-  // <html> element of this frame, relative to the top-left of the layer. Note
+  // (sometimes called "CSS viewport" in older code).
-  // that its offset is structured in such a way that it doesn't depend on the
-  // method layout uses to scroll content.
   //
-  // This is mainly useful on the root layer, however nested iframes can have
+  // Its size is the dimensions we're using to constrain the <html> element
-  // their own viewport, which will just be the size of the window of the
+  // of the document (i.e. the initial containing block (ICB) size).
-  // iframe. For layers that don't correspond to a document, this metric is
+  //
-  // meaningless and invalid.
+  // Its origin is the RSF's layout scroll position, i.e. the scroll position
+  // exposed to web content via window.scrollX/Y.
+  //
+  // Note that only the root content document's RSF has a layout viewport
+  // that's distinct from the visual viewport. For an iframe RSF, the two
+  // are the same.
+  //
+  // For a scroll frame that is not an RSF, this metric is meaningless and
+  // invalid.
   CSSRect mViewport;
 
   // The extra resolution at which content in this scroll frame is drawn beyond
   // that necessary to draw one Layer pixel per Screen pixel.
   ScreenToLayerScale2D mExtraResolution;
 
-  // The time at which the APZC last requested a repaint for this scrollframe.
+  // The time at which the APZC last requested a repaint for this scroll frame.
   TimeStamp mPaintRequestTime;
 
   // Whether mScrollOffset was updated by something other than the APZ code, and
@@ -659,7 +661,10 @@ struct FrameMetrics {
   // otherwise use the display port rect.
   bool mUseDisplayPortMargins : 1;
 
-  // Whether or not this frame has a "scroll info layer" to capture events.
+  // True if this scroll frame is a scroll info layer. A scroll info layer is
+  // not layerized and its content cannot be truly async-scrolled, but its
+  // metrics are still sent to and updated by the compositor, with the updates
+  // being reflected on the next paint rather than the next composite.
   bool mIsScrollInfoLayer : 1;
 
   // WARNING!!!!
@@ -673,7 +678,7 @@ struct FrameMetrics {
   //    (as needed):
   //      FrameMetrics::operator ==
   //      AsyncPanZoomController::NotifyLayersUpdated
-  //      The ParamTraits specialization in GfxMessageUtils.h
+  //      The ParamTraits specialization in LayersMessageUtils.h
   //
   // Please add new fields above this comment.
 
@@ -782,11 +787,12 @@ struct LayerClip {
 typedef Maybe<LayerClip> MaybeLayerClip;  // for passing over IPDL
 
 /**
- * Metadata about a scroll frame that's stored in the layer tree for use by
+ * Metadata about a scroll frame that's sent to the compositor during a layers
- * the compositor (including APZ). This includes the scroll frame's
+ * or WebRender transaction, and also stored by APZ between transactions.
- * FrameMetrics, as well as other metadata. We don't put the other metadata into
+ * This includes the scroll frame's FrameMetrics, as well as other metadata.
- * FrameMetrics to avoid FrameMetrics becoming too bloated (as a FrameMetrics is
+ * We don't put the other metadata into FrameMetrics to avoid FrameMetrics
- * e.g. sent over IPC for every repaint request for every active scroll frame).
+ * becoming too bloated (as a FrameMetrics is e.g. stored in memory shared
+ * with the content process).
  */
 struct ScrollMetadata {
   friend struct IPC::ParamTraits<mozilla::layers::ScrollMetadata>;
@@ -1007,8 +1013,7 @@ struct ScrollMetadata {
   // updated to include them (as needed):
   //    1. ScrollMetadata::operator ==
   //    2. AsyncPanZoomController::NotifyLayersUpdated
-  //    3. The ParamTraits specialization in GfxMessageUtils.h and/or
+  //    3. The ParamTraits specialization in LayersMessageUtils.h
-  //       LayersMessageUtils.h
   //
   // Please add new fields above this comment.
 };