dev_pixelpipe.c

Go to the documentation of this file.

/*
    This file is part of the Ansel project.
    Copyright (C) 2026 Aurélien PIERRE.
    Copyright (C) 2026 Guillaume Stutin.
    
    Ansel is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
    
    Ansel is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
    
    You should have received a copy of the GNU General Public License
    along with Ansel.  If not, see <http://www.gnu.org/licenses/>.
*/
 
#include "widgets/widget_settings.h"
#include "common/conf.h"
#include "system/macros.h"
#include "develop/pipe_cache_policy.h"
#include "system/mem_alloc.h"
#include "common/hash.h"
#include "common/logging.h"
#include "common/times.h"
#include "common/paths.h"
#include "gui/application.h"
#include "system/dtpthread.h"
#include "system/atomic.h"
#include "develop/dev_history.h"
#include "develop/geometry/geometry.h"
#include "develop/imageop.h"
#include "develop/masks/masks_history.h"
#include "develop/pixelpipe.h"
#include "caches/pixelpipe_cache.h"
#include "develop/supervisor.h"
#include "develop/blend.h"
#include "control/control.h"
#include "control/signal.h"
#include <stdint.h>
#include <stdlib.h>
 
static void _sync_pipe_nodes_from_history_from_node(dt_dev_pixelpipe_t *pipe, GList *history_list,
                                                    const uint32_t history_end, GList *start_node,
                                                    const char *debug_label);
// dt_dev_pixelpipe_propagate_formats() is the authoritative forward buffer-format pass; it is
// declared in dev_pixelpipe.h. It must run before any dt_pixelpipe_get_global_hash() because the
// auto-disable it performs feeds the cumulative global hash (see its definition).
static void _dt_dev_pixelpipe_cache_wait_ready_callback(gpointer instance, const guint64 hash,
                                                        const guint64 producer_node_key,
                                                        gpointer user_data);
 
/* What stays here is the TRANSPORT and the PRESENTATION of the wait queue, not the queue:
 * whether we are currently subscribed to the ready signal, and whether the busy cursor is up.
 * The queue, its lock, its counters and its matching rule are cache state and live in
 * caches/pixelpipe_cache_wait.{h,c}.
 *
 * Both flags are GUI-thread-only, like every accessor below: DT_SIGNAL_CACHELINE_READY is
 * declared asynchronous (control/signal.c), so its handler is marshalled to the main loop, and
 * every enqueue site is an expose, a widget callback or an idle. That asynchrony is load-bearing
 * and must not be optimised away -- see the file comment in caches/pixelpipe_cache_wait.h. */
static gboolean _cache_wait_connected = FALSE;
static gboolean _cache_wait_cursor_active = FALSE;
 
static gboolean _cache_wait_cursor_progress(gpointer user_data)
{
  if(IS_NULL_PTR(dt_control_get_global()) || IS_NULL_PTR(dt_gui_get_global()) || IS_NULL_PTR(dt_gui_get_ui()))
    return G_SOURCE_REMOVE;
 
  dt_control_change_cursor_by_name_and_flush("progress");
  return G_SOURCE_REMOVE;
}
 
static gboolean _cache_wait_cursor_restore(gpointer user_data)
{
  if(IS_NULL_PTR(dt_control_get_global()) || IS_NULL_PTR(dt_gui_get_global()) || IS_NULL_PTR(dt_gui_get_ui()))
    return G_SOURCE_REMOVE;
 
  dt_control_commit_cursor();
  dt_control_queue_redraw_center();
  return G_SOURCE_REMOVE;
}
 
static void _dump_one_pending(const dt_dev_pixelpipe_cache_wait_t *wait, const int64_t age_us,
                              gpointer user_data)
{
  (void)user_data;
  dt_print(DT_DEBUG_PIPECACHE,
           "[cache-wait] pending id=%" PRIu64 " owner=%s hash=%" PRIu64
           " target=%s connected=%d age_ms=%" PRId64 "\n",
           wait->request_id,
           !IS_NULL_PTR(wait->owner_tag) ? wait->owner_tag : "(unknown)",
           wait->hash,
           !IS_NULL_PTR(wait->module) ? wait->module_op : "backbuf",
           wait->connected,
           MAX(age_us / 1000, 0));
}
 
void dt_dev_pixelpipe_cache_wait_dump_pending(const char *reason)
{
  const char *context = !IS_NULL_PTR(reason) ? reason : "unspecified";
 
  uint64_t queued = 0, served = 0, cancelled = 0, immediate = 0, misses = 0;
  dt_pixelpipe_cache_wait_get_stats(&queued, &served, &cancelled, &immediate, &misses);
 
  dt_print(DT_DEBUG_PIPECACHE,
           "[cache-wait] dump reason=%s pending=%u queued=%" PRIu64 " served=%" PRIu64
           " cancelled=%" PRIu64 " immediate=%" PRIu64 " misses=%" PRIu64 "\n",
           context, dt_pixelpipe_cache_wait_pending_count(), queued, served, cancelled,
           immediate, misses);
 
  dt_pixelpipe_cache_wait_foreach_pending(_dump_one_pending, NULL);
}
 
static gboolean _module_requires_global_histogram_output_cache(const dt_dev_pixelpipe_t *pipe,
                                                               const dt_iop_module_t *module)
{
  if(IS_NULL_PTR(pipe) || IS_NULL_PTR(module)) return FALSE;
  if(pipe->type != DT_DEV_PIXELPIPE_PREVIEW) return FALSE;
  if(dt_dev_pixelpipe_get_realtime(pipe)) return FALSE;
  if(!pipe->gui_observable_source) return FALSE;
 
  return !strcmp(module->op, "initialscale") || !strcmp(module->op, "colorout");
}
 
static gboolean _module_requires_global_histogram_input_cache(const dt_dev_pixelpipe_t *pipe,
                                                              const dt_iop_module_t *module)
{
  if(IS_NULL_PTR(pipe) || IS_NULL_PTR(module)) return FALSE;
  if(pipe->type != DT_DEV_PIXELPIPE_PREVIEW) return FALSE;
  if(dt_dev_pixelpipe_get_realtime(pipe)) return FALSE;
  if(!pipe->gui_observable_source) return FALSE;
 
  return !strcmp(module->op, "gamma");
}
 
static gboolean _module_feeds_color_picker(const dt_dev_pixelpipe_t *pipe,
                                           const dt_iop_module_t *module,
                                           const dt_iop_module_t *picker_module)
{
  if(IS_NULL_PTR(picker_module) || IS_NULL_PTR(module)) return FALSE;
  if(module == picker_module) return TRUE;
 
  const dt_dev_pixelpipe_iop_t *const piece = dt_dev_pixelpipe_get_module_piece(pipe, picker_module);
  const dt_dev_pixelpipe_iop_t *const previous_piece = dt_dev_pixelpipe_get_prev_enabled_piece(pipe, piece);
 
  return !IS_NULL_PTR(previous_piece) && previous_piece->module == module;
}
 
static gchar *_get_debug_pipe_name(const dt_dev_pixelpipe_t *pipe, const dt_develop_t *dev)
{
  (void)dev;
  return g_strdup(dt_pixelpipe_get_pipe_name(!IS_NULL_PTR(pipe) ? pipe->type : DT_DEV_PIXELPIPE_NONE));
}
 
static GList *_find_detailmask_node(dt_dev_pixelpipe_t *pipe)
{
  for(GList *nodes = g_list_first(pipe->nodes); nodes; nodes = g_list_next(nodes))
  {
    dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)nodes->data;
    if(!IS_NULL_PTR(piece) && !strcmp(piece->module->op, "detailmask")) return nodes;
  }
 
  return NULL;
}
 
static void _refresh_pipe_detail_mask_state(dt_dev_pixelpipe_t *pipe)
{
  dt_dev_pixelpipe_iop_t *detailmask_piece = NULL;
  pipe->want_detail_mask = DT_DEV_DETAIL_MASK_NONE;
 
  for(GList *nodes = g_list_first(pipe->nodes); nodes; nodes = g_list_next(nodes))
  {
    dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)nodes->data;
    if(IS_NULL_PTR(piece)) continue;
 
    if(!strcmp(piece->module->op, "detailmask")) detailmask_piece = piece;
    if(piece->detail_mask)
    {
      pipe->want_detail_mask = DT_DEV_DETAIL_MASK_ENABLED;
      break;
    }
  }
 
  if(!IS_NULL_PTR(detailmask_piece))
  {
    const gboolean enabled = (pipe->want_detail_mask == DT_DEV_DETAIL_MASK_ENABLED)
                             && (detailmask_piece->dsc_in.channels == 4)
                             && (detailmask_piece->dsc_in.datatype == TYPE_FLOAT)
                             && (detailmask_piece->dsc_in.cst == IOP_CS_RGB);
    detailmask_piece->enabled = enabled;
    detailmask_piece->process_tiling_ready = !enabled;
    if(!IS_NULL_PTR(detailmask_piece->data)) *((int *)detailmask_piece->data) = enabled ? 1 : 0;
  }
}
 
static void _change_pipe(dt_dev_pixelpipe_t *pipe, dt_dev_pixelpipe_change_t flag)
{
  if(IS_NULL_PTR(pipe)) return;
  dt_dev_pixelpipe_or_changed(pipe, flag);
  dt_atomic_set_int(&pipe->shutdown, TRUE);
}
 
/* Record the history item a resync last synchronized to, holding a reference on it.
 *
 * The resync runs against a snapshot outside history_mutex, so by the time it writes this the
 * item may already have been cloned out of dev->history by the GUI thread's copy-on-write.
 * Two things follow. The reference keeps the item alive for as long as the pipe names it, so an
 * identity compare on the pointer can never hit a recycled address. The atomic exchange is
 * what makes the write safe against dt_dev_history_cow_touch() re-pointing the same slot at the
 * clone from the GUI thread: whichever side loses the race still ends up releasing exactly the
 * reference it took, never the other side's. */
static void _pipe_set_last_history_item(dt_dev_pixelpipe_t *pipe, dt_dev_history_item_t *hist)
{
  if(!IS_NULL_PTR(hist)) dt_dev_history_item_ref(hist);
  dt_dev_history_item_t *previous
      = (dt_dev_history_item_t *)dt_atomic_exch_ptr(&pipe->last_history_item, hist);
  dt_dev_free_history_item(previous);
}
 
/* `snap` is the caller's history snapshot (dt_dev_history_snapshot_take): this runs outside
 * history_mutex and must not touch dev->history or dev->history_end directly. */
static gboolean _sync_focused_in_place(dt_dev_pixelpipe_t *pipe, const dt_dev_history_snapshot_t *snap)
{
  if(IS_NULL_PTR(pipe) || IS_NULL_PTR(pipe->dev) || IS_NULL_PTR(pipe->dev->gui_module)) return FALSE;
  dt_develop_t *dev = pipe->dev;
  dt_iop_module_t *focus = dev->gui_module;
 
  const gboolean transient = dt_dev_transient_params_active(dev, focus);
  const gboolean realtime = dt_dev_pixelpipe_get_realtime(pipe);
  if(!transient && !realtime) return FALSE;
 
  const uint32_t history_end = (uint32_t)snap->history_end;
  if(history_end == 0) return FALSE;
 
  // Enable/blend state comes from the focused module's history item (transient edits are params-only).
  dt_dev_history_item_t *hist = dt_dev_history_get_last_item_by_module(snap->items, focus, history_end);
  if(IS_NULL_PTR(hist) || IS_NULL_PTR(hist->module) || IS_NULL_PTR(hist->params)) return FALSE;
 
  dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)dt_dev_pixelpipe_get_module_piece(pipe, focus);
  if(IS_NULL_PTR(piece)) return FALSE;
 
  // Resolve params: thread-safe transient snapshot when published, else the history snapshot. A copy is
  // taken so the slot lock is not held across commit_params(); never the live GUI module->params.
  dt_iop_params_t *params = hist->params;
  void *tbuf = NULL;
  uint64_t transient_serial = 0;
  gboolean used_transient = FALSE;
  if(transient && focus->params_size > 0)
  {
    tbuf = g_malloc0(focus->params_size);
    if(!IS_NULL_PTR(tbuf)
       && dt_dev_transient_params_get(dev, focus, tbuf, (size_t)focus->params_size, NULL, 0, NULL,
                                      &transient_serial))
    {
      params = (dt_iop_params_t *)tbuf;
      used_transient = TRUE;
    }
    else
      dt_free(tbuf);
  }
 
  const gboolean previous_want_detail_mask = (pipe->want_detail_mask != DT_DEV_DETAIL_MASK_NONE);
  piece->enabled = hist->enabled;
  piece->detail_mask = !IS_NULL_PTR(hist->blend_params) && hist->blend_params->details != 0.0f;
  dt_iop_commit_params(focus, params, hist->blend_params, pipe, piece);
  dt_free(tbuf);
 
  /* `dt_iop_commit_params()` hands the params we pass to `module->commit_params()`, so the piece
   * PROCESSES the transient blob -- but it derives the piece's identity from
   * `dt_iop_compute_module_hash()`, which hashes `module->params`. That function says so itself:
   * "WARNING: doesn't take into account parameters dynamically set at runtime". So a transient
   * edit changed the pixels a recompute would produce without changing the hash that decides
   * whether to recompute at all, and `dt_dev_pixelpipe_process()` exact-hit the cache and
   * republished the previous frame. Drawlayer used to hide this by bumping `module->params`
   * from its paint worker -- which is the very cross-thread write on GUI-owned state that the
   * transient channel exists to avoid.
   *
   * The transient serial advances once per publish and is fetched under the same lock as the
   * blob, so folding it in makes the piece's identity describe exactly the params it committed.
   * Do this BEFORE `dt_pixelpipe_get_global_hash()` below, which folds the piece hashes into the
   * cumulative pipe hash the cache is probed with. */
  if(used_transient)
  {
    piece->hash = dt_hash(piece->hash, (const char *)&transient_serial, sizeof(transient_serial));
    piece->global_hash = piece->hash;
  }
  _refresh_pipe_detail_mask_state(pipe);
  if(previous_want_detail_mask != (pipe->want_detail_mask != DT_DEV_DETAIL_MASK_NONE)) return FALSE;
 
  // The global hash is cumulative and skips disabled nodes, so the format contract (which may
  // disable a node on an incompatible input) must be settled first.
  dt_dev_pixelpipe_propagate_formats(pipe);
  dt_pixelpipe_get_global_hash(pipe);
 
  // Only advance the synch_top fence when the focused module is the newest history item (the realtime
  // drawlayer case, where each heartbeat appended a top item). For a transient edit of a non-top module
  // no history item changed, so the fence must stay where the last real history sync left it.
  GList *last_item = g_list_nth(snap->items, history_end - 1);
  if(last_item && (dt_dev_history_item_t *)last_item->data == hist)
  {
    pipe->last_history_hash = hist->hash;
    _pipe_set_last_history_item(pipe, hist);
  }
  return TRUE;
}
 
static void _seal_opencl_cache_policy(dt_dev_pixelpipe_t *pipe)
{
  if(IS_NULL_PTR(pipe) || IS_NULL_PTR(pipe->nodes)) return;
 
  // The scopes/global histogram are not refreshed while a realtime stroke is in progress (the preview
  // pipe is paused), so do not force any module to publish a host copy of its output just to feed them.
  // This drops the per-frame RAM copy of `colorout` (and the histogram input/module caches) during
  // realtime drawing, where it is pure overhead.
  const gboolean realtime = dt_dev_pixelpipe_get_realtime(pipe);
 
  // ONE read each, for the whole walk. Both belong to the GUI thread, and both were read LIVE at
  // every node: a focus change or a picker toggle landing mid-walk gave the early nodes one
  // answer and the later nodes another, so the sealed pipe described no single moment. Sampling
  // them here does not make the pipeline the owner of these facts -- having the GUI publish them
  // instead needs the layer flip, since gui/ may not reach up into develop/ today -- but it does
  // make one resync describe one moment.
  const dt_iop_module_t *const focused_module = pipe->dev->gui_module;
  const dt_iop_module_t *const picker_module = pipe->dev->color_picker.module;
 
  gboolean current_output_must_cache_host = TRUE;
 
  for(GList *pieces = g_list_last(pipe->nodes); pieces; pieces = g_list_previous(pieces))
  {
    dt_dev_pixelpipe_iop_t *piece = pieces->data;
    dt_iop_module_t *module = !IS_NULL_PTR(piece) ? piece->module : NULL;
    if(IS_NULL_PTR(piece) || IS_NULL_PTR(module) || !piece->enabled) continue;
 
    gboolean supports_opencl = FALSE;
#ifdef HAVE_OPENCL
    supports_opencl = dt_opencl_is_inited() && piece->process_cl_ready && module->process_cl;
#endif
 
    gchar *string = g_strdup_printf("/plugins/%s/cache", module->op);
    if(!dt_conf_key_exists(string) || !dt_conf_key_not_empty(string))
      dt_conf_set_bool(string, piece->cache_output_on_ram);
 
    const gboolean authored_cache = piece->cache_output_on_ram;
    const gboolean user_requested_cache = dt_conf_get_bool(string);
    dt_free(string);
 
    const gboolean color_picker_on = _module_feeds_color_picker(pipe, module, picker_module);
    const gboolean global_hist_output_on
        = !realtime && _module_requires_global_histogram_output_cache(pipe, module);
    const gboolean global_hist_input_on
        = !realtime && _module_requires_global_histogram_input_cache(pipe, module);
    const gboolean module_hist_on
        = !realtime
          && (pipe->type == DT_DEV_PIXELPIPE_PREVIEW
           && pipe->gui_observable_source
           && (pipe->dev->gui_attached || !(piece->request_histogram & DT_REQUEST_ONLY_IN_GUI))
           && (piece->request_histogram & DT_REQUEST_ON));
    const gboolean active_in_gui
        = (pipe->type == DT_DEV_PIXELPIPE_FULL || pipe->type == DT_DEV_PIXELPIPE_PREVIEW)
           && focused_module == module;
 
    const gboolean has_autoset = pipe->autoset && !IS_NULL_PTR(module->autoset);
 
    // The decision is a pure function of these nine facts (develop/pipe_cache_policy.h), pinned
    // by tests/unittests/test_pipe_cache_policy.c. What stays here is GATHERING them, which
    // is the part that needs a pipe and a dev to look at.
    const dt_dev_pipe_cache_policy_inputs_t inputs = { .authored_cache = authored_cache,
                                                       .user_requested_cache = user_requested_cache,
                                                       .supports_opencl = supports_opencl,
                                                       .color_picker_on = color_picker_on,
                                                       .global_hist_output_on = global_hist_output_on,
                                                       .global_hist_input_on = global_hist_input_on,
                                                       .module_hist_on = module_hist_on,
                                                       .active_in_gui = active_in_gui,
                                                       .has_autoset = has_autoset };
 
    /* One hop is enough: a node that did not publish host data leaves none for a later consumer
     * to trust, since a rekeyed cacheline reports no host pixels until they are rewritten. */
    piece->cache_output_on_ram
        = dt_dev_pipe_cache_policy_decide(&inputs, current_output_must_cache_host,
                                          &current_output_must_cache_host);
  }
}
 
void dt_dev_pixelpipe_rebuild_all_real(dt_develop_t *dev)
{
  if(IS_NULL_PTR(dev) || !dev->gui_attached) return;
  _change_pipe(dev->preview_pipe, DT_DEV_PIPE_REMOVE);
  _change_pipe(dev->pipe, DT_DEV_PIPE_REMOVE);
  /* Rebuilt here, and deliberately not PUBLISHED here: these are the flag-raising paths, and
   * nothing may observe geometry before the publication that belongs with it -- the ordering
   * rule from the fix for #1157. */
  dt_geometry_chain_rebuild(dev);
}
 
void dt_dev_pixelpipe_resync_history_main_real(dt_develop_t *dev)
{
  if(IS_NULL_PTR(dev) || !dev->gui_attached) return;
  _change_pipe(dev->pipe, DT_DEV_PIPE_SYNCH);
}
 
void dt_dev_pixelpipe_resync_history_preview_real(dt_develop_t *dev)
{
  if(IS_NULL_PTR(dev) || !dev->gui_attached) return;
  _change_pipe(dev->preview_pipe, DT_DEV_PIPE_SYNCH);
  dt_geometry_chain_rebuild(dev);
}
 
void dt_dev_pixelpipe_resync_history_all_real(dt_develop_t *dev)
{
  if(IS_NULL_PTR(dev) || !dev->gui_attached) return;
  dt_dev_pixelpipe_resync_history_preview(dev);
  dt_dev_pixelpipe_resync_history_main(dev);
}
 
void dt_dev_pixelpipe_update_history_main_real(dt_develop_t *dev)
{
  if(IS_NULL_PTR(dev) || !dev->gui_attached) return;
  _change_pipe(dev->pipe, DT_DEV_PIPE_TOP_CHANGED);
}
 
void dt_dev_pixelpipe_update_history_preview_real(dt_develop_t *dev)
{
  if(IS_NULL_PTR(dev) || !dev->gui_attached) return;
  _change_pipe(dev->preview_pipe, DT_DEV_PIPE_TOP_CHANGED);
  dt_geometry_chain_rebuild(dev);
}
 
void dt_dev_pixelpipe_update_history_all_real(dt_develop_t *dev)
{
  if(IS_NULL_PTR(dev) || !dev->gui_attached) return;
  dt_dev_pixelpipe_update_history_preview(dev);
  dt_dev_pixelpipe_update_history_main(dev);
}
 
void dt_dev_pixelpipe_update_zoom_preview_real(dt_develop_t *dev)
{
  if(IS_NULL_PTR(dev) || !dev->gui_attached) return;
  _change_pipe(dev->preview_pipe, DT_DEV_PIPE_ZOOMED);
  dt_geometry_chain_rebuild(dev);
}
 
void dt_dev_pixelpipe_update_zoom_main_real(dt_develop_t *dev)
{
  if(IS_NULL_PTR(dev) || !dev->gui_attached) return;
  /* Zoom/pan updates must run through the normal validity/ROI flow.
   * If a module left the main pipe in realtime mode, force it back to
   * standard mode here so zoom changes cannot get visually stuck on a
   * best-effort backbuffer policy. */
  dt_dev_pixelpipe_set_realtime(dev->pipe, FALSE);
  _change_pipe(dev->pipe, DT_DEV_PIPE_ZOOMED);
  dt_geometry_chain_rebuild(dev);
}
 
void dt_dev_pixelpipe_reset_all(dt_develop_t *dev)
{
  dt_dev_pixelpipe_cache_flush(-1);
  if(dt_gui_widgets_suppressed() || IS_NULL_PTR(dev) || !dev->gui_attached) return;
  dt_dev_pixelpipe_rebuild_all(dev);
}
 
void dt_dev_pixelpipe_change_zoom_main(dt_develop_t *dev)
{
  if (IS_NULL_PTR(dev) || !dev->gui_attached) return;
  /* Entering a zoom/pan change always exits realtime rendering policy.
   * Realtime is stroke-scoped and should never control darkroom navigation. */
  dt_dev_pixelpipe_set_realtime(dev->pipe, FALSE);
  // Slightly different logic: killswitch ASAP,
  // then redraw UI ASAP for feedback,
  // finally flag the pipe as dirty for later recompute.
  // Remember GUI responsiveness is paramount, since a laggy UI
  // will make user repeat their order for lack of feedback, 
  // meaning relaunching a pipe recompute, meaning working more
  // for the same contract.
  dt_atomic_set_int(&dev->pipe->shutdown, TRUE);
  dt_control_navigation_redraw();
  gtk_widget_queue_draw(dt_gui_center_widget());
  dt_dev_pixelpipe_update_zoom_main(dev);
  dt_dev_update_mouse_effect_radius(dev);
}
 
gboolean dt_dev_pixelpipe_activemodule_disables_currentmodule(struct dt_develop_t *dev, struct dt_iop_module_t *current_module)
{
  return (dev                  // don't segfault
          && dev->gui_attached // don't run on background/export pipes
          && dev->gui_module   // don't segfault
          && dev->gui_module != current_module 
          // current_module is not the active one (capturing edit mode)
          && dev->gui_module->operation_tags_filter() & current_module->operation_tags())
          // current_module does operation(s) that active module doesn't want
          && dt_iop_get_cache_bypass(dev->gui_module); 
          // cache bypass is our hint that the active module is in "editing" mode
}
 
 
void dt_dev_pixelpipe_get_roi_out(dt_dev_pixelpipe_t *pipe,
                                  const int width_in, const int height_in,
                                  int *width, int *height)
{
  dt_iop_roi_t roi_in = (dt_iop_roi_t){ 0, 0, width_in, height_in, 1.0 };
  dt_iop_roi_t roi_out = roi_in;
  gchar *pipe_name = NULL;
  if(dt_get_debug_flags() & DT_DEBUG_PIPE)
    pipe_name = _get_debug_pipe_name(pipe, pipe->dev);
 
  for(GList *nodes = g_list_first(pipe->nodes); nodes; nodes = g_list_next(nodes))
  {
    dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)nodes->data;
    dt_iop_module_t *module = piece->module;
 
    piece->buf_in = roi_in;
 
    // If in GUI and using a module that needs a full, undistorterted image,
    // we need to shutdown temporarily any module distorting the image.
    if(dt_dev_pixelpipe_activemodule_disables_currentmodule(pipe->dev, module))
      piece->enabled = FALSE;
 
    // If module is disabled, modify_roi_out() is a no-op
    if(piece->enabled)
      module->modify_roi_out(module, pipe, piece, &roi_out, &roi_in);
    else
      roi_out = roi_in;
 
    // Forward ROI planning answers "what output rectangle does this module
    // produce from the previous one ?". Logging the tuple here makes each
    // module-local geometry change visible on `-d pipe`.
    if(piece->enabled && (dt_get_debug_flags() & DT_DEBUG_PIPE))
      dt_print(DT_DEBUG_PIPE,
               "[roi-out] pipe=%-15s module=%-18s enabled=%d in =(x=%5d y=%5d w=%5d h=%5d scale=%2.2f)"
               " out=(x=%5d y=%5d w=%5d h=%5d scale=%2.2f)\n",
               pipe_name, module->op, piece->enabled,
               roi_in.x, roi_in.y, roi_in.width, roi_in.height, roi_in.scale,
               roi_out.x, roi_out.y, roi_out.width, roi_out.height, roi_out.scale);
 
    piece->buf_out = roi_out;
    roi_in = roi_out;
  }
 
  if(pipe_name) dt_free(pipe_name);
  *width = roi_out.width;
  *height = roi_out.height;
}
 
static uint64_t _default_pipe_hash(dt_dev_pixelpipe_t *pipe)
{
  // Start with a hash that is unique, image-wise.
  return dt_hash(5381, (const char *)&pipe->dev->image_storage.filename, DT_MAX_FILENAME_LEN);
}
 
/* Publish, on every enabled node, the cumulative hash of the PARAMETERS of the enabled modules
 * above it -- `dt_dev_pixelpipe_iop_t.upstream_hash`, which says what that field is for.
 *
 * It is its own pass, run at the top of ROI planning as well as from the global-hash pass,
 * because ROI planning is its first consumer and runs BEFORE the global hash is built: a
 * `modify_roi_in()` that memoises anything against the chain above it would otherwise find
 * either the value a commit invalidated or one describing a chain that has since changed.
 * Nothing here reads an ROI, so running it twice per plan costs a walk and answers the same. */
static void _publish_upstream_hashes(dt_dev_pixelpipe_t *pipe)
{
  uint64_t upstream = _default_pipe_hash(pipe);
 
  for(GList *node = g_list_first(pipe->nodes); node; node = g_list_next(node))
  {
    dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)node->data;
    if(IS_NULL_PTR(piece) || !piece->enabled) continue;
 
    piece->upstream_hash = upstream;
    upstream = dt_hash(upstream, (const char *)&piece->hash, sizeof(uint64_t));
 
    /* Whether the module currently focused in the GUI suppresses this one's distortion. It is
     * not in piece->hash -- it is GUI state, not history -- yet it decides whether this module
     * takes part in dt_dev_distort_transform_plus(), which is precisely what a consumer of this
     * hash back-transforms through. Focusing crop moves every drawn shape's box. */
    const int bypass_distort = dt_dev_pixelpipe_activemodule_disables_currentmodule(pipe->dev, piece->module);
    upstream = dt_hash(upstream, (const char *)&bypass_distort, sizeof(int));
  }
}
 
void dt_dev_pixelpipe_get_roi_in(dt_dev_pixelpipe_t *pipe, const struct dt_iop_roi_t roi_out)
{
  // while module->modify_roi_out describes how the current module will change the size of
  // the output buffer depending on its parameters (pretty intuitive),
  // module->modify_roi_in describes "how much material" the current module needs from the previous one,
  // because some modules (lens correction) need a padding on their input.
  // The tricky part is therefore that the effect of the current module->modify_roi_in() needs to be repercuted
  // upstream in the pipeline for proper pipeline cache invalidation, so we need to browse the pipeline
  // backwards.
 
  // This function does not support NULL pipes or ad-hoc temp nodes.
 
  // A modify_roi_in() that reads drawn shapes (retouch's source areas) resolves them in
  // pipe->forms, the refcounted snapshot the run renders from, never in the GUI-owned dev->forms,
  // which the GUI thread replaces and frees mid-edit. dt_dev_pixelpipe_process() takes its snapshot
  // before planning, so both see the same shapes; any other caller plans against a snapshot held
  // for the length of the walk, which it then owns and releases.
  const gboolean owns_forms = IS_NULL_PTR(pipe->forms);
  if(owns_forms) pipe->forms = dt_masks_snapshot_current_forms(pipe->dev, FALSE);
 
  // a modify_roi_in() memoising against the chain above it needs this before the walk starts
  _publish_upstream_hashes(pipe);
 
  dt_iop_roi_t roi_out_temp = roi_out;
  dt_iop_roi_t roi_in;
  gchar *pipe_name = NULL;
  if(dt_get_debug_flags() & DT_DEBUG_PIPE)
    pipe_name = _get_debug_pipe_name(pipe, pipe->dev);
  for(GList *nodes = g_list_last(pipe->nodes); nodes; nodes = g_list_previous(nodes))
  {
    dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)nodes->data;
    dt_iop_module_t *module = piece->module;
 
    piece->roi_out = roi_out_temp;
 
    // If in GUI and using a module that needs a full, undistorterted image,
    // we need to shutdown temporarily any module distorting the image.
    if(dt_dev_pixelpipe_activemodule_disables_currentmodule(pipe->dev, module))
      piece->enabled = FALSE;
 
    // If module is disabled, modify_roi_in() is a no-op
    if(piece->enabled)
      module->modify_roi_in(module, pipe, piece, &roi_out_temp, &roi_in);
    else
      roi_in = roi_out_temp;
 
    // Backward ROI planning answers "how much input rectangle does this
    // module need from upstream to deliver the requested downstream output ?".
    // Logging that request before and after modify_roi_in() makes ROI growth
    // and padding traceable module-by-module on `-d pipe`.
    if(piece->enabled && (dt_get_debug_flags() & DT_DEBUG_PIPE))
      dt_print(DT_DEBUG_PIPE,
               "[roi-in ] pipe=%-15s module=%-18s enabled=%d out=(x=%5d y=%5d w=%5d h=%5d scale=%2.2f)"
               " in=(x=%5d y=%5d w=%5d h=%5d scale=%2.2f)\n",
               pipe_name, module->op, piece->enabled,
               roi_out_temp.x, roi_out_temp.y, roi_out_temp.width, roi_out_temp.height, roi_out_temp.scale,
               roi_in.x, roi_in.y, roi_in.width, roi_in.height, roi_in.scale);
 
    piece->roi_in = roi_in;
    roi_out_temp = roi_in;
  }
 
  if(pipe_name) dt_free(pipe_name);
 
  if(owns_forms) dt_masks_forms_snapshot_release(&pipe->forms);
 
  /* ROI planning runs backwards, but rawprepare seals the effective Bayer/X-Trans phase only once
   * the real input crop is known. Forward that authored RAW descriptor now so the downstream RAW
   * modules process with the same CFA layout that rawprepare just computed for this run. */
  dt_iop_buffer_dsc_t upstream_dsc = pipe->dev->image_storage.dsc;
  for(GList *nodes = g_list_first(pipe->nodes); nodes; nodes = g_list_next(nodes))
  {
    dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)nodes->data;
 
    if(piece->dsc_in.cst == IOP_CS_RAW && piece->dsc_in.channels == 1)
    {
      piece->dsc_in.filters = upstream_dsc.filters;
      memcpy(piece->dsc_in.xtrans, upstream_dsc.xtrans, sizeof(piece->dsc_in.xtrans));
    }
 
    if(piece->dsc_out.cst == IOP_CS_RAW && piece->dsc_out.channels == 1
       && (!piece->enabled || strcmp(piece->module->op, "rawprepare")))
    {
      piece->dsc_out.filters = piece->dsc_in.filters;
      memcpy(piece->dsc_out.xtrans, piece->dsc_in.xtrans, sizeof(piece->dsc_out.xtrans));
    }
 
    upstream_dsc = piece->dsc_out;
  }
 
}
 
 
uint64_t dt_dev_pixelpipe_node_hash(dt_dev_pixelpipe_t *pipe, const dt_dev_pixelpipe_iop_t *piece, 
                                    const dt_iop_roi_t roi_out, const int pos)
{
  // to be called at runtime, not at pipe init.
 
  // Only at the first step of pipe, we don't have a module because we init the base buffer.
  if(!IS_NULL_PTR(piece))
    return piece->global_hash;
  else
  {
    // This is used for the first step of the pipe, before modules, when initing base buffer
    // We need to take care of the ROI manually
    uint64_t hash = _default_pipe_hash(pipe);
    hash = dt_hash(hash, (const char *)&roi_out, sizeof(dt_iop_roi_t));
    return dt_hash(hash, (const char *)&pos, sizeof(int));
  }
}
 
const dt_dev_pixelpipe_iop_t *dt_dev_pixelpipe_get_module_piece(const dt_dev_pixelpipe_t *pipe,
                                                                const dt_iop_module_t *module)
{
  if(IS_NULL_PTR(pipe) || IS_NULL_PTR(module)) return NULL;
 
  for(GList *node = g_list_first(pipe->nodes); node; node = g_list_next(node))
  {
    dt_dev_pixelpipe_iop_t *const piece = node->data;
    if(piece && piece->enabled && piece->module == module)
      return piece;
  }
 
  return NULL;
}
 
const dt_dev_pixelpipe_iop_t *dt_dev_pixelpipe_get_prev_enabled_piece(const dt_dev_pixelpipe_t *pipe,
                                                                      const dt_dev_pixelpipe_iop_t *piece)
{
  if(IS_NULL_PTR(pipe) || IS_NULL_PTR(piece)) return NULL;
 
  GList *node = g_list_find(pipe->nodes, (gpointer)piece);
  if(IS_NULL_PTR(node)) return NULL;
 
  for(node = g_list_previous(node); node; node = g_list_previous(node))
  {
    dt_dev_pixelpipe_iop_t *const previous = node->data;
    if(previous && previous->enabled)
      return previous;
  }
 
  return NULL;
}
 
static gboolean _peek_gui(dt_dev_pixelpipe_t *pipe, const dt_dev_pixelpipe_iop_t *piece,
                          void **data, dt_pixel_cache_entry_t **cache_entry,
                          dt_dev_pixelpipe_cache_wait_t *wait,
                          dt_dev_pixelpipe_cache_ready_callback_t restart,
                          gpointer restart_data, const gboolean retain)
{
  if(!IS_NULL_PTR(data)) *data = NULL;
  if(!IS_NULL_PTR(cache_entry)) *cache_entry = NULL;
  if(IS_NULL_PTR(pipe)) return FALSE;
 
  // Module-output cache requests are not satisfiable when the target piece
  // itself bypasses cache retention. Re-queueing those from GUI redraws would
  // keep transient edit modes in a self-feeding recompute loop.
  // Upstream targets (for example color-picker input sampling) stay allowed even if a
  // downstream piece enabled bypass mode.
  if(!IS_NULL_PTR(piece)
     && (dt_dev_pixelpipe_get_realtime(pipe) || pipe->no_cache || piece->bypass_cache))
    return FALSE;
 
  const uint64_t hash = !IS_NULL_PTR(piece) ? piece->global_hash : dt_dev_pixelpipe_get_hash(pipe);
 
  // For the final backbuffer (piece == NULL), GUI consumers display the last *published* frame,
  // identified by pipe->backbuf.hash. The pipeline plans the next frame ahead of publishing it, so
  // pipe->hash (the planned final hash) runs ahead of the backbuffer while a recompute is in flight.
  // This is the normal steady state of realtime drawing: every heartbeat plans a new frame. Peeking
  // the planned hash would then miss the perfectly valid published frame, the darkroom main-surface
  // lock would fail, and the view would drop to the paused preview pipe (which lacks the in-progress
  // stroke) — the flicker between "drawing applied" and "original". So look up the published backbuf
  // hash for display, and keep the planned hash only to drive recompute on a genuine miss below.
  uint64_t display_hash = hash;
  if(IS_NULL_PTR(piece))
  {
    const uint64_t backbuf_hash = dt_dev_backbuf_get_hash(&pipe->backbuf);
    if(backbuf_hash != DT_PIXELPIPE_CACHE_HASH_INVALID) display_hash = backbuf_hash;
  }
 
  void *buffer = NULL;
  dt_pixel_cache_entry_t *entry = NULL;
  // GUI consumers run on the CPU and never own the OpenCL device lock, so we pass preferred_devid = -1:
  // dt_dev_pixelpipe_cache_peek() then returns host-resident cachelines directly but refuses to
  // materialize device-only ones from the GPU (which would enqueue hidden GPU work from the GUI thread,
  // racing whichever pipeline thread currently owns the device — the clReleaseEvent crash). A device-only
  // entry is reported as a miss, so the request below waits for the pipeline to publish a host copy
  // (modules whose output the GUI samples, e.g. initialscale, already cache to RAM).
  //
  // `retain` picks between the two ownership models a GUI consumer can have on a cacheline, and
  // they are not interchangeable. A consumer that merely BORROWS the currently published
  // backbuffer (the darkroom surface, the navigation thumbnail, the scopes) is covered by the
  // keepalive reference its publisher holds, and must not take one of its own. A consumer that
  // samples an INTERMEDIATE module cacheline (color picker, module histograms, autoset,
  // colorequal) has no such cover: those entries sit at refcount 0 between renders and the
  // pipeline may evict one at any moment. Looking one up and taking the reference afterwards
  // leaves a window in which it is freed under the caller, so that acquisition happens under one
  // hold of the cache lock -- the hazard `dt_dev_pixelpipe_process_rec()` already avoids for its
  // own exact-hit lookups, for exactly the same reason.
  const gboolean got = display_hash != DT_PIXELPIPE_CACHE_HASH_INVALID
                       && (retain ? dt_dev_pixelpipe_cache_ref_host_entry_by_hash(display_hash, &buffer, &entry)
                                  : dt_dev_pixelpipe_cache_peek(display_hash, &buffer, &entry, -1, NULL));
  if(got && !IS_NULL_PTR(buffer) && !IS_NULL_PTR(entry))
  {
    dt_pixelpipe_cache_wait_count_immediate_hit();
    dt_dev_pixelpipe_cache_wait_cleanup(wait, "peek-gui-immediate-hit");
    if(!IS_NULL_PTR(data)) *data = buffer;
    if(!IS_NULL_PTR(cache_entry)) *cache_entry = entry;
    return TRUE;
  }
 
  /* A retained entry the caller cannot be handed back (it asked for neither the data nor the
   * entry) would leak its reference: nobody would ever release it. */
  if(retain && got && !IS_NULL_PTR(entry))
  {
    dt_dev_pixelpipe_cache_ref_count_entry(FALSE, entry);
    entry = NULL;
    buffer = NULL;
  }
 
  dt_pixelpipe_cache_wait_count_miss();
 
  gboolean request_cacheline = TRUE;
  if(!IS_NULL_PTR(wait) && !IS_NULL_PTR(restart) && hash != DT_PIXELPIPE_CACHE_HASH_INVALID)
  {
    const gboolean changed_target = !wait->connected
                                    || wait->pipe != pipe
                                    || wait->module != (!IS_NULL_PTR(piece) ? piece->module : NULL)
                                    || wait->hash != hash
                                    || wait->restart != restart;
    if(changed_target)
    {
      gboolean activate_wait_cursor = FALSE;
      dt_dev_pixelpipe_cache_wait_cleanup(wait, "peek-gui-target-changed");
      wait->pipe = pipe;
      wait->module = !IS_NULL_PTR(piece) ? piece->module : NULL;
 
      // Copy the labels now, while both objects are certainly alive. The queue never reads
      // through the two identity pointers above; everything it reports about a waiter comes
      // from here.
      const dt_iop_module_t *target_module = !IS_NULL_PTR(piece) ? piece->module : NULL;
      if(!IS_NULL_PTR(target_module))
      {
        g_strlcpy(wait->module_op, target_module->op, sizeof(wait->module_op));
        wait->module_multi_priority = target_module->multi_priority;
      }
      else
      {
        wait->module_op[0] = '\0';
        wait->module_multi_priority = 0;
      }
      wait->pipe_type = (int)pipe->type;
      wait->pipe_imgid = pipe->imgid;
 
      wait->hash = hash;
      // Record the producing node identity so CACHELINE_READY can serve this waiter by
      // its target module even if the exact awaited hash drifts before publish (§8). A
      // backbuf target (piece == NULL) has no single producing node, so it keeps to the
      // exact-hash match only.
      wait->target_node_key = !IS_NULL_PTR(piece) && !IS_NULL_PTR(piece->module)
                                  ? dt_supervisor_node_key(pipe->type, piece->module->op,
                                                           piece->module->multi_priority)
                                  : DT_PIXELPIPE_CACHE_HASH_INVALID;
      wait->restart = restart;
      wait->user_data = restart_data;
      if(IS_NULL_PTR(wait->owner_tag))
        wait->owner_tag = !IS_NULL_PTR(piece) && !IS_NULL_PTR(piece->module) ? piece->module->op : "gui-backbuf";
      if(IS_NULL_PTR(wait->owner_object))
        wait->owner_object = restart_data;
      wait->connected = TRUE;
 
      // The queue assigns the request id and reports whether it just went from empty to
      // non-empty; the subscription and the cursor are ours, and both hang off exactly that
      // transition -- which is why they were one flag each in the old manager.
      const gboolean queue_became_busy = dt_pixelpipe_cache_wait_enqueue(wait);
      if(queue_became_busy)
      {
        if(!_cache_wait_connected)
        {
          DT_DEBUG_CONTROL_SIGNAL_CONNECT(dt_control_signal_get_global(), DT_SIGNAL_CACHELINE_READY,
                                          G_CALLBACK(_dt_dev_pixelpipe_cache_wait_ready_callback), NULL);
          _cache_wait_connected = TRUE;
        }
        if(!_cache_wait_cursor_active)
        {
          _cache_wait_cursor_active = TRUE;
          activate_wait_cursor = TRUE;
        }
      }
      if(activate_wait_cursor)
        g_main_context_invoke(NULL, _cache_wait_cursor_progress, NULL);
 
      dt_print(DT_DEBUG_PIPECACHE,
               "[cache-wait] queued id=%" PRIu64 " owner=%s hash=%" PRIu64 " target=%s\n",
               wait->request_id,
               !IS_NULL_PTR(wait->owner_tag) ? wait->owner_tag : "(unknown)",
               wait->hash,
               !IS_NULL_PTR(wait->module) ? wait->module_op : "backbuf");
 
      if(dt_supervisor_active())
        dt_supervisor_cache_wait(DT_SV_CREATE, wait->request_id, wait->hash, wait->owner_tag,
                                 !IS_NULL_PTR(wait->module) ? wait->module_op : NULL,
                                 wait->module_multi_priority,
                                 (int)pipe->type, pipe->imgid, TRUE, NULL);
    }
    else
    {
      /* The GUI already waits for this exact cacheline. Re-emitting CACHE_REQUEST from
       * each expose keeps retrying an unsatisfied target forever when the pipeline cannot
       * publish it, for example after an OpenCL memory pre-check failure on very large images. */
      request_cacheline = FALSE;
 
      /* A deduped re-poll: the consumer asked again for a wait already in flight, and no
       * new CACHE_REQUEST was emitted. A run of these with no matching serve (and no
       * cacheline ever published under wait->hash) is the "never processed, never
       * finishes" signature. */
      if(dt_supervisor_active())
        dt_supervisor_cache_wait(DT_SV_READ, wait->request_id, wait->hash, wait->owner_tag,
                                 !IS_NULL_PTR(wait->module) ? wait->module_op : NULL,
                                 wait->module_multi_priority,
                                 (int)pipe->type, pipe->imgid, FALSE, "dedup-poll");
    }
  }
 
  if(request_cacheline)
  {
    dt_dev_pixelpipe_set_cache_request(pipe,
                                       !IS_NULL_PTR(piece) ? DT_DEV_PIXELPIPE_CACHE_REQUEST_MODULE
                                                           : DT_DEV_PIXELPIPE_CACHE_REQUEST_BACKBUF,
                                       !IS_NULL_PTR(piece) ? piece->module : NULL);
    dt_dev_pixelpipe_or_changed(pipe, DT_DEV_PIPE_CACHE_REQUEST);
 
    dt_print(DT_DEBUG_DEV, "[pixelpipe/gui] request host cache pipe=%s target=%s hash=%" PRIu64 "\n",
             dt_pixelpipe_get_pipe_name(pipe->type),
             !IS_NULL_PTR(piece) && !IS_NULL_PTR(piece->module) ? piece->module->op : "backbuf", hash);
  }
 
  return FALSE;
}
 
gboolean dt_dev_pixelpipe_cache_peek_gui(dt_dev_pixelpipe_t *pipe, const dt_dev_pixelpipe_iop_t *piece,
                                         void **data, dt_pixel_cache_entry_t **cache_entry,
                                         dt_dev_pixelpipe_cache_wait_t *wait,
                                         dt_dev_pixelpipe_cache_ready_callback_t restart,
                                         gpointer restart_data)
{
  return _peek_gui(pipe, piece, data, cache_entry, wait, restart, restart_data, FALSE);
}
 
gboolean dt_dev_pixelpipe_cache_peek_gui_retained(dt_dev_pixelpipe_t *pipe, const dt_dev_pixelpipe_iop_t *piece,
                                                  void **data, dt_pixel_cache_entry_t **cache_entry,
                                                  dt_dev_pixelpipe_cache_wait_t *wait,
                                                  dt_dev_pixelpipe_cache_ready_callback_t restart,
                                                  gpointer restart_data)
{
  return _peek_gui(pipe, piece, data, cache_entry, wait, restart, restart_data, TRUE);
}
 
 
static void _dt_dev_pixelpipe_cache_wait_ready_callback(gpointer instance, const guint64 hash,
                                                        const guint64 producer_node_key,
                                                        gpointer user_data)
{
  gboolean restore_wait_cursor = FALSE;
  gboolean drained = FALSE;
 
  // The queue decides who this publication satisfies and hands them back; running their
  // callbacks is ours, and stays OUTSIDE any queue lock, because a restart handler queues
  // redraws and asks for new cachelines.
  GList *to_restart = dt_pixelpipe_cache_wait_take_matching(hash, producer_node_key, &drained);
 
  if(drained && _cache_wait_connected)
  {
    DT_DEBUG_CONTROL_SIGNAL_DISCONNECT(dt_control_signal_get_global(),
                                       G_CALLBACK(_dt_dev_pixelpipe_cache_wait_ready_callback), NULL);
    _cache_wait_connected = FALSE;
  }
  if(drained && _cache_wait_cursor_active)
  {
    _cache_wait_cursor_active = FALSE;
    restore_wait_cursor = TRUE;
  }
  if(restore_wait_cursor)
    g_main_context_invoke(NULL, _cache_wait_cursor_restore, NULL);
 
  for(GList *iter = to_restart; iter; iter = g_list_next(iter))
  {
    dt_dev_pixelpipe_cache_wait_t *wait = iter->data;
    const dt_dev_pixelpipe_cache_ready_callback_t restart = wait->restart;
    gpointer restart_data = wait->user_data;
    // A drift serve: the awaited hash never published, but the target module did
    // (matched via producer_node_key). Record it as such so the supervisor timeline
    // shows the recovery instead of a phantom exact hit.
    const gboolean drift_serve = wait->hash != hash;
 
    dt_print(DT_DEBUG_PIPECACHE,
             "[cache-wait] served id=%" PRIu64 " owner=%s awaited=%" PRIu64 " published=%" PRIu64
             " target=%s%s\n",
             wait->request_id,
             !IS_NULL_PTR(wait->owner_tag) ? wait->owner_tag : "(unknown)",
             wait->hash, hash,
             !IS_NULL_PTR(wait->module) ? wait->module_op : "backbuf",
             drift_serve ? " (drift: node-key)" : "");
 
    if(dt_supervisor_active())
      dt_supervisor_cache_wait(DT_SV_DELETE, wait->request_id, wait->hash, wait->owner_tag,
                               !IS_NULL_PTR(wait->module) ? wait->module_op : NULL,
                               wait->module_multi_priority,
                               !IS_NULL_PTR(wait->pipe) ? (int)wait->pipe_type : -1,
                               !IS_NULL_PTR(wait->pipe) ? wait->pipe_imgid : -1, FALSE,
                               drift_serve ? "served (drift: node-key)" : "served");
 
    wait->pipe = NULL;
    wait->module = NULL;
    wait->hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    wait->target_node_key = DT_PIXELPIPE_CACHE_HASH_INVALID;
    wait->restart = NULL;
    wait->user_data = NULL;
    wait->request_id = 0;
 
    if(!IS_NULL_PTR(restart)) restart(restart_data);
  }
  g_list_free(to_restart);
}
 
void dt_dev_pixelpipe_cache_wait_cleanup(dt_dev_pixelpipe_cache_wait_t *wait, const char *reason)
{
  if(IS_NULL_PTR(wait) || !wait->connected) return;
  gboolean restore_wait_cursor = FALSE;
  const uint64_t request_id = wait->request_id;
  const uint64_t hash = wait->hash;
  const char *owner_tag = wait->owner_tag;
  // Snapshot the identity and its labels together, before the reset below clears them. Nothing
  // here dereferences the module or the pipe: the labels were copied when the wait was queued,
  // precisely because either object can be gone by the time a wait is cancelled.
  const gboolean had_module = !IS_NULL_PTR(wait->module);
  const gboolean had_pipe = !IS_NULL_PTR(wait->pipe);
  const char *module_op = had_module ? wait->module_op : NULL;
  const int module_multi_priority = wait->module_multi_priority;
  const int cancel_pipe_type = wait->pipe_type;
  const int32_t cancel_pipe_imgid = wait->pipe_imgid;
  const char *cancel_reason = !IS_NULL_PTR(reason) ? reason : "unspecified";
 
  gboolean drained = FALSE;
  dt_pixelpipe_cache_wait_cancel(wait, &drained);
 
  if(drained && _cache_wait_connected)
  {
    DT_DEBUG_CONTROL_SIGNAL_DISCONNECT(dt_control_signal_get_global(),
                                       G_CALLBACK(_dt_dev_pixelpipe_cache_wait_ready_callback), NULL);
    _cache_wait_connected = FALSE;
  }
  if(drained && _cache_wait_cursor_active)
  {
    _cache_wait_cursor_active = FALSE;
    restore_wait_cursor = TRUE;
  }
  if(restore_wait_cursor)
    g_main_context_invoke(NULL, _cache_wait_cursor_restore, NULL);
 
  // -1: the queue owns the enqueue timestamp, and a cancellation is not worth an extra query
  // into it. The dump reports real ages for everything still pending.
  const int64_t age_ms = -1;
  dt_print(DT_DEBUG_PIPECACHE,
           "[cache-wait] cancelled id=%" PRIu64 " owner=%s hash=%" PRIu64
           " target=%s age_ms=%" PRId64 " reason=%s\n",
           request_id,
           !IS_NULL_PTR(owner_tag) ? owner_tag : "(unknown)",
           hash,
           had_module ? module_op : "backbuf",
           age_ms,
           cancel_reason);
 
  if(dt_supervisor_active())
  {
    char note[64];
    g_snprintf(note, sizeof(note), "cancelled: %s", cancel_reason);
    dt_supervisor_cache_wait(DT_SV_DELETE, request_id, hash, owner_tag,
                             module_op, module_multi_priority,
                             had_pipe ? cancel_pipe_type : -1,
                             had_pipe ? cancel_pipe_imgid : -1, FALSE, note);
  }
 
  wait->pipe = NULL;
  wait->module = NULL;
  wait->hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
  wait->target_node_key = DT_PIXELPIPE_CACHE_HASH_INVALID;
  wait->restart = NULL;
  wait->user_data = NULL;
  wait->request_id = 0;
  wait->connected = FALSE;
}
 
void dt_dev_pixelpipe_cache_wait_set_owner(dt_dev_pixelpipe_cache_wait_t *wait,
                                           const char *owner_tag,
                                           gpointer owner_object)
{
  if(IS_NULL_PTR(wait)) return;
  wait->owner_tag = owner_tag;
  wait->owner_object = owner_object;
}
 
/* Establish the *input* side of a piece's buffer contract from the upstream descriptor by
 * asking the module's input_format(). This does NOT decide compatibility or finalize the
 * output: the single authoritative pass dt_dev_pixelpipe_propagate_formats() owns the mismatch/auto-disable
 * decision so it is taken once, on the fully-committed and consistently-threaded chain, never
 * on the stale partial state a synch_top / realtime edit can leave behind (issue #733).
 *
 * It is split out from that pass because commit_params() of a few modules (exposure, highlights,
 * invert, temperature) reads piece->dsc_in (filters, processed_maximum), so the commit loop must
 * set dsc_in before committing. */
// Short colorspace name for the [dsc] format-propagation debug log (-d pipe). Knowing the cst of
// each node's input/output is essential to spot when the pixelpipe's automatic RGB<->Lab conversion
// should fire: a Lab-domain module whose dsc_in.cst is not "lab" will silently consume RGB.
static const char *_dsc_cst_name(const int cst)
{
  switch(cst)
  {
    case IOP_CS_RAW:         return "raw";
    case IOP_CS_LAB:         return "lab";
    case IOP_CS_RGB:         return "rgb";
    case IOP_CS_RGB_DISPLAY: return "display-rgb";
    case IOP_CS_LCH:         return "lch";
    case IOP_CS_HSL:         return "hsl";
    case IOP_CS_JZCZHZ:      return "jzczhz";
    case IOP_CS_NONE:        return "none";
    default:                 return "?";
  }
}
 
static void _prepare_piece_input_contract(dt_dev_pixelpipe_t *pipe, dt_dev_pixelpipe_iop_t *piece,
                                          const dt_iop_buffer_dsc_t *upstream_dsc)
{
  piece->dsc_in = *upstream_dsc;
  piece->dsc_out = *upstream_dsc;
  dt_iop_buffer_dsc_update_bpp(&piece->dsc_in);
  dt_iop_buffer_dsc_update_bpp(&piece->dsc_out);
 
  /* Disabled modules are strict pass-through stages. Their advertised contracts must
   * not rewrite the upstream descriptor, otherwise a disabled RGB-only module can make
   * downstream RAW stages such as demosaic believe the stream was already converted. */
  if(!piece->enabled) return;
 
  piece->module->input_format(piece->module, pipe, piece, &piece->dsc_in);
  dt_iop_buffer_dsc_update_bpp(&piece->dsc_in);
  piece->dsc_out = piece->dsc_in;
  dt_iop_buffer_dsc_update_bpp(&piece->dsc_out);
}
 
static void _commit_piece_contract(dt_dev_pixelpipe_t *pipe, dt_dev_pixelpipe_iop_t *piece,
                                   dt_iop_params_t *params, dt_develop_blend_params_t *blend_params,
                                   dt_iop_buffer_dsc_t *upstream_dsc)
{
  const dt_iop_buffer_dsc_t actual_input_dsc = *upstream_dsc;
 
  // Set dsc_in before committing (commit_params() of some modules reads it). Compatibility and
  // the final output descriptor are settled later by dt_dev_pixelpipe_propagate_formats(), so this loop
  // never auto-disables a module on a possibly-stale upstream descriptor.
  _prepare_piece_input_contract(pipe, piece, upstream_dsc);
 
  // This should run even if the module is disabled because
  // some modules with no history self-enable based on runtime context
  dt_iop_commit_params(piece->module, params, blend_params, pipe, piece);
 
  if(piece->enabled)
  {
    piece->module->output_format(piece->module, pipe, piece, &piece->dsc_out);
    dt_iop_buffer_dsc_update_bpp(&piece->dsc_out);
  }
  else
  {
    piece->dsc_in = actual_input_dsc;
    piece->dsc_out = actual_input_dsc;
    dt_iop_buffer_dsc_update_bpp(&piece->dsc_in);
    dt_iop_buffer_dsc_update_bpp(&piece->dsc_out);
  }
 
  *upstream_dsc = piece->dsc_out;
}
 
/* Direction-independent forward format pass.
 *
 * The buffer-format contract (channels / datatype / colorspace / CFA presence flowing from one
 * module to the next) is conceptually independent of ROI planning, which runs in both
 * directions (end->start for a target size, start->end for the native size). Deriving the
 * contract inside the history-sync commit loop made it sensitive to partial syncs
 * (synch_top / realtime top edits): a downstream module could read a stale upstream descriptor
 * and get wrongly disabled for an "unexpected input buffer format" (issue #733). Worse, the
 * auto-disable is one-way, so a later pass could not undo a false positive.
 *
 * This single forward pass re-threads the whole chain from the input image descriptor after
 * params have been committed, and is the *only* place that disables a module for a genuinely
 * incompatible input. Disabling here is safe because the chain is consistent and fully threaded
 * from pipe->dev->image_storage.dsc. Only the first stage (basebuffer) reads the input image
 * type; every later node derives its contract solely from its upstream piece. The lone
 * ROI-dependent refinement, rawprepare's CFA phase shift, is finalized later in modify_roi_*().
 *
 * It is deliberately NON-destructive for compatible enabled modules: it verifies the input
 * contract and re-threads dsc_in, but keeps the dsc_out that commit_params() produced. dsc_out
 * carries runtime fields (processed_maximum, rawprepare black/white, temperature coeffs, CFA
 * phase) that input/output_format cannot reconstruct, so recomputing them here would wipe the
 * tonal scaling and render images black/white. */
void dt_dev_pixelpipe_propagate_formats(dt_dev_pixelpipe_t *pipe)
{
  if(IS_NULL_PTR(pipe)) return;
 
  dt_iop_buffer_dsc_t upstream_dsc = pipe->dev->image_storage.dsc;
  gchar *pipe_name = (dt_get_debug_flags() & DT_DEBUG_PIPE) ? _get_debug_pipe_name(pipe, NULL) : NULL;
 
  for(GList *nodes = g_list_first(pipe->nodes); nodes; nodes = g_list_next(nodes))
  {
    dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)nodes->data;
    if(IS_NULL_PTR(piece) || IS_NULL_PTR(piece->module)) continue;
 
    const dt_iop_buffer_dsc_t actual_input_dsc = upstream_dsc;
 
    if(!piece->enabled)
    {
      // Disabled modules are strict pass-through stages.
      piece->dsc_in = actual_input_dsc;
      piece->dsc_out = actual_input_dsc;
      dt_iop_buffer_dsc_update_bpp(&piece->dsc_in);
      dt_iop_buffer_dsc_update_bpp(&piece->dsc_out);
    }
    else
    {
      // Ask the module what input it expects, into a scratch descriptor. We must NOT recompute
      // piece->dsc_out from input/output_format here: commit_params() already produced dsc_out
      // with runtime fields that those methods cannot reconstruct (processed_maximum, rawprepare
      // black/white, temperature coeffs, CFA phase). Recomputing would reset processed_maximum to
      // the input image's value and blow up downstream tone handling (black/white renders).
      dt_iop_buffer_dsc_t declared_in = actual_input_dsc;
      dt_iop_buffer_dsc_update_bpp(&declared_in);
      piece->module->input_format(piece->module, pipe, piece, &declared_in);
      dt_iop_buffer_dsc_update_bpp(&declared_in);
 
      // A module whose declared input does not match what the previous stage actually publishes
      // cannot run: disable it (in the pipe only; history is untouched) and turn it into a
      // pass-through so the contract keeps flowing to the next stage.
      const gboolean input_mismatch
          = (declared_in.bpp != actual_input_dsc.bpp
             || declared_in.channels != actual_input_dsc.channels
             || declared_in.filters != actual_input_dsc.filters);
 
      if(input_mismatch)
      {
        dt_control_log(_("disabled module `%s`: unexpected input buffer format"),
                       piece->module->name());
        dt_print(DT_DEBUG_PIPE,
                 "[pixelpipe] disabling module %s because input format expects %" G_GSIZE_FORMAT
                 " B/px, %u channels, filters %u but upstream publishes %" G_GSIZE_FORMAT
                 " B/px, %u channels, filters %u\n",
                 piece->module->op, declared_in.bpp, declared_in.channels, declared_in.filters,
                 actual_input_dsc.bpp, actual_input_dsc.channels, actual_input_dsc.filters);
 
        piece->enabled = FALSE;
        piece->hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
        piece->blendop_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
        piece->global_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
        piece->global_mask_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
        piece->upstream_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
        piece->dsc_in = actual_input_dsc;
        piece->dsc_out = actual_input_dsc;
        dt_iop_buffer_dsc_update_bpp(&piece->dsc_in);
        dt_iop_buffer_dsc_update_bpp(&piece->dsc_out);
      }
      else
      {
        // Input is compatible: publish the module's DECLARED input descriptor. `declared_in` was
        // seeded from the upstream descriptor and then run through input_format(), so it already
        // carries the upstream runtime fields (processed_maximum, rawprepare, temperature, CFA
        // phase) AND the colorspace/channel layout the module actually consumes.
        //
        // Critically, we must NOT fall back to `actual_input_dsc` here: that would reset dsc_in.cst
        // to the upstream colorspace and make it equal to the buffer's cst, so the pixelpipe's
        // automatic colorspace conversion (pixelpipe_cpu.c / pixelpipe_gpu.c) would believe no
        // conversion is needed. Lab-domain modules (old color balance, color checker, atrous, ...)
        // inserted after an RGB stage would then receive RGB data interpreted as Lab and render
        // garbled/solid colors. The full-resync path keeps dsc_in from input_format() for the same
        // reason; this incremental (synch_top) path must match it.
        piece->dsc_in = declared_in;
        dt_iop_buffer_dsc_update_bpp(&piece->dsc_in);
      }
    }
 
    if(pipe_name)
      dt_print(DT_DEBUG_PIPE,
               "[dsc] pipe=%s module=%s enabled=%d in=(cst=%s ch=%i bpp=%" G_GSIZE_FORMAT
               " filters=%u) out=(cst=%s ch=%i bpp=%" G_GSIZE_FORMAT " filters=%u)\n",
               pipe_name, piece->module->op, piece->enabled,
               _dsc_cst_name(piece->dsc_in.cst), piece->dsc_in.channels, piece->dsc_in.bpp, piece->dsc_in.filters,
               _dsc_cst_name(piece->dsc_out.cst), piece->dsc_out.channels, piece->dsc_out.bpp, piece->dsc_out.filters);
 
    upstream_dsc = piece->dsc_out;
  }
 
  dt_free(pipe_name);
}
 
/* `history_list` is the snapshot's list (dt_dev_history_snapshot_t::items), never dev->history:
 * this runs OUTSIDE history_mutex, and the snapshot's references are what keep every item it
 * walks alive and unmodified (see dt_dev_history_snapshot_take). */
static void _sync_pipe_nodes_from_history(dt_dev_pixelpipe_t *pipe, GList *history_list,
                                          const uint32_t history_end, const char *debug_label)
{
  dt_iop_buffer_dsc_t upstream_dsc = pipe->dev->image_storage.dsc;
  const gboolean previous_want_detail_mask = (pipe->want_detail_mask != DT_DEV_DETAIL_MASK_NONE);
 
  for(GList *nodes = g_list_first(pipe->nodes); nodes; nodes = g_list_next(nodes))
  {
    dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)nodes->data;
    if(IS_NULL_PTR(piece)) continue;
 
    piece->hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    piece->blendop_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    piece->global_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    piece->global_mask_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    piece->upstream_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    piece->enabled = piece->module->default_enabled;
    piece->detail_mask = FALSE;
 
    dt_iop_params_t *params = piece->module->default_params;
    dt_develop_blend_params_t *blend_params = piece->module->default_blendop_params;
    uint64_t history_param_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    gboolean found_history = FALSE;
 
    for(GList *history = g_list_nth(history_list, history_end - 1);
        history;
        history = g_list_previous(history))
    {
      dt_dev_history_item_t *hist = (dt_dev_history_item_t *)history->data;
      if(piece->module == hist->module)
      {
        piece->enabled = hist->enabled;
        params = hist->params;
        blend_params = hist->blend_params;
        history_param_hash = hist->hash; // the history entry key (module->hash)
        found_history = TRUE;
        break;
      }
    }
 
    piece->detail_mask = blend_params && blend_params->details != 0.0f;
    if(!strcmp(piece->module->op, "detailmask"))
      piece->enabled = (pipe->want_detail_mask == DT_DEV_DETAIL_MASK_ENABLED);
    _commit_piece_contract(pipe, piece, params, blend_params, &upstream_dsc);
 
    // Tie this node to the history item it was just synchronized with, so the
    // cachelines it produces resolve to that history state through the node.
    // Use the history entry key (module->hash), NOT piece->hash: the latter folds
    // in runtime_data_hash() for some modules and then no longer matches history.
    if(dt_supervisor_active() && found_history)
      dt_supervisor_node(DT_SV_UPDATE,
                         dt_supervisor_node_key(pipe->type, piece->module->op, piece->module->multi_priority),
                         history_param_hash, DT_PIXELPIPE_CACHE_HASH_INVALID, piece->module->op,
                         piece->module->multi_priority, piece->module->iop_order, pipe->type, pipe->imgid);
 
    if(!found_history)
      dt_print(DT_DEBUG_PARAMS, "[pixelpipe] info: committed default params for %s (%s) in pipe %s\n",
               piece->module->op, piece->module->multi_name, debug_label);
  }
 
  _refresh_pipe_detail_mask_state(pipe);
  if(previous_want_detail_mask != (pipe->want_detail_mask != DT_DEV_DETAIL_MASK_NONE))
  {
    GList *detailmask_node = _find_detailmask_node(pipe);
    if(detailmask_node)
      _sync_pipe_nodes_from_history_from_node(pipe, history_list, history_end, detailmask_node, debug_label);
  }
}
 
static void _sync_pipe_nodes_from_history_from_node(dt_dev_pixelpipe_t *pipe, GList *history_list,
                                                    const uint32_t history_end, GList *start_node,
                                                    const char *debug_label)
{
  if(IS_NULL_PTR(pipe) || IS_NULL_PTR(start_node)) return;
 
  dt_iop_buffer_dsc_t upstream_dsc = pipe->dev->image_storage.dsc;
  const gboolean previous_want_detail_mask = (pipe->want_detail_mask != DT_DEV_DETAIL_MASK_NONE);
  for(GList *node = g_list_first(pipe->nodes); node && node != start_node; node = g_list_next(node))
  {
    dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)node->data;
    if(IS_NULL_PTR(piece)) continue;
 
    upstream_dsc = piece->dsc_out;
  }
 
  for(GList *nodes = start_node; nodes; nodes = g_list_next(nodes))
  {
    dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)nodes->data;
    if(IS_NULL_PTR(piece)) continue;
 
    piece->hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    piece->blendop_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    piece->global_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    piece->global_mask_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    piece->upstream_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
 
    piece->enabled = piece->module->default_enabled;
    piece->detail_mask = FALSE;
 
    dt_iop_params_t *params = piece->module->default_params;
    dt_develop_blend_params_t *blend_params = piece->module->default_blendop_params;
    uint64_t history_param_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    gboolean found_history = FALSE;
 
    for(GList *history = g_list_nth(history_list, history_end - 1);
        history;
        history = g_list_previous(history))
    {
      dt_dev_history_item_t *hist = (dt_dev_history_item_t *)history->data;
      if(piece->module == hist->module)
      {
        piece->enabled = hist->enabled;
        params = hist->params;
        blend_params = hist->blend_params;
        history_param_hash = hist->hash; // the history entry key (module->hash)
        found_history = TRUE;
        break;
      }
    }
 
    piece->detail_mask = blend_params && blend_params->details != 0.0f;
    if(!strcmp(piece->module->op, "detailmask"))
      piece->enabled = (pipe->want_detail_mask == DT_DEV_DETAIL_MASK_ENABLED);
    _commit_piece_contract(pipe, piece, params, blend_params, &upstream_dsc);
 
    // Tie this node to the history item it was just synchronized with, so the
    // cachelines it produces resolve to that history state through the node.
    // Use the history entry key (module->hash), NOT piece->hash: the latter folds
    // in runtime_data_hash() for some modules and then no longer matches history.
    if(dt_supervisor_active() && found_history)
      dt_supervisor_node(DT_SV_UPDATE,
                         dt_supervisor_node_key(pipe->type, piece->module->op, piece->module->multi_priority),
                         history_param_hash, DT_PIXELPIPE_CACHE_HASH_INVALID, piece->module->op,
                         piece->module->multi_priority, piece->module->iop_order, pipe->type, pipe->imgid);
 
    if(!found_history)
      dt_print(DT_DEBUG_PARAMS, "[pixelpipe] info: committed default params for %s (%s) in pipe %s\n",
               piece->module->op, piece->module->multi_name, debug_label);
  }
 
  _refresh_pipe_detail_mask_state(pipe);
  if(previous_want_detail_mask != (pipe->want_detail_mask != DT_DEV_DETAIL_MASK_NONE))
  {
    GList *detailmask_node = _find_detailmask_node(pipe);
    if(detailmask_node && detailmask_node != start_node)
      _sync_pipe_nodes_from_history_from_node(pipe, history_list, history_end, detailmask_node, debug_label);
  }
}
 
void dt_pixelpipe_get_global_hash(dt_dev_pixelpipe_t *pipe)
{
  /* Traverse the pipeline node by node and compute the cumulative (global) hash of each module.
  *  This hash takes into account the hashes of the previous modules and the size of the current ROI.
  *  It is used to map pipeline cache states to current parameters.
  *  It represents the state of internal modules params as well as their position in the pipe and their output size.
  *  It is to be called at pipe init, not at runtime.
  */
 
  // bernstein hash (djb2)
  uint64_t hash = _default_pipe_hash(pipe);
  gboolean passthrough_preview = FALSE;
 
  // see dt_dev_pixelpipe_iop_t.upstream_hash: its own pass, and not derived from `hash` below,
  // which folds each piece's ROI
  _publish_upstream_hashes(pipe);
 
  // Bypassing cache contaminates downstream modules, starting at the module requesting it.
  // Usecase : crop, clip, ashift, etc. that need the uncropped image ;
  // mask displays ; overexposed/clipping alerts and all other transient previews.
  gboolean bypass_cache = FALSE;
 
  for(GList *node = g_list_first(pipe->nodes); node; node = g_list_next(node))
  {
    dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)node->data;
    if(!piece->enabled) continue;
 
    // Combine with the previous bypass states
    bypass_cache |= piece->module->bypass_cache;
    piece->bypass_cache = bypass_cache;
 
    // Combine with the previous modules hashes
    uint64_t local_hash = piece->hash;
 
    // Some GUI previews author their final display inside the active module,
    // then runtime forwards that exact buffer through later pass-through stages.
    // Keep the planned hash contract aligned with the published cacheline so the
    // GUI does not keep requesting a downstream output hash that will never exist.
    if(passthrough_preview
       && !(piece->module->operation_tags() & IOP_TAG_DISTORT)
       && (piece->dsc_in.bpp == piece->dsc_out.bpp)
       && !memcmp(&piece->roi_in, &piece->roi_out, sizeof(dt_iop_roi_t)))
    {
      piece->global_mask_hash = hash;
      piece->global_hash = hash;
      continue;
    }
 
    // Panning and zooming change the ROI. Some GUI modes (crop in editing mode) too.
    // dt_dev_get_roi_in() should have run before
    //
    // These two folds are ALSO how the darkroom viewport reaches this hash, which is why the
    // pipe's latched dt_dev_roi_request_t (pixelpipe_hb.h) deliberately does NOT contribute its
    // generation here. Every field of that record reaches the ROI by construction, in
    // _update_darkroom_roi(): zoom and the fit scale become roi.scale (their product), the
    // centre becomes roi.x/roi.y, the box and the processed size become roi.width/height. Even
    // finalscale's piece->enabled -- the one consumer that reads the record rather than the ROI
    // -- is a function of that same product, and a disabled piece is skipped above, so a toggle
    // changes the chain anyway.
    //
    // Folding the generation on top would therefore add no discriminating power and would only
    // over-invalidate: a republication that advances the generation while producing identical
    // ROIs (a sub-pixel pan that rounds to the same roi.x, a box change the fminf clamp absorbs)
    // would rekey the whole FULL-pipe cache chain for pixels that are bit-identical. Content,
    // not version, is the right key here -- unlike mask_preview_settings_revision below, which
    // hashes a revision precisely because its state reaches no ROI at all.
    local_hash = dt_hash(local_hash, (const char *)&piece->roi_in, sizeof(dt_iop_roi_t));
    local_hash = dt_hash(local_hash, (const char *)&piece->roi_out, sizeof(dt_iop_roi_t));
 
    local_hash = dt_hash(local_hash, (const char *)&piece->dsc_in, sizeof(dt_iop_buffer_dsc_t));
    local_hash = dt_hash(local_hash, (const char *)&piece->dsc_out, sizeof(dt_iop_buffer_dsc_t));
 
    /* The pipe's drawn-mask rasterisation step changes the mask a module blends with, so it
     * changes that module's pixels. It belongs HERE, with request_mask_display below, and for
     * the same reason: it is global GUI state that no module's history carries, so
     * dt_iop_commit_params() would only fold it when that module's own parameters changed --
     * flipping the preference from auto to never would leave every cached line valid-looking
     * and stale.
     *
     * Only for a module that actually draws a mask: the raw stages upstream cannot carry one,
     * and rehashing them would cost cache misses for pixels that cannot move. */
    // From piece->blendop_data, NOT piece->module->blend_params. This function runs on the
    // darkroom worker thread, and blend_params belongs to the GUI thread -- the rule this file
    // states twice above ("never the live GUI module->params"). Reading it here dereferences a
    // module the GUI can be tearing down or reallocating underneath us, which is Sentry
    // 142904894: EXCEPTION_ACCESS_VIOLATION at this line, from resync_pipe_with_history() on
    // the pipeline thread. blendop_data is the per-piece copy dt_iop_commit_params() writes
    // from the history snapshot, which is what blend.c itself reads.
    const dt_develop_blend_params_t *const blend_data
        = (const dt_develop_blend_params_t *)piece->blendop_data;
    if(!IS_NULL_PTR(blend_data)
       && (blend_data->mask_mode & DEVELOP_MASK_SHAPE)
       && blend_data->mask_id > 0)
      local_hash = dt_hash(local_hash, (const char *)&pipe->mask_rasterization_step, sizeof(int));
 
/*
    fprintf(stdout, "start->end : %-17s | ROI in: %4ix%-4i @%2.4f | ROI out: %4ix%-4i @%2.4f\n", piece->module->op,
            piece->buf_in.width, piece->buf_in.height, piece->buf_in.scale, piece->buf_out.width,
            piece->buf_out.height, piece->buf_out.scale);
    fprintf(stdout, "end->start : %-17s | ROI in: %4ix%-4i @%2.4f | ROI out: %4ix%-4i @%2.4f\n", piece->module->op,
            piece->roi_in.width, piece->roi_in.height, piece->planned_roi_in.scale,
            piece->roi_out.width, piece->roi_out.height, piece->roi_out.scale);
*/
    // Mask preview display doesn't re-commit params, so we need to keep that of it here
    // Too much GUI stuff interleaved with pipeline stuff...
    // Mask display applies only to main preview in darkroom.
    if(pipe->type == DT_DEV_PIXELPIPE_FULL)
    {
      local_hash = dt_hash(local_hash, (const char *)&piece->module->request_mask_display, sizeof(int));
 
      /* Mask-preview appearance is global GUI state, not module history. Hash
       * its revision at the module producing the active preview so upstream
       * cache entries remain reusable while this module and gamma are rerun. */
      if(pipe->dev->gui_attached
         && piece->module == pipe->dev->gui_module
         && piece->module->request_mask_display != DT_DEV_PIXELPIPE_DISPLAY_NONE)
      {
        const int revision = dt_atomic_get_int(&pipe->dev->mask_preview_settings_revision);
        local_hash = dt_hash(local_hash, (const char *)&revision, sizeof(revision));
      }
 
      // bypass_cache_variant (see dt_iop_module_t.bypass_cache_variant) is, like
      // request_mask_display above, module-owned GUI state whose real effect a module such as
      // retouch applies only to this main/FULL pipe -- never to the preview pipe, which always
      // renders as if none of these toggles were active. But the field itself lives on
      // the shared dt_iop_module_t, so it reads the same non-zero value from every pipe type. Left
      // ungated, a preview-pipe run with the same ROI/params (e.g. at zoom == fit) can compute the
      // exact same hash chain as the FULL pipe despite publishing different pixels, and either
      // pipe's cache entry then gets silently reused by the other via the cross-pipe "another pipe
      // already owns this hash" exact-hit path -- exactly like request_mask_display's own hazard.
      local_hash = dt_hash(local_hash, (const char *)&piece->module->bypass_cache_variant, sizeof(int));
    }
    else
    {
      const int zero = 0;
      local_hash = dt_hash(local_hash, (const char *)&zero, sizeof(int));
      local_hash = dt_hash(local_hash, (const char *)&zero, sizeof(int));
    }
 
    // Keep track of distortion bypass in GUI. That may affect upstream modules in the stack,
    // while bypass_cache only affects downstream ones.
    // In theory, distortion bypass should already affect planned ROI in/out, but it depends whether
    // internal params are committed. Anyway, make it more reliable.
    int bypass_distort = dt_dev_pixelpipe_activemodule_disables_currentmodule(pipe->dev, piece->module);
    local_hash = dt_hash(local_hash, (const char *)&bypass_distort, sizeof(int));
 
    // If the cache bypass is on, the corresponding cache lines will be freed immediately after use,
    // we need to track that. It somewhat overlaps module->request_mask_display, but...
    local_hash = dt_hash(local_hash, (const char *)&piece->bypass_cache, sizeof(gboolean));
 
    // Update global hash for this stage
    hash = dt_hash(hash, (const char *)&local_hash, sizeof(uint64_t));
 
    if(dt_get_debug_flags() & DT_DEBUG_VERBOSE)
    {
      gchar *type = _get_debug_pipe_name(pipe, pipe->dev);
      dt_print(DT_DEBUG_PIPE,
               "[pixelpipe] global hash for %20s (%s) in pipe %s enabled=%d bypass_cache=%d with hash %lu\n",
               piece->module->op, piece->module->multi_name, type, piece->enabled, piece->bypass_cache,
               (long unsigned int)hash);
      dt_free(type);
    }
    // In case of drawn masks, we would need to account only for the distortions of previous modules.
    // Aka conditional to: if((piece->module->operation_tags() & IOP_TAG_DISTORT) == IOP_TAG_DISTORT)
    // But in case of parametric masks, they depend on previous modules parameters.
    // So, all in all, (parametric | drawn | raster) masking depends on everything :
    // - if masking on output, internal params + blendop params + all previous modules internal params + ROI size,
    // - if masking on input, blendop params + all previous modules internal params + ROI size
    // So we use all that ot once : 
    piece->global_mask_hash = dt_hash(hash, (const char *)&piece->blendop_hash, sizeof(uint64_t));
 
    // Finally, the output of the module also depends on the mask:
    hash = dt_hash(hash, (const char *)&piece->global_mask_hash, sizeof(uint64_t));
    piece->global_hash = hash;
 
    if(pipe->type == DT_DEV_PIXELPIPE_FULL
       && pipe->dev->gui_attached
       && (piece->module == pipe->dev->gui_module)
       && (piece->module->request_mask_display != DT_DEV_PIXELPIPE_DISPLAY_NONE))
    {
      passthrough_preview = TRUE;
    }
  }
 
  // The pipe hash is the hash of its last module.
  dt_dev_pixelpipe_set_hash(pipe, hash);
  pipe->bypass_cache = bypass_cache;
}
 
/* Resync every node against a history snapshot. Runs outside history_mutex: everything it reads
 * is owned by `snap`, whose references keep the items alive and, through the writer's
 * copy-on-write gate, unmodified. */
static void _synch_all_snapshot(dt_dev_pixelpipe_t *pipe, const dt_dev_history_snapshot_t *snap,
                                const char *caller_func)
{
  gchar *type = _get_debug_pipe_name(pipe, pipe->dev);
  dt_print(DT_DEBUG_DEV, "[pixelpipe] synch all modules with history for pipe %s called from %s\n", type, caller_func);
 
  const uint32_t history_end = (uint32_t)snap->history_end;
  _sync_pipe_nodes_from_history(pipe, snap->items, history_end, type);
 
  // Keep track of the last history item to have been synced
  GList *last_item = g_list_nth(snap->items, history_end - 1);
  if(last_item)
  {
    dt_dev_history_item_t *last_hist = (dt_dev_history_item_t *)last_item->data;
    pipe->last_history_hash = last_hist->hash;
    _pipe_set_last_history_item(pipe, last_hist);
  }
  else
  {
    pipe->last_history_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    _pipe_set_last_history_item(pipe, NULL);
  }
 
  dt_free(type);
}
 
/* Public entry: export, snapshots and the focus overlay drive a throwaway pipe through this
 * without going through dt_dev_pixelpipe_change(), and none of them holds history_mutex. Take
 * the snapshot here, under a read lock held only for the copy. A caller that DOES already hold
 * the lock (as reader or writer) re-enters it on the same thread, which dt_pthread_rwlock_t
 * permits (see dtpthread.h). */
void dt_dev_pixelpipe_synch_all_real(dt_dev_pixelpipe_t *pipe, const char *caller_func)
{
  dt_dev_history_snapshot_t snap;
  dt_pthread_rwlock_rdlock(&pipe->dev->history_mutex);
  dt_dev_history_snapshot_take(pipe->dev, &snap);
  dt_pthread_rwlock_unlock(&pipe->dev->history_mutex);
 
  _synch_all_snapshot(pipe, &snap, caller_func);
 
  dt_dev_history_snapshot_release(&snap);
}
 
/* Resync only the nodes touched since the last sync, against a history snapshot. Runs outside
 * history_mutex, same contract as _synch_all_snapshot(). */
static void _synch_top_snapshot(dt_dev_pixelpipe_t *pipe, const dt_dev_history_snapshot_t *snap)
{
  gchar *type = _get_debug_pipe_name(pipe, pipe->dev);
 
  dt_print(DT_DEBUG_DEV, "[pixelpipe] synch top modules with history for pipe %s\n", type);
 
  const uint32_t history_end = (uint32_t)snap->history_end;
  GList *last_item = g_list_nth(snap->items, history_end - 1);
  if(last_item)
  {
    // The identity marker is read once: the GUI thread may re-point it at a clone (see
    // dt_dev_history_cow_touch) while this walk runs, and the reference the pipe holds on it
    // is what makes comparing against a possibly-departed item safe.
    const dt_dev_history_item_t *last_synced
        = (const dt_dev_history_item_t *)dt_atomic_get_ptr(&pipe->last_history_item);
 
    GList *first_item = NULL;
    for(GList *history = last_item; history; history = g_list_previous(history))
    {
      dt_dev_history_item_t *hist = (dt_dev_history_item_t *)history->data;
      first_item = history;
 
      if(hist->hash == pipe->last_history_hash || hist == last_synced)
        break;
    }
 
    GList *fence_item = g_list_nth(snap->items, history_end);
    for(GList *history = first_item; history && history != fence_item; history = g_list_next(history))
    {
      dt_dev_history_item_t *hist = (dt_dev_history_item_t *)history->data;
      if(!hist || !hist->module) continue;
      dt_print(DT_DEBUG_PARAMS, "[pixelpipe] synch top history module `%s` (%s) for pipe %s\n",
               hist->module->op, hist->module->multi_name, type);
      for(GList *nodes = g_list_last(pipe->nodes); nodes; nodes = g_list_previous(nodes))
      {
        dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)nodes->data;
        if(IS_NULL_PTR(piece) || piece->module != hist->module) continue;
 
        _sync_pipe_nodes_from_history_from_node(pipe, snap->items, history_end, nodes, type);
        break;
      }
    }
 
    dt_dev_history_item_t *last_hist = (dt_dev_history_item_t *)last_item->data;
    pipe->last_history_hash = last_hist->hash;
    _pipe_set_last_history_item(pipe, last_hist);
  }
  else
  {
    dt_print(DT_DEBUG_DEV, "[pixelpipe] synch top history module missing error for pipe %s\n", type);
    pipe->last_history_hash = DT_PIXELPIPE_CACHE_HASH_INVALID;
    _pipe_set_last_history_item(pipe, NULL);
  }
 
  dt_free(type);
}
 
void dt_dev_pixelpipe_synch_top(dt_dev_pixelpipe_t *pipe)
{
  dt_dev_history_snapshot_t snap;
  dt_pthread_rwlock_rdlock(&pipe->dev->history_mutex);
  dt_dev_history_snapshot_take(pipe->dev, &snap);
  dt_pthread_rwlock_unlock(&pipe->dev->history_mutex);
 
  _synch_top_snapshot(pipe, &snap);
 
  dt_dev_history_snapshot_release(&snap);
}
 
// Modules without history need to be resynced unconditionnally with their internal params
// because some of them are self-enabled/disabled from commit_params() methods
void dt_dev_pixelpipe_sync_no_history(dt_dev_pixelpipe_t *pipe)
{
  for(GList *nodes = g_list_first(pipe->nodes); nodes; nodes = g_list_next(nodes))
  {
    dt_dev_pixelpipe_iop_t *piece = (dt_dev_pixelpipe_iop_t *)nodes->data;
    if(IS_NULL_PTR(piece) || IS_NULL_PTR(piece->module)) continue;
    dt_iop_module_t *module = piece->module;
    if(module->flags() & IOP_FLAGS_NO_HISTORY_STACK)
      dt_iop_commit_params(module, module->default_params, module->default_blendop_params, pipe, piece);
  }
}
 
void dt_dev_pixelpipe_change(dt_dev_pixelpipe_t *pipe)
{
  dt_times_t start;
  dt_get_times(&start);
 
  dt_dev_pixelpipe_change_t status
      = (dt_dev_pixelpipe_change_t)dt_atomic_exch_int((dt_atomic_int *)&pipe->changed, DT_DEV_PIPE_UNCHANGED);
 
  gchar *type = _get_debug_pipe_name(pipe, pipe->dev);
  char *status_str = g_strdup_printf("%s%s%s%s%s%s%s%s",
                                  (status & DT_DEV_PIPE_UNCHANGED) ? "UNCHANGED " : "",
                                  (status & DT_DEV_PIPE_REMOVE) ? "REMOVE " : "",
                                  (status & DT_DEV_PIPE_TOP_CHANGED) ? "TOP_CHANGED " : "",
                                  (status & DT_DEV_PIPE_SYNCH) ? "SYNCH " : "",
                                  (status & DT_DEV_PIPE_ZOOMED) ? "ZOOMED " : "",
                                  (status & DT_DEV_PIPE_CACHE_REQUEST) ? "CACHE_REQUEST " : "",
                                  (status & DT_DEV_PIPE_REENTRY) ? "REENTRY " : "",
                                  (status & DT_DEV_PIPE_SWITCHED) ? "SWITCHED " : "");
 
  dt_print(DT_DEBUG_DEV, "[dt_dev_pixelpipe_change] pipeline state changing for pipe %s, flag %s\n",
     type, status_str);
 
  dt_free(status_str);
 
  // mask display off as a starting point
  pipe->mask_display = DT_DEV_PIXELPIPE_DISPLAY_NONE;
  pipe->bypass_blendif = 0;
 
  // Only raised here: whatever changes next, the run that renders the switched-to state must
  // leave the previous state's outputs alone. dt_dev_pixelpipe_process() lowers it once it did.
  if(status & DT_DEV_PIPE_SWITCHED) pipe->keep_outputs = TRUE;
 
  /* Zoom/pan only replans ROI and hashes, it does not replay history sync.
   * Rebuild the aggregate detail-mask demand from the already synchronized
   * pieces in that case, otherwise the pipe forgets that the hidden
   * `detailmask` stage is needed before the next processing run starts. */
  if(status & (DT_DEV_PIPE_REMOVE | DT_DEV_PIPE_SYNCH | DT_DEV_PIPE_TOP_CHANGED))
    pipe->want_detail_mask = DT_DEV_DETAIL_MASK_NONE;
  else
    _refresh_pipe_detail_mask_state(pipe);
 
  // Snapshot history under the read lock, then resync against the snapshot with the lock
  // RELEASED. The resync is O(nodes x history) and runs every module's commit_params() --
  // tens of ms routinely, over 200 ms under mask-heavy history -- and it used to hold this
  // lock for all of it. The GUI thread needs the writer side of the same lock on every
  // commit (each slider tick, each throttled mask-drag commit), and glibc's writer-preferring
  // policy then also blocks every NEW reader behind the queued writer: one slow resync stalled
  // the whole application until it finished. The snapshot holds a reference on each item, and
  // the writer's copy-on-write gate (dt_dev_history_cow_touch) clones a shared item before
  // touching it, so what this resync reads can neither move nor change under it.
  //
  // A call chain that already holds history_mutex as writer on this same thread can re-enter
  // here (e.g. history-commit paths that resync a pipe while still holding the write lock);
  // dt_pthread_rwlock_rdlock is same-thread-recursive for exactly that (see dtpthread.h).
  const double _history_mutex_hold_start = dt_get_wtime();
  dt_dev_history_snapshot_t snap;
  dt_pthread_rwlock_rdlock(&pipe->dev->history_mutex);
  dt_dev_history_snapshot_take(pipe->dev, &snap);
  dt_pthread_rwlock_unlock(&pipe->dev->history_mutex);
  const double _history_mutex_hold_ms = (dt_get_wtime() - _history_mutex_hold_start) * 1000.0;
  if(_history_mutex_hold_ms > 1.0)
    dt_print(DT_DEBUG_HISTORY,
             "[dt_dev_pixelpipe_change] tid %lu pipe %s held history_mutex for %.2f ms (status 0x%x)\n",
             (unsigned long)pthread_self(), type, _history_mutex_hold_ms, (unsigned)status);
 
  // The realtime in-place path settles the format contract and the global hash itself (it must,
  // since that hash is cumulative over enabled nodes); the other paths defer it to the
  // unconditional pass below.
  gboolean formats_propagated = FALSE;
 
  // case DT_DEV_PIPE_UNCHANGED: case DT_DEV_PIPE_ZOOMED:
  if(status & DT_DEV_PIPE_REMOVE)
  {
    // modules have been added in between or removed. need to rebuild the whole pipeline.
    if(pipe->nodes) dt_dev_pixelpipe_cleanup_nodes(pipe);
    dt_dev_pixelpipe_create_nodes(pipe);
    dt_dev_pixelpipe_sync_no_history(pipe);
    _synch_all_snapshot(pipe, &snap, __FUNCTION__);
  }
  else if(status & DT_DEV_PIPE_SYNCH)
  {
    // pipeline topology remains intact, only change all params.
    dt_dev_pixelpipe_sync_no_history(pipe);
    _synch_all_snapshot(pipe, &snap, __FUNCTION__);
  }
  else if(status & DT_DEV_PIPE_TOP_CHANGED)
  {
    // only top history item(s) changed, or a focused module published transient/realtime params
    if(_sync_focused_in_place(pipe, &snap))
    {
      formats_propagated = TRUE;
    }
    else
    {
      dt_dev_pixelpipe_sync_no_history(pipe);
      _synch_top_snapshot(pipe, &snap);
    }
  }
  else // DT_DEV_PIPE_ZOOMED DT_DEV_PIPE_CACHE_REQUEST DT_DEV_PIPE_REENTRY
  {
    // Finalscale will need to self-enable/disable depending on zoom level
    dt_dev_pixelpipe_sync_no_history(pipe);
  }
  // The hash the SNAPSHOT carried, not the live one: a commit may have landed since the lock
  // was released, and this pipe is synced to what it just resynced against, nothing newer. The
  // worker loop compares this against the live hash and re-flags the pipe if they differ.
  dt_dev_pixelpipe_set_history_hash(pipe, snap.history_hash);
  dt_dev_history_snapshot_release(&snap);
  const double _resync_ms = (dt_get_wtime() - _history_mutex_hold_start) * 1000.0;
  if(_resync_ms > 1.0)
    dt_print(DT_DEBUG_HISTORY,
             "[dt_dev_pixelpipe_change] tid %lu pipe %s resynced from snapshot in %.2f ms, lock-free (status 0x%x)\n",
             (unsigned long)pthread_self(), type, _resync_ms, (unsigned)status);
 
  // Re-establish the buffer-format contract of the whole chain once, after whichever sync path
  // (full, top-only or realtime-in-place) committed params. This is the single authoritative,
  // direction-independent place where per-node dsc_in/dsc_out are settled and incompatible
  // modules are disabled (issue #733), so the OpenCL cache policy and ROI planning below see a
  // consistent contract. The realtime path already did this before computing its global hash.
  if(!formats_propagated)
    dt_dev_pixelpipe_propagate_formats(pipe);
 
  _seal_opencl_cache_policy(pipe);
  
  // Update theoritical final scale based on distorting modules
  // This also writes piece->buf_in/out for each pipe->nodes piece,
  // so it's not nearly a matter of getting processed_width/height
  dt_dev_pixelpipe_get_roi_out(pipe, pipe->iwidth, pipe->iheight, &pipe->processed_width,
                               &pipe->processed_height);
 
  dt_show_times_f(&start, "[dev_pixelpipe] pipeline resync with history", "for pipe %s", type);
  dt_free(type);
}
 
gboolean dt_dev_pixelpipe_is_backbufer_valid(dt_dev_pixelpipe_t *pipe)
{
  return dt_dev_backbuf_get_hash(&pipe->backbuf) != DT_PIXELPIPE_CACHE_HASH_INVALID
         && dt_dev_pixelpipe_get_hash(pipe) == dt_dev_backbuf_get_hash(&pipe->backbuf)
         && dt_dev_get_history_hash(pipe->dev) == dt_dev_backbuf_get_history_hash(&pipe->backbuf)
         && dt_dev_backbuf_get_history_hash(&pipe->backbuf) == dt_dev_get_history_hash(pipe->dev);
}
 
gboolean dt_dev_pixelpipe_is_pipeline_valid(dt_dev_pixelpipe_t *pipe)
{
  return dt_dev_get_history_hash(pipe->dev) == dt_dev_pixelpipe_get_history_hash(pipe);
}