||NOTE ON LOCK ORDERING IN APZ **************************
To avoid deadlock, APZ imposes and respects a global ordering on threads
and locks relevant to APZ.
Please see the "Threading / Locking Overview" section of
gfx/docs/AsyncPanZoom.rst (hosted in rendered form at
for what the ordering is, and what are the rules for respecting it.
||Cancel all animations
||Attempt to handle a main-thread scroll offset update without cancelling
the animation. This may or may not make sense depending on the type of
the animation and whether the scroll update is relative or absolute.
If the scroll update is relative, |aRelativeDelta| will contain the
delta of the relative update. If the scroll update is absolute,
|aRelativeDelta| will be Nothing() (the animation can check the APZC's
FrameMetrics for the new absolute scroll offset if it wants to handle
and absolute update).
Returns whether the animation could handle the scroll update. If the
return value is false, the animation will be cancelled.
||Represents a transform from the ParentLayer coordinate space of an APZC
to the ParentLayer coordinate space of its parent APZC.
Each layer along the way contributes to the transform. We track
contributions that are perspective transforms separately, as sometimes
these require special handling.
For an AutoDir wheel scroll, there's some situations where we should adjust a
wheel event's delta values. AutoDirWheelDeltaAdjuster converts delta values
for AutoDir scrolling. An AutoDir wheel scroll lets the user scroll a frame
with only one scrollbar, using either a vertical or a horzizontal wheel.
For more detail about the concept of AutoDir scrolling, see the comments in
This is the APZ implementation of AutoDirWheelDeltaAdjuster.
||Compare two coordinates for equality, accounting for rounding error.
Use both FuzzyEqualsAdditive() with COORDINATE_EPISLON, which accounts for
things like the error introduced by rounding during a round-trip to app
units, and FuzzyEqualsMultiplicative(), which accounts for accumulated error
due to floating-point operations (which can be larger than COORDINATE_EPISLON
for sufficiently large coordinate values).
||This class records information relevant to one "checkerboard event", which is
a contiguous set of frames where a given APZC was checkerboarding. The intent
of this class is to record enough information that it can provide actionable
steps to reduce the occurrence of checkerboarding. Furthermore, it records
information about the severity of the checkerboarding so as to allow
prioritizing the debugging of some checkerboarding events over others.
||This class is used to track state that is used when determining whether a
fling should be accelerated.
||This class is used for tracking chrome and content focus targets and
calculating global focus information from them for use by APZCTreeManager
for async keyboard scrolling.
# Calculating the element to scroll
Chrome and content processes have independently focused elements. This makes
it difficult to calculate the global focused element and its scrollable
frame from the chrome or content side. So instead we send the local focus
information from each process to here and then calculate the global focus
information. This local information resides in a `focus target`.
A focus target indicates that either:
1. The focused element is a remote browser along with its layer tree ID
2. The focused element is not scrollable
3. The focused element is scrollable along with the ViewID's of its
Using this information we can determine the global focus information by
starting at the focus target of the root layer tree ID and following remote
browsers until we reach a scrollable or non-scrollable focus target.
# Determinism and sequence numbers
and others. This makes it impossible to always have the current focus
information in APZ as it can be changed asynchronously at any moment. If we
don't have the latest focus information, we may incorrectly scroll a target
when we shouldn't.
A tradeoff is designed here whereby we will maintain deterministic focus
here is that `setTimeout` and others are already non-deterministic and so it
might not be as breaking to web content.
To maintain deterministic focus changes for a given stream of user inputs,
we invalidate our focus state whenever we receive a user input that may
trigger event listeners. We then attach a new sequence number to these
events and dispatch them to content. Content will then include the latest
sequence number it has processed to every focus update. Using this we can
determine whether any potentially focus changing events have yet to be
handled by content.
Once we have received the latest focus sequence number from content, we know
that all event listeners triggered by user inputs, and their resulting focus
changes, have been processed and so we have a current target that we can use
||This class is used for communicating information about the currently focused
element of a document and the scrollable frames to use when keyboard
scrolling it. It is created on the main thread at paint-time, but is then
passed over IPC to the compositor/APZ code.
||The FlingPhysics template parameter determines the physics model
that the fling animation follows. It must have the following methods:
- Default constructor.
- Init(const ParentLayerPoint& aStartingVelocity, float aPLPPI).
Called at the beginning of the fling, with the fling's starting velocity,
and the number of ParentLayer pixels per (Screen) inch at the point of
the fling's start in the fling's direction.
- Sample(const TimeDuration& aDelta,
Called on each sample of the fling.
|aDelta| is the time elapsed since the last sample.
|aOutVelocity| should be the desired velocity after the current sample,
in ParentLayer pixels per millisecond.
|aOutOffset| should be the desired _delta_ to the scroll offset after
the current sample. |aOutOffset| should _not_ be clamped to the APZC's
scrollable bounds; the caller will do the clamping, and it needs to
know the unclamped value to handle handoff/overscroll correctly.
||Amount of span or focus change needed to take us from the
GESTURE_WAITING_PINCH state to the GESTURE_PINCH state. This is measured as
either a change in distance between the fingers used to compute the span
ratio, or the a change in position of the focus point between the two
||Platform-non-specific, generalized gesture event listener. This class
intercepts all touches events on their way to AsyncPanZoomController and
determines whether or not they are part of a gesture.
For example, seeing that two fingers are on the screen means that the user
wants to do a pinch gesture, so we don't forward the touches along to
AsyncPanZoomController since it will think that they are just trying to pan
the screen. Instead, we generate a PinchGestureInput and send that. If the
touch event is not part of a gesture, we just return nsEventStatus_eIgnore
and AsyncPanZoomController is expected to handle it.
||This class represents a node in a tree that is used by the APZCTreeManager
to do hit testing. The tree is roughly a copy of the layer tree, but will
contain multiple nodes in cases where the layer has multiple FrameMetrics.
In other words, the structure of this tree should be identical to the
WebRenderScrollDataWrapper tree (see documentation in
Not all HitTestingTreeNode instances will have an APZC associated with them;
only HitTestingTreeNodes that correspond to layers with scrollable metrics
Multiple HitTestingTreeNode instances may share the same underlying APZC
instance if the layers they represent share the same scrollable metrics (i.e.
are part of the same animated geometry root). If this happens, exactly one of
the HitTestingTreeNode instances will be designated as the "primary holder"
of the APZC. When this primary holder is destroyed, it will destroy the APZC
along with it; in contrast, destroying non-primary-holder nodes will not
destroy the APZC.
Code should not make assumptions about which of the nodes will be the
primary holder, only that that there will be exactly one for each APZC in
The reason this tree exists at all is so that we can do hit-testing on the
thread that we receive input on (referred to the as the controller thread in
APZ terminology), which may be different from the compositor thread.
Accessing the compositor layer tree can only be done on the compositor
thread, and so it is simpler to make a copy of the hit-testing related
properties into a separate tree.
The tree pointers on the node (mLastChild, etc.) can only be manipulated
while holding the APZ tree lock. Any code that wishes to use a
HitTestingTreeNode outside of holding the tree lock should do so by using
the HitTestingTreeNodeAutoLock wrapper, which prevents the node from
being recycled (and also holds a RefPtr to the node to prevent it from
||A base class that stores state common to various input blocks.
Note that the InputBlockState constructor acquires the tree lock, so callers
from inside AsyncPanZoomController should ensure that the APZC lock is not
||This class stores incoming input events, associated with "input blocks",
until they are ready for handling.
||This class is an off main-thread <xul:handler> for scrolling commands.
||This class represents a scrolling action to be performed on a scrollable
||This class represents the chain of APZCs along which overscroll is handed
off. It is created by APZCTreeManager by starting from an initial APZC which
is the target for input events, and following the scroll parent ID links
(often but not always corresponding to parent pointers in the APZC tree),
then adjusting for scrollgrab.
||Handles detection and telemetry reporting of overshoot events, which are
situations where the user changes scrolling direction shortly after a
previous scroll in the other direction, indicating that the user likely
scrolled too far and had to backtrack.
Currently this data collection is focused on forms of input that trigger
animated rather than instant scrolling. That includes ScrollWheelInput
(currently implemented) and KeyboardInput (planned in bug 1838568).
||This class allows the owner to track the duration of time considered
"potentially checkerboarding". This is the union of two possibly-intersecting
sets of time periods. The first set is that in which checkerboarding was
actually happening, since by definition it could potentially be happening.
The second set is that in which the APZC is actively transforming content
in the compositor, since it could potentially transform it so as to display
checkerboarding to the user.
The caller of this class calls the appropriate methods to indicate the start
and stop of these two sets, and this class manages accumulating the union
of the various durations.
||This lightweight class holds a pointer to an input event that has not yet
been completely processed, along with the input block that the input event
is associated with.
||RecentEventsBuffer: maintains an age constrained buffer of events
Intended for use with elements of type InputData, but the only requirement
is a member "mTimeStamp" of type TimeStamp
||Re-clamp mVisualScrollOffset to the scroll range specified by the provided
metrics. This only needs to be called if the scroll offset changes
outside of AsyncPanZoomController::SampleCompositedAsyncTransform().
It also recalculates mLayoutViewport so that it continues to enclose
the visual viewport. This only needs to be called if the
layout viewport changes outside of SampleCompositedAsyncTransform().
||Compute the updated shadow transform for a scroll thumb layer that
reflects async scrolling of the associated scroll frame.
@param aCurrentTransform The current shadow transform on the scroll thumb
layer, as returned by Layer::GetLocalTransform() or similar.
@param aScrollableContentTransform The current content transform on the
scrollable content, as returned by Layer::GetTransform().
@param aApzc The APZC that scrolls the scroll frame.
@param aMetrics The metrics associated with the scroll frame, reflecting
the last paint of the associated content. Note: this metrics should
NOT reflect async scrolling or zooming, i.e. they should be the layer
tree's copy of the metrics, or APZC's last-content-paint metrics.
@param aScrollbarData The scrollbar data for the the scroll thumb layer.
@param aScrollbarIsDescendant True iff. the scroll thumb layer is a
descendant of the layer bearing the scroll frame's metrics.
@return The new shadow transform for the scroll thumb layer, including
any pre- or post-scales.
||Advances a smooth scroll simulation based on the time passed in |aDelta|.
This should be called whenever sampling the content transform for this
frame. Returns true if the smooth scroll should be advanced by one frame,
or false if the smooth scroll has ended.