Cryptomatte selection: doc comments for the functions this change touches

crates/ui-egui/src/panels/viewer.rs

@@ -96,6 +96,7 @@ struct Grabs {
     guides: Vec<(f32, bool)>,
 }
 
+/// The egui data key of the viewer's [`Grabs`] for the current pass.
 fn grabs_id() -> egui::Id {
     egui::Id::unique("viewer-grabs")
 }
@@ -1180,6 +1181,8 @@ fn led_by_a_moved_ancestor(comp: &Comp, layers: &[MoveLayer]) -> Vec<bool> {
     layers.iter().map(|l| led(l.0)).collect()
 }
 
+/// Starts the gesture a new primary drag begins (pan, move, scale, a handle, a vertex, a marquee),
+/// unless an overlay claimed the press.
 fn phase_dragstart(app: &mut EffectcraftApp, ui: &mut egui::Ui, ectx: &EvalCtx, resp: &egui::Response, v: &mut Vw<'_>) {
     let comp_rect = v.comp_rect;
     let zoom = v.zoom;
@@ -1780,6 +1783,8 @@ fn phase_stopped(app: &mut EffectcraftApp, ui: &mut egui::Ui, ectx: &EvalCtx, re
     v.pin_hits = pin_hits;
 }
 
+/// Acts on a click in the viewer for the active tool (select, zoom, add or delete vertices),
+/// including a click an overlay passed on, and not one an overlay claimed.
 fn phase_clicked(app: &mut EffectcraftApp, ectx: &EvalCtx, resp: &egui::Response, v: &mut Vw<'_>) {
     let area = v.area;
     let zoom = v.zoom;
@@ -1926,6 +1931,8 @@ fn phase_clicked(app: &mut EffectcraftApp, ectx: &EvalCtx, resp: &egui::Response
     v.puppet_layers = puppet_layers;
 }
 
+/// Acts on a double-click: a path's points into a Free Transform box, or a precomp opened; lets
+/// go of an overlay's claim on the press once the button is up.
 fn phase_dblclick(app: &mut EffectcraftApp, ectx: &EvalCtx, resp: &egui::Response, v: &mut Vw<'_>) {
     let map = v.map;
     let ctx = v.ctx.clone();
@@ -1986,6 +1993,8 @@ fn phase_dblclick(app: &mut EffectcraftApp, ectx: &EvalCtx, resp: &egui::Respons
     v.paths = paths;
 }
 
+/// Runs the overlays drawn on top of the viewer (effect, gradient and text handles), after
+/// recording the viewer's own controls for them, and draws the status chips.
 fn phase_tail(app: &mut EffectcraftApp, ui: &mut egui::Ui, ectx: &EvalCtx, v: &mut Vw<'_>) {
     let t = v.t;
     let cid = v.cid;

crates/ui-egui/tests/it/ui_crypto_pick_undo.rs

@@ -452,6 +452,8 @@ enum Step {
     Blur(u64, f64),
 }
 
+/// Performs one model step (a pick, an edit, undo or redo, applying or removing the effect) and
+/// records the state the model expects after it.
 fn run_step(h: &mut Harness<'_, EffectcraftApp>, f: &Fix, m: &mut Model, size: [f64; 2], step: &Step, n: usize) {
     let mut o = m.state().clone();
     let before = h.state().session.history.undo.len();

crates/ui-egui/tests/it/ui_crypto_select.rs

@@ -73,6 +73,7 @@ fn on_plate(h: &Harness<'_, EffectcraftApp>, x: f64, y: f64) -> Pos2 {
     comp_to_screen(&h.ctx, [(80.0 + x) as f32, y as f32]).unwrap()
 }
 
+/// Moves the pointer to `pos`, waits until the Cryptomatte IDs are read, and returns the chip's text.
 fn hover(h: &mut Harness<'_, EffectcraftApp>, pos: Pos2) -> Option<String> {
     h.event(Event::PointerMoved(pos));
     // The overlay comes up over the layer in this pass and is hovered from the next one on.
@@ -97,6 +98,7 @@ fn click(h: &mut Harness<'_, EffectcraftApp>, pos: Pos2, modifiers: Modifiers) {
     h.run_steps(2);
 }
 
+/// Presses at `from`, drags by `by` over a few passes and releases.
 fn drag(h: &mut Harness<'_, EffectcraftApp>, from: Pos2, by: egui::Vec2) {
     h.event(Event::PointerMoved(from));
     h.step();
@@ -110,6 +112,7 @@ fn drag(h: &mut Harness<'_, EffectcraftApp>, from: Pos2, by: egui::Vec2) {
     h.run_steps(3);
 }
 
+/// The plate's Cryptomatte Selection text.
 fn selection(h: &Harness<'_, EffectcraftApp>, ids: &Ids) -> String {
     let s = &h.state().session;
     match &s.active_comp().unwrap().layer(LayerId(ids.plate)).unwrap().props.find(ids.sel).unwrap().value {
@@ -118,15 +121,18 @@ fn selection(h: &Harness<'_, EffectcraftApp>, ids: &Ids) -> String {
     }
 }
 
+/// The layer's Position value, formatted for comparison.
 fn position(h: &Harness<'_, EffectcraftApp>, layer: u64) -> String {
     let l = h.state().session.active_comp().unwrap().layer(LayerId(layer)).unwrap().clone();
     format!("{:?}", l.transform().and_then(|t| t.get("position")).map(|p| p.value.clone()))
 }
 
+/// How many steps the undo history holds.
 fn undo_steps(h: &Harness<'_, EffectcraftApp>) -> usize {
     h.state().session.history.undo.len()
 }
 
+/// The ids of the selected layers.
 fn selected_layers(h: &Harness<'_, EffectcraftApp>) -> Vec<u64> {
     h.state().session.state.selected_layers.iter().map(|l| l.0).collect()
 }