pixelpipe_hb.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2009-2013 johannes hanika.
    Copyright (C) 2011 Henrik Andersson.
    Copyright (C) 2011-2014, 2017 Ulrich Pegelow.
    Copyright (C) 2012 Richard Wonka.
    Copyright (C) 2013 Simon Spannagel.
    Copyright (C) 2014-2016 Roman Lebedev.
    Copyright (C) 2014, 2016-2017, 2019 Tobias Ellinghaus.
    Copyright (C) 2016 Pedro Côrte-Real.
    Copyright (C) 2018-2019 Edgardo Hoszowski.
    Copyright (C) 2020, 2022-2026 Aurélien PIERRE.
    Copyright (C) 2020-2021 Pascal Obry.
    Copyright (C) 2020 Ralf Brown.
    Copyright (C) 2021-2022 Hanno Schwalm.
    Copyright (C) 2022 Martin Bařinka.
    
    darktable 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.
    
    darktable 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 darktable.  If not, see <http://www.gnu.org/licenses/>.
*/
 
#pragma once
 
#include "common/atomic.h"
#include "common/image.h"
#include "common/imageio.h"
#include "common/iop_order.h"
#include "develop/imageop.h"
#include "develop/pixelpipe_cache.h"
 
 
struct dt_iop_module_t;
struct dt_dev_raster_mask_t;
struct dt_iop_order_iccprofile_info_t;
struct dt_develop_t;
 
typedef struct dt_dev_pixelpipe_raster_mask_t
{
  int id; // 0 is reserved for the reusable masks written in blend.c
  float *mask;
} dt_dev_pixelpipe_raster_mask_t;
 
typedef struct dt_dev_pixelpipe_iop_t
{
  struct dt_iop_module_t *module;  // the module in the dev operation stack
  void *data;                      // to be used by the module to store stuff per pipe piece
 
  // Memory size of *data upon which we will compute integrity hashes.
  // This needs to be the size of the constant part of the data structure.
  // It can even be 0 if nothing relevant to cache integrity hashes is held there.
  // If the data struct contains pointers, they should go at the end of the struct,
  // and the size here should be adjusted to only include constant bits, starting at the address of *data.
  // "Constant" means identical between 2 pipeline nodes init,
  // because the lifecycle of a pixelpipe cache is longer than that of a pixelpipe itself.
  // See an example in colorbalancergb.c
  size_t data_size;
 
  void *blendop_data;              // to be used by the module to store blendop per pipe piece
  gboolean enabled; // used to disable parts of the pipe for export, independent on module itself.
  gboolean detail_mask; // TRUE when the piece blend parameters request detail-mask refinement.
 
  dt_dev_request_flags_t request_histogram;              // (bitwise) set if you want an histogram captured
  dt_dev_histogram_collection_params_t histogram_params; // set histogram generation params
 
  int iwidth, iheight; // width and height of input buffer
 
  // Hash representing the current state of the params, blend params and enabled state of this individual module
  uint64_t hash;
  uint64_t blendop_hash;
 
  // Cumulative hash representing the current module hash and all the upstream modules from the pipeline,
  // for the current ROI.
  uint64_t global_hash;
 
  // Same as global hash but for raster masks
  uint64_t global_mask_hash;
 
  int bpc;             // bits per channel, 32 means float
  dt_iop_roi_t buf_in, buf_out; // theoretical full buffer regions of interest, as passed through modify_roi_out
  dt_iop_roi_t roi_in, roi_out; // planned runtime regions of interest after backward ROI propagation
  int process_cl_ready;       // set this to 0 in commit_params to temporarily disable the use of process_cl
  int process_tiling_ready;   // set this to 0 in commit_params to temporarily disable tiling
 
  // Sealed descriptor contract for this module instance.
  // dsc_in is the module input contract after input_format() sanitized against
  // the actual upstream storage format.
  // dsc_out is the authored module output contract after commit_params() and
  // output_format().
  // dsc_mask carries the mask-side storage contract when masks are produced.
  dt_iop_buffer_dsc_t dsc_in, dsc_out, dsc_mask;
 
  // bypass the cache for this module
  gboolean bypass_cache;
 
  // Snapshot of the last reusable output cacheline metadata.
  // This is intentionally NOT used for bypass_cache / no_cache / reentry modes:
  // - disposable outputs are flagged auto-destroy and must not be rekeyed,
  // - realtime outputs and GPU-transient outputs can safely reuse their cacheline.
  // The reused line is rekeyed while still write-locked, and it is destroyed if processing later
  // fails before producing a valid output for the new hash.
  dt_pixel_cache_entry_t cache_entry;
 
  // Set to TRUE for modules that should mandatorily cache their output to RAM
  // even when running on OpenCL. This is a processing-policy flag authored
  // during synchronization and then consumed by one recursion step; it does not
  // change the descriptor contract.
  gboolean cache_output_on_ram;
} dt_dev_pixelpipe_iop_t;
 
typedef enum dt_dev_pixelpipe_change_t
{
  DT_DEV_PIPE_UNCHANGED = 0,        // no event
  DT_DEV_PIPE_TOP_CHANGED = 1 << 0, // only params of top element changed
  DT_DEV_PIPE_REMOVE = 1 << 1,      // possibly elements of the pipe have to be removed
  DT_DEV_PIPE_SYNCH
  = 1 << 2, // all nodes up to end need to be synched, but no removal of module pieces is necessary
  DT_DEV_PIPE_ZOOMED = 1 << 3, // zoom event, preview pipe does not need changes
  DT_DEV_PIPE_CACHE_REQUEST = 1 << 4, // GUI requested one cacheline to be materialized on host
  DT_DEV_PIPE_REENTRY = 1 << 5 // retry runtime side-band generation without rebuilding nodes
} dt_dev_pixelpipe_change_t;
 
typedef enum dt_dev_pixelpipe_cache_request_t
{
  DT_DEV_PIXELPIPE_CACHE_REQUEST_NONE = 0,
  DT_DEV_PIXELPIPE_CACHE_REQUEST_BACKBUF = 1,
  DT_DEV_PIXELPIPE_CACHE_REQUEST_MODULE = 2
} dt_dev_pixelpipe_cache_request_t;
 
typedef struct dt_backbuf_t
{
  size_t bpp;            // bits per pixel
  size_t width;          // pixel size of image
  size_t height;         // pixel size of image
  dt_atomic_uint64 hash;         // data checksum/integrity hash, for example to connect to a cacheline
  dt_atomic_uint64 history_hash; // arbitrary state hash
} dt_backbuf_t;
 
static inline uint64_t dt_dev_backbuf_get_hash(const dt_backbuf_t *backbuf)
{
  return dt_atomic_get_uint64(&backbuf->hash);
}
 
static inline void dt_dev_backbuf_set_hash(dt_backbuf_t *backbuf, const uint64_t hash)
{
  dt_atomic_set_uint64(&backbuf->hash, hash);
}
 
static inline uint64_t dt_dev_backbuf_get_history_hash(const dt_backbuf_t *backbuf)
{
  return dt_atomic_get_uint64(&backbuf->history_hash);
}
 
static inline void dt_dev_backbuf_set_history_hash(dt_backbuf_t *backbuf, const uint64_t history_hash)
{
  dt_atomic_set_uint64(&backbuf->history_hash, history_hash);
}
 
typedef struct dt_dev_pixelpipe_t
{
  // The development to which this pipeline is attached
  struct dt_develop_t *dev;
 
  // input image. Will be fetched directly from mipmap cache
  int32_t imgid;
  dt_mipmap_size_t size;
 
  // width and height of full-resolution input buffer
  int iwidth, iheight;
 
  // Input scaling between full-resolution source image and
  // actual pipeline mipmap input. 
  // = 1.f, unless we take downscaled RAW for thumbnail export.
  float iscale;
 
  // dimensions of processed buffer assuming we take full-resolution input
  int processed_width, processed_height;
 
  struct dt_iop_order_iccprofile_info_t *work_profile_info;
  struct dt_iop_order_iccprofile_info_t *input_profile_info;
  struct dt_iop_order_iccprofile_info_t *output_profile_info;
 
  // instances of pixelpipe, stored in GList of dt_dev_pixelpipe_iop_t
  GList *nodes;
  // event flag
  dt_atomic_int changed;
 
  // backbuffer (output)
  dt_backbuf_t backbuf;
 
  // Validity checksum of whole pipeline, 
  // taken as the global hash of the last pipe node (module),
  // after the last synchronization between dev history and pipe nodes completed.
  // This is computed in dt_dev_pixelpipe_get_global_hash
  // ahead of processing image.
  dt_atomic_uint64 hash;
 
  // Lock this while a pipeline is working.
  // This is meant to prevent pipeline destruction/cleanup while it is working.
  // It should __NEVER__ be used from the GUI thread, the GUI thread interacts
  // with pipelines __ONLY__ through the pipeline cache.
  dt_pthread_mutex_t busy_mutex;
 
  // The hidden detailmask module publishes the full-resolution detail mask in
  // the global pixelpipe cache under a salted hash derived from its
  // piece->global_hash. The pipeline keeps only that cache key plus the source
  // ROI of the published mask so zoom/pan updates can reuse the same payload
  // exactly like raster masks do.
  uint64_t rawdetail_mask_hash;
  struct dt_iop_roi_t rawdetail_mask_roi;
  int want_detail_mask;
 
  // References held on the dedicated global raster-mask cachelines required by
  // the current graph. Keeping them at pipe level prevents LRU eviction between
  // provider publication and downstream consumption or mask export.
  GArray *raster_mask_hashes;
 
  int output_imgid;
  // processing is true when actual pixel computations are ongoing
  int processing;
  // running is true when the pipe thread is running, computing or idle
  int running;
  // shutting down?
  dt_atomic_int shutdown;
  /* Optional caller-owned kill switch used by background thumbnail/surface jobs.
   * The pipe keeps its own shutdown flag for local teardown, but long-running
   * non-GUI jobs also need a way to stop as soon as their output target changed
   * size. Callers own the storage and may flip it from another thread. */
  dt_atomic_int *shutdown_ext;
  // Best-effort processing mode. When TRUE, the processing path bypasses the
  // early-abort shutdown kill-switch checks that normally stop a stale pipeline
  // as soon as parameters changed. This allows long-running interactive
  // pipelines to keep producing "good enough" output until the flag is cleared.
  // Cleanup/teardown shutdown semantics are unchanged.
  dt_atomic_int realtime;
  // opencl enabled for this pixelpipe?
  int opencl_enabled;
  // opencl error detected?
  int opencl_error;
  // running in a tiling context?
  int tiling;
  // should this pixelpipe display a mask in the end?
  int mask_display;
  // should this pixelpipe completely suppressed the blendif module?
  int bypass_blendif;
  // input data based on this timestamp:
  int input_timestamp;
  dt_dev_pixelpipe_type_t type;
  // This pipe feeds GUI-side observables such as global histograms and picker
  // sampling. The processing core reacts to this property instead of branching
  // on pipeline type.
  gboolean gui_observable_source;
  // the final output pixel format this pixelpipe will be converted to
  dt_imageio_levels_t levels;
  // opencl device that has been locked for this pipe.
  int devid;
  // last opencl device this pipe ran on, kept after `devid` is reset to -1 at
  // the end of dt_dev_pixelpipe_process(). Used by dt_dev_pixelpipe_cleanup()
  // to release only this pipe's own cl_mem cache payloads. -1 if this pipe
  // never ran on OpenCL.
  int last_devid;
  // the user might choose to overwrite the output color space and rendering intent.
  dt_colorspaces_color_profile_type_t icc_type;
  gchar *icc_filename;
  dt_iop_color_intent_t icc_intent;
  // snapshot of modules iop_order
  GList *iop_order_list;
  // snapshot of mask list
  GList *forms;
  // Publish every provider mask in the global pixelpipe cache, including masks
  // which have no downstream consumer but may be requested by export.
  gboolean store_all_raster_masks;
 
  // hash of the last history item synchronized with pipeline
  // that's because the sync_top option can't assume only one history
  // item was added since the last synchronization.
  uint64_t last_history_hash;
  // pointer identity of the last synchronized history item.
  // This complements `last_history_hash` for in-place top-entry updates where
  // the same history node is reused and its hash changes.
  gpointer last_history_item;
 
  // hash of the whole history stack at the time of synchonization
  // between pipe and history. This is a local copy of 
  // dev_history_get_hash()
  dt_atomic_uint64 history_hash;
  // GUI readers can request one extra host-visible cacheline without pretending
  // history changed. BACKBUF targets the final pipe output, MODULE targets the
  // output of cache_request_module.
  dt_atomic_int cache_request;
  dt_atomic_ptr cache_request_module;
  // Modules can set this to TRUE internally so the pipeline will
  // restart right away, in the same thread.
  // The reentry flag can only be reset (to FALSE) by the same object that captured it.
  // DO NOT SET THAT DIRECTLY, use the setter/getter functions
  gboolean reentry;
 
  // Unique identifier of the object capturing the reentry flag.
  // This can be a mask or module hash, or anything that stays constant
  // across 2 pipeline runs from a same thread (aka as long as we don't reinit).
  // DO NOT SET THAT DIRECTLY, use the setter/getter functions
  uint64_t reentry_hash;
 
  // Can be set arbitrarily by pixelpipe modules at runtime
  // to invalidate downstream module cache lines.
  // This always gets reset to FALSE when a pipeline finishes,
  // whether on success or on error.
  gboolean flush_cache;
 
  // TRUE if at least one module is bypassing the cache
  gboolean bypass_cache;
 
  // If TRUE, do not keep any pixelpipe cache lines around for reuse.
  // This is intended for one-shot pipelines such as thumbnail exports where caching is pure overhead
  // and can lead to memory pressure (RAM buffers + OpenCL pinned/device buffers).
  gboolean no_cache;
 
  // Temporarily pause the infinite loop of pipeline
  gboolean pause;
 
  // Run a self-setting pipeline that will update history for each module
  // depending on its input if it implements the autoset() method
  gboolean autoset;
 
} dt_dev_pixelpipe_t;
 
static inline uint64_t dt_dev_pixelpipe_get_hash(const dt_dev_pixelpipe_t *pipe)
{
  return dt_atomic_get_uint64(&pipe->hash);
}
 
static inline void dt_dev_pixelpipe_set_hash(dt_dev_pixelpipe_t *pipe, const uint64_t hash)
{
  dt_atomic_set_uint64(&pipe->hash, hash);
}
 
static inline uint64_t dt_dev_pixelpipe_get_history_hash(const dt_dev_pixelpipe_t *pipe)
{
  return dt_atomic_get_uint64(&pipe->history_hash);
}
 
static inline void dt_dev_pixelpipe_set_history_hash(dt_dev_pixelpipe_t *pipe, const uint64_t history_hash)
{
  dt_atomic_set_uint64(&pipe->history_hash, history_hash);
}
 
static inline dt_dev_pixelpipe_change_t dt_dev_pixelpipe_get_changed(const dt_dev_pixelpipe_t *pipe)
{
  return (dt_dev_pixelpipe_change_t)dt_atomic_get_int((dt_atomic_int *)&pipe->changed);
}
 
static inline void dt_dev_pixelpipe_set_changed(dt_dev_pixelpipe_t *pipe, const dt_dev_pixelpipe_change_t v)
{
  dt_atomic_set_int((dt_atomic_int *)&pipe->changed, (int)v);
}
 
static inline void dt_dev_pixelpipe_or_changed(dt_dev_pixelpipe_t *pipe, const dt_dev_pixelpipe_change_t flags)
{
  dt_atomic_or_int((dt_atomic_int *)&pipe->changed, (int)flags);
}
 
static inline dt_dev_pixelpipe_cache_request_t dt_dev_pixelpipe_get_cache_request(const dt_dev_pixelpipe_t *pipe)
{
  return pipe ? (dt_dev_pixelpipe_cache_request_t)dt_atomic_get_int((dt_atomic_int *)&pipe->cache_request)
              : DT_DEV_PIXELPIPE_CACHE_REQUEST_NONE;
}
 
static inline const struct dt_iop_module_t *dt_dev_pixelpipe_get_cache_request_module(const dt_dev_pixelpipe_t *pipe)
{
  return pipe ? (const struct dt_iop_module_t *)dt_atomic_get_ptr(&pipe->cache_request_module) : NULL;
}
 
static inline void dt_dev_pixelpipe_set_cache_request(dt_dev_pixelpipe_t *pipe,
                                                      const dt_dev_pixelpipe_cache_request_t request,
                                                      const struct dt_iop_module_t *module)
{
  if(IS_NULL_PTR(pipe)) return;
  dt_atomic_set_ptr(&pipe->cache_request_module, (void *)module);
  dt_atomic_set_int((dt_atomic_int *)&pipe->cache_request, (int)request);
}
 
static inline void dt_dev_pixelpipe_reset_cache_request(dt_dev_pixelpipe_t *pipe)
{
  if(IS_NULL_PTR(pipe)) return;
  dt_atomic_set_int((dt_atomic_int *)&pipe->cache_request, DT_DEV_PIXELPIPE_CACHE_REQUEST_NONE);
  dt_atomic_set_ptr(&pipe->cache_request_module, NULL);
}
 
struct dt_develop_t;
 
#ifdef __cplusplus
extern "C" {
#endif
 
char *dt_pixelpipe_get_pipe_name(dt_dev_pixelpipe_type_t pipe_type);
 
// inits the pixelpipe with plain passthrough input/output and empty input and default caching settings.
int dt_dev_pixelpipe_init(dt_dev_pixelpipe_t *pipe, struct dt_develop_t *dev);
// inits the preview pixelpipe with plain passthrough input/output and empty input and default caching
// settings.
int dt_dev_pixelpipe_init_preview(dt_dev_pixelpipe_t *pipe, struct dt_develop_t *dev);
// inits the pixelpipe with settings optimized for full-image export (no history stack cache)
int dt_dev_pixelpipe_init_export(dt_dev_pixelpipe_t *pipe, struct dt_develop_t *dev, int levels, gboolean store_masks);
// inits the pixelpipe with settings optimized for thumbnail export (no history stack cache)
int dt_dev_pixelpipe_init_thumbnail(dt_dev_pixelpipe_t *pipe, struct dt_develop_t *dev);
// inits all but the pixel caches, so you can't actually process an image (just get dimensions and
// distortions)
int dt_dev_pixelpipe_init_dummy(dt_dev_pixelpipe_t *pipe, struct dt_develop_t *dev);
// inits the pixelpipe
int dt_dev_pixelpipe_init_cached(dt_dev_pixelpipe_t *pipe);
// enable/disable best-effort processing mode, bypassing the usual early-abort
// shutdown checks while the flag stays enabled.
void dt_dev_pixelpipe_set_realtime(dt_dev_pixelpipe_t *pipe, gboolean state);
// return whether best-effort processing mode is currently enabled.
gboolean dt_dev_pixelpipe_get_realtime(const dt_dev_pixelpipe_t *pipe);
static inline gboolean dt_dev_pixelpipe_has_shutdown(const dt_dev_pixelpipe_t *pipe)
{
  return pipe && (dt_atomic_get_int((dt_atomic_int *)&pipe->shutdown)
                  || (pipe->shutdown_ext && dt_atomic_get_int(pipe->shutdown_ext)));
}
// constructs a new input buffer from given RGB float array.
void dt_dev_pixelpipe_set_input(dt_dev_pixelpipe_t *pipe, int32_t imgid, int width,
                                int height, float iscale, dt_mipmap_size_t size);
// set some metadata for colorout to avoid race conditions.
void dt_dev_pixelpipe_set_icc(dt_dev_pixelpipe_t *pipe, dt_colorspaces_color_profile_type_t icc_type,
                              const gchar *icc_filename, dt_iop_color_intent_t icc_intent);
// destroys all allocated data.
void dt_dev_pixelpipe_cleanup(dt_dev_pixelpipe_t *pipe);
// cleanup all nodes except clean input/output
void dt_dev_pixelpipe_cleanup_nodes(dt_dev_pixelpipe_t *pipe);
// sync with develop_t history stack from scratch (new node added, have to pop old ones)
// this should be called with dev->history_mutex locked in read mode
void dt_dev_pixelpipe_create_nodes(dt_dev_pixelpipe_t *pipe);
// sync with develop_t history stack by just copying the top item params (same op, new params on top)
void dt_dev_pixelpipe_synch_all_real(dt_dev_pixelpipe_t *pipe, const char *caller_func);
#define dt_dev_pixelpipe_synch_all(pipe) dt_dev_pixelpipe_synch_all_real(pipe, __FUNCTION__)
// adjust output node according to history stack (history pop event)
void dt_dev_pixelpipe_synch_top(dt_dev_pixelpipe_t *pipe);
 
// process region of interest of pixels. returns 1 if pipe was altered during processing.
int dt_dev_pixelpipe_process(dt_dev_pixelpipe_t *pipe, dt_iop_roi_t roi);
 
// Refresh GUI samplers from the cachelines already published by a darkroom pipe.
 
// disable given op and all that comes after it in the pipe:
void dt_dev_pixelpipe_disable_after(dt_dev_pixelpipe_t *pipe, const char *op);
// disable given op and all that comes before it in the pipe:
void dt_dev_pixelpipe_disable_before(dt_dev_pixelpipe_t *pipe, const char *op);
 
float *dt_dev_get_raster_mask(dt_dev_pixelpipe_t *pipe, const struct dt_iop_module_t *raster_mask_source,
                              const int raster_mask_id, const struct dt_iop_module_t *target_module,
                              int *error);
 
// helper function writing the pipe-processed ctmask data to dest
float *dt_dev_distort_detail_mask(const dt_dev_pixelpipe_t *pipe, float *src, const struct dt_iop_module_t *target_module);
float *dt_dev_retrieve_rawdetail_mask(const dt_dev_pixelpipe_t *pipe, const struct dt_iop_module_t *target_module);
 
 
gboolean dt_dev_pixelpipe_set_reentry(dt_dev_pixelpipe_t *pipe, uint64_t hash);
 
gboolean dt_dev_pixelpipe_unset_reentry(dt_dev_pixelpipe_t *pipe, uint64_t hash);
 
// check if pipeline should re-entry after it completes
gboolean dt_dev_pixelpipe_has_reentry(dt_dev_pixelpipe_t *pipe);
 
// Force-reset pipeline re-entry flag, for example if we lost the unique ID of the object
// in a re-entry loop.
void dt_dev_pixelpipe_reset_reentry(dt_dev_pixelpipe_t *pipe);
 
#ifdef __cplusplus
}
#endif
 
// clang-format off
// modelines: These editor modelines have been set for all relevant files by tools/update_modelines.py
// vim: shiftwidth=2 expandtab tabstop=2 cindent
// kate: tab-indents: off; indent-width 2; replace-tabs on; indent-mode cstyle; remove-trailing-spaces modified;
// clang-format on