diff --git a/components/compositing/scrolling.md b/components/compositing/scrolling.md new file mode 100644 index 00000000000..b577d32ebad --- /dev/null +++ b/components/compositing/scrolling.md @@ -0,0 +1,57 @@ +Scrolling +========= + +Scrolling is implemented by the compositor. Compositor layers that opt in to +scroll events via the `wants_scroll_events` flag can scroll their contents. +These will be referred "scrolling roots." Scrolling roots serve as a viewport +into their content, which is stored in descendant layers. In order for +scrolling roots to be able to scroll their content, they need to be smaller +than that content. If the content was smaller than the scrolling root, it would +not be able to move around inside the scrolling root. Imagine a browser window +that is larger than the content that it contains. The size of each layer is +defined by the window size (the root layer) or the block size for iframes and +elements with `overflow:scroll`. + +Since the compositor allows layers to exist independently of their parents, +child layers can overflow or fail to intersect their parents completely. To +prevent this, scrolling roots use the `masks_to_bounds` flag, which is a signal +to the compositor that it should not paint the parts of descendant layers that +lie outside the boundaries of the scrolling root. + +Below is an ASCII art diagram showing a scrolling root with three content +layers (a, b, and c), scrolled down a few ticks. `masks_to_bounds` has not been +applied in the diagram. + +
++-----------------------+ +| | +========================= +| | scrolling +| <-------------+root +| | +| +-------+ | +========================= +| | b | | +++-------+ +--^----+ | +|| | | | +|| | | | content +|| c <---------+---------+layers +|+-------+ / | +| a < | +| | ++-----------------------+ ++ +Everything above and below the set of `====` bars would be hidden by +`masks_to_bounds`, so the composited scene will just be the viewport defined by +the scrolling root with the content layers a and b visible. + +
+========================= +| | +| | +| | +| +-------+ | +========================= ++