Module layer_followers

Reference for the layer follower system.

Layer Followers

Layer followers let one layer get repainted and have damage tracking following a second layer. This is primarily used by LayerTree::replicate_node to mirror an existing layer, using layer_as_content to share the rendering logic.

Relationship Setup

• The declarative entry-point is the optional replicate_node field on LayerTree (src/view/layer_tree.rs:105). When a view tree includes this field, the build step tries to resolve the referenced layer.
• During tree construction, build_layer_tree sets the follower’s draw callback with Layer::set_draw_content and registers the follower with the source layer via Layer::add_follower_node (src/view/build_layer_tree.rs:162-166).
• Layer::add_follower_node stores the follower id inside the source SceneNode.followers set and schedules a NoopChange so the engine treats the source as dirty (src/layers/layer/mod.rs:512-523; src/engine/command.rs:99-114).

Engine Tracking and Layout

• SceneNode maintains a HashSet<NodeRef> named followers, ensuring each follower is tracked exactly once even if the view layer replays the same relationship (src/engine/node/mod.rs:77-104).
• In the layout stage, whenever a node has RenderableFlags::NEEDS_LAYOUT, the engine also marks each follower as changed. This guarantees a layout pass after updates to the source layer so both leader and follower remain geometrically consistent (src/engine/stages/mod.rs:193-201).
• Followers rely on the scheduled NoopChange to flag the leader as needing both layout and paint, which in turn triggers the follower bookkeeping above.

Rendering Pipeline

• A follower renders by calling the leader’s Layer::as_content closure, which runs render_node_tree against the source node inside the follower’s own canvas clip (src/layers/layer/mod.rs:535-548; src/drawing/scene.rs:34-45).
• Because drawing happens through the standard scene traversal, all of the source node’s picture and image caches remain valid, and animated or transactional updates on the leader automatically appear during the follower’s draw.
• The follower keeps its own layout, transforms, and pointer handlers—the shared part is purely the picture generated by the source layer subtree.

Cleanup and Caveats

• Removing a follower requires calling Layer::remove_follower_node on the source, which drops the follower id from the SceneNode.followers set (src/layers/layer/mod.rs:525-534). When building dynamic trees, ensure the old relationship is cleared before reusing the follower in a different role.
• Creating circular relationships (a node following one of its ancestors) would recurse indefinitely when render_node_tree executes, so the view layer builder must avoid such configurations.
• The follower mechanism does not clone pointer handlers or model state; if the replicated visual needs independent interactivity, wire new handlers onto the follower layer itself.