![]() |
Ansel 0.0
A darktable fork - bloat + design vision
|
Verified against f37105c227 on 2026-09-29. That pass found 9 claim(s) in this file that were wrong of the tree and 17 that had gone stale; the ones corrected since carry a note saying what they used to say. Anything not yet corrected is flagged inline. Re-measure before acting on a claim older than the code you are changing, and re-date this line when you do.
src/iop/drawlayer.c plus src/iop/drawlayer/ is a painting layer: a full-resolution RGBA canvas per layer, a brush that stamps dabs into it, a sidecar TIFF that stores it, and a composite into the pipe. This note is the map — what the parts are, which thread owns what, and where a realtime stroke's time goes. It was written from a full read of the module; every number below is derived from the code and cites it.
Re-verified against the tree on 2026-09-29, after #1418, #1430, #1431 and #1471, and corrected again the same day against 1cfa1551c8. The second pass found six claims still wrong — two of them describing defects the refactor had already fixed, which is the worse direction: §2's self->params finding and §7's dead-function list. Citations drift as the code moves, and this note has now shipped a finding that named the wrong struct, one whose count was stale, and two that survived their own repair — so re-measure before acting on any claim, and say so here when you do.
A mechanical check worth re-running: every file.ext:NNN in this document should resolve to a line that exists. All of them do as of 1cfa1551c8 — but note a bare :NNN, continuing a previous citation, is invisible to that check and is how drawlayer.c:4238 survived in §2 for a file of 4169 lines. Write the filename out. Sections 1, 6 and 7 carry a note where their earlier version was wrong rather than being quietly corrected, because the way each was wrong is the more useful thing to know.
This section used to be titled "the module is not the directory" and described four files text-#included into drawlayer.c. #1431 removed that; the numbers below are 2026-09-29.
src/iop/CMakeLists.txt compiles all eleven .c files. There is no #include of a .c anywhere in the module, so a static really is private to its file and the directory buys the encapsulation its layout suggests.
What that cost, and why it is worth keeping: as one unit the module was 7130 lines, a static in worker.c shared a namespace with one in drawlayer.c, and ten alias macros existed so pasted code could call a public function by a private-looking name (_commit_dabs for dt_drawlayer_commit_dabs). Compiled alone the four spliced files raised 819 errors, every one a header they had been borrowing from their host without naming it. Three headers could not be included first either: coordinates.h declared twelve functions over dt_iop_module_t, dt_iop_roi_t and dt_drawlayer_brush_dab_t and included nothing; worker.h named types it never pulled in; runtime.h held a dt_drawlayer_cache_patch_t by value without cache.h.
Actual units, by role:
| file | lines | role |
|---|---|---|
| drawlayer.c | 4169 | module API, GUI, the whole OpenCL composite, process/process_cl |
| worker.c | 1828 | the draw-back thread, the ring, batching, the heartbeat |
| brush.c | 1196 | the per-pixel rasterizer |
| io.c | 1101 | sidecar TIFF read/write |
| paint.c | 994 | pointer samples → dabs (interpolation, spacing, smoothing) |
| runtime.c | 973 | the event→schedule→action dispatcher |
| widgets.c | 851 | widget construction helpers |
| layers.c | 489 | layer CRUD, the GUI-side canvas loader |
| conf.c | 375 | preferences, and the tablet-mapping widget↔key pairing |
| coordinates.c | 366 | coordinate spaces |
| cache.c | 246 | patch allocation over the pixelpipe cache arena |
Ownership is not clean, and that is the module's central defect. The same base_patch is written by the worker (worker.c:961-970), read by the pipeline across a whole process() (rdlock drawlayer.c:1621, released through the dt_drawlayer_runtime_release_t set at drawlayer.c:4049, :4129 and :4149), and replaced by the GUI (layers.c:199-213). The entry's rwlock guards the pixels; nothing guards the patch struct that holds the lock.
Two things cross a thread boundary they should not:
Two labels in this diagram were corrected on 2026-09-29. The 26 conf reads per event were real when first measured but are not what _fill_input_brush_settings does: they live in _refresh_brush_settings_cache (drawlayer.c:206-247), which the filler calls at drawlayer.c:252 only when g->ui.brush_settings_valid is false. And the drain loop has honoured the input path's publish deadline since worker.c:1282 — the "Fixed" list in §4 says so, and the diagram was still showing the state before it.
With r = brush radius (conf default 64, conf.c:78), s = spacing (1 + distance/100 * (2r-1), paint.c:64; distance default 0 ⇒ s = 1 px), T = omp_get_max_threads(), B = 2T dabs per batch (worker.c:898):
A stroke pixel used to be composited about 128 times. It is now composited once per batch, and the reason is algebra rather than tuning.
With the stroke mask present and the internal flow at 0 (UI Flow 100%, the default), the per-pixel alpha is capped = min(ba, (cap − s)/(1 − s)) with the mask update s' = 1 − (1 − capped)(1 − s). Both branches of that min collapse into one closed form —
s' = min( 1 − (1 − ba)(1 − s), cap )
because the cap is absorbing: once it binds, every later dab leaves s at cap. Over a batch that composes to
s_final = min( 1 − Πᵢ (1 − baᵢ) · (1 − s₀), cap )
a product of per-dab transmittance factors, clamped once. So dt_drawlayer_brush_rasterize_batch (brush.c) runs two passes: pass 1 accumulates T ·= (1 − ba) into a scalar plane — four bytes per pixel, no destination load, no powf — and pass 2 walks the batch box once and does a single float4 composite.
Three properties of that, in order of how easy they are to lose:
tests/unittests/test_drawlayer_batch_raster.c pins all of this, including the gate's refusals and the thread-count independence.
Measured, one heartbeat batch at the defaults (r=64, spacing 1, 32 dabs, 8 cores):
| per-dab | batch | |
|---|---|---|
| plain | 21.0 ms | 1.6 ms |
| sprinkles 0.6 | 131.9 ms | 3.3 ms |
The old figures are the interesting ones. A plain stroke was above the 20 ms heartbeat budget, so the rasterizer alone could not keep up with its own publish rate; a textured one was 6.6× over it, which is what "the brush lags" means in practice.
Three things used to sit in it and no longer do.
What remains per pixel is a sqrtf, a shape switch, and the transmittance multiply.
Fixed:
Not fixed:
Re-measured 2026-09-29; the line numbers below are current, the previous ones had drifted off their targets entirely. Check them before quoting them — this section has been wrong once.
The logical state — idle / hovering / painting / draining / committing / loading / saving — is spread across twelve independent booleans in five structs, with no enum and no asserted invariant:
| struct | booleans | runtime.h |
|---|---|---|
| dt_drawlayer_session_state_t | pointer_valid, background_job_running | :20, :30 |
| dt_drawlayer_process_state_t | cache_valid, cache_dirty, base_patch_loaded_ref, last_composite_valid | :44, :45, :51, :69 |
| dt_drawlayer_stroke_state_t | last_dab_valid, finish_commit_pending | :77, :80 |
| dt_drawlayer_ui_state_t | brush_color_valid, brush_settings_valid | :124, :126 |
| dt_drawlayer_runtime_manager_t | realtime_active, painting_active | :255, :256 |
Beside them sits a 15-boolean schedule, dt_drawlayer_runtime_schedule_t — declared in runtime.c, not the header. _build_runtime_schedule (runtime.c:462) maps an event onto it and the dispatcher executes the set bits. It recomputes its whole state twice per dispatch and pushes realtime mode twice.
realtime_active is NOT a cached pure function, which an earlier version of this section claimed. It is computed from three inputs (runtime.c:345), then overridden to FALSE for four event kinds (:356), and written FALSE again from two commit-time sites outside that computation (drawlayer.c:1878, :1894). Replacing it with a predicate would lose both overrides. Note the pairing at those two sites — the flag and dt_drawlayer_set_pipeline_realtime_mode(self, FALSE) are set together, while four other places derive the pipeline mode from the flag (runtime.c:434, :443, :679, :880). Two spellings of one operation, and the shape this module keeps paying for.
brush_color_valid deserves its own warning: it is set TRUE once (drawlayer.c, in dt_drawlayer_sync_cached_brush_colors) and never cleared anywhere. Nothing rebuilds the cached brush colours lazily, so every path that changes what they depend on must refresh them explicitly. Until #1471 the refresh happened only because refilling the HDR exposure slider woke _widget_changed on the panel paths that were not frozen — an accident the frozen path never had.
Drained across #1430, #1431 and #1471. What is left is at the bottom; the rest is kept as a record, because two of the original entries were WRONG and the way they were wrong is worth knowing.
Removed:
Two entries in this list were wrong. Verify before acting on any of the rest.
Still open:
Both fixed; recorded because the shapes recur.
The worker could deadlock itself and take the GUI down with it. _backend_worker_on_idle called dt_drawlayer_commit_dabs (worker.c:1234) → dt_drawlayer_worker_wait_idle (worker.c:1415) — the private-looking spellings _commit_dabs and _wait_worker_idle are from the splice era and exist nowhere in the tree — which blocks while ring_count > 0 — and the ring's only consumer is the worker's own loop. It read the "ready" predicate under the mutex, dropped it, then committed, so a GUI push in that window made the wait real. The only escape, worker->stop, is written by _stop_worker after it calls _wait_worker_idle too, so the next GUI-side commit hung the GUI thread on the same predicate. The worker now posts the commit to the GUI thread and decides-and-posts under one lock acquisition; dt_drawlayer_worker_wait_idle carries a tripwire. Note the cheap fix — making the wait a no-op on the worker thread — is wrong: at that point the ring may hold a new stroke's events, and the commit would wipe that stroke's session state.
A never-cleared arena page was published as a valid canvas. dt_drawlayer_cache_patch_alloc_shared allocates but does not clear, and _refresh_piece_base_cache set cache_valid = TRUE without clearing when it never attempted a load. The GUI-side twin had always cleared; the two loaders had diverged. Both key the same cache entry, so an uncleared page created by the pipeline is adopted by the GUI as the layer's content and a later sidecar write makes it permanent. The clear stays at the call site: moving it into the allocator would add a dead full-canvas memset on the rekey-conflict path, which memcpys the whole buffer on its next statement.
Three more of the same family, also fixed: the worker wrote self->params (it now carries its own blob, seeded from the GUI thread, because the hash is an accumulator); the damage rectangle was published after releasing the write lock that wrote the pixels it describes; and dt_dev_pixelpipe_t.pause was a plain gboolean written cross-thread beside three fields that are atomics for exactly that reason.
Still open: the pipeline thread writes self->params and opens the sidecar — PROCESS_*_BEFORE schedules ensure_layer_cache, whose first act is _sanitize_params on self->params. Removing it is not a deletion: g->process.cache_valid = TRUE happens in exactly one place, inside that function, so a display pipe would never composite the layer again without a GUI-thread request path to replace it.
Established 2026-11-16 against dcb82baf2a, on a 7380x4928 Nikon raw held portrait with one painted layer.
A lipstick stroke on the lips came out in the hair above the temple, by the same offset at every zoom, and a full-resolution export carried a washed-out band across the bottom third of the frame starting at exactly row 4928. One cause.
_flip_swaps_axes() (coordinates.c) asks flip's size fold whether this image's axes are swapped, reading piece->buf_in/buf_out on a pipe and the geometry chain's record off one. It returned a plain gboolean, so "upright" and "cannot tell yet" were the same answer. Those rectangles are written by dt_dev_pixelpipe_get_roi_out(), and the canvas is resolved before that runs. Measured, in one CLI render, the same function on the same pipe answering twice:
The flip piece is found, so the old in.width <= 0 guard read "not written yet" as "no swap", and dt_drawlayer_layer_canvas_for_pipe() reported success with a transposed canvas. Because it succeeded, _refresh_piece_base_cache's fallback — the sidecar page's own dimensions, right there in info and correct — was never consulted. The patch was then allocated 7380x4928 and cached, and the cache's own validity check re-hashes with the patch's own width and height, so it is self-consistent and never notices.
Two symptoms, one transpose:
The fix is that _flip_swaps_axes() now reports whether it could answer at all, and an unresolved orientation fails the canvas rather than defaulting to upright. The two answers are a transpose of each other, so guessing is not a near miss.
The same mistake was also sitting in the fallbacks: four callers substituted geometry.raw_width/raw_height when resolution failed. The raw pair is unrotated, so that names a transposed canvas for every portrait image — the identical defect, one level up, waiting for resolution to start failing. They now go through dt_drawlayer_canvas_from_sidecar(), which reads the dimensions the stored page was authored at, and fail when there is no page yet.
Since closed, and it was not drawlayer's: that memcpy fast path would read past the end of its input for any caller whose output window exceeded its input, silently, at scale 1 — the generic path clips, the fast path did not, and which one runs is decided by roi_out->scale alone. _interpolation_resample_plain() now tests containment first: a contained window keeps the straight-line copy it always had, and anything else replicates the edge, which is the answer the generic path already gives. tests/unittests/test_interpolation_resample_window.c pins it. The control matters more than the test: against the pre-fix resampler 6 of its 7 cases fail, and only the contained one passes, with valgrind naming the read — Invalid read of size 8 ... at memmove ... interpolation.c:955, which is that memcpy. After the fix, 7/7 and ERROR SUMMARY: 0 errors.
No, not as the next step, and the reasoning is not about kernel speed. The dab stream is produced by pointer events on the GUI thread; CLAUDE.md's OpenCL GUI-thread materialization hazard forbids the GUI thread enqueueing work on a device it does not own; the canvas would then live on the device and the CPU-side base patch would need syncing for every process(), export and sidecar write; and the current split already keeps a 384 MB canvas resident in vRAM per layer. The CPU rasterizer had a **~26× algorithmic factor and a ~16× parallelism factor** on the table (§4), and the algorithmic half has since been spent: 2875569cc8 composites a stroke pixel once per batch instead of 128 times, and 6b16818e79 hoists the per-pixel constants the dab and the stroke already fix (both 2026-09-19, i.e. before this document's 2026-09-29 rewrite, which is why the claim read as open when it was not). The parallelism factor is still there. The argument stands either way: spend what is left on the CPU first, because it costs no new synchronisation and no vRAM.