From 59203c63bb777a3bacec32fb8830fba33540e809 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 12 Jun 2024 07:35:29 +0200 Subject: Adding upstream version 127.0. Signed-off-by: Daniel Baumann --- layout/docs/DynamicChangeHandling.md | 83 ++++++ layout/docs/LayoutOverview.md | 529 +++++++++++++++++++++++++++++++++++ layout/docs/StyleSystemOverview.md | 173 ++++++++++++ layout/docs/index.rst | 14 +- 4 files changed, 794 insertions(+), 5 deletions(-) create mode 100644 layout/docs/DynamicChangeHandling.md create mode 100644 layout/docs/LayoutOverview.md create mode 100644 layout/docs/StyleSystemOverview.md (limited to 'layout/docs') diff --git a/layout/docs/DynamicChangeHandling.md b/layout/docs/DynamicChangeHandling.md new file mode 100644 index 0000000000..50df613412 --- /dev/null +++ b/layout/docs/DynamicChangeHandling.md @@ -0,0 +1,83 @@ +# Dynamic change handling along the rendering pipeline + +The ability to make changes to the DOM from script is a major feature of +the Web platform. Web authors rely on the concept (though there are a +few exceptions, such as animations) that changing the DOM from script +leads to the same rendering that would have resulted from starting from +that DOM tree. They also rely on the performance characteristics of +these changes: small changes to the DOM that have small effects should +have proportionally small processing time. This means that Gecko needs +to efficiently propagate changes from the content tree to style, the +frame tree, the geometry of the frame tree, and the screen. + +For many types of changes, however, there is substantial overhead to +processing a change, no matter how small. For example, reflow must +propagate from the top of the frame tree down to the frames that are +dirty, no matter how small the change. One very common way around this +is to batch up changes. We batch up changes in lots of ways, for +example: + +- The content sink adds multiple nodes to the DOM tree before + notifying listeners that they\'ve been added. This allows notifying + once about an ancestor rather than for each of its descendants, or + notifying about a group of descendants all at once, which speeds up + the processing of those notifications. +- We batch up nodes that require style reresolution (recomputation of + selector matching and processing the resulting style changes). This + batching is tree based, so it not only merges multiple notifications + on the same element, but also merges a notification on an ancestor + with a notification on its descendant (since *some* of these + notifications imply that style reresolution is required on all + descendants). +- We wait to reconstruct frames that require reconstruction (after + destroying frames eagerly). This, like the tree-based style + reresolution batching, avoids duplication both for same-element + notifications and ancestor-descendant notifications, even though it + doesn\'t actually do any tree-based caching. +- We postpone doing reflows until needed. As for style reresolution, + this maintains tree-based dirty bits (see the description of + NS\_FRAME\_IS\_DIRTY and NS\_FRAME\_HAS\_DIRTY\_CHILDREN under + Reflow). +- We allow the OS to queue up multiple invalidates before repainting + (though we will likely switch to controlling that ourselves). This + leads to a single repaint of some set of pixels where there might + otherwise have been multiple (though it may also lead to more pixels + being repainted if multiple rectangles are merged to a single one). + +Having changes buffered up means, however, that various pieces of +information (layout, style, etc.) may not be up-to-date. Some things +require up-to-date information: for example, we don\'t want to expose +the details of our buffering to Web page script since the programming +model of Web page script assumes that DOM changes take effect +\"immediately\", i.e., that the script shouldn\'t be able to detect any +buffering. Many Web pages depend on this. + +We therefore have ways to flush these different sorts of buffers. There +are methods called FlushPendingNotifications on nsIDocument and +nsIPresShell, that take an argument of what things to flush: + +- Flush\_Content: create all the content nodes from data buffered in + the parser +- Flush\_ContentAndNotify: the above, plus notify document observers + about the creation of all nodes created so far +- Flush\_Style: the above, plus make sure style data are up-to-date +- Flush\_Frames: the above, plus make sure all frame construction has + happened (currently the same as Flush\_Style) +- Flush\_InterruptibleLayout: the above, plus perform layout (Reflow), + but allow interrupting layout if it takes too long +- Flush\_Layout: the above, plus ensure layout (Reflow) runs to + completion +- Flush\_Display (should never be used): the above, plus ensure + repainting happens + +The major way that notifications of changes propagate from the content +code to layout and other areas of code is through the +nsIDocumentObserver and nsIMutationObserver interfaces. Classes can +implement this interface to listen to notifications of changes for an +entire document or for a subtree of the content tree. + +WRITE ME: \... layout document observer implementations + +TODO: how style system optimizes away rerunning selector matching + +TODO: style changes and nsChangeHint diff --git a/layout/docs/LayoutOverview.md b/layout/docs/LayoutOverview.md new file mode 100644 index 0000000000..0375ab5480 --- /dev/null +++ b/layout/docs/LayoutOverview.md @@ -0,0 +1,529 @@ +# Layout Overview + +Much of the layout code deals with operations on the frame tree (or +rendering tree). In the frame tree, each node represents a rectangle +(or, for SVG, other shapes). The frame tree has a shape similar to the +content tree, since many content nodes have one corresponding frame, +though it differs in a few ways, since some content nodes have more than +one frame or don\'t have any frames at all. When elements are +display:none in CSS or undisplayed for certain other reasons, they +won\'t have any frames. When elements are broken across lines or pages, +they have multiple frames; elements may also have multiple frames when +multiple frames nested inside each other are needed to display a single +element (for example, a table, a table cell, or many types of form +controls). + +Each node in the frame tree is an instance of a class derived from +`nsIFrame`. As with the content tree, there is a substantial type +hierarchy, but the type hierarchy is very different: it includes types +like text frames, blocks and inlines, the various parts of tables, flex +and grid containers, and the various types of HTML form controls. + +Frames are allocated within an arena owned by the PresShell. Each frame +is owned by its parent; frames are not reference counted, and code must +not hold on to pointers to frames. To mitigate potential security bugs +when pointers to destroyed frames, we use [frame +poisoning](http://robert.ocallahan.org/2010/10/mitigating-dangling-pointer-bugs-using_15.html), +which takes two parts. When a frame is destroyed other than at the end +of life of the presentation, we fill its memory with a pattern +consisting of a repeated pointer to inaccessible memory, and then put +the memory on a per-frame-class freelist. This means that if code +accesses the memory through a dangling pointer, it will either crash +quickly by dereferencing the poison pattern or it will find a valid +frame. + +Like the content tree, frames must be accessed only from the UI thread. + +The frame tree should not store any important data, i.e. any data that +cannot be recomputed on-the-fly. While the frame tree does usually +persist while a page is being displayed, frames are often destroyed and +recreated in response to certain style changes, and in the future we may +do the same to reduce memory use for pages that are currently inactive. +There were a number of cases where this rule was violated in the past +and we stored important data in the frame tree; however, most (though +not quite all) such cases are now fixed. + +The rectangle represented by the frame is what CSS calls the element\'s +border box. This is the outside edge of the border (or the inside edge +of the margin). The margin lives outside the border; and the padding +lives inside the border. In addition to nsIFrame::GetRect, we also have +the APIs nsIFrame::GetPaddingRect to get the padding box (the outside +edge of the padding, or inside edge of the border) and +nsIFrame::GetContentRect to get the content box (the outside edge of the +content, or inside edge of the padding). These APIs may produce out of +date results when reflow is needed (or has not yet occurred). + +In addition to tracking a rectangle, frames also track two overflow +areas: ink overflow and scrollable overflow. These overflow areas +represent the union of the area needed by the frame and by all its +descendants. The ink overflow is used for painting-related +optimizations: it is a rectangle covering all of the area that might be +painted when the frame and all of its descendants paint. The scrollable +overflow represents the area that the user should be able to scroll to +to see the frame and all of its descendants. In some cases differences +between the frame\'s rect and its overflow happen because of descendants +that stick out of the frame; in other cases they occur because of some +characteristic of the frame itself. The two overflow areas are similar, +but there are differences: for example, margins are part of scrollable +overflow but not ink overflow, whereas text-shadows are part of ink +overflow but not scrollable overflow. + +When frames are broken across lines, columns, or pages, we create +multiple frames representing the multiple rectangles of the element. The +first one is the primary frame, and the rest are its continuations +(which are more likely to be destroyed and recreated during reflow). +These frames are linked together as continuations: they have a +doubly-linked list that can be used to traverse the continuations using +nsIFrame::GetPrevContinuation and nsIFrame::GetNextContinuation. +(Currently continuations always have the same style data, though we may +at some point want to break that invariant.) + +Continuations are sometimes siblings of each other (i.e. +nsIFrame::GetNextContinuation and nsIFrame::GetNextSibling might return +the same frame), and sometimes not. For example, if a paragraph contains +a span which contains a link, and the link is split across lines, then +the continuations of the span are siblings (since they are both children +of the paragraph), but the continuations of the link are not siblings +(since each continuation of the link is descended from a different +continuation of the span). Traversing the entire frame tree does **not** +require explicit traversal of any frames\' continuations-list, since all +of the continuations are descendants of the element containing the +break. + +We also use continuations for cases (most importantly, bidi reordering, +where left-to-right text and right-to-left text need to be separated +into different continuations since they may not form a contiguous +rectangle) where the continuations should not be rewrapped during +reflow: we call these continuations fixed rather than fluid. +nsIFrame::GetNextInFlow and nsIFrame::GetPrevInFlow traverse only the +fluid continuations and do not cross fixed continuation boundaries. + +If an inline frame has non-inline children, then we split the original +inline frame into parts. The original inline\'s children are distributed +into these parts like so: The children of the original inline are +grouped into runs of inline and non-inline, and runs of inline get an +inline parent, while runs of non-inline get an anonymous block parent. +We call this \'ib-splitting\' or \'block-inside-inline splitting\'. This +splitting proceeds recursively up the frame tree until all non-inlines +inside inlines are ancestors of a block frame with anonymous block +wrappers in between. This splitting maintains the relative order between +these child frames, and the relationship between the parts of a split +inline is maintained using an ib-sibling chain. It is important to note +that any wrappers created during frame construction (such as for tables) +might not be included in the ib-sibling chain depending on when this +wrapper creation takes place. + +TODO: nsBox craziness from + + +TODO: link to documentation of block and inline layout + +TODO: link to documentation of scrollframes + +TODO: link to documentation of XUL frame classes + +Code (note that most files in base and generic have useful one line +descriptions at the top that show up in DXR): + +- [layout/base/](http://dxr.mozilla.org/mozilla-central/source/layout/base/) + contains objects that coordinate everything and a bunch of other + miscellaneous things +- [layout/generic/](http://dxr.mozilla.org/mozilla-central/source/layout/generic/) + contains the basic frame classes as well as support code for their + reflow methods (ReflowInput, ReflowOutput) +- [layout/forms/](http://dxr.mozilla.org/mozilla-central/source/layout/forms/) + contains frame classes for HTML form controls +- [layout/tables/](http://dxr.mozilla.org/mozilla-central/source/layout/tables/) + contains frame classes for CSS/HTML tables +- [layout/mathml/](http://dxr.mozilla.org/mozilla-central/source/layout/mathml/) + contains frame classes for MathML +- [layout/svg/](http://dxr.mozilla.org/mozilla-central/source/layout/svg/) + contains frame classes for SVG +- [layout/xul/](http://dxr.mozilla.org/mozilla-central/source/layout/xul/) + contains frame classes for the XUL box model and for various XUL + widgets + +Bugzilla: + +- All of the components whose names begin with \"Layout\" in the + \"Core\" product + +Further documentation: + +- Talk: [Introduction to graphics/layout + architecture](https://air.mozilla.org/introduction-to-graphics-layout-architecture/) + (Robert O\'Callahan, 2014-04-18) +- Talk: [Layout and + Styles](https://air.mozilla.org/bz-layout-and-styles/) (Boris + Zbarsky, 2014-10-14) + +## Frame Construction + +Frame construction is the process of creating frames. This is done when +styles change in ways that require frames to be created or recreated or +when nodes are inserted into the document. The content tree and the +frame tree don\'t have quite the same shape, and the frame construction +process does some of the work of creating the right shape for the frame +tree. It handles the aspects of creating the right shape that don\'t +depend on layout information. So for example, frame construction handles +the work needed to implement [table anonymous +objects](http://www.w3.org/TR/CSS21/tables.html#anonymous-boxes) but +does not handle frames that need to be created when an element is broken +across lines or pages. + +The basic unit of frame construction is a run of contiguous children of +a single parent element. When asked to construct frames for such a run +of children, the frame constructor first determines, based on the +siblings and parent of the nodes involved, where in the frame tree the +new frames should be inserted. Then the frame constructor walks through +the list of content nodes involved and for each one creates a temporary +data structure called a **frame construction item**. The frame +construction item encapsulates various information needed to create the +frames for the content node: its style data, some metadata about how one +would create a frame for this node based on its namespace, tag name, and +styles, and some data about what sort of frame will be created. This +list of frame construction items is then analyzed to see whether +constructing frames based on it and inserting them at the chosen +insertion point will produce a valid frame tree. If it will not, the +frame constructor either fixes up the list of frame construction items +so that the resulting frame tree would be valid or throws away the list +of frame construction items and requests the destruction and re-creation +of the frame for the parent element so that it has a chance to create a +list of frame construction items that it ``{=html}can``{=html} +fix up. + +Once the frame constructor has a list of frame construction items and an +insertion point that would lead to a valid frame tree, it goes ahead and +creates frames based on those items. Creation of a non-leaf frame +recursively attempts to create frames for the children of that frame\'s +element, so in effect frames are created in a depth-first traversal of +the content tree. + +The vast majority of the code in the frame constructor, therefore, falls +into one of these categories: + +- Code to determine the correct insertion point in the frame tree for + new frames. +- Code to create, for a given content node, frame construction items. + This involves some searches through static data tables for metadata + about the frame to be created. +- Code to analyze the list of frame construction items. +- Code to fix up the list of frame construction items. +- Code to create frames from frame construction items. + +Code: +[layout/base/nsCSSFrameConstructor.h](http://dxr.mozilla.org/mozilla-central/source/layout/base/nsCSSFrameConstructor.h) +and +[layout/base/nsCSSFrameConstructor.cpp](http://dxr.mozilla.org/mozilla-central/source/layout/base/nsCSSFrameConstructor.cpp) + +## Physical Sizes vs. Logical Sizes + +TODO: Discuss inline-size (typically width) and block size (typically +height), writing modes, and the various logical vs. physical size/rect +types. + +## Reflow + +Reflow is the process of computing the positions and sizes of frames. +(After all, frames represent rectangles, and at some point we need to +figure out exactly \*what\* rectangle.) Reflow is done recursively, with +each frame\'s Reflow method calling the Reflow methods on that frame\'s +descendants. + +In many cases, the correct results are defined by CSS specifications +(particularly [CSS 2.1](http://www.w3.org/TR/CSS21/visudet.html)). In +some cases, the details are not defined by CSS, though in some (but not +all) of those cases we are constrained by Web compatibility. When the +details are defined by CSS, however, the code to compute the layout is +generally structured somewhat differently from the way it is described +in the CSS specifications, since the CSS specifications are generally +written in terms of constraints, whereas our layout code consists of +algorithms optimized for incremental recomputation. + +The reflow generally starts from the root of the frame tree, though some +other types of frame can act as \"reflow roots\" and start a reflow from +them (nsTextControlFrame is one example; see the +[NS\_FRAME\_REFLOW\_ROOT](https://searchfox.org/mozilla-central/search?q=symbol:E_%3CT_nsFrameState%3E_NS_FRAME_REFLOW_ROOT&redirect=true) +frame state bit). Reflow roots must obey the invariant that a change +inside one of their descendants never changes their rect or overflow +areas (though currently scrollbars are reflow roots but don\'t quite +obey this invariant). + +In many cases, we want to reflow a part of the frame tree, and we want +this reflow to be efficient. For example, when content is added or +removed from the document tree or when styles change, we want the amount +of work we need to redo to be proportional to the amount of content. We +also want to efficiently handle a series of changes to the same content. + +To do this, we maintain two bits on frames: +[NS\_FRAME\_IS\_DIRTY](https://searchfox.org/mozilla-central/search?q=symbol:E_%3CT_nsFrameState%3E_NS_FRAME_IS_DIRTY&redirect=true) +indicates that a frame and all of its descendants require reflow. +[NS\_FRAME\_HAS\_DIRTY\_CHILDREN](https://searchfox.org/mozilla-central/search?q=symbol:E_%3CT_nsFrameState%3E_NS_FRAME_HAS_DIRTY_CHILDREN&redirect=true) +indicates that a frame has a descendant that is dirty or has had a +descendant removed (i.e., that it has a child that has +NS\_FRAME\_IS\_DIRTY or NS\_FRAME\_HAS\_DIRTY\_CHILDREN or it had a +child removed). These bits allow coalescing of multiple updates; this +coalescing is done in PresShell, which tracks the set of reflow roots +that require reflow. The bits are set during calls to +[PresShell::FrameNeedsReflow](https://searchfox.org/mozilla-central/search?q=PresShell%3A%3AFrameNeedsReflow&path=) +and are cleared during reflow. + +The layout algorithms used by many of the frame classes are those +specified in CSS, which are based on the traditional document formatting +model, where widths are input and heights are output. + +In some cases, however, widths need to be determined based on the +content. This depends on two *intrinsic widths*: the minimum intrinsic +width (see +[nsIFrame::GetMinISize](https://searchfox.org/mozilla-central/search?q=nsIFrame%3A%3AGetMinISize&path=)) +and the preferred intrinsic width (see +[nsIFrame::GetPrefISize](https://searchfox.org/mozilla-central/search?q=nsIFrame%3A%3AGetPrefISize&path=)). +The concept of what these widths represent is best explained by +describing what they are on a paragraph containing only text: in such a +paragraph the minimum intrinsic width is the width of the longest word, +and the preferred intrinsic width is the width of the entire paragraph +laid out on one line. + +Intrinsic widths are invalidated separately from the dirty bits +described above. When a caller informs the pres shell that a frame needs +reflow (PresShell::FrameNeedsReflow), it passes one of three options: + +- eResize indicates that no intrinsic widths are dirty +- eTreeChange indicates that intrinsic widths on it and its ancestors + are dirty (which happens, for example, if new children are added to + it) +- eStyleChange indicates that intrinsic widths on it, its ancestors, + and its descendants are dirty (for example, if the font-size + changes) + +Reflow is the area where the XUL frame classes (those that inherit from +nsBoxFrame or nsLeafBoxFrame) are most different from the rest. Instead +of using nsIFrame::Reflow, they do their layout computations using +intrinsic size methods called GetMinSize, GetPrefSize, and GetMaxSize +(which report intrinsic sizes in two dimensions) and a final layout +method called Layout. In many cases these methods defer some of the +computation to a separate object called a layout manager. + +When an individual frame\'s Reflow method is called, most of the input +is provided on an object called ReflowInput and the output is filled in +to an object called ReflowOutput. After reflow, the caller (usually the +parent) is responsible for setting the frame\'s size based on the +metrics reported. (This can make some computations during reflow +difficult, since the new size is found in either the reflow state or the +metrics, but the frame\'s size is still the old size. However, it\'s +useful for invalidating the correct areas that need to be repainted.) + +One major difference worth noting is that in XUL layout, the size of the +child is set prior to its parent calling its Layout method. (Once +invalidation uses display lists and is no longer tangled up in Reflow, +it may be worth switching non-XUL layout to work this way as well.) + +## Painting + +TODO: display lists (and event handling) + +TODO: layers + +## Pagination + +Pagination (also known as fragmentation) is a concept used in printing, +print-preview, and multicolumn layout. + +### Continuations in the Frame Tree + +To render a DOM node, represented as `nsIContent` object, Gecko creates +zero or more frames (`nsIFrame` objects). Each frame represents a +rectangular area usually corresponding to the node\'s CSS box as +described by the CSS specs. Simple elements are often representable with +exactly one frame, but sometimes an element needs to be represented with +more than one frame. For example, text breaking across lines: + + xxxxxx AAAA + AAA xxxxxxx + +The A element is a single DOM node but obviously a single rectangular +frame isn\'t going to represent its layout precisely. + +Similarly, consider text breaking across pages: + + | BBBBBBBBBB | + | BBBBBBBBBB | + +------------+ + + +------------+ + | BBBBBBBBBB | + | BBBBBBBBBB | + | | + +Again, a single rectangular frame cannot represent the layout of the +node. Columns are similar. + +Another case where a single DOM node is represented by multiple frames +is when a text node contains bidirectional text (e.g. both Hebrew and +English text). In this case, the text node and its inline ancestors are +split so that each frame contains only unidirectional text. + +The first frame for an element is called the **primary frame**. The +other frames are called **continuation frames**. Primary frames are +created by `nsCSSFrameConstructor` in response to content insertion +notifications. Continuation frames are created during bidi resolution, +and during reflow, when reflow detects that a content element cannot be +fully laid out within the constraints assigned (e.g., when inline text +will not fit within a particular width constraint, or when a block +cannot be laid out within a particular height constraint). + +Continuation frames created during reflow are called \"fluid\" +continuations (or \"in-flows\"). Other continuation frames (currently, +those created during bidi resolution), are, in contrast, \"non-fluid\". +The `NS_FRAME_IS_FLUID_CONTINUATION` state bit indicates whether a +continuation frame is fluid or not. + +The frames for an element are put in a doubly-linked list. The links are +accessible via `nsIFrame::GetNextContinuation` and +`nsIFrame::GetPrevContinuation`. If only fluid continuations are to be +accessed, `nsIFrame::GetNextInFlow` and `nsIFrame::GetPrevInFlow` are +used instead. + +The following diagram shows the relationship between the original frame +tree considering just primary frames, and a possible layout with +breaking and continuations: + + Original frame tree Frame tree with A broken into three parts + Root Root + | / | \ + A A1 A2 A3 + / \ / | | | + B C B C1 C2 C3 + | /|\ | | | \ | + D E F G D E F G1 G2 + +Certain kinds of frames create multiple child frames for the same +content element: + +- `nsPageSequenceFrame` creates multiple page children, each one + associated with the entire document, separated by page breaks +- `nsColumnSetFrame` creates multiple block children, each one + associated with the column element, separated by column breaks +- `nsBlockFrame` creates multiple inline children, each one associated + with the same inline element, separated by line breaks, or by + changes in text direction +- `nsTableColFrame` creates non-fluid continuations for itself if it + has span=\"N\" and N \> 1 +- If a block frame is a multi-column container and has + `column-span:all` children, it creates multiple `nsColumnSetFrame` + children, which are linked together as non-fluid continuations. + Similarly, if a block frame is within a multi-column formatting + context and has `column-span:all` children, it is chopped into + several flows, which are linked together as non-fluid continuations + as well. See documentation and example frame trees in + [`nsCSSFrameConstructor::ConstructBlock()`](https://searchfox.org/mozilla-central/rev/d24696b5abaf9fb75f7985952eab50d5f4ed52ac/layout/base/nsCSSFrameConstructor.cpp#10431). + +#### Overflow Container Continuations + +Sometimes the content of a frame needs to break across pages even though +the frame itself is complete. This usually happens if an element with +fixed height has overflow that doesn\'t fit on one page. In this case, +the completed frame is \"overflow incomplete\", and special +continuations are created to hold its overflow. These continuations are +called \"overflow containers\". They are invisible, and are kept on a +special list in their parent. See documentation in +[nsContainerFrame.h](https://searchfox.org/mozilla-central/source/layout/generic/nsContainerFrame.h) +and example trees in [bug 379349 comment +3](https://bugzilla.mozilla.org/show_bug.cgi?id=379349#c3). + +This infrastructure was extended in [bug +154892](https://bugzilla.mozilla.org/show_bug.cgi?id=154892) to also +manage continuations for absolutely-positioned frames. + +#### Relationship of continuations to frame tree structure + +It is worth emphasizing two points about the relationship of the +prev-continuation / next-continuation linkage to the existing frame tree +structure. + +First, if you want to traverse the frame tree or a subtree thereof to +examine all the frames once, you do ``{=html}not``{=html} want +to traverse next-continuation links. All continuations are reachable by +traversing the `GetNextSibling` links from the result of `GetFirstChild` +for all child lists. + +Second, the following property holds: + +- Consider two frames F1 and F2 where F1\'s next-continuation is F2 + and their respective parent frames are P1 and P2. Then either P1\'s + next continuation is P2, or P1 == P2, because P is responsible for + breaking F1 and F2. + +In other words, continuations are sometimes siblings of each other, and +sometimes not. If their parent content was broken at the same point, +then they are not siblings, since they are children of different +continuations of the parent. So in the frame tree for the markup + +` 

This is some 
text.

` + +the two continuations for the `b` element are siblings (unless the line +break is also a page break), but the two continuations for the `i` +element are not. + +There is an exception to that property when F1 is a first-in-flow float +placeholder. In that case F2\'s parent will be the next-in-flow of F1\'s +containing block. + +### Reflow statuses + +The aStatus argument of Reflow reflects that. `IsComplete()` means that +we reflowed all the content and no more next-in-flows are needed. At +that point there may still be next in flows, but the parent will delete +them. `IsIncomplete()` means \"some content did not fit in this frame\". +`IsOverflowIncomplete()` means that the frame is itself complete, but +some of its content didn\'t fit: this triggers the creation of overflow +containers for the frame\'s continuations. `IsIncomplete()` and +`NextInFlowNeedsReflow()` means \"some content did not fit in this frame +AND it must be reflowed\". These values are defined and documented in +[nsIFrame.h](https://searchfox.org/mozilla-central/source/layout/generic/nsIFrame.h) +(search for \"Reflow status\"). + +### Dynamic Reflow Considerations + +When we reflow a frame F with fluid continuations, two things can +happen: + +- Some child frames do not fit in the passed-in width or height + constraint. These frames must be \"pushed\" to F\'s next-in-flow. If + F has no next-in-flow, we must create one under F\'s parent\'s + next-in-flow \-\-- or if F\'s parent is managing the breaking of F, + then we create F\'s next in flow directly under F\'s parent. If F is + a block, it pushes overflowing child frames to its \"overflow\" + child list and forces F\'s next in flow to be reflowed. When we + reflow a block, we pull the child frames from the prev-in-flow\'s + overflow list into the current frame. +- All child frames fit in the passed-in width or height constraint. + Then child frames must be \"pulled\" from F\'s next-in-flow to fill + in the available space. If F\'s next-in-flow becomes empty, we may + be able to delete it. + +In both of these situations we might end up with a frame F containing +two child frames, one of which is a continuation of the other. This is +incorrect. We might also create holes, where there are frames P1 P2 and +P3, P1 has child F1 and P3 has child F2, but P2 has no F child. + +A strategy for avoiding these issues is this: When pulling a frame F2 +from parent P2 to prev-in-flow P1, if F2 is a breakable container, then: + +- If F2 has no prev-in-flow F1 in P1, then create a new primary frame + F1 in P1 for F2\'s content, with F2 as its next-in-flow. +- Pull children from F2 to F1 until F2 is empty or we run out of + space. If F2 goes empty, pull from the next non-empty next-in-flow. + Empty continuations with no next-in-flows can be deleted. + +When pushing a frame F1 from parent P1 to P2, where F1 has a +next-in-flow F2 (which must be a child of P2): + +- Merge F2 into F1 by moving all F2\'s children into F1, then deleting + F2 + +For inline frames F, we have our own custom strategy that coalesces +adjacent inline frames. This need not change. + +We do need to implement this strategy when F is a normal in-flow block, +a floating block, and eventually an absolutely positioned block. diff --git a/layout/docs/StyleSystemOverview.md b/layout/docs/StyleSystemOverview.md new file mode 100644 index 0000000000..bed5fd057f --- /dev/null +++ b/layout/docs/StyleSystemOverview.md @@ -0,0 +1,173 @@ +# Style System Overview + +## Quantum CSS (Stylo) + +Starting with Firefox 57 and later, Gecko makes use of the parallel +style system written in Rust that comes from Servo. There\'s an +[overview](https://hacks.mozilla.org/2017/08/inside-a-super-fast-css-engine-quantum-css-aka-stylo/) +of this with graphics to help explain what\'s going on. The [Servo +wiki](https://github.com/servo/servo/wiki/Layout-Overview) has some more +details. + +## Gecko + +The rest of the style section section describes the Gecko style system +used in Firefox 56 and earlier. Some bits may still apply, but it likely +needs revising. + +In order to display the content, Gecko needs to compute the styles +relevant to each DOM node. It does this based on the model described in +the CSS specifications: this model applies to style specified in CSS +(e.g. by a \'style\' element, an \'xml-stylesheet\' processing +instruction or a \'style\' attribute), style specified by presentation +attributes, and the default style specified by our own user agent style +sheets. There are two major sets of data structures within the style +system: + +- first, data structures that represent sources of style data, such as + CSS style sheets or data from stylistic HTML attributes +- second, data structures that represent computed style for a given + DOM node. + +These sets of data structures are mostly distinct (for example, they +store values in different ways). + +The loading of CSS style sheets from the network is managed by the [CSS +loader](https://dxr.mozilla.org/mozilla-central/source/layout/style/Loader.h); +they are then tokenized by the [CSS +scanner](https://dxr.mozilla.org/mozilla-central/source/layout/style/nsCSSScanner.h) +and parsed by the [CSS +parser](https://dxr.mozilla.org/mozilla-central/source/layout/style/nsCSSParser.h). +Those that are attached to the document also expose APIs to script that +are known as the CSS Object Model, or CSSOM. + +The style sheets that apply to a document are managed by a class called +the [style +set](https://dxr.mozilla.org/mozilla-central/source/layout/style/nsStyleSet.h). +The style set interacts with the different types of style sheets +(representing CSS style sheets, presentational attributes, and \'style\' +attributes) through two interfaces: +[nsIStyleSheet](http://dxr.mozilla.org/mozilla-central/source/layout/style/nsIStyleSheet.h) +for basic management of style sheets and +[nsIStyleRuleProcessor](http://dxr.mozilla.org/mozilla-central/source/layout/style/nsIStyleRuleProcessor.h) +for getting the style data out of them. Usually the same object +implements both interfaces, except in the most important case, CSS style +sheets, where there is a single rule processor for all of the CSS style +sheets in each origin (user/UA/author) of the CSS cascade. + +The computed style data for an element/frame are exposed to the rest of +Gecko through the class mozilla::ComputedStyle (previously called +nsStyleContext). Rather than having a member variable for each CSS +property, it breaks up the properties into groups of related properties +called style structs. These style structs obey the rule that all of the +properties in a single struct either inherit by default (what the CSS +specifications call \"Inherited: yes\" in the definition of properties; +we call these inherited structs) or all are not inherited by default (we +call these reset structs). Separating the properties in this way +improves the ability to share the structs between similar ComputedStyle +objects and reduce the amount of memory needed to store the style data. +The ComputedStyle API exposes a method for getting each struct, so +you\'ll see code like `sc->GetStyleText()->mTextAlign` for getting the +value of the text-align CSS property. (Frames (see the Layout section +below) also have the same GetStyle\* methods, which just forward the +call to the frame\'s ComputedStyle.) + +The ComputedStyles form a tree structure, in a shape somewhat like the +content tree (except that we coalesce identical sibling ComputedStyles +rather than keeping two of them around; if the parents have been +coalesced then this can apply recursively and coalasce cousins, etc.; we +do not coalesce parent/child ComputedStyles). The parent of a +ComputedStyle has the style data that the ComputedStyle inherits from +when CSS inheritance occurs. This means that the parent of the +ComputedStyle for a DOM element is generally the ComputedStyle for that +DOM element\'s parent, since that\'s how CSS says inheritance works. + +The process of turning the style sheets into computed style data goes +through three main steps, the first two of which closely relate to the +[nsIStyleRule](http://dxr.mozilla.org/mozilla-central/source/layout/style/nsIStyleRule.h) +interface, which represents an immutable source of style data, +conceptually representing (and for CSS style rules, directly storing) a +set of property:value pairs. (It is similar to the idea of a CSS style +rule, except that it is immutable; this immutability allows for +significant optimization. When a CSS style rule is changed through +script, we create a new style rule.) + +The first step of going from style sheets to computed style data is +finding the ordered sequence of style rules that apply to an element. +The order represents which rules override which other rules: if two +rules have a value for the same property, the higher ranking one wins. +(Note that there\'s another difference from CSS style rules: +declarations with !important are represented using a separate style +rule.) This is done by calling one of the +nsIStyleRuleProcessor::RulesMatching methods. The ordered sequence is +stored in a [trie](http://en.wikipedia.org/wiki/Trie) called the rule +tree: the path from the root of the rule tree to any (leaf or non-leaf) +node in the rule tree represents a sequence of rules, with the highest +ranking farthest from the root. Each rule node (except for the root) has +a pointer to a rule, but since a rule may appear in many sequences, +there are sometimes many rule nodes pointing to the same rule. Once we +have this list we create a ComputedStyle (or find an appropriate +existing sibling) with the correct parent pointer (for inheritance) and +rule node pointer (for the list of rules), and a few other pieces of +information (like the pseudo-element). + +The second step of going from style sheets to computed style data is +getting the winning property:value pairs from the rules. (This only +provides property:value pairs for some of the properties; the remaining +properties will fall back to inheritance or to their initial values +depending on whether the property is inherited by default.) We do this +step (and the third) for each style struct, the first time it is needed. +This is done in nsRuleNode::WalkRuleTree, where we ask each style rule +to fill in its property:value pairs by calling its MapRuleInfoInto +function. When called, the rule fills in only those pairs that haven\'t +been filled in already, since we\'re calling from the highest priority +rule to the lowest (since in many cases this allows us to stop before +going through the whole list, or to do partial computation that just +adds to data cached higher in the rule tree). + +The third step of going from style sheets to computed style data (which +various caching optimizations allow us to skip in many cases) is +actually doing the computation; this generally means we transform the +style data into the data type described in the \"Computed Value\" line +in the property\'s definition in the CSS specifications. This +transformation happens in functions called nsRuleNode::Compute\*Data, +where the \* in the middle represents the name of the style struct. This +is where the transformation from the style sheet value storage format to +the computed value storage format happens. + +Once we have the computed style data, we then store it: if a style +struct in the computed style data doesn\'t depend on inherited values or +on data from other style structs, then we can cache it in the rule tree +(and then reuse it, without recomputing it, for any ComputedStyles +pointing to that rule node). Otherwise, we store it on the ComputedStyle +(in which case it may be shared with the ComputedStyle\'s descendant +ComputedStyles). This is where keeping inherited and non-inherited +properties separate is useful: in the common case of relatively few +properties being specified, we can generally cache the non-inherited +structs in the rule tree, and we can generally share the inherited +structs up and down the ComputedStyle tree. + +The ownership models in style sheet structures are a mix of reference +counted structures (for things accessible from script) and directly +owned structures. ComputedStyles are reference counted, and own their +parents (from which they inherit), and rule nodes are garbage collected +with a simple mark and sweep collector (which often never needs to run). + +- code: + [layout/style/](http://dxr.mozilla.org/mozilla-central/source/layout/style/), + where most files have useful one line descriptions at the top that + show up in DXR +- Bugzilla: Style System (CSS) +- specifications + - [CSS 2.1](http://www.w3.org/TR/CSS21/) + - [CSS 2010, listing stable css3 + modules](http://www.w3.org/TR/css-2010/) + - [CSS WG editors drafts](http://dev.w3.org/csswg/) (often more + current, but sometimes more unstable than the drafts on the + technical reports page) + - [Preventing attacks on a user\'s history through CSS :visited + selectors](http://dbaron.org/mozilla/visited-privacy) +- documentation + - [style system + documentation](http://www-archive.mozilla.org/newlayout/doc/style-system.html) + (somewhat out of date) diff --git a/layout/docs/index.rst b/layout/docs/index.rst index 16d9df8b05..39455a1075 100644 --- a/layout/docs/index.rst +++ b/layout/docs/index.rst @@ -1,8 +1,9 @@ -Layout & CSS -============ +Style system (CSS) & Layout +=========================== -Here contains design documents for the Gecko's style system and layout engine. -They live in the mozilla-central repository under layout/docs directory. +Here contains the overview and design documents for Firefox's layout engine and +style system. They live in the mozilla-central repository under `layout/docs +`__ directory. `Layout page `__ on mozilla wiki contains general information about layout and the layout team at Mozilla. @@ -10,6 +11,9 @@ contains general information about layout and the layout team at Mozilla. .. toctree:: :maxdepth: 1 - AccessibleCaret + StyleSystemOverview + LayoutOverview + DynamicChangeHandling Reftest LayoutDebugger + AccessibleCaret -- cgit v1.2.3