![]() |
Ansel 0.0
A darktable fork - bloat + design vision
|
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.
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.
Three suffix schemes were proposed (_in, _frozen, _ext). All three are unnecessary, because the tree already distinguishes the cases positionally:
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.
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.
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.
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.
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).
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.
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.
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:
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.
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.
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.)
PR 3 — blend.h stops being the masks module's delivery van. (Done.) Remove masks.h from blend.h:43. blend.h names zero masks symbols, but it does declare functions taking dt_iop_module_t and dt_develop_t, so it takes develop/develop.h directly instead — the house rule that a header includes what its own declarations need. Three supply lines broke and were fixed by naming what the file actually uses: common/times.h in common/opencl.c and darktable.c, and DEVELOP_MASKS_NB_SHAPES — pure vocabulary — moved into masks_types.h so blend_gui.h can take the light header. masks_types.h also gained the forward typedef of dt_masks_form_t, so a file that only passes a form along needs the name and not the layout.
Measured correction to this plan. The claim that this edge is "worth more than the other twenty put together" does not survive measurement: masks.h's transitive fan-in is 50 before and 50 after. The files that reached it through blend.h reach it another way. What the change actually achieves is that only two headers still include masks.h — masks_gui.h, which is external-facing, and masks/masks_functions.h, which is module-private. So the reach will not drop until the masks_gui.h edge is cut, and that — not blend.h — is the one carrying the surface to the rest of the tree. Retarget the next header tranche accordingly.