Module webrender::clip

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