Module 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
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§

add_clip_node_to_current_chain 🔒
compute_box_shadow_parameters 🔒
is_left_of_line: Test where point p is relative to the infinite line that passes through the segment defined by p0 and p1. Point p is on the “left” of the line if the triangle (p0, p1, p) forms a counter-clockwise triangle.
polygon_contains_point
projected_rect_contains
rounded_rectangle_contains_box_quick 🔒: Return true if the rounded rectangle described by container and radii definitely contains containee. May return false negatives, but never false positives.
rounded_rectangle_contains_point

Type Aliases§

ClipDataHandle
ClipDataStore
PolygonDataHandle