Module webrender::clip

Expand description

Internal representation of clips in WebRender.

Data structures

There are a number of data structures involved in the clip module:

ClipStore - Main interface used by other modules.
ClipItem - A single clip item (e.g. a rounded rect, or a box shadow). These are an exposed API type, stored inline in a ClipNode.
ClipNode - A ClipItem with an attached GPU handle. The GPU handle is populated when a ClipNodeInstance is built from this node (which happens while preparing primitives for render).

ClipNodeInstance - A ClipNode with attached positioning information (a spatial node index). This is stored as a contiguous array of nodes within the ClipStore.

+-----------------------+-----------------------+-----------------------+
| ClipNodeInstance      | ClipNodeInstance      | ClipNodeInstance      |
+-----------------------+-----------------------+-----------------------+
| ClipItem              | ClipItem              | ClipItem              |
| Spatial Node Index    | Spatial Node Index    | Spatial Node Index    |
| GPU cache handle      | GPU cache handle      | GPU cache handle      |
| ...                   | ...                   | ...                   |
+-----------------------+-----------------------+-----------------------+
           0                        1                       2
   +----------------+    |                                              |
   | ClipNodeRange  |____|                                              |
   |    index: 1    |                                                   |
   |    count: 2    |___________________________________________________|
   +----------------+

ClipNodeRange - A clip item range identifies a range of clip nodes instances. It is stored as an (index, count).
ClipChainNode - A clip chain node contains a handle to an interned clip item, positioning information (from where the clip was defined), and an optional parent link to another ClipChainNode. ClipChainId is an index into an array, or ClipChainId::NONE for no parent.

+----------------+    ____+----------------+    ____+----------------+   /---> ClipChainId::NONE
| ClipChainNode  |   |    | ClipChainNode  |   |    | ClipChainNode  |   |
+----------------+   |    +----------------+   |    +----------------+   |
| ClipDataHandle |   |    | ClipDataHandle |   |    | ClipDataHandle |   |
| Spatial index  |   |    | Spatial index  |   |    | Spatial index  |   |
| Parent Id      |___|    | Parent Id      |___|    | Parent Id      |___|
| ...            |        | ...            |        | ...            |
+----------------+        +----------------+        +----------------+

ClipChainInstance - A ClipChain that has been built for a specific primitive + positioning node.

When given a clip chain ID, and a local primitive rect and its spatial node, the clip module creates a clip chain instance. This is a struct with various pieces of useful information (such as a local clip rect). It also contains a (index, count) range specifier into an index buffer of the ClipNodeInstance structures that are actually relevant for this clip chain instance. The index buffer structure allows a single array to be used for all of the clip-chain instances built in a single frame. Each entry in the index buffer also stores some flags relevant to the clip node in this positioning context.

+----------------------+
| ClipChainInstance    |
+----------------------+
| ...                  |
| local_clip_rect      |________________________________________________________________________
| clips_range          |_______________                                                        |
+----------------------+              |                                                        |
                                      |                                                        |
+------------------+------------------+------------------+------------------+------------------+
| ClipNodeInstance | ClipNodeInstance | ClipNodeInstance | ClipNodeInstance | ClipNodeInstance |
+------------------+------------------+------------------+------------------+------------------+
| flags            | flags            | flags            | flags            | flags            |
| ...              | ...              | ...              | ...              | ...              |
+------------------+------------------+------------------+------------------+------------------+

Rendering clipped primitives

See the segment module documentation.

Structs

ClipChain
Represents a clip-chain as defined by the public API that we decompose in to the clip-tree. In future, we would like to remove this and have Gecko directly build the clip-tree.
ClipChainInstance
ClipInternData
The data available about an interned clip node during scene building
ClipItem
ClipItemKey
ClipLeafId
ID for a ClipTreeLeaf
ClipNode
ClipNodeFlags
ClipNodeId
ID for a ClipTreeNode
ClipNodeInfo 🔒
ClipNodeInstance
ClipNodeRange
ClipStackEntry
ClipStore
The main clipping public interface that other modules access.
ClipStoreScratchBuffer
ClipTree
A clip-tree built during scene building and used during frame-building to apply clips to primitives.
ClipTreeBuilder
Used by the scene builder to build the clip-tree that is part of the built scene.
ClipTreeLeaf
A leaf node in a clip-tree. Any primitive that is clipped will have a handle to a clip-tree leaf.
ClipTreeNode
A (non-leaf) node inside a clip-tree
ComplexTranslateIter
Geometry
Represents a local rect and a device space rectangles that are either outside or inside bounds.

Enums

ClipIntern
ClipItemKeyKind
ClipItemKind
ClipNodeKind
Helper to identify simple clips (normal rects) from other kinds of clips, which can often be handled via fast code paths.
ClipResult 🔒
ClipSpaceConversion 🔒
A helper struct for converting between coordinate systems of clip sources and primitives.
PolygonIntern
PolygonKeys get interned, because it’s a convenient way to move the data for the polygons out of the ClipItemKind and ClipItemKeyKind enums. The polygon data is both interned and retrieved by the scene builder, and not accessed at all by the frame builder. Another oddity is that the PolygonKey contains the totality of the information about the polygon, so the InternData and StoreData types are both PolygonKey.

Functions