Skip to content

masks: a brush draws where its fading starts, and its size and fading edit its solid part and its ramp - #1634

Merged
Jiyone merged 13 commits into
masterfrom
masks/brush-fading-contour
Nov 12, 2026
Merged

Jiyone merged 13 commits into
masterfrom
masks/brush-fading-contour

Conversation

@Jiyone

@Jiyone Jiyone commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

What changes

A brush now shows where its fading starts, and its size and fading edit the two parts of its radius as a circle's do. One commit per step, then nine follow-ups.

1. The edge where the fading starts is drawn solid (2081ffb00b)

A brush paints each spoke at full density over the first fading of its length and ramps to zero past it. The overlay drew only its spine and, when selected, its dashed border: nothing showed where the fading started, or what a scroll on the fading had changed.

  • get_points_border hands out the contour on the spokes through a new fading out-parameter, built in place from the producer's payload. Every other shape leaves it NULL.
  • That contour is not the edge to draw. Where the spokes lie along the spine (a size that climbs steeply, a small fading on a wide node), the edge of the solid part is made of the spokes' sides, which no pass over the spoke ends can trace.
  • The new masks_solid.c fills the union of the bands between neighbouring spokes on a grid of one cell per device pixel, then traces its half-coverage level into closed loops by marching squares. It does not use cairo, since check_module_boundaries.sh keeps the toolkit out of develop/.
  • The brush strokes those loops solid in every state. The dashed border is still drawn only when the brush is selected.

2. The centreline is dotted (5a136d1a04)

The line through the nodes carries them but is not an edge of the mask, and it looked just like the new solid line.

  • dt_masks_draw_path_seg_by_seg() strokes it with round dots. Its round_ends argument, which only the brush passed, becomes centreline.
  • The polygon's outline stays solid.
  • The discs it painted on the two ends are kept commented out for reuse: stroked solid, they came out darker than the dots they end.

3. Size edits the solid part, fading the ramp (5ce746a011)

A node stores its whole radius and the fraction of it that is solid, and the controls edited those two numbers. So size grew the ramp along with the solid part, and the node's border handle changed its size.

  • _brush_resize_part() turns a change of one part into a new radius and fraction, keeping the other part as it is. The wheel, the context-menu sliders, both node handles and the creation defaults all go through it.
  • The "Fading" slider sets the width of the ramp, in the units of the circle's and the polygon's border.
  • The wheel scales either part by 1.02 per notch, raised to flow as the circle does, and up grows it. Fading used to go the other way.
  • A selected node gets a second handle, where its spoke turns from solid to ramp; it moves the edge of the solid part. The outer handle now moves only the outer edge of the ramp. Both share the border-handle state and are told apart by handle_border_solid.
  • dt_masks_find_closest_handle_common() takes its callbacks as a dt_masks_hit_callbacks_t, going from 10 parameters to 5, instead of gaining an eleventh. post_expose is handed the form it draws, since the new handle needs the node's fraction.
  • Nothing stored is converted: a node keeps its radius and its fraction. The follow-up on the solid part below changes how a brush is painted between nodes that differ.

4. Follow-ups

  • A polygon reads its winding from the form it draws (9894b78409). Its post_expose looked the form up again through the visible group, at its own index: outside a group that found nothing, and in a creation session the index counts the session's shapes, not the group's.
  • get_points_border writes through a dt_masks_outline_out_t (7b11701ed8). With fading it had reached seven out-parameters, eleven arguments in all. The struct holds the addresses of the caller's variables, NULL for a part not wanted, as the arguments did, so the five shapes and the six callers change in form only. Each function goes from 11 parameters to 5 and loses 2 of lizard's complexity. The shapes no longer clear border_skips themselves, since dt_masks_get_points_border(), their only caller, already does.
  • A brush's creation preview keeps the size the wheel set (2924759cfb). Every read of the brush's border conf key allows a whole radius of up to 1, except the creation preview's, which clamped it to 0.5 and wrote that back. A size scrolled past 0.5 before the first stroke was toasted, then cut back, and the brush started from 0.5. The preview now reads the key as the others do.
  • A brush's centreline is drawn only while it is selected (a6e97875cc), as its dashed border is. An unselected brush shows where its fading starts and nothing else.
  • Hit-test callbacks read their user data as const (aff63448d6), so the brush no longer casts away the const of the form it passes. Alongside, the SonarCloud smells in the code this branch touches: an unused parameter marked, chained assignments and multiple declarations split.
  • A brush's fading edge keeps a neck thinner than half a cell (c34db68a44). Where the spokes lie along the spine, the solid part is a thread round it. On brush-fading-neck it is some 0.5 px thick, its cells reading 50 to 175 out of 255 against a level of 128, so it broke into islands that float rounding chose: 9 loops with -ffast-math, 7 without. The Debug builds of the CI, without it, failed the geometry corpus on GNU, LLVM 20 and Windows. The spokes start on the spine, so the cells it crosses are now set full before the trace, and the neck is one loop round it in both builds.
  • Hit-test callbacks mark what they ignore, and the spine walk steps from its start (1b124f5651), for the SonarCloud issues the two commits above raised. The callbacks that ignore their user data mark it __attribute__((unused)), since they must keep their callback type's signature. The walk along the spine had a cognitive complexity of 29: each step now decides from the segment's start which side of its cell it reaches first, instead of carrying four accumulators. Every verdict and every overlay of the geometry corpus is identical to the byte, in a RelWithDebInfo and a Debug build.
  • The gradient's post-select marks the parameters it ignores (0d108992d6): the last SonarCloud issue of that kind.
  • A brush's solid part is a disc union of its own (3bac7a1a1b). Between two nodes the solid part was the first fading of each spoke, with the fading eased linearly while the radius eased by a smoothstep. That point leans with the border's rate and lies on the envelope of nothing. So between two nodes of one solid radius and different radii, the line where the fading starts bulged toward the wider node and moved when the border handle was dragged. Where the smaller disc nests in the larger, the solid part thinned to a thread.
    • A node's solid radius is its radius times its fading, eased by the same smoothstep, and a spoke's edge sample lies on the envelope of those discs. _brush_border_get_XY() places it in the same Bézier evaluation as the border sample.
    • The payload stores that edge in the frame of its spoke (three values a sample), so it follows any distortion. The pipe and the GUI turn it into points after their own distortion.
    • The raster paints each spoke solid to its edge, then ramps to its border. A spoke whose solid piece repeats the previous one's paints only its ramp: these are the arcs that close a gap in the border, all ending on their leaf's edge.
    • masks_solid.c begins a run once its bands have swept a tenth of a cell between them. Waiting for one band that wide dropped part of brush-ramp-nested's fill, where the spine is sampled a fiftieth of a pixel apart.
    • Existing brushes paint differently between nodes whose radius or fading differ. Where all nodes are alike, 12 to 26 % of the painted pixels move, by at most 9 to 17 out of 255.

These commits also bring the doc/ line citations into the touched files up to date, including some that earlier commits of the branch or of master had left behind.

Documented in:

  • doc/brush-boundary.md, section "Where the fading starts";
  • doc/masks-gui.md, section "A brush's size and fading edit its solid part and its ramp, as a circle's do";
  • doc/masks-geometry.md.

Measured

Measured with tests/masks/masks_geometry.c on a RelWithDebInfo build.

Accuracy. The corpus gains four brushes and two judges:

  • the brushes are brush-fading-pinch, brush-fading-neck, and brush-ramp-taper and brush-ramp-nested (modelled on the test session's screenshots);
  • _judge_fading_edge() wants every pixel on the edge of the raster's full-density part within 4 px of the traced edge;
  • _judge_solid_part() holds that full part to the disc union. Every pixel within the discs shrunk by 2 px must be full, and every full pixel must lie within them grown by 3.

On 3bac7a1a1b, in RelWithDebInfo and in Debug, the solid-part judge passes all 21 brushes and frames with 0 px either way. Against the library built from 1b124f5651, it fails 11 of them, for example brush-ramp-taper with 2744 px in excess and brush-fading-neck with 6639 missing. The worst pixel of the fading edge is 1.53 to 1.70 px away, against 2.02 to 2.65 before.

In a Debug build, brush-1074-flare traces 4 loops where RelWithDebInfo traces one. On aff63448d6, one of them was a hole about a pixel wide inside its solid part, which the judge does not see. It is left as is.

Alternative measured. In place of the fill and trace, a boundary pass over the edge samples (dt_masks_outline_boundary_skips()) was faster on 3 of 21 cases and slower on the others. It left 1 to 19 open runs instead of closed loops, and kept up to 1281 points inside the solid part where the envelope folds (brush-1074-flare-b).

Cost. --time-overlay 30 at a 2560×1440 view and fit zoom, lower of two runs, before → after, in ms:

case frame, member frame, selected outline build
brush-1313-cusp 2.34 → 3.26 3.68 → 4.55 9.7 → 11.8
brush-zigzag 4.70 → 8.63 7.88 → 11.39 21.6 → 32.5
brush-selfcross 4.44 → 7.63 7.08 → 10.08 23.4 → 29.4
brush-1360-pressure-ramp 3.58 → 4.53 5.57 → 6.50 24.4 → 32.7
brush-1074-flare 3.92 → 5.24 5.35 → 6.55 26.7 → 31.1
brush-fading-neck 3.15 → 3.63 3.76 → 4.22 18.7 → 21.0
polygon-comb (no fading edge) 5.91 → 5.82 8.57 → 8.58 19.9 → 19.9
group-11 (eleven shapes) 3.10 → 3.22 5.39 → 6.51 149.2 → 198.1

The table was measured before c34db68a44. On 3bac7a1a1b against 1b124f5651, two runs each way: every brush's frames are within 0.26 ms and its builds within 3.4 ms.

Raster, MASKS_DEBUG=1, summed over the corpus's 22 brushes and frames, lower of three runs, 1b124f5651 → 3bac7a1a1b:

  • walk 224.2 → 238.5 ms. A second Bézier evaluation for the edge cost some 337 ms; computing it in the border's evaluation avoids that.
  • painting 1522.0 → 1118.0 ms (1578.0 without skipping the repeated solid pieces);
  • whole buffer 1772.5 → 1396.4 ms.

The skip changes no pixel: the corpus's 29 masks are identical to the bit with and without it. The walk along the spine adds 0.59 ms in median over the corpus's 39 fills and 1.88 to 2.00 ms at most, on 178,887 bands, over two runs with a probe in a RelWithDebInfo build on 1b124f5651.

The fill itself is described in doc/brush-boundary.md: runs of one orientation, bow-tie lobes, the radix sort of the crossings, and the grid limits.

Tested by hand in a RelWithDebInfo build with OpenCL:

  • before the rebase onto e19adbd0b9:

    • the solid line, the dotted centreline and the two handles on a brush;
    • the wheel, the sliders and the handles on existing brushes and during creation;
    • the other shapes, whose hit test and post_expose changed signature;
  • before the rebase onto f76012b77f:

    • the creation preview growing past the old limit;
    • a polygon's curve handles, in a module's mask and in retouch;
    • the outlines of every shape and of a clone's source.
  • on 3bac7a1a1b, before its edge moved into the border's Bézier evaluation and before the repeated solid pieces were skipped: the line where the fading starts between two nodes of one solid radius, moderate and nested, while dragging the border handle.

Not tested by hand yet:

  • a6e97875cc, which hides the centreline of an unselected brush;
  • c34db68a44, which turns a thin neck from islands into one loop.

ctest: 32/32 pass on c34db68a44, on 1b124f5651 and on 3bac7a1a1b. The CI passes on c34db68a44, its Debug cells included.

Gates run on this head, 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_conditional_includes.sh origin/master
  • check_unused_includes.sh --changed origin/master

check_statelessness.sh was not run: it covers src/system, src/math and src/widgets, which this branch does not touch. No new warning under clang-19.

Left as is

Accepted in SonarCloud:

  • the cognitive complexity of the brush's and the polygon's post_expose and of the test's judge (c:S3776);
  • the nesting in the fill and in the judge (c:S134), the two breaks of the trace's loop (c:S924);
  • _change_part's 8 parameters (c:S107);
  • the commented-out disc block in masks_gui.c (c:S125), kept on purpose for reuse;
  • two false positives: a null border in brush.c (c:S2259), which the producer never hands out with a payload, and an out-of-bounds read in the test (c:S3519).

🤖 Generated with Claude Code

t and others added 9 commits November 11, 2026 23:36
A brush paints each spoke at full density over the first `fading` of its length and ramps to zero past it, but the overlay drew only its spine and, when selected, its dashed border: nothing showed where the fading started, or that a scroll on the fading had changed it. `get_points_border` now hands out the contour on the spokes through a new `fading` out-parameter, built in place from the producer's payload and index-aligned with the border; every other shape leaves it NULL.

That contour is not the edge to draw. The solid part is the union of the bands between neighbouring spokes, and where the spokes lie along the spine (a size that climbs steeply, a small fading on a wide node) its edge is made of the spokes' sides, which no pass over the spoke ends can trace. The new masks_solid.c fills that union on a grid of one cell per device pixel and traces its half-coverage level by marching squares into closed loops, which the brush strokes solid in every state; its dashed border is still drawn only when it is selected.

The bands are grouped into runs of one orientation, each a positively wound polygon, filled non-zero with exact crossings on four sub-scanlines per row, without cairo, which the toolkit ratchet keeps out of develop/. A run turns over only after a tenth of a cell of backward sweep, so a trembling long spoke does not split it at every band; the lobe of a bow-tie band wound against its run is added back twice, or it leaves a hole; a line's crossings are radix-sorted past 32.

The corpus gains brush-fading-pinch and brush-fading-neck, and a judge that wants every pixel on the edge of the raster's full-density part within 4 px of the traced edge: all are within 3.12 px. At fit zoom a brush's outline build costs 1.2 to 10.9 ms more and a frame 0.5 to 3.9 ms more; the measurements are in doc/brush-boundary.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The line through a brush's nodes carries them but is no edge of the mask; the edge where its fading starts is now the solid line, and the two read alike when both are solid. dt_masks_draw_path_seg_by_seg() strokes the centreline with round dots; its `round_ends` argument, which only the brush passes, becomes `centreline`. The discs it painted on the two true ends are left commented out: stroked solid, they come out darker than the dots they end. The polygon's outline stays solid.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A brush node stores its whole radius and the fraction of it that is solid, and the controls edited those two numbers, so size grew the ramp along with the solid part and the node's border handle changed its size. They now edit the two parts as a circle's controls do: size the solid radius, fading the width of the ramp, each keeping the other. `_brush_resize_part()` turns a change of one part into a new radius and fraction, and the wheel, the context-menu sliders, the node handles and the creation defaults all go through it. The "Fading" slider sets the ramp width, in the units of the circle's and the polygon's border. The wheel scales either part by 1.02 per notch, raised to `flow` as the circle does, up growing it, where fading used to go the other way. A stored brush keeps its mask until one of its nodes is edited.

A selected node gets a second handle where its own spoke turns from solid to ramp, which moves the edge of the solid part; the outer handle now moves only the ramp's outer edge. Both share the border-handle state and are told apart by `handle_border_solid`. dt_masks_find_closest_handle_common() takes its callbacks as a dt_masks_hit_callbacks_t, which gains `solid_handle`, rather than an eleventh argument, and post_expose is handed the form it draws, since the handle needs the node's fraction.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
post_expose is handed the form it draws, but the polygon still looked it up again, through the visible group at its own index, to tell which way round its handles go. It now reads the form it is given. Outside a group that lookup found nothing, and in a creation session the index counts the session's shapes, not the group's. _polygon_is_clockwise() takes a const form.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
get_points_border and dt_masks_get_points_border() took seven out-parameters, eleven arguments in all, since the brush added `fading`. They now take one dt_masks_outline_out_t, holding the addresses of the caller's variables, NULL for a part not wanted, as the arguments did: the five shapes and the six callers change in form only, each caller declaring its struct before the call. The shapes no longer clear `border_skips` themselves, which dt_masks_get_points_border(), their only caller, already does.

The line numbers doc/ cites in the files touched follow, among them two the previous commits had left behind, in doc/darkroom-redraw.md and doc/masks-geometry.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every read of the brush's `border` conf key keeps it within FADING_MIN and FADING_MAX, a whole radius of at most 1, as the size and fading controls do, except the creation preview's: it kept the key within BORDER_MIN and BORDER_MAX, at most 0.5, and wrote the clamped value back. A size scrolled past 0.5 before the first stroke was toasted, then cut back by the next expose, and the brush started from 0.5. The preview now reads the key as the others do; BORDER_MIN and BORDER_MAX, used nowhere else, are gone.

Four line numbers doc/ cites follow, two in brush.c, one in masks_gui.c and one in the geometry test, which the previous commits and the latest of master had left behind.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The dotted centreline carries the nodes but is no edge of the mask, and every brush drew it in every state, next to the solid line where its fading starts. It is now drawn on the selected brush only, as its dashed border is: an unselected brush shows where its fading starts and nothing else.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
dt_masks_hit_callbacks_t carries its user data, and the five callback types take it, as const void *: no callback writes through it, and the brush, which passes the form it draws, no longer casts the const away. Alongside, as SonarCloud asks of the code this branch touches: _gradient_get_points_border() marks its unused `source` and loses a comment orphaned by an earlier change, a brush node's two border values are assigned one at a time, and every multiple declaration in masks_solid.c, dt_masks_gui_form_remove() and the geometry test's fading-edge judge is split one to a line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
dt_masks_solid_edge() traces the half-coverage level of the union of the bands between neighbouring spokes. Where the spokes lie along the spine, that union is a thread round it, and brush-fading-neck's is some 0.5 px thick: across the neck its cells read 50 to 175 out of 255, the level at 128, so it broke into islands that float rounding chose. The RelWithDebInfo build, with -ffast-math, traced 9 loops; the Debug builds the CI runs, without it, traced 7, left 9 px of the neck with no edge point within 4 px, and failed the geometry corpus on GNU, LLVM 20 and Windows alike.

The spokes start on the spine, so the solid part holds it: every cell the spine of a kept band crosses is now set full before the trace, the segment walked from cell to cell across their sides. The neck is one loop round the spine in both builds, all its pixels within 2.47 px of the edge; brush-fading-pinch, whose solid part narrows to a point at its middle node, becomes one loop joined there, under the node's disc; the 18 other brushes and frames trace the same loops as before, within the same 2.65 px. The walk takes 0.57 ms in median over the corpus's 39 fills and 1.84 ms at most.

doc/brush-boundary.md records it, and that a Debug build traces 4 loops on brush-1074-flare where RelWithDebInfo traces one, one of them a hole about a pixel wide that the judge does not see.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Jiyone
Jiyone force-pushed the masks/brush-fading-contour branch from e3a1020 to c34db68 Compare November 12, 2026 00:01
t and others added 4 commits November 12, 2026 01:26
…teps from its start

The previous two commits changed lines SonarCloud then read as new. Thirteen hit-test callbacks ignore their user data (three each of the brush, the ellipse, the gradient and the polygon, and the circle's one; SonarCloud flagged nine of them), and the ellipse's post-select also ignores `inside` and `inside_source`: they must keep the signature of their callback type, so those parameters are marked __attribute__((unused)), as the tree marks them elsewhere.

_solid_spine() had a cognitive complexity of 29. It walked each segment with four accumulators, the fraction of the segment to the next side across x and across y and their steps. Each step now decides from the segment's start which side of the cell it reaches first, comparing |sx dy| with |sy dx|: two variables fewer, no error building up along the segment, and a complexity of about 17 counted by hand, below the 25 SonarCloud allows. On the geometry corpus, every verdict and every one of the 27 overlays is identical to the byte with the previous walk, in the RelWithDebInfo build and in a Debug one. The walk takes 0.59 ms in median over the corpus's 39 fills and 1.88 to 2.00 ms at most over two runs, against 0.57 and 1.84 ms before; doc/brush-boundary.md carries the new figures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
_gradient_post_select_cb() reads neither `inside_source` nor its user data. They keep the signature of the callback type, so both are marked __attribute__((unused)), as the other hit-test callbacks mark theirs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Between two nodes, the solid part was the first `fading` of each spoke, the fading eased linearly while the radius eased by a smoothstep. That point leans with the border's rate, not the solid part's, and lies on the envelope of nothing: between two nodes of one solid radius and different radii, the line where the fading starts bulged toward the wider node and moved when the border handle was dragged, and where the smaller disc nests in the larger the solid part thinned to a thread.

A node's solid radius is now its radius times its fading, eased between the nodes by the same smoothstep, and a spoke's edge sample lies on the envelope of those discs, placed by _brush_border_get_XY() in the same evaluation of the Bézier that places its border sample. The payload stores that edge in the frame of its spoke, three values a sample, so it rides any distortion; the pipe and the GUI turn it into points after their own with _brush_payload_to_edges(). A joint arc, a cap or a borrowed border is radial; the spokes of an arc closing a gap in the border inside a segment take their leaf's edge. The raster paints each spoke solid to its edge and ramping from there to its border, and a spoke whose solid piece is the previous one's, to the pixel and the density, paints only its ramp.

masks_solid.c begins a run once its bands have swept a tenth of a cell between them, not once one band is that wide: where the border moves fast the spine is sampled a fiftieth of a pixel apart, and brush-ramp-nested lost a stretch of its fill.

The corpus gains a `solid part` judge, which holds the raster's full part to the disc union (every pixel within the discs shrunk by 2 px full, every full pixel within them grown by 3), and two brushes modelled on a test session's screenshots, brush-ramp-taper and brush-ramp-nested. Against the library built from 1b124f5 the judge fails 11 of its 21 brushes and frames; now it passes all 21 with 0 px either way, in the RelWithDebInfo build and in a Debug one, and every pixel on the full part's edge lies within 1.53 to 1.70 px of the fading edge, against 2.02 to 2.65.

On the corpus, where a brush's nodes share a radius and a fading, 12 to 26 % of its painted pixels change, by at most 9 to 17 out of 255; elsewhere the solid part changes shape. Summed over its 22 brushes and frames, the lower of three runs, the walk takes 238.5 ms against 224.2, painting 1118.0 against 1522.0 and the whole buffer 1396.4 against 1772.5; the overlay's frames and builds move within noise. A boundary pass over the edge samples, measured in place of the fill and trace, kept up to 1281 points inside the solid part for no saving. doc/brush-boundary.md, masks-geometry.md and masks-gui.md carry the account.

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

SonarCloud reported five issues on the previous commit. _solid_band_signs() had a cognitive complexity of 35 and a nested conditional operator: it now sets the signs in one pass, a run waiting to begin handled apart from a run going on, then counts the bow ties and extends the box over the kept bands in a second. A run turns only on a band against it, so it turns to the other way without testing that band's sign. On the geometry corpus every verdict is the same and every render is identical to the byte with the previous code, against the bank's baselines.

_brush_get_mask() declares its three segment ends one per statement.

The two others, the `restrict` of _brush_bounding_box_raw() and the nine parameters of _brush_bounding_box(), are master's own issues on lines this branch changed; fixing them would twist the code, so they are left to be accepted in SonarCloud.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Jiyone
Jiyone merged commit 6a9005e into master Nov 12, 2026
18 checks passed
@Jiyone
Jiyone deleted the masks/brush-fading-contour branch November 12, 2026 02:41
@sonarqubecloud

Copy link
Copy Markdown

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