Skip to content

masks: a shape creation session ends with the first edit made off the canvas - #1633

Merged
Jiyone merged 2 commits into
masterfrom
masks-creation-ends-off-canvas
Nov 11, 2026
Merged

Jiyone merged 2 commits into
masterfrom
masks-creation-ends-off-canvas

Conversation

@Jiyone

@Jiyone Jiyone commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

The rule

A shape creation session is a tool for the canvas. Its strokes, the canvas's own edits of the shapes they make, the settings of the armed tool, zooming, panning, undo and redo keep it armed. Every other edit ends it, as Escape does.

On master, whether a gesture ended the session depended on whether the module's mask group was empty, not on what the gesture was:

  • a module slider or the module's on/off switch never ended it;
  • the parametric mask's toggle, or a style or pasted history, ended it only before the session's first stroke;
  • undo always ended it.

The only off-canvas exit was a side effect of dt_iop_gui_blend_masks_update(), a display refresh, which switched the masks off whenever the group had no shape. After dt_iop_gui_update(), it also left the module's brush button pressed with creation off: the user saw the tool armed, drew, and nothing came out.

The change

  • Widget edits end the session. dt_dev_add_history_item_real(), the entry every widget commits through, calls dt_masks_form_exit_creation(). That covers module parameters, the on/off switch, presets, the whole blending panel and module moves.
  • History reloads end it. dt_dev_history_gui_update() does the same. That covers a jump in the history list, styles, pasted or compressed history, and module-order presets.
  • Undo and redo keep it. They refresh the widgets through the GUI handler _pop_undo() already calls, so they never reach the exit above. The handler skips the recorded edit mode while a session is armed. _pop_undo() now leaves that whole presentation half to the handler, so dev_history_gui.c is the only new includer of masks_gui.h outside the module. The check_module_boundaries.sh baseline goes from 11 to 12, with the reason written next to it.
  • The session's own commits bypass the widget entry. Each saved shape and the darkroom's mask-edit commit (_delayed_history_commit(), already throttled) go through dt_dev_history_commit_item_now(), after flushing what is queued so their order is kept. Without this, the darkroom's commit ended every session right after its first shape. Measured: that was the first thing the new exit broke.
  • The settings of an armed shape tool keep it armed. Sentry's review found the first one: retouch's algorithm buttons arm the tool again for the new algorithm, and their commit through the widget entry then ended the session. While a tool is armed, they now commit through dt_dev_history_commit_item_now(). A widget built from the params can carry the "dt-masks-tool-setting" object data, which dt_iop_gui_changed() reads next to the existing "dt-blendop-header-update": it then commits the same way. Retouch's heal algorithm list carries it. In retouch's "retouch tools" section, the armed shape's own button and "editing" still end the session, since that is what they are for. Committing through the widget entry first and arming again afterwards was measured and rejected: ending the session sets the module's shapes to full edit, and the "editing" button lit up at the next stroke.
  • The panel refresh no longer ends a session. dt_iop_gui_blend_masks_update() leaves a session that has not saved a shape yet alone.
  • The session overlay counts only the shapes the history still holds. Without this, undoing a session's stroke left the cache key unchanged, and the overlay kept painting the undone stroke until the next one.

Documented in doc/masks-gui.md, section "A creation session ends with the first edit made off the canvas".

Measured

Build: Debug + ASan, clang 19, CPU only, one build of origin/master and one of this branch. A shim loaded with LD_PRELOAD drives the GUI thread:

  1. it arms the brush on "diffuse or sharpen";
  2. it fires one gesture;
  3. it plays two strokes through dt_control_button_pressed() / dt_control_mouse_moved() / dt_control_button_released();
  4. it counts the shapes saved.

Each gesture runs with the module's group empty and with one shape already saved.

gesture master, empty master, 1 shape branch, empty branch, 1 shape
none armed, 2 saved armed, 2 armed, 2 armed, 2
a module slider (1 → 2) armed, 2 armed, 2 ended, 0 ended, 0
the module's on/off switch armed, 2 armed, 2 ended, 0 ended, 0
the parametric mask's toggle ended, 0 armed, 2 ended, 0 ended, 0
dt_apply_dev_history_update() ended, 0 armed, 2 ended, 0 ended, 0
dt_undo_do_undo() ended, 0 ended, 0 armed, 2 armed, 2
dt_iop_gui_update() alone ended, button still pressed armed, 2 armed, 2 armed, 2

The same shim on retouch arms the brush by its button, plays one stroke, presses one control, then plays two more strokes:

control master widget entry only this branch
"blur" armed, brush turned non-clone, 2 saved ended, 0 armed, non-clone, 2
"heal algorithm" list armed, 2 ended, 0 armed, 2
the circle button armed, circle, 2 armed, circle, 2 armed, circle, 2
the brush button again ended ended ended
"editing" ended ended ended

"Editing" stays off while the tool is armed, as on master. The "blur" click and the list change each add one undo step at once (4 → 5); on master the step comes later, from the queue.

None of these runs reads freed memory. With -d perf, undoing the session's only stroke triggers an immediate re-render of the overlay with 0 shapes. Before the count fix, no re-render came until the next stroke.

Tested by hand on 59d3244c5d, in a RelWithDebInfo build with OpenCL, over eight cases: strokes in a row, zoom and pan, and Ctrl+Z / Ctrl+Y keep the tool armed; a module slider, the on/off switch, the blending panel, the history list or a style or a pasted history, and a reset or a focus change end it. Everything looked right.

Gates run, all pass:

  • check_layering.sh (cycles 0)
  • check_module_boundaries.sh
  • check_return_types.py
  • check_list_order.py
  • pragma_once_to_guards.py --verify
  • check_statelessness.sh
  • check_conditional_includes.sh origin/master
  • check_unused_includes.sh --changed origin/master

No new warning under clang-19.

Not tested:

  • the history list, the module reset (it already ended the session through dt_iop_gui_blending_lose_focus()) and a focus change were in the manual test, not measured with the shim;
  • module-order presets were only read from the code. They go through the same dt_dev_history_gui_update() as the measured dt_apply_dev_history_update();
  • retouch's controls were measured with the shim only, not by hand;
  • image_test.sh: the change is in GUI event handling and history commit routing, which the pixel pipeline never runs.

Overlap with #1632

#1632 touches src/develop/masks/masks_gui.c and adds a section to doc/masks-gui.md, "A creation session ends only when the user ends it", whose list of exits predates this rule. Whichever PR merges second needs a rebase, and that section must then state this PR's rule.

🤖 Generated with Claude Code

Comment thread src/develop/dev_history_gui.c Resolved
t and others added 2 commits November 10, 2026 23:04
… canvas

A creation session is a tool for the canvas: its strokes, the canvas's own edits of the shapes they make, zooming, panning, undo and redo keep it armed, and every other edit ends it, as Escape does. Before, a module slider or the module's on/off switch left it armed, the parametric mask's toggle or a style ended it only while the module's group had no shape yet, and undo always ended it.

`dt_dev_add_history_item_real()`, the entry every widget commits through, and `dt_dev_history_gui_update()`, which every history reload goes through, now end it through `dt_masks_form_exit_creation()`. Undo and redo refresh the widgets through the GUI handler `_pop_undo()` already calls, which keeps the session armed and skips the recorded edit mode while it is; `_pop_undo()` leaves that whole presentation half to the handler, so `dev_history_gui.c` is the only new includer of `masks_gui.h` outside the module (baseline 11 -> 12).

The session's own commits, each saved shape (`dt_masks_gui_form_save_creation()`) and the darkroom's mask-edit commit (`_delayed_history_commit()`), go through `dt_dev_history_commit_item_now()` after flushing what is queued, since the widget entry would end the session they belong to.

`dt_iop_gui_blend_masks_update()` no longer switches the masks off for a module whose session has not saved a shape yet; it ended the session behind the user's back and left the module's brush button pressed with creation off.

The session overlay counts only the shapes the history still holds, so undoing a session's stroke redraws the overlay without it instead of painting it from the cache until the next stroke.

Measured under ASan with a shim that arms the brush on "diffuse or sharpen", fires a gesture and plays two strokes, against origin/master, with the module's group empty and with one shape saved: the table is in doc/masks-gui.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e tool armed

Retouch's algorithm buttons arm the shape tool again for the new algorithm, then committed through dt_dev_add_history_item(), which now ends every creation session: the click that re-armed the tool disarmed it. While a tool is armed they commit through dt_dev_history_commit_item_now() instead, after flushing what is queued, as the session's saved shapes do.

A widget built from the params commits through dt_iop_gui_changed(), which now commits the same way when the widget carries the "dt-masks-tool-setting" object data. Retouch's heal algorithm list, the other control of that section, carries it. The armed shape's own button and "editing" still end the session: that is what they are for.

Committing through the widget entry first and arming again afterwards was measured and rejected: ending the session sets the module's shapes to full edit, and retouch's "editing" button lit up at the next stroke.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Jiyone
Jiyone force-pushed the masks-creation-ends-off-canvas branch from 7db98d1 to f43fccf Compare November 10, 2026 22:04
@sonarqubecloud

Copy link
Copy Markdown

@Jiyone
Jiyone merged commit e19adbd into master Nov 11, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Development

Successfully merging this pull request may close these issues.

1 participant