Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
51 changes: 51 additions & 0 deletions doc/masks-geometry.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,64 @@ node, `ctrl2`), then the centerline sampled **forward** from the first node to t
**same** centerline sampled backward. The border wraps around the stroke, so the line under it is
walked there and back (`_brush_get_pts_border()`); the backward half is never drawn.

The border is index-aligned with the points, header included. A brush's and a polygon's border
header repeats the outline's, three entries per node, and a polygon then writes each node's border
handle into the first of the three (`_polygon_walk_write_header()`). Nothing reads the rest: the
pipeline's area starts after the header (`_brush_bounding_box_raw()`). It used to be zeros, the
image's origin, which every box taken over the whole buffer counted (see
[`overlay-raster.md`](overlay-raster.md)).

The forward half ends at `_brush_centerline_end()` — `node_count * 3 + (points_count - node_count
* 3) / 2`, i.e. half of the **samples**. Half of the whole array is a different number: the header
belongs to neither pass, so counting it in falls one and a half points per node short, and the
last node's own coordinate sits at the very end of the forward pass. Everything that walks the
drawn centerline (the outline stroking, the source shape, the clone link's midpoint) uses that
helper.

## A brush shorter than a pixel draws its source by its border

*Found on top of `17a0cfe80b`, 2026-11-10.*

A click without a drag makes a brush: the press records the first point, the release pads it with
a second node a hundredth of a pixel away (`_brush_events_button_released()`), and the mask is the
full disc of the border. Its centreline has no length. Unselected, a brush draws its centreline
only, which for a dot is two round end caps the width of the line, and its dashed border, like any
brush's, only while it is selected. Its clone source was not drawn at all, arrow included —
`_brush_get_source_center()` anchors the link at the centreline's midpoint, and a line with no
length has none.

`_brush_is_dot()` is a centreline shorter than one pixel of the output image. For such a brush the
link's two ends fall back to the first nodes. The source outline built for the GUI carries no border, so
the dot's source is its border shifted by the source node minus the main node, the shift
`_brush_get_distance()` already uses to hit the source, and drawn solid like every source
outline. The shift is exact where the distortions after the module are affine; behind a lens
correction or a perspective it is the same approximation the hit test makes. The overlay only
composites what lies in the outline's box, so that box holds the shape's box carried onto the
source (`dt_masks_gui_points_update_bbox()`, see [`overlay-raster.md`](overlay-raster.md)).

The source is hit where it is drawn: `_brush_get_distance()` tests a brush's source by the cursor's
reach around its centreline carried onto the source, which for a dot is its centre alone, so the
dot's source is hit anywhere inside its border carried there, as a circle's source is inside its
outline. It needs the box above as well: a cursor outside the box is answered "nothing here"
before any sample is walked.

*Measured on top of `17a0cfe80b`, 2026-11-10*, with an `LD_PRELOAD` shim on a RelWithDebInfo
build, Xephyr at 1280×900, a JPEG at fit zoom: retouch's brush armed by its button, a click, a
stroke, creation ended, every `dt_masks_draw_outline_runs()` call logged as a device-space bounding
box. Before, the unselected click drew its centreline walk and nothing else, with no
`dt_masks_draw_source()` call; the stroke drew its source. After, `dt_masks_draw_source()` runs
for the click and draws a 32×32 px ring at its source. Selected, it had drawn its dashed border
and still no source; it draws the same border and its source.

*Checked on top of `0801e6eed1`, 2026-11-11*, with the overlay dumped (`MASKS_DUMP_OVERLAY`) by the
same kind of shim right after the click, the dot unselected in its creation session: the canvas
holds the source's ring and arrow and the brush cursor, and no ring at the shape.

*Measured on top of `f4960a122d`, 2026-11-10*, with the same shim, the source placed by Shift+click
and drawn as a ring of radius 16 px: the cursor moved from the source's centre outwards along
each axis. It selected the source up to 4 px from the centre and nothing at 8, 12 and 15 px, not
even the shape; it selects the source at every one of them.

## `inside_border` is proximity to the feather's outer line, not the feather band

*Found `447c35d38e`, 2026-09-07.*
Expand Down
43 changes: 43 additions & 0 deletions doc/masks-gui.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,49 @@ instead would survive that, since `dt_masks_gui_selected_segment_index()` (`mask
`seg_hovered` outright and consults no selection flag — but two spellings of one question is what
this section exists to prevent, so the flags are kept honest at the source instead.

## A shape's event handler may replace the visible form, so the dispatcher reads it again after

*Found on top of `3ce1ec6716`, 2026-11-09.*

`dev->form_gui->form_visible` is a raw pointer and holds no reference. The event dispatchers in
`masks/masks_gui.c` read it, hand one shape's handler the event, and then still have work to do —
the group selection change after a release, the hint, the cursor. By then the visible form may no
longer be the one they read: finishing a shape in a creation session
(`dt_masks_gui_form_save_creation()`) makes the next unfinished shape visible, the saved one living
on in `dev->forms`; and `dt_masks_cow_touch()`, one step earlier, may have cloned it and released
the original.

So nothing the dispatcher read before the handler describes what is visible after it.
`_set_hinter_message()` reads the visible form itself instead of taking one from its caller,
`dt_masks_events_button_released()` and `dt_masks_events_mouse_scrolled()` read it again after the
handler, and `dt_masks_events_button_pressed()` computes what describes the state before the click
(`shape_was_selected`) before the handler runs. `dt_masks_events_key_pressed()` reads its
`mask_form` again only after a handler that declined the key, and no handler replaces the visible
form while declining.

## A creation session ends only when the user ends it

*Found on top of `58765cdb5b`, 2026-11-09.*

A shape's event handlers never end a creation session on their own. Finishing a shape keeps the
tool armed for the next one, and a brush release whose press gathered no point
(`_brush_events_button_released()`) draws nothing and leaves the session as it was: the same
unfinished shape stays visible, `creation` stays set. Such a release is one whose press never
collected a point — the press carried Shift and the release did not, the press did not reach the
masks, or the device sent the release twice. What ends a session is a gesture of the user's:
Escape, the context menu's entry, the armed toolbar button clicked again, BackSpace on a polygon
with no node placed (all through `dt_masks_form_exit_creation()`), entering edit mode
(`dt_masks_change_form_gui()`), giving another module the focus (`dt_masks_reset_form_gui()` from
`dt_iop_request_focus()`), the first edit made off the canvas (see the section of that name below),
and the darkroom tearing down.

Measured under ASan (Debug, clang 19) with a `LD_PRELOAD` shim that, on the GUI thread, arms the
brush on "diffuse or sharpen" and plays three strokes through `dt_control_button_pressed()`,
`dt_control_mouse_moved()` and `dt_control_button_released()`. Three ordinary strokes save three
shapes. When the second stroke has no press, a Shift press, or a second release after its own, that
release leaves the unfinished shape's `formid` and the count of `dev->forms` unchanged with
`creation` still set, and the third stroke is saved. No run reads freed memory.

## A shape toolbar's pressed button is a view on the creation state, not a state of its own

*Found `1083ebf27b`, 2026-09-01.*
Expand Down
3 changes: 2 additions & 1 deletion doc/masks-history.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,8 @@ are now refcounted (`dt_masks_form_t.refcount`, `src/develop/masks/masks_history
`blend_gui.c` group operations, the shape-manager panel in `libs/shape_manager.c`) must route through
this before touching `form->points` or any other field. `dt_masks_cow_touch` also re-points
`dev->form_gui->form_visible` if it was the form that got cloned — that's the only other raw
`dt_masks_form_t*` cached outside `dev->forms`.
`dt_masks_form_t*` cached outside `dev->forms`. It holds no reference, so a copy of it does not
outlive a shape's event handler either ([`masks-gui.md`](masks-gui.md)).
- `dt_masks_replace_current_forms()` swaps `dev->forms` wholesale (used when history navigation
rebuilds it) by releasing the old references and taking new ones — never a raw deep copy.
- `pipe->forms` (the pixel-pipeline's own snapshot, taken once per `dt_dev_pixelpipe_process()`
Expand Down
72 changes: 66 additions & 6 deletions doc/overlay-raster.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,12 +52,72 @@ surface the size of the clip in pixels (created once, kept across frames, given
device scale), draws every shape into it through a `cairo_t` carrying `cr`'s matrix shifted to
the clip's origin, and composites onto the view only the rectangle that was painted: the
rasteriser's own record, plus a bound on what cairo may draw on top — the node header of every
outline, node and both control points, three per node, with a margin for a node's disc and an
arrow head. That bound is computed *before* anything is drawn and the canvas context is clipped
to it, so a handle that lands outside the estimate is not painted rather than left behind for
the next frame (the harness draws a panned frame after every state and fails on any pixel a
fresh surface would not show). The rectangle is then cleared by hand for the next frame. A creation
session, which paints through its own cached pattern, takes the whole canvas.
outline, node and both control points, three per node, and the outline's box, with a margin for a
node's disc and an arrow head. That bound is computed *before* anything is drawn and the canvas
context is clipped to it, so a handle that lands outside the estimate is not painted rather than
left behind for the next frame (the harness draws a panned frame after every state and fails on
any pixel a fresh surface would not show). The rectangle is then cleared by hand for the next frame.
A creation session, which paints through its own cached pattern, is bounded by the union of its
outlines' boxes and not clipped. The shape being drawn has no outline yet: what of it the
rasteriser paints it records, and what cairo strokes itself — a brush's trace and cursor
(`_brush_events_post_expose()`), a clone's source cross (`dt_draw_cross()`) — is declared with
`dt_stroke_raster_touch_path()`, which adds the path's extents, grown by half the line width, to
the same touched rectangle. Undeclared, it is painted into the canvas and composited only where
the session's box happens to cover it. The first stroke of a session is the exception that hid
this: with no box yet, the bound is the whole canvas.

*Measured on top of `0a3d158d66`, 2026-11-10*, with the same shim: retouch's brush armed, a first
stroke from (75, 97) to (150, 130), then a second from inside its box to (400, 518), the frame
dumped at the second stroke's last motion. The composited rectangle ended at (199, 187), the trace
beyond it drawn and never shown; it ends at (418, 536).

The outline's box (`dt_masks_gui_points_update_bbox()`) holds its samples, its border, its clone
source's samples, and the shape's box carried onto the source by the shift between the first
points of the two outlines. Cairo strokes the source and the arrow, wherever the user put the
source, and a source may be drawn as large as the border: a brush too short to have a line draws
its border there ([`masks-geometry.md`](masks-geometry.md)).

A point that is not finite is not a sample, and the box leaves it out. A gradient's border joins its
two curves with an `(INFINITY, INFINITY)` separator (`_gradient_get_pts_border()`), and counting it
made the box infinite: no hit test could rule a gradient out, and the bounds carried the infinity
into `_rect_include()`, whose conversion to `int` is undefined. On x86 it gives `INT_MIN`, which
here happened to make a rectangle that covered everything; nothing was measured on ARM.

The session clip (`_session_clip()`) took that box too: a rectangle of infinite width, which let
nothing through, so in a gradient creation session the gradient already made was not drawn while
the next one was placed.

*Measured on top of `8e5892d09f`, 2026-11-10*, with a shim that makes a gradient in exposure's drawn
mask, dumps the frame with the session still open, then selects the gradient the way Escape does.
The box was x −1684 to inf, y −642 to inf; it is x −1684 to 4082, y −642 to 2242. The selected
gradient draws the same pixels. The session frame draws 3230 more, all within 2 px of where the
gradient is drawn once selected; master drew none of them either.

The border's header holds no point the shape does not draw: a brush's and a polygon's repeat the
outline's header there ([`masks-geometry.md`](masks-geometry.md)). It was zeros, the image's origin,
so the box of every brush and polygon reached the top-left corner of the image, and with it the
rectangle composited and cleared each frame and the session's bound.

*Measured on top of `815455e77b`, 2026-11-10*, at fit zoom in a 500×648 view, shapes at the bottom
right of the image. A brush's box went from x 0..2407, y 0..1529 to x 1717..2407, y 1097..1529 (image
pixels), its composited rectangle from 500×421 to 204×202, and the composite from 0.31 to 0.10 ms per
frame (400 frames each; 0.10 ms is the print's resolution). A dot's rectangle went from 247×133 to
88×87, a polygon's from 500×457 to 213×263, a two-stroke creation session's from 418×473 to 387×473.
Every overlay drew the same pixels, nothing painted was left outside the rectangle, and a mouse move
cost the same, about 180 µs, inside the old box or outside both.

The rectangle is cut to the frame before it is composited and recorded. One reaching out of the
view is a rectangle no expose covers: `_overlay_damage_record()` asks a redraw of what the expose
did not cover, so such a rectangle repaints the overlay frame after frame for as long as it lasts.

*Measured on top of `6fde4487bb`, 2026-11-10*, with an `LD_PRELOAD` shim on a RelWithDebInfo
build, Xephyr at 1280×900, a 2400×1600 JPEG at fit zoom, the rectangle read from
`MASKS_DUMP_OVERLAY`: retouch's shape armed by its button, its source placed by Shift+click, a click
to make the shape. In the creation session, a circle of radius 0.3 had its source down to canvas
row 485 and a composited rectangle ending at row 323; it ends at 511. A one-point brush, its source
at row 389 and its rectangle ending at 230, ends at 424. Selected outside the session, the brush's
rectangle began at column −15: the overlay drew 57 frames in the next second with nothing moving,
and draws 1.

## Measured

Expand Down
Loading
Loading