Bug 1518584 - Update out-of-date comments in FrameMetrics.h. r=kats
authorBotond Ballo <botond@mozilla.com>
Wed, 09 Jan 2019 15:27:53 +0000
changeset 510203 5029552447c130b47c28cb86ed80fb68ce6de186
parent 510174 cf9a58cbb9040639fb3f83e2f7b70e6f4b4518e8
child 510204 465d94722195cff562b4e63156bff8670a5691e7
push id10547
push userffxbld-merge
push dateMon, 21 Jan 2019 13:03:58 +0000
treeherdermozilla-beta@24ec1916bffe [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerskats
bugs1518584
milestone66.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1518584 - Update out-of-date comments in FrameMetrics.h. r=kats Differential Revision: https://phabricator.services.mozilla.com/D15970
gfx/layers/FrameMetrics.h
--- a/gfx/layers/FrameMetrics.h
+++ b/gfx/layers/FrameMetrics.h
@@ -40,20 +40,31 @@ namespace layers {
 struct ScrollUpdateInfo {
   uint32_t mScrollGeneration;
   CSSPoint mScrollOffset;
   CSSPoint mBaseScrollOffset;
   bool mIsRelative;
 };
 
 /**
- * The viewport and displayport metrics for the painted frame at the
- * time of a layer-tree transaction.  These metrics are especially
- * useful for shadow layers, because the metrics values are updated
- * atomically with new pixels.
+ * Metrics about a scroll frame that are sent to the compositor and used
+ * by APZ.
+ *
+ * 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>;
 
   typedef ScrollableLayerGuid::ViewID ViewID;
 
  public:
   // clang-format off
@@ -487,56 +498,51 @@ struct FrameMetrics {
   // and visual viewport rects (e.g. the "effective" ones used to implement
   // the frame delay).
   // Modifies |aLayoutViewport| to continue enclosing |aVisualViewport|
   // if possible.
   static void KeepLayoutViewportEnclosingVisualViewport(
       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
-  // are not always the same. In this case, we calculate the displayport using
-  // an area bigger than the region we're compositing to. If we used the
-  // 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.
+  // The size of the composition bounds corresponds to the size of the scroll
+  // frame's scroll port (but in a coordinate system where the size does not
+  // change during zooming).
   //
-  // This value is valid for nested scrollable layers as well, and is still
-  // relative to the layer tree origin. This value is provided by Gecko at
-  // layout/paint time.
+  // The origin of the composition bounds is relative to the layer tree origin.
+  // Unlike the scroll port's origin, it does not change during scrolling.
+  //
+  // 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
-  // mCompositionBounds.
+  // The area of a scroll frame's contents that has been painted, relative to
+  // mScrollOffset.
   //
-  // Note that this is structured in such a way that it doesn't depend on the
-  // method layout uses to scroll content.
+  // Should not be larger than GetExpandedScrollableRect().
   //
-  // May be larger or smaller than |mScrollableRect|.
-  //
-  // To pre-render a margin of 100 CSS pixels around the window,
+  // To pre-render a margin of 100 CSS pixels around the scroll port,
   // { 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
   // to paint. Area outside of this area (i.e. area inside mDisplayPort, but
   // outside of mCriticalDisplayPort) is considered low-priority, and may be
   // painted with lower precision, or not painted at all.
   //
   // The same restrictions for mDisplayPort apply here.
@@ -548,62 +554,52 @@ struct FrameMetrics {
   // the x value may be negative.
   //
   // For scrollable frames that are overflow:hidden the x and y are usually
   // set to the value of the current scroll offset, and the width and height
   // will match the composition bounds width and height. In effect this reduces
   // 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 system is understood by window.scrollTo().
-  //
-  // This is valid on any layer unless it has no content.
+  // coordinate space than |mDisplayPort|. Note also that this coordinate
+  // system is understood by window.scrollTo().
   CSSRect mScrollableRect;
 
   // The cumulative resolution that the current frame has been painted at.
   // This is the product of the pres-shell resolutions of the document
   // 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
-  // "inherit" the 2D-ness of this one, such as mZoom.)
+  // for subframes (mIsRootContent = false). (The same applies to other scales
+  // 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
-  // conversion factor for device pixels to layers pixels is just the
-  // resolution.
+  // This can vary based on a variety of things, such as reflowing-zoom.
   CSSToLayoutDeviceScale mDevPixelsPerCSSPixel;
 
-  // The position of the top-left of the CSS viewport, relative to the document
-  // (or the document relative to the viewport, if that helps understand it).
+  // The position of the top-left of the scroll frame's scroll port, relative
+  // to the scrollable content's origin.
   //
-  // Thus it is relative to the document. It is in the same coordinate space as
-  // |mScrollableRect|, but a different coordinate space than |mViewport| and
-  // |mDisplayPort|.
+  // This is in the same coordinate space as |mScrollableRect|, but a different
+  // coordinate space than |mDisplayPort|.
   //
   // It is required that the rect:
   // { x = mScrollOffset.x, y = mScrollOffset.y,
-  //   width = mCompositionBounds.x / mResolution.scale,
-  //   height = mCompositionBounds.y / mResolution.scale }
-  // Be within |mScrollableRect|.
-  //
-  // This is valid for any layer, but is always relative to this frame and
-  // not any parents, regardless of parent transforms.
+  //   width = scrollPort.width,
+  //   height = scrollPort.height }
+  // (where scrollPort = CalculateCompositedSizeInCssPixels())
+  // be within |mScrollableRect|.
   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
   // the APZC.
   CSSToParentLayerScale2D mZoom;
 
   // The scroll generation counter used to acknowledge the scroll offset update.
   uint32_t mScrollGeneration;
@@ -617,32 +613,38 @@ struct FrameMetrics {
   CSSSize mRootCompositionSize;
 
   // A display port expressed as layer margins that apply to the rect of what
   // is drawn of the scrollable element.
   ScreenMargin mDisplayPortMargins;
 
   uint32_t mPresShellId;
 
-  // The CSS viewport, which is the dimensions we're using to constrain the
-  // <html> element of this frame, relative to the top-left of the layer. Note
-  // that its offset is structured in such a way that it doesn't depend on the
-  // method layout uses to scroll content.
+  // For a root scroll frame (RSF), the document's layout viewport
+  // (sometimes called "CSS viewport" in older code).
+  //
+  // Its size is the dimensions we're using to constrain the <html> element
+  // of the document (i.e. the initial containing block (ICB) size).
   //
-  // This is mainly useful on the root layer, however nested iframes can have
-  // their own viewport, which will just be the size of the window of the
-  // 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
   // if the APZC receiving this metrics should update its local copy.
   ScrollOffsetUpdateType mScrollUpdateType;
 
   // Whether or not this is the root scroll frame for the root content document.
   bool mIsRootContent : 1;
@@ -654,31 +656,34 @@ struct FrameMetrics {
   // When mDoSmoothScroll, the scroll offset should be animated to
   // smoothly transition to mScrollOffset rather than be updated instantly.
   bool mDoSmoothScroll : 1;
 
   // If this is true then we use the display port margins on this metrics,
   // 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!!!!
   //
   // When adding a new field:
   //
   //  - First, consider whether the field can be added to ScrollMetadata
   //    instead. If so, prefer that.
   //
   //  - Otherwise, the following places should be updated to include them
   //    (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.
 
   // Private helpers for IPC purposes
   void SetDoSmoothScroll(bool aValue) { mDoSmoothScroll = aValue; }
 };
 
 struct ScrollSnapInfo {
@@ -777,21 +782,22 @@ struct LayerClip {
   // Optionally, specifies a mask layer that's part of the clip.
   // This is an index into the MetricsMaskLayers array on the Layer.
   Maybe<size_t> mMaskLayerIndex;
 };
 
 typedef Maybe<LayerClip> MaybeLayerClip;  // for passing over IPDL
 
 /**
- * Metadata about a scroll frame that's stored in the layer tree for use by
- * the compositor (including APZ). This includes the scroll frame's
- * FrameMetrics, as well as other metadata. We don't put the other metadata into
- * FrameMetrics to avoid FrameMetrics becoming too bloated (as a FrameMetrics is
- * e.g. sent over IPC for every repaint request for every active scroll frame).
+ * Metadata about a scroll frame that's sent to the compositor during a layers
+ * or WebRender transaction, and also stored by APZ between transactions.
+ * This includes the scroll frame's FrameMetrics, as well as other metadata.
+ * We don't put the other metadata into FrameMetrics to avoid FrameMetrics
+ * 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>;
 
   typedef ScrollableLayerGuid::ViewID ViewID;
 
  public:
   static StaticAutoPtr<const ScrollMetadata>
@@ -1002,18 +1008,17 @@ struct ScrollMetadata {
   OverscrollBehaviorInfo mOverscrollBehavior;
 
   // WARNING!!!!
   //
   // When adding new fields to ScrollMetadata, the following places should be
   // updated to include them (as needed):
   //    1. ScrollMetadata::operator ==
   //    2. AsyncPanZoomController::NotifyLayersUpdated
-  //    3. The ParamTraits specialization in GfxMessageUtils.h and/or
-  //       LayersMessageUtils.h
+  //    3. The ParamTraits specialization in LayersMessageUtils.h
   //
   // Please add new fields above this comment.
 };
 
 typedef std::map<ScrollableLayerGuid::ViewID, ScrollUpdateInfo>
     ScrollUpdatesMap;
 
 }  // namespace layers