Ansel 0.0
A darktable fork - bloat + design vision
Loading...
Searching...
No Matches
Masks enclosure, phase P2: the group-membership API

First checked 2026-09-29. This file was mechanically checked against 8f4638a04e on 2026-09-29 — every file:line citation resolved, every backticked symbol looked up in the tree, every OPEN/planned status claim tested, and every gate or baseline number it quotes compared with tools/check_module_boundaries.sh and tools/include_baseline.txt. No per-claim semantic read was done: a citation that resolves can still describe the wrong thing, so this is a floor, not a verification. The status was stale and is corrected: P2 has largely shipped as src/develop/masks_group.h, and the ratchet's masks_member_baseline is 68 against the 102 this survey measured.

Status

Design only — no API code has been written yet. P2 has largely shipped (checked 2026-09-29 at 8f4638a04e). src/develop/masks_group.h exists and carries the API this document designs, with the dt_masks_result_t return and the id-keyed, dev-first shape argued for below: dt_masks_group_set_member_operation() (:135), dt_masks_group_get_member() (:152), dt_masks_group_contains() (:165), dt_masks_group_covers_shapes() (:180), dt_masks_group_first_use() (:197), dt_masks_group_find_holder() (:212), dt_masks_group_list() (:229), dt_masks_group_set_member_opacity() (:251), plus dt_masks_form_get_info() and dt_masks_group_copy_members().

The ratchet says how much it drained: tools/check_module_boundaries.sh:423 now reads masks_member_baseline=68, against the 102 this survey measured — a third of the external struct accesses are gone. The other counters stand at masks_include_baseline=18, masks_gui_include_baseline=11, masks_write_baseline=16, masks_alloc_baseline=1, masks_forms_baseline=67, masks_row_baseline=27. src/develop/masks is still not closed, which is what those non-zero baselines mean, so the rest of this document is live work rather than history.

Phases P0 and P1 shipped before it (typed rasterisation result; the section-9 ratchet itself).

It was produced by surveying every one of the ~385 external accesses in the five consumer files, grouping them by intent rather than by struct mechanics, then designing three independent APIs (minimal-orthogonal, CRUD-shaped, opaque-handle-and-iterator) and judging them against the survey. Everything below marked verified was checked against the code, and several of those checks overturned what the proposals assumed.

The convention: the first parameter names the world

Three suffix schemes were proposed (_in, _frozen, _ext). All three are unnecessary, because the tree already distinguishes the cases positionally:

  • GList *forms first → resolve against a borrowed refcounted snapshot (pipe->forms, hist->forms). No lock, no copy-on-write, read-only.
  • const dt_masks_form_t * first → an already-resolved handle. Thread-neutral: it reads only that object's own memory. No lock, no COW, and no _in twin is needed.
  • dt_develop_t *dev first → touches the live list. Returns dt_masks_result_t ⟹ it writes, locks and COW-touches internally; returns a value ⟹ it reads under the read lock.

Only the resolvers come in pairs. That removes about six functions relative to the CRUD proposal, and it makes a pipeline-thread lookup in self->dev->forms — the bug retouch and spots both carried in modify_roi_in() and process() — visibly wrong at the call site.

The first resolver of the snapshot side already exists and takes the pipe itself rather than its list: dt_masks_get_from_id_in_pipe(const dt_dev_pixelpipe_t *pipe, int id) (develop/masks.h), used by retouch and spots on the pipeline thread. The pipe still names the world first, and callers no longer touch pipe->forms, which is what the ->forms ratchet counts.

Handles are non-negotiable for reads. Verified: dt_masks_get_visible_form() can return a formid == 0 transient display group that is in neither dev->forms nor dev->allforms (masks_gui.c:4009-4051), so no id-keyed reader can reach it — yet retouch.c:986, spots.c:289 and blend_gui.c:2159 all read it.

Headers

Neither masks.h nor masks_functions.h can host the new API.

Two new headers, modelled exactly on the colorprofiles/profile_types.h cut and on masks/masks_history.h (which already compiles against an opaque dt_masks_form_t using tag declarations and <glib.h> alone):

Implementation goes in src/develop/masks/masks.c, the data-model translation unit. No CMake change is needed.

Value types crossing the boundary

#define DT_MASKS_FORM_NAME_LEN 128
typedef enum dt_masks_result_t
{
DT_MASKS_OK = 0, /* the model changed */
DT_MASKS_UNCHANGED, /* legal request, nothing to do -- caller skips the history commit */
DT_MASKS_NOT_FOUND, /* no such group, or no such member in it */
DT_MASKS_INVALID /* refused: not a group, self-inclusion, bad argument */
typedef struct dt_masks_member_t
{
int formid;
int parentid; /* the row's AUTHORED origin; != holder inside a display group */
guint index; /* position == compositing order == GTK row identity */
dt_masks_state_t state; /* tightened from the struct's plain `int` */
float opacity;
typedef struct dt_masks_form_info_t
{
int formid;
int version;
gboolean is_group;
gboolean is_retouch; /* (type & DT_MASKS_IS_RETOUCHE) != 0 */
guint member_count; /* 0 unless is_group; NOT recursive */
#define DT_MASKS_FORM_NAME_LEN
Definition masks_types.h:46
dt_masks_state_t
Definition masks_types.h:87
dt_masks_type_t
Definition masks_types.h:62
dt_masks_result_t
What a request that may change the masks model did.
@ DT_MASKS_OK
@ DT_MASKS_UNCHANGED
@ DT_MASKS_NOT_FOUND
@ DT_MASKS_INVALID
const float uint32_t state[4]
What a form IS, BY VALUE: identity, kind, and – for a group – how many members.
dt_masks_type_t type
One shape's membership of one group, BY VALUE.

Why dt_masks_form_group_t moves rather than going opaque. common/xmp_sidecar.cc:1203-1204 casts an XMP binary blob straight to dt_masks_form_group_t * and validates entry->mask_nb * sizeof(dt_masks_form_group_t) == entry->mask_points_len. The struct's size and field order are the on-disk format in every user's sidecars and database. It can never be made opaque and its layout can never change — which is exactly why the value-typed dt_masks_member_t must be what everyone else consumes.

The API

Resolvers — the only dev / snapshot pair

dt_masks_form_t *dt_masks_get_group_from_id (struct dt_develop_t *dev, int group_id);
dt_masks_form_t *dt_masks_get_group_from_id_in_pipe(const dt_dev_pixelpipe_t *pipe, int group_id);
dt_atomic_set_uint64 & dev
static const dt_dev_pixelpipe_t * pipe
Definition layers.h:49

NULL unless it resolves and is a group. Collapses ~30 sites that write dt_masks_get_from_id(...) followed by (x->type & DT_MASKS_GROUP). Do not collapse the pair — that reintroduces the spots.c cross-thread bug as the path of least resistance.

Reads — handle-taking, thread-neutral, no lock, no COW

dt_masks_member_t *out, guint out_max);
gboolean dt_masks_group_get_member (const dt_masks_form_t *group, int formid,
gboolean dt_masks_group_get_member_at(const dt_masks_form_t *group, guint index,
gboolean dt_masks_form_get_anchor(const dt_masks_form_t *form, float anchor[2], float source[2]);
const char *dt_masks_type_name(dt_masks_type_t type); /* untranslated token; takes a VALUE */
const dt_colormatrix_t dt_aligned_pixel_t out
_lib_location_type_t type
Definition location.c:1
dt_masks_result_t dt_masks_group_get_member(dt_develop_t *dev, const int group_id, const int formid, dt_masks_member_t *out)
Read one group member by identity.
Definition masks.c:1927
gboolean dt_masks_form_get_info(const dt_masks_form_t *form, dt_masks_form_info_t *out)
Definition masks.c:1682
guint dt_masks_group_copy_members(const dt_masks_form_t *group, dt_masks_member_t *out, const guint out_max)
Definition masks.c:1760
const char * dt_masks_type_name(const dt_masks_type_t type)
The stable, untranslated token for a shape kind: circle, ellipse, polygon, brush, gradient,...
Definition masks.c:1785
  • get_info retires ~40 ->formid, ~30 ->type, 24 ->name and supervisor's ->version reads, plus every hand-written type & (DT_MASKS_CLONE|DT_MASKS_NON_CLONE) (8 copies; masks.h:422 already names that predicate). name is copied: the borrowed const char * is exactly the hazard blend_gui.c:1701 already trips, caching parent_form->name and using it down to :1712.
  • copy_members returns the total always and fills min(total, out_max); out == NULL makes it a count. Order is the contract, and it must be stated at the declaration: stored order == compositing order == GTK row order == retouch.c:725's p->rt_forms[] index == spots.c:565's d->clone_algo[pos] index, which is persisted in every user's database. A member that fails to resolve still consumes its index — verified: spots.c:569 continues but pos++ sits in the for-increment. Never filter, never recurse, never reorder.
  • All four assert the group type internally and return 0/FALSE otherwise — that is what makes the polymorphic ->points unreachable — and leave *out completely untouched on FALSE (the dt_colorspaces_profile_at() convention).
  • get_anchor is the only reason dt_masks_node_* is public today. It dispatches through the already-private form->functions vtable and replaces retouch.c:893-930 and its byte-for-byte copy at spots.c:513-538.

Reads that must resolve children — take dev, read lock internally

gboolean dt_masks_group_has_leaf_shape (struct dt_develop_t *dev, int group_id);
gboolean dt_masks_group_is_single_group_wrapper(struct dt_develop_t *dev, int group_id);
int dt_masks_form_owner_group (struct dt_develop_t *dev, int formid); /* 0 = none */
guint dt_masks_forms_list_ids (struct dt_develop_t *dev, int **out_ids);
gchar *dt_masks_group_member_label (struct dt_develop_t *dev, int group_id, int formid);

The first two delete blend_gui.c:1482-1521 outright — pure masks-graph queries with zero GUI content in a GUI file. Depth-cap both at 32, as _masks_find_any_parent_group() already does and neither copy does. owner_group replaces the old any-parent lookup and drops its COW side effect — verified at survey time: that function copy-on-write-touched inside a lookup. It shipped as dt_masks_group_find_holder() (develop/masks_group.h:212); the surviving entry-level helper is dt_masks_form_group_find_entry() (masks/masks_gui.c:1368), which is a plain read. Neither dt_masks_form_group_find_any() nor _masks_find_any_parent_group() exists any more, so take the names in this paragraph as the survey's, not the tree's — the depth cap they were cited for lives in the recursive search at masks_gui.c:1496-1501, whose comment explains that a raw DB/XMP load does not validate against a group referencing its own ancestor (the interactive path guards it in dt_masks_group_add_form).

Writes — all id-keyed, all COW internal, all returning dt_masks_result_t

int formid, dt_masks_state_t operation);
int formid, float opacity);
dt_masks_result_t dt_masks_group_nudge_member_opacity(struct dt_develop_t *dev, int group_id,
int formid, float amount,
dt_masks_increment_t increment, int flow);
float dt_masks_group_set_member_property (struct dt_develop_t *dev, int group_id,
int formid, dt_masks_interaction_t property,
float value, dt_masks_increment_t increment,
int flow); /* NAN = not applicable */
dt_masks_result_t dt_masks_group_move_member (struct dt_develop_t *dev, int group_id,
int formid, int delta); /* -1 up, +1 down */
dt_masks_result_t dt_masks_group_add_member (struct dt_develop_t *dev, int group_id, int formid,
dt_masks_state_t state, float opacity);
dt_masks_result_t dt_masks_group_remove_member(struct dt_develop_t *dev,
struct dt_iop_module_t *module /* nullable */,
int group_id, int formid);
dt_masks_result_t dt_masks_form_set_name (struct dt_develop_t *dev, int formid, const char *name);
dt_masks_result_t dt_masks_form_set_retouch_mode(struct dt_develop_t *dev, int formid, gboolean is_clone);
int dt_masks_group_create_for_module(struct dt_iop_module_t *module, const char *name);
const float delta
dev roi_request value
dt_masks_result_t dt_masks_group_set_member_operation(dt_develop_t *dev, const int group_id, const int formid, const dt_masks_state_t operation, dt_masks_member_t *out)
Set a group member's combination operator, or toggle its inversion.
Definition masks.c:1803
dt_masks_result_t dt_masks_group_set_member_opacity(dt_develop_t *dev, const int group_id, const int formid, const float opacity, dt_masks_member_t *out)
Set a group member's opacity.
Definition masks.c:2047
dt_masks_interaction_t
dt_masks_increment_t
const char * name
Definition pdf.h:90

The line numbers below are historical. They were verified against libs/shape_manager.c as it stood when this survey was made. That file is now libs/shape_manager.c and has been substantially rewritten since — the panel was split into two lists and grew per-row actions — so the numbers locate nothing in the current tree. The file and symbol names are still right; find the code by those.

Every one: resolve → dt_masks_cow_touch() → re-resolve the row from the touched group → mutate → compare. An id-keyed signature is the only shape that can be written this way, which is the whole point: cloning a parent also clones its dt_masks_form_group_t blocks, so any entry pointer taken before the touch belongs to the abandoned copy.

Corrections the survey overturned

These are the findings that contradict what the proposals — and in one case this project's own assumptions — took for granted. They are the reason to read this document before implementing.

  1. dt_masks_form_set_interaction_value() does not copy-on-write for opacity. All three proposals claimed it does and wanted to route opacity writes through it. Verified false: masks_gui.c:4361-4365 dispatches to _change_opacity() (:4920-4928), a bare in-place write plus a toast; the touch lives in the caller dt_masks_form_change_opacity() (:4939-4941). Only the geometry branch touches, and it touches the shape. Reusing the existing setter as-is would ship the retouch.c:598 bug into the new API.
  2. The locking rationale is misdiagnosed. The framing "~21 unlocked external walks of `dev->forms`" is wrong about which end is dangerous: every writer of dev->forms is on the GUI thread, and the only cross-thread reader is pixelpipe_hb.c:1629's snapshot on the worker. Single writer ⟹ the unlocked GUI reads are benign today. The genuinely racy site is the unlocked write at libs/shape_manager.c:377. Read-side locking in the new enumerators is cheap insurance, not a bug fix — and it is still a behaviour change that needs approval.
  3. P2 does not make dt_masks_form_t opaque, and no phase of P2 will. Three blockers survive: the rasterisers take non-const dt_masks_form_t * because they lazily fill cached geometry (12 external sites); spots.c:583-595 reads circle->center/->radius for a fast path and :149-158 mallocs a node for the v1 migration; and dt_masks_get_form_size_from_nodes() casts each points element to const float * assuming float node[2] is the first member — a node layout hard-coded in a public header. Budget a P2b per-shape geometry axis and freeze it against retouch and spots together.
  4. The type-token set feeds persisted conf keys. _get_mask_type() feeds dt_masks_get_set_conf_value(), which builds plugins/darkroom/<plugin>/<type>/<feature> — keys declared in data/anselconfig.xml.in as .../polygon/fading etc. So the token is polygon, never supervisor's "path": adopting supervisor's spelling in a unified function would silently repoint every polygon shape at a non-confgen key defaulting to 0.
  5. Two ratchet mechanics decide how the API is consumed. Section 9 counts -> only, so a converted site that reads m[i].formid by value is invisible to the gate while one that takes dt_masks_member_t *p = &m[i] puts the count straight back — this is why value structs, not accessor-per-field, are what actually drain the number. And masks_strip() drops lines starting with * or // but not /* (verified: blend.c:570 is counted), so do not reflow comments in a commit that moves a baseline.

The first pull request

Convert develop/supervisor.c and views/studio_capture.c. Not the biggest consumers — the two that can reach zero direct accesses. supervisor.c is the only pure consumer in the tree: 8 member reads, no ->forms touches, no allocations, no COW requirement, no lock, all inside three functions, behind a dt_supervisor_active() gate. It exercises all three read functions and both value structs, including the ordered members walk, on real code with a debug-only blast radius.

Three commits, because each moves a different set of baselines and must stay bisectable:

  1. Headers and the three read functions (moves no count): create masks_types.h and masks_group.h, move the enums, implement get_info / copy_members / type_name, fold _get_mask_type() into the last of these, extend test_masks_raster_contract.c with read-API cases reusing its stack-built fixtures.
  2. dt_masks_release_all_forms() in masks_history.h (moves 2 baselines): replaces the four-line free-both-lists block copy-pasted verbatim into develop.c, darkroom.c and studio_capture.c; studio_capture.c then drops masks.h. Baselines → includers 23, ->forms 76.
  3. Convert supervisor.c (moves 3 baselines): the three functions, plus renaming its own dt_sv_entry_t.formid → form_id so the gate's documented false positive genuinely disappears — and delete that paragraph from section 9 in the same commit. Baselines → includers 22, member reads 94, writes 26.

Expected ratchet movement: 24 → 22 includers, 11 → 11 masks_gui.h (unchanged), 102 → 94 reads, 27 → 26 writes, 4 → 4 allocations, 88 → 76 ->forms.

Honesty the PR description must carry, because the numbers overstate the result: neither file becomes masks.h-free — supervisor.c still reaches it through blend.h:43 and studio_capture.c through masks_gui.h:50. The literal count falls; the edge does not die until the blend.h supply line is cut in its own PR.

Verification

tools/check_module_boundaries.sh after each commit (a "ROSE"/"fell" line means the baseline edit is in the wrong commit and bisect will fail); three build configurations sequentially — Release, Debug and build-nofeatures, which is the one that caught the last include-supply-line break; tools/check_unused_includes.sh; pragma_once_to_guards.py --verify and include_graph.py --summary (cycles 0); ctest; tools/check_it_runs.sh — the gate that caught the colorprofiles double-free after every static check had passed; and a pixel comparison with tools/check_export_pixels.sh on a raw carrying both a drawn mask group and a retouch clone, --disable-opencl. Nothing in PR 1 is on the pixel path, but the claim has to be measured.

The biggest silent risk is the ordering contract: supervisor only emits ids, so a copy_members that filtered or reordered would pass PR 1 unnoticed and silently re-pair every shape with the wrong clone algorithm the moment spots.c converts.

Later tranches

The rule that keeps this honest: a function lands in the same commit as its first caller, and every commit that moves a count moves its baseline. (The survey found dt_masks_form_get/set_interaction_value already do what five external sites hand-roll, and have zero callers, because they shipped ahead of their consumers.)