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
252 changes: 238 additions & 14 deletions doc/brush-boundary.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion doc/darkroom-redraw.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ last frame composited, in the view's coordinates (`_overlay_damage`), and the da
a dragged shape moves with the pointer, a hovered one does not move -- when the masks handled
the motion and nothing else did; a module's own overlay knows no rectangle and keeps the whole
widget. The invalidation is an estimate made before the frame is drawn: when a frame outgrows
it, `_overlay_damage_record()` (`masks_gui.c:4584-4592`) compares the composited rectangle with
it, `_overlay_damage_record()` (`masks_gui.c:4624-4632`) compares the composited rectangle with
the clip of the expose and, if the clip does not cover it, asks for the **whole damage
rectangle** again — not "the rest" — which the next, small expose paints. At worst that is one extra small
frame; it can never leave part of an overlay unpainted.
Expand Down
6 changes: 3 additions & 3 deletions doc/develop-split.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,8 +138,8 @@ members in one per-shape table — that is the only reason every IOP that wants
sees cairo and GTK. The split is a parallel `dt_masks_gui_functions_t` registered per shape
type. **The header split landed (T3b-1, `965e32ecbc`) but the vtable split did NOT**: `masks.h`
keeps only the forward typedef at :128, and the body moved to
`develop/masks/masks_functions.h:60` — where it still mixes `get_mask` (:91), `get_mask_roi`
(:106), `mouse_moved` (:127), `mouse_scrolled` (:130) and `post_expose(cairo_t *cr, …)` (:142)
`develop/masks/masks_functions.h:73` — where it still mixes `get_mask` (:109), `get_mask_roi`
(:124), `mouse_moved` (:145), `mouse_scrolled` (:148) and `post_expose(cairo_t *cr, …)` (:160)
in one table. **This is the one knot in this section still genuinely open.**
`control/control.h` in masks.h supplied **zero symbols** — pure supply line, **deleted (T1c,
`1127ce3d48`)**, and it had been feeding `control.h` to eight files that used none of it. Two traps: the spline sampler
Expand Down Expand Up @@ -201,7 +201,7 @@ completed sequence, not as work waiting.
(the name-table definitions were already in `blend.c`, so that half was a false alarm —
see the knot above); `masks.h` drops control.h outright and moves `dt_masks_form_gui_t` +
draw.h into a new `masks_gui.h`. **The GUI vtable did not move** and is still mixed into
`dt_masks_functions_t`, now at `develop/masks/masks_functions.h:60`. After T1, **90 IOPs
`dt_masks_functions_t`, now at `develop/masks/masks_functions.h:73`. After T1, **90 IOPs
stopped receiving GTK through develop headers**.
* **T2 — pipeline message/notification inversions** ✅ `8173ad4af1`: `dt_control_log` → a
pipe-registered message handler (the `history/notify.h` shape, third time); progress + redraw
Expand Down
54 changes: 42 additions & 12 deletions doc/masks-geometry.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,11 +43,12 @@ helper.

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.
full disc of the border. Its centreline has no length. A brush draws the edge where its fading
starts in every state ([`brush-boundary.md`](brush-boundary.md#where-the-fading-starts)), and its
dotted centreline, for a dot two round end caps the width of the line, and its dashed border only
while it is selected (on top of `2924759cfb`, 2026-11-11). 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
Expand Down Expand Up @@ -127,11 +128,11 @@ something else happens to be drawn: a leftover tail comes out dashed when the sh
border is stroked next, comes out highlighted when another shape is hovered, and is invisible when
nothing is drawn after it. That is a path leak, not a style or selection bug.

Which segments exist at all is decided by the caller's shape: an open path (a brush — the only
caller asking for round ends, since only an open path has two true ends) has `node_count - 1`
segments, a closed one has one more, and a shape still being created has no closing segment yet.
The walk stops once it has stroked them all, so it must be handed a point count that lets it
**reach** the last node.
Which segments exist at all is decided by the caller's shape: an open path (a brush's centreline,
the only caller passing `centreline`, and the only open path) has `node_count - 1` segments, a
closed one has one more, and a shape still being created has no closing segment yet. The walk
stops once it has stroked them all, so it must be handed a point count that lets it **reach** the
last node.

## Brush masks rasterize as radial spokes — wedge holes across the stroke (CLOSED)

Expand All @@ -143,7 +144,7 @@ The walk stops once it has stroked them all, so it must be handed a point count
> switched off behind an always-FALSE `allow_border_gap_rounding` flag, so a joint had no border
> samples across it and no spokes were stamped there. That flag had 3 occurrences at the report
> commit and has **0** today; joints now go through `_brush_joint_arc()`
> (`develop/masks/brush.c:947`) unconditionally, and the corpus runs a two-sided oracle with an
> (`develop/masks/brush.c:948`) unconditionally, and the corpus runs a two-sided oracle with an
> explicit MISSING map. Left marked OPEN, this section sent a reader to re-derive a landed fix.
>
> *One honest caveat:* the reporter's `_DSC9410.NEF` 57-node brush was never added to the corpus,
Expand All @@ -162,7 +163,7 @@ Two things make the diagnosis quick, and both were got wrong on the first pass:
like that at a glance. Look at the small ones at full resolution instead: each has a
*perfectly straight* edge cutting across the stroke, which no smooth outline produces.
- **They are not the sparse-sampling path.** `use_sparse` is now
`pipe->mask_rasterization_step > 1` (`develop/masks/brush.c:3269`); the six hand-rolled copies
`pipe->mask_rasterization_step > 1` (`develop/masks/brush.c:3395`); the six hand-rolled copies
of `has_preview_output() || type == THUMBNAIL` were deliberately removed because one pipe could
be classified two ways inside a single frame (`develop/pixelpipe_hb.h:491`). The conclusion is
unchanged and now holds structurally: the step defaults to 1 and only `dev->gui_attached`
Expand Down Expand Up @@ -316,6 +317,35 @@ rules that were each paid for by a reported defect:
stretched at every run boundary. `dt_stroke_raster_path()` now carries one `_dash_t` across
all its sub-paths: a dash is a function of the pixels of border drawn before it. A dash cut by
a hidden stretch shows as a stub, which that metric owes.
- **A brush's solid part is a disc union of its own** (on top of `0d108992d6`, 2026-11-12): a
node's solid radius is `fading · border`, eased between nodes by the radius's smoothstep, and a
spoke is solid out to its edge sample on the envelope of those discs, then ramps. The payload
holds that edge in the frame of its spoke, so it rides any distortion. The first `fading` of
each spoke, with the fading eased linearly, leaned with the border's rate: between two nodes of
one solid radius it bulged toward the wider node, and where one disc nests in the other it
thinned to a thread. The corpus's `solid part` judge fails it on 11 of 21 brushes and frames and
passes the union on all 21.
- **Where a brush's fading starts is traced from a fill of its solid part, not walked over the
edge samples** (on top of `a8997b8e28`, 2026-11-11). Where the spokes lie along the spine, the
edge of their union is their sides -- 94 of the 872 px of `brush-fading-neck`'s edge then lay
more than 2 px from the line through the ends -- and no pass over the ends draws a side; on the
disc union, `dt_masks_outline_boundary_skips()` over the edge samples kept up to 1281 points
inside the solid part where the envelope folds, for no saving (on top of `0d108992d6`).
`dt_masks_solid_edge()` (`masks_solid.c`) fills the bands between neighbouring spokes, in runs
of one orientation, non-zero, and traces the half-coverage level. Two traps: the lobe of a
bow-tie band wound against its run cancels the band under it, so it is added back twice and
never dropped, however thin -- dropping those thinner than a tenth of a cell opened loops 86 px
inside the solid part, slivers along neighbouring spokes stacking; and a long spoke trembling
by a hundredth of a pixel turns a run at every band unless the turn waits for a tenth of a cell
of sweep (4621 runs to 1399 on `brush-1360-pressure-ramp`), and a run begins once its bands
have swept that far, summed, since a fast border samples the spine a fiftieth of a pixel apart.
A neck thinner than half a cell is under half coverage and, traced from the fill alone, breaks
into islands that float rounding chooses -- on `brush-fading-neck`, 9 loops with `-ffast-math`
and 7 without, where a Debug build fails the judge below -- so the cells the spine crosses are
set full before the trace, and the neck is one loop round it (on top of `aff63448d6`,
2026-11-12). It fills without cairo, for the toolkit ratchet. The corpus's `fading edge` judge
wants every pixel on the edge of the raster's full part within 4 px of the traced edge. The
full account is [Where the fading starts](brush-boundary.md#where-the-fading-starts).
- **`MASKS_DUMP_OVERLAY=<dir>` makes the darkroom write what each frame drew**: the canvas
before it is composited and cleared, the frame and dirty rectangles, and every cached outline
with its skip ranges (`outline-<n>.txt`, the harness's format). It exists because a darkroom
Expand Down
44 changes: 43 additions & 1 deletion doc/masks-gui.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,12 +53,54 @@ panel becomes the authority.
Consequence for the on-canvas hints (`set_hint_message`, per shape): they document **gestures
only** — drag, ctrl+click, right-click, Del, Enter, Esc — never the wheel, which the panel now
shows. Their branches follow the hit-test order of `dt_masks_find_closest_handle_common()`
(border handle, curve handle, node, segment, then the shape), because the innermost target under
(border handle, curve handle, node, a brush's solid-part handle, segment, then the shape), because the innermost target under
the cursor is what the next click acts on. Two traps when editing them: a node's Del and
ctrl+click only work once that node is *selected* (a mere hover gets the shorter message), and
`dt_hinter_set_message()` joins `\n` into `, `, so each line must read as a clause of one
sentence.

## A brush's size and fading edit its solid part and its ramp, as a circle's do

*Found on top of `5a136d1a04`, 2026-11-11.*

A brush node stores its whole radius (`border[0]` and `border[1]`, which every writer sets
together) and the fraction `fading` of it that is solid. The controls edit neither number as
such: **size** edits the solid radius `fading · border`, **fading** the width of the ramp outside
it, `(1 − fading) · border`, and each leaves the other part as it is — the way a circle's size and
fading edit its radius and its border. `_brush_resize_part()` (`brush.c`) is the one place that
turns a change of one part into a new `border` and `fading`, and every control goes through it:
the wheel, the context-menu sliders, both node handles, and the defaults a new brush is drawn
with.

- `get_interaction_value(DT_MASKS_INTERACTION_FADING)` answers the mean ramp width, in the
normalized units of the circle's and the polygon's border, so the absolute "Fading" slider
(0–100 %) sets the ramp width. "Size" is the shared relative log2 slider and scales the solid
radius.
- The wheel scales the part it edits by 1.02 per notch, up growing it, for both parts.
- Neither part goes below `PART_MIN` (0.0005, the circle's narrowest border) and the whole radius
stays at most 1. A part at that floor grows back slowly under the wheel, as a circle's border
does.
- An edit applies the same change to the `border`/`fading` conf keys the next brush is created
with; during creation the wheel edits those keys alone, so size grows the preview's filled disc
and fading its ring.
- Nothing stored is converted: a node keeps its `border` and `fading`. Between two nodes whose
radius or fading differ, the solid part is a disc union of its own
([brush-boundary.md](brush-boundary.md#the-solid-part-is-a-disc-union)), so a brush saved
before that paints another solid part there (on top of `0d108992d6`, 2026-11-12).

A selected node has two handles on one ray from the node. The outer one, on the whole radius,
moves the ramp's outer edge; the inner one, `_brush_get_solid_handle()`, sits where the node's own
spoke turns from solid to ramp and moves the edge of the solid part. Both are border handles to
the selection state (`handle_border_hovered`, `_selected`, `_dragging`) and are told apart by
`mask_gui->handle_border_solid`, which the hit test writes and a drag keeps. A third handle family
would have needed every reset, `dt_masks_is_anything_selected/hovered()`,
`dt_masks_gui_set/reset_dragging()` and the cursor shape to learn about it; sharing the state
covers all of them untouched. The hit test offers the inner handle through
`dt_masks_hit_callbacks_t.solid_handle`, tested **after** the node itself: on a node whose solid
part is narrower than the cursor the handle covers the node, and testing it first would leave the
node out of reach. The handle needs the node's fraction, which the GUI points do not carry, which
is why `post_expose` is handed the form it draws.

## A right click targets, it never drags — and the context menu leans on that

*Found `15f4e0b9c8`, 2026-09-07.*
Expand Down
6 changes: 3 additions & 3 deletions doc/masks_history_dedup.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ exact same form is unchanged across dozens of consecutive steps:
- SQL table `masks_history` (schema in `src/database/database.c`):
`(imgid, num, formid, form, name, version, points, points_count, source)`, no `UNIQUE`
constraint. Written by `dt_masks_write_masks_history_item()`
(`src/develop/masks/masks.c:1131`) — which no longer issues SQL itself but goes through the
(`src/develop/masks/masks.c:1130`) — which no longer issues SQL itself but goes through the
history repository — called once per form per history item from
`src/develop/dev_history.c:1574`, inside the rewrite `dt_dev_write_history_ext()` performs for
**every** history step.
Expand All @@ -50,7 +50,7 @@ exact same form is unchanged across dozens of consecutive steps:
`dt_dev_mask_history_overload()` (`src/develop/dev_history.c:1505`) already warns users about
this via a toast ("consider compressing history...") without fixing it. The intended direction
is flagged as a code comment near `dt_masks_read_masks_history()`
(`src/develop/masks/masks.c:1118`): attach the forms snapshot to its own object, linked by ID
(`src/develop/masks/masks.c:1117`): attach the forms snapshot to its own object, linked by ID
to the history item, instead of duplicating it inline.

**Historical precedent**: before XMP format version 3, `read_masks()` (now
Expand Down Expand Up @@ -122,7 +122,7 @@ lives (`:83-90` copies into `memory.undo_masks_history`, `:123-126` copies back,

### Read path (in-memory dedup bonus)

`dt_masks_read_masks_history()` (`src/develop/masks/masks.c:1118`) reads rows through
`dt_masks_read_masks_history()` (`src/develop/masks/masks.c:1117`) reads rows through
`dt_history_repository_foreach_mask_item()`, so the join goes in the **repository**, not here:
join the two tables on `content_id`, ordered by `num`, and keep handing `masks.c` one row at a
time. Keep a local `GHashTable` (`content_id` →
Expand Down
1 change: 1 addition & 0 deletions src/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -245,6 +245,7 @@ FILE(GLOB SOURCE_FILES
"develop/masks/masks_gui.c"
"develop/masks/masks_history.c"
"develop/masks/masks_outline.c"
"develop/masks/masks_solid.c"
"develop/masks/polygon.c"
"develop/format.c"
"pixel/format.c"
Expand Down
Loading
Loading