Skip to content

Update some documentation #3472

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jan 5, 2019
Merged

Update some documentation #3472

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3c8cf21
Remove unused ClipNodeIndex
staktrace Jan 4, 2019
0ad3593
Fix ClipNode documentation
staktrace Jan 4, 2019
d1bd1b6
ClipItemRange isn't a thing anymore, ClipNodeRange is the new hotness.
staktrace Jan 4, 2019
6868ce3
ClipChain isn't a thing, but there's a ClipChainNode
staktrace Jan 4, 2019
8b16400
Update ClipChainInstance docs
staktrace Jan 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion webrender/doc/CLIPPING_AND_POSITIONING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@ also are pushed and popped like stacking contexts.
WebRender must access `ClipNodes` and `SpatialNodes` quite a bit when building
scenes and frames, so it tries to convert `ClipIds`, which are already
per-pipeline indices, to global scene-wide indices. Internally this is a
conversion from `ClipId` into `SpatialNodeIndex`, `ClipNodeIndex` or
conversion from `ClipId` into `SpatialNodeIndex` or
`ClipChainIndex`. In order to make this conversion cheaper, the
`DisplayListFlattner` assigns offsets for each pipeline and node type in the
scene-wide `ClipScrollTree`.
Expand Down
58 changes: 31 additions & 27 deletions webrender/src/clip.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,60 +36,70 @@ use util::{extract_inner_rect_safe, project_rect, ScaleOffset};
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 attached positioning information (a spatial node index).
Stored as a contiguous array of nodes within the ClipStore.
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

+----------------+ | |
| ClipItemRange |____| |
| ClipNodeRange |____| |
| index: 1 | |
| count: 2 |___________________________________________________|
+----------------+

ClipItemRange - A clip item range identifies a range of clip nodes. It is stored
as an (index, count).
ClipNodeRange - A clip item range identifies a range of clip nodes instances.
It is stored as an (index, count).

ClipChain - A clip chain node contains a range of ClipNodes (a ClipItemRange)
and a parent link to an optional ClipChain. Both legacy hierchical clip
chains and user defined API clip chains use the same data structure.
ClipChainId is an index into an array, or ClipChainId::NONE for no parent.
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.

+----------------+ ____+----------------+ ____+----------------+ ____+----------------+
| ClipChain | | | ClipChain | | | ClipChain | | | ClipChain |
+----------------+ | +----------------+ | +----------------+ | +----------------+
| ClipItemRange | | | ClipItemRange | | | ClipItemRange | | | ClipItemRange |
| Parent Id |___| | Parent Id |___| | Parent Id |___| | Parent Id |
+----------------+ +----------------+ +----------------+ +----------------+
+----------------+ ____+----------------+ ____+----------------+ /---> 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 + spatial node, the clip module
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 and affected local bounding rect). It also contains a (index, count)
range specifier into an index buffer of the ClipNode structures that are actually relevant
(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 |
| local_bounding_rect |________________________________________________________________________
| ... |
| local_clip_rect |________________________________________________________________________
| clips_range |_______________ |
+----------------------+ | |
| |
+------------------+------------------+------------------+------------------+------------------+
| ClipNodeInstance | ClipNodeInstance | ClipNodeInstance | ClipNodeInstance | ClipNodeInstance |
+------------------+------------------+------------------+------------------+------------------+
| flags | flags | flags | flags | flags |
| ClipNodeIndex | ClipNodeIndex | ClipNodeIndex | ClipNodeIndex | ClipNodeIndex |
| ... | ... | ... | ... | ... |
+------------------+------------------+------------------+------------------+------------------+

*/
Expand Down Expand Up @@ -206,12 +216,6 @@ pub struct ClipChainNode {
pub parent_clip_chain_id: ClipChainId,
}

// An index into the clip_nodes array.
#[derive(Clone, Copy, Debug, PartialEq, Hash, Eq)]
#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
pub struct ClipNodeIndex(pub u32);

// When a clip node is found to be valid for a
// clip chain instance, it's stored in an index
// buffer style structure. This struct contains
Expand Down