From 66bad9bae625bfadff0af6482d288cca13c7bfb4 Mon Sep 17 00:00:00 2001 From: Botond Ballo Date: Wed, 9 Jan 2019 15:27:53 +0000 Subject: [PATCH] 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 | 141 ++++++++++++++++++++------------------ 1 file changed, 73 insertions(+), 68 deletions(-) diff --git a/gfx/layers/FrameMetrics.h b/gfx/layers/FrameMetrics.h index a908973f5e5a..9daf8336d05f 100644 --- a/gfx/layers/FrameMetrics.h +++ b/gfx/layers/FrameMetrics.h @@ -45,10 +45,21 @@ struct ScrollUpdateInfo { }; /** - * 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; @@ -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 - // 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 @@ -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 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. @@ -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 - // "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 @@ -622,22 +618,28 @@ struct FrameMetrics { uint32_t mPresShellId; - // The CSS viewport, which is the dimensions we're using to constrain the - // 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). // - // 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 size is the dimensions we're using to constrain the element + // of the document (i.e. the initial containing block (ICB) size). + // + // 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 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; @@ -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 - // LayersMessageUtils.h + // 3. The ParamTraits specialization in LayersMessageUtils.h // // Please add new fields above this comment. };