Module 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

ClipEntry

A reference to an interned clip paired with the spatial node that positions it.

ClipInternData

The data available about an interned clip node during scene building

ClipItem

ClipItemEntry

A clip item key paired with the spatial node that positions it, used during scene building.

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

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 🔒

clamped_radius

Clamp corner radii so adjacent radii don’t overlap along an edge of size. Rounded-rect radii are interned unclamped, so consumers must clamp against the instance-specific clip rect before use.

corner_encroaches 🔒

Check if a rounded corner region from a rect whose corner is at (cx, cy) with radius r extends into the intersection rect at corner (ix, iy). (sx, sy) are direction signs toward the rect interior from this corner.

intersect_rounded_rects

Try to intersect two ClipMode::Clip rounded rects (in the same coordinate space) into a single rounded rect. Returns None if the two rounded rects cannot be combined (e.g. their curved regions overlap in a way that can’t be represented by a single rounded rect).

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

resolve_corner_radius 🔒

Determine the radius at a single corner of the intersection of two rounded rects. Each corner is identified by:

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