Bugzilla

I can provide some background on the conceptual model here.

Every level in the hit testing tree represents a layer, and every layer has its own coordinate space.

The number of layers is dynamic, so their coordinate systems can't each get a different static type. Instead, functions that work with layer coordinate systems typically have a notion of a "current layer", and quantities in the coordinate system of the current layer use `LayerPixel` as their units.

It's also common to work with quantities in the coordinate system of the current layer's parent layer, so we have `ParentLayerPixel` for this purpose.

When accumulating a transform over several layers, you often need to change your view of what the "current layer" is in a loop (or through recursion). To do this, we cast from `ParentLayer` units to `Layer` units, or vice versa. Casting requires a justification, and we have a justification named [`MovingDownToChildren`](https://searchfox.org/mozilla-central/rev/92d11a33250a8e368c8ca3e962e15ca67117f765/layout/base/UnitTransforms.h#36) for this purpose.

Going from a layer to its parent involves applying potentially two kinds of transforms: a "CSS transform" (called that because it typically comes from a CSS `transform` property, though it could come from some other things as well), and an "async transform" (representing OMTA or APZ scrolling/zooming). We apply these two in that order, and give them the types `CSSTransformMatrix` and `AsyncTransformMatrix`, respectively. (To fit into our unit model, we invented the intermediate coordinate space `CSSTransformedLayerPixel`, so that `CSSTransformMatrix` goes from `LayerPixel` to `CSSTransformedLayerPixel`, and `AsyncTransformMatrix` from `CSSTransformedLayerPixel` to `ParentLayerPixel`, but that's mostly an implementation detail.)

Sometimes, you want to accumulate transforms ignoring the async transforms (because they're going to change asynchronously anyways). In such cases, to get a `Layer` to `ParentLayer` transform representing the CSS transform only, you take the CSS transform and multiply it by an empty `AsyncTransformMatrix`.

The rootmost coordinate space is `Screen` space. It is equivalent to the `ParentLayer` space of the topmost layer, and we have a justification named [`ScreenIsParentLayerForRoot`](https://searchfox.org/mozilla-central/rev/92d11a33250a8e368c8ca3e962e15ca67117f765/layout/base/UnitTransforms.h#26) for casting between those as well.

I can provide some background on the conceptual model here.

Every level in the hit testing tree represents a layer, and every layer has its own coordinate space.

The number of layers is dynamic, so their coordinate systems can't each get a different static type. Instead, functions that work with layer coordinate systems typically have an (implicit) notion of a "current layer", and quantities in the coordinate system of the current layer use `LayerPixel` as their units.

It's also common to work with quantities in the coordinate system of the current layer's parent layer, so we have `ParentLayerPixel` for this purpose.

When accumulating a transform over several layers, you often need to change your view of what the "current layer" is in a loop (or through recursion). To do this, we cast from `ParentLayer` units to `Layer` units, or vice versa. Casting requires a justification, and we have a justification named [`MovingDownToChildren`](https://searchfox.org/mozilla-central/rev/92d11a33250a8e368c8ca3e962e15ca67117f765/layout/base/UnitTransforms.h#36) for this purpose.

Going from a layer to its parent involves applying potentially two kinds of transforms: a "CSS transform" (called that because it typically comes from a CSS `transform` property, though it could come from some other things as well), and an "async transform" (representing OMTA or APZ scrolling/zooming). We apply these two in that order, and give them the types `CSSTransformMatrix` and `AsyncTransformMatrix`, respectively. (To fit into our unit model, we invented the intermediate coordinate space `CSSTransformedLayerPixel`, so that `CSSTransformMatrix` goes from `LayerPixel` to `CSSTransformedLayerPixel`, and `AsyncTransformMatrix` from `CSSTransformedLayerPixel` to `ParentLayerPixel`, but that's mostly an implementation detail.)

Sometimes, you want to accumulate transforms ignoring the async transforms (because they're going to change asynchronously anyways). In such cases, to get a `Layer` to `ParentLayer` transform representing the CSS transform only, you take the CSS transform and multiply it by an empty `AsyncTransformMatrix`.

The rootmost coordinate space is `Screen` space. It is equivalent to the `ParentLayer` space of the topmost layer, and we have a justification named [`ScreenIsParentLayerForRoot`](https://searchfox.org/mozilla-central/rev/92d11a33250a8e368c8ca3e962e15ca67117f765/layout/base/UnitTransforms.h#26) for casting between those as well.