Module webrender::scene_building
source · Expand description
§Scene building
Scene building is the phase during which display lists, a representation built for serialization, are turned into a scene, webrender’s internal representation that is suited for rendering frames.
This phase is happening asynchronously on the scene builder thread.
§General algorithm
The important aspects of scene building are:
- Building up primitive lists (much of the cost of scene building goes here).
- Creating pictures for content that needs to be rendered into a surface, be it so that filters can be applied or for caching purposes.
- Maintaining a temporary stack of stacking contexts to keep track of some of the drawing states.
- Stitching multiple display lists which reference each other (without cycles) into a single scene (see build_reference_frame).
- Interning, which detects when some of the retained state stays the same between display lists.
The scene builder linearly traverses the serialized display list which is naturally ordered back-to-front, accumulating primitives in the top-most stacking context’s primitive list. At the end of each stacking context (see pop_stacking_context), its primitive list is either handed over to a picture if one is created, or it is concatenated into the parent stacking context’s primitive list.
The flow of the algorithm is mostly linear except when handling:
- shadow stacks (see push_shadow and pop_all_shadows),
- backdrop filters (see add_backdrop_filter)
Structs§
- A primitive instance + some extra information about the primitive. This is stored when constructing 3d rendering contexts, which involve cutting primitive lists.
- Properties of a stacking context that are maintained during creation of the scene. These structures are not persisted after the initial scene build.
- A data structure that keeps track of mapping between API Ids for spatials and the indices used internally in the SpatialTree to avoid having to do HashMap lookups for primitives and clips during frame building.
- A primitive that is added while a shadow context is active is stored as a pending primitive and only added to pictures during pop_all_shadows.
- As shadows are pushed, they are stored as pending shadows, and handled at once during pop_all_shadows.
- Helper struct to build picture chains during scene building from a flattened stacking context struct.
- A structure that converts a serialized display list into a form that WebRender can use to later build a frame. This structure produces a BuiltScene. Public members are typically those that are destructured into the BuiltScene.
- A helper for reusing the scene builder’s memory allocations and dropping scene allocations on the scene builder thread to avoid lock contention in jemalloc.
- Offsets primitives (and clips) by the external scroll offset supplied to scroll nodes.
- Slice flags
- Internal tracking information about the currently pushed stacking context. Used to track what operations need to happen when a stacking context is popped.
Enums§
- Represents the current input for a picture chain builder (either a prim list from the stacking context, or a wrapped picture instance).