imageop.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2009-2013 johannes hanika.
    Copyright (C) 2010-2012 Henrik Andersson.
    Copyright (C) 2011 Edouard Gomez.
    Copyright (C) 2011-2012 Jérémy Rosen.
    Copyright (C) 2011 Robert Bieber.
    Copyright (C) 2011 Rostyslav Pidgornyi.
    Copyright (C) 2011-2014, 2016, 2018-2019 Tobias Ellinghaus.
    Copyright (C) 2011-2017 Ulrich Pegelow.
    Copyright (C) 2012-2013, 2019-2021 Aldric Renaudin.
    Copyright (C) 2012 Richard Wonka.
    Copyright (C) 2013, 2018-2022 Pascal Obry.
    Copyright (C) 2013-2016 Roman Lebedev.
    Copyright (C) 2013 Simon Spannagel.
    Copyright (C) 2014, 2021 Dan Torop.
    Copyright (C) 2014 Mikhail Trishchenkov.
    Copyright (C) 2016 Pedro Côrte-Real.
    Copyright (C) 2017-2019 Edgardo Hoszowski.
    Copyright (C) 2019-2020 Heiko Bauke.
    Copyright (C) 2020, 2022-2026 Aurélien PIERRE.
    Copyright (C) 2020, 2022 Chris Elston.
    Copyright (C) 2020-2022 Diederik Ter Rahe.
    Copyright (C) 2020 Harold le Clément de Saint-Marcq.
    Copyright (C) 2020 Philippe Weyland.
    Copyright (C) 2020-2021 Ralf Brown.
    Copyright (C) 2021-2022 Hanno Schwalm.
    Copyright (C) 2021 Marco.
    Copyright (C) 2021 Mark-64.
    Copyright (C) 2021 Paolo DePetrillo.
    Copyright (C) 2021 Sakari Kapanen.
    Copyright (C) 2022 luzpaz.
    Copyright (C) 2022 Martin Bařinka.
    Copyright (C) 2022 Philipp Lutz.
    Copyright (C) 2023 Luca Zulberti.
    Copyright (C) 2024-2025 Alynx Zhou.
    Copyright (C) 2025 Guillaume Stutin.
    
    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 <gmodule.h>
#include <gtk/gtk.h>
#include <sched.h>
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef struct dt_iop_roi_t
{
  int x, y, width, height;
  double scale;
} dt_iop_roi_t;
 
#ifdef __cplusplus
}
#endif
 
#include "common/darktable.h"
#include "common/introspection.h"
#include "common/gui_module_api.h"
#include "common/opencl.h"
 
#include "control/settings.h"
#include "develop/pixelpipe.h"
#include "dtgtk/togglebutton.h"
#include "gui/gtk.h"
#include "gui/gui_throttle.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct dt_develop_t;
struct dt_dev_pixelpipe_t;
struct dt_dev_pixelpipe_iop_t;
struct dt_develop_blend_params_t;
struct dt_develop_tiling_t;
struct dt_iop_color_picker_t;
 
typedef enum dt_iop_module_header_icons_t
{
  IOP_MODULE_SWITCH = 0,
  IOP_MODULE_ICON,
  IOP_MODULE_LABEL,
  IOP_MODULE_MASK,
  IOP_MODULE_INSTANCE,
  IOP_MODULE_RESET,
  IOP_MODULE_PRESETS,
  IOP_MODULE_LAST
} dt_iop_module_header_icons_t;
 
float dt_dev_get_module_scale(const struct dt_dev_pixelpipe_t *pipe, const dt_iop_roi_t *roi_in);
 
typedef enum dt_iop_group_t
{
  IOP_GROUP_NONE = 0,
  IOP_GROUP_TONES = 1,
  IOP_GROUP_FILM = 2,
  IOP_GROUP_COLOR = 3,
  IOP_GROUP_REPAIR = 4,
  IOP_GROUP_SHARPNESS = 5,
  IOP_GROUP_EFFECTS = 6,
  IOP_GROUP_TECHNICAL= 7,
  IOP_GROUP_LAST
} dt_iop_group_t;
 
typedef enum dt_iop_tags_t
{
  IOP_TAG_NONE = 0,
  IOP_TAG_DISTORT = 1 << 0,
  IOP_TAG_DECORATION = 1 << 1,
  IOP_TAG_CLIPPING = 1 << 2,
 
  // might be some other filters togglable by user?
  // IOP_TAG_SLOW       = 1<<3,
  // IOP_TAG_DETAIL_FIX = 1<<3,
} dt_iop_tags_t;
 
typedef enum dt_iop_flags_t
{
  IOP_FLAGS_NONE = 0,
 
  IOP_FLAGS_INCLUDE_IN_STYLES = 1 << 0,
  IOP_FLAGS_SUPPORTS_BLENDING = 1 << 1, // Does provide blending modes
  IOP_FLAGS_DEPRECATED = 1 << 2,
  IOP_FLAGS_ALLOW_TILING = 1 << 3, // Does allow tile-wise processing (valid for CPU and GPU processing)
  IOP_FLAGS_HIDDEN = 1 << 4,       // Hide the iop from userinterface
  IOP_FLAGS_TILING_FULL_ROI = 1 << 5, // Tiling code has to expect arbitrary roi's for this module (incl. flipping, mirroring etc.)
  IOP_FLAGS_ONE_INSTANCE = 1 << 6,       // The module doesn't support multiple instances
  IOP_FLAGS_PREVIEW_NON_OPENCL = 1 << 7, // Preview pixelpipe of this module must not run on GPU but always on CPU
  IOP_FLAGS_NO_HISTORY_STACK = 1 << 8,   // This iop will never show up in the history stack
  IOP_FLAGS_NO_MASKS = 1 << 9,           // The module doesn't support masks (used with SUPPORT_BLENDING)
  IOP_FLAGS_TAKE_NO_INPUT = 1 << 10,     // The module doesn't use input
  IOP_FLAGS_UNSAFE_COPY = 1 << 11,       // Unsafe to copy as part of history
  IOP_FLAGS_GUIDES_SPECIAL_DRAW = 1 << 12, // handle the grid drawing directly
  IOP_FLAGS_INTERNAL_MASKS = 1 << 13,     // Module uses masks internally, outside of blendops. This advertises the need to commit them to history unconditionnaly.
  IOP_FLAGS_CPU_WRITES_OPENCL = 1 << 14  // Special case where the process() CPU path inits OpenCL vRAM output cache too
} dt_iop_flags_t;
 
typedef struct dt_iop_gui_data_t
{
  // "base type" for all dt_iop_XXXX_gui_data_t types used by iops
  // to avoid compiler error about different sizes of empty structs between C and C++, we need at least one member
  int dummy;
} dt_iop_gui_data_t;
 
typedef void dt_iop_data_t;
typedef void dt_iop_global_data_t;
 
typedef enum dt_dev_request_colorpick_flags_t
{
  DT_REQUEST_COLORPICK_OFF = 0,   // off
  DT_REQUEST_COLORPICK_MODULE = 1 // requested by module (should take precedence)
} dt_dev_request_colorpick_flags_t;
 
typedef enum dt_iop_colorspace_type_t
{
  IOP_CS_NONE = -1,
  IOP_CS_RAW = 0,
  IOP_CS_LAB = 1,
  IOP_CS_RGB = 2,
  IOP_CS_LCH = 3,
  IOP_CS_HSL = 4,
  IOP_CS_JZCZHZ = 5,
  IOP_CS_RGB_DISPLAY = 6,
} dt_iop_colorspace_type_t;
 
static inline gboolean dt_iop_colorspace_is_rgb(const dt_iop_colorspace_type_t cst)
{
  return cst == IOP_CS_RGB || cst == IOP_CS_RGB_DISPLAY;
}
 
typedef struct dt_iop_module_so_t
{
  // Needs to stay on top for casting
  dt_gui_module_t common_fields;
 
#define INCLUDE_API_FROM_MODULE_H
#include "iop/iop_api.h"
 
  GModule *module;
  dt_dev_operation_t op;
  dt_iop_global_data_t *data;
//  dt_iop_gui_data_t *gui_data;
  int (*process_plain)(struct dt_iop_module_t *self, const struct dt_dev_pixelpipe_t *pipe,
                       const struct dt_dev_pixelpipe_iop_t *piece, const void *const i, void *const o);
 
  // introspection related data
  gboolean have_introspection;
} dt_iop_module_so_t;
 
typedef struct dt_iop_module_t
{
  // Needs to stay on top for casting
  dt_gui_module_t common_fields;
 
#define INCLUDE_API_FROM_MODULE_H
#include "iop/iop_api.h"
 
  GModule *module;
  dt_dev_operation_t op;
  int32_t instance;
  int iop_order;
  int32_t hide_enable_button;
  dt_dev_request_colorpick_flags_t request_color_pick;
  dt_dev_request_flags_t request_histogram;
  int request_mask_display;
  int32_t suppress_mask;
  gboolean bypass_cache;
  dt_aligned_pixel_t picked_color, picked_color_min, picked_color_max;
  dt_aligned_pixel_t picked_output_color, picked_output_color_min, picked_output_color_max;
  uint32_t *histogram;
  dt_dev_histogram_stats_t histogram_stats;
  uint32_t histogram_max[4];
  dt_iop_colorspace_type_t histogram_cst;
  int histogram_middle_grey;
  // FIXME: this should disappear from there.
  // To access the develop object from backend (pipeline threads), we already have pipe->dev 
  // referenced in the pipeline object.
  // To access the develop object from frontend (GUI), we have the global darktable.develop reference.
  // Splitting like this between frontend/backend makes things clear and legible.
  // This internal reference can be either, and used for writes and reads alike, 
  // which is impossible to track across the program.
  struct dt_develop_t *dev;
  gboolean enabled;
  gboolean default_enabled;
 
  gboolean workflow_enabled;
  dt_iop_params_t *params, *default_params;
  int32_t params_size;
  dt_iop_gui_data_t *gui_data;
  dt_pthread_mutex_t gui_lock;
  dt_iop_global_data_t *global_data;
  struct dt_develop_blend_params_t *blend_params, *default_blendop_params;
  gpointer blend_data;
  struct {
    struct {
      GHashTable *users;
      GHashTable *masks;
    } source;
    struct {
      struct dt_iop_module_t *source;
      int id;
    } sink;
  } raster_mask;
  GtkWidget *widget;
  GtkDarktableToggleButton *off;
  GtkWidget *header;
  GtkWidget *mask_indicator;
  GtkWidget *expander;
  gboolean expanded;
  GtkWidget *reset_button;
  GtkWidget *presets_button;
  GtkWidget *fusion_slider;
 
  GtkWidget *guides_toggle;
  GtkWidget *guides_combo;
 
  dt_iop_module_so_t *so;
 
  int multi_priority; // user may change this
  char multi_name[128]; // user may change this name
  gboolean multi_show_close;
  gboolean multi_show_up;
  gboolean multi_show_down;
  gboolean multi_show_new;
  GtkWidget *multimenu_button;
 
  guint timeout_handle;
 
  int (*process_plain)(struct dt_iop_module_t *self, const struct dt_dev_pixelpipe_t *pipe,
                       const struct dt_dev_pixelpipe_iop_t *piece, const void *const i, void *const o);
 
  // introspection related data
  gboolean have_introspection;
 
  // parameters hash
  uint64_t hash;
 
  // blendop hash
  // Ideally, this would be added to struct dt_develop_blend_params_t *blendop
  // but since blendops are dumped to DB as a memory blob, we can't change their length
  // without updating version (aka breaking backwards compatibility), and this minor
  // stuff is not worth it.
  uint64_t blendop_hash;
 
} dt_iop_module_t;
 
void dt_iop_load_modules_so(void);
void dt_iop_unload_modules_so(void);
int dt_iop_load_module_by_so(dt_iop_module_t *module, dt_iop_module_so_t *so, struct dt_develop_t *dev);
int dt_iop_load_module(dt_iop_module_t *module, dt_iop_module_so_t *module_so, struct dt_develop_t *dev);
void dt_iop_cleanup_module(dt_iop_module_t *module);
void dt_iop_init_pipe(struct dt_iop_module_t *module, struct dt_dev_pixelpipe_t *pipe,
                      struct dt_dev_pixelpipe_iop_t *piece);
void dt_iop_cleanup_pipe(struct dt_iop_module_t *module, struct dt_dev_pixelpipe_t *pipe,
                      struct dt_dev_pixelpipe_iop_t *piece);
gboolean dt_iop_so_is_hidden(dt_iop_module_so_t *module);
gboolean dt_iop_is_hidden(dt_iop_module_t *module);
 
gboolean dt_iop_is_visible(dt_iop_module_t *module);
 
static inline void dt_iop_gui_enter_critical_section(dt_iop_module_t *const module)
  ACQUIRE(&module->gui_lock)
{
  dt_pthread_mutex_lock(&module->gui_lock);
}
static inline void dt_iop_gui_leave_critical_section(dt_iop_module_t *const module)
  RELEASE(&module->gui_lock)
{
  dt_pthread_mutex_unlock(&module->gui_lock);
}
void dt_iop_gui_cleanup_module(dt_iop_module_t *module);
void dt_iop_gui_set_enable_button(dt_iop_module_t *module);
void dt_iop_gui_update(dt_iop_module_t *module);
void dt_iop_gui_reset(dt_iop_module_t *module);
void dt_iop_gui_set_expanded(dt_iop_module_t *module, gboolean expanded, gboolean collapse_others);
void dt_iop_gui_update_expanded(dt_iop_module_t *module);
/* duplicate module and return new instance */
dt_iop_module_t *dt_iop_gui_duplicate(dt_iop_module_t *base, gboolean copy_params);
 
void dt_iop_gui_update_header(dt_iop_module_t *module);
 
void dt_iop_commit_params(dt_iop_module_t *module, dt_iop_params_t *params,
                          struct dt_develop_blend_params_t *blendop_params, struct dt_dev_pixelpipe_t *pipe,
                          struct dt_dev_pixelpipe_iop_t *piece);
void dt_iop_commit_blend_params(dt_iop_module_t *module, const struct dt_develop_blend_params_t *blendop_params);
void dt_iop_set_mask_mode(dt_iop_module_t *module, int mask_mode);
void dt_iop_gui_set_expander(dt_iop_module_t *module);
GtkWidget *dt_iop_gui_get_widget(dt_iop_module_t *module);
GtkWidget *dt_iop_gui_get_pluginui(dt_iop_module_t *module);
 
void dt_iop_request_focus(dt_iop_module_t *module);
void dt_iop_default_init(dt_iop_module_t *module);
void dt_iop_load_default_params(dt_iop_module_t *module);
void dt_iop_gui_init(dt_iop_module_t *module);
void dt_iop_reload_defaults(dt_iop_module_t *module);
 
void dt_iop_nap(int32_t usec);
 
dt_iop_module_t *dt_iop_get_colorout_module(void);
/* returns the iop-module found in list with the given name */
dt_iop_module_t *dt_iop_get_module_from_list(GList *iop_list, const char *op);
dt_iop_module_t *dt_iop_get_module(const char *op);
dt_iop_module_t *dt_iop_get_module_by_op_priority(GList *modules, const char *operation, const int multi_priority);
dt_iop_module_t *dt_iop_get_module_by_instance_name(GList *modules, const char *operation, const char *multi_name);
 
gboolean dt_iop_is_first_instance(GList *modules, dt_iop_module_t *module);
 
 
int dt_iop_get_module_flags(const char *op);
 
const gchar *dt_iop_get_localized_name(const gchar *op);
const gchar *dt_iop_get_localized_aliases(const gchar *op);
 
void dt_iop_update_multi_priority(dt_iop_module_t *module, int new_priority);
 
gboolean dt_iop_module_has_raster_mask(const dt_iop_module_t *module);
gboolean dt_iop_module_needs_mask_history(const dt_iop_module_t *module);
 
gboolean dt_iop_is_raster_mask_used(dt_iop_module_t *module, int id);
 
dt_iop_module_t *dt_iop_gui_get_previous_visible_module(dt_iop_module_t *module);
dt_iop_module_t *dt_iop_gui_get_next_visible_module(dt_iop_module_t *module);
gboolean dt_iop_gui_module_is_visible(dt_iop_module_t *module);
gboolean dt_iop_gui_move_module_before(dt_iop_module_t *module, dt_iop_module_t *module_next,
                                       const char *reason);
gboolean dt_iop_gui_commit_iop_order_change(struct dt_develop_t *dev, dt_iop_module_t *module,
                                            gboolean enable, gboolean write_history, const char *reason);
gboolean dt_iop_gui_move_module_after(dt_iop_module_t *module, dt_iop_module_t *module_prev,
                                      const char *reason);
 
// initializes memory.darktable_iop_names
void dt_iop_set_darktable_iop_table();
 
void dt_iop_throttled_history_update(gpointer data);
 
void dt_iop_add_remove_mask_indicator(dt_iop_module_t *module);
 
// format modules description going in tooltips
const char **dt_iop_set_description(dt_iop_module_t *module, const char *main_text,
                                    const char *purpose, const char *input,
                                    const char *process, const char *output);
 
static inline dt_iop_gui_data_t *_iop_gui_alloc(dt_iop_module_t *module, size_t size)
{
  // Align so that DT_ALIGNED_ARRAY may be used within gui_data struct
  module->gui_data = (dt_iop_gui_data_t*)dt_calloc_align(size);
  dt_pthread_mutex_init(&module->gui_lock,NULL);
  return module->gui_data;
}
#define IOP_GUI_ALLOC(module) \
  (dt_iop_##module##_gui_data_t *)_iop_gui_alloc(self,sizeof(dt_iop_##module##_gui_data_t))
 
#define IOP_GUI_FREE \
  dt_pthread_mutex_destroy(&self->gui_lock);       \
  if(self->gui_data){                              \
    dt_free_align(self->gui_data);                 \
    self->gui_data = NULL;                         \
  }                                                \
  self->gui_data = NULL;
 
/* bring up module rename dialog */
void dt_iop_gui_rename_module(dt_iop_module_t *module);
 
/* dispatch post-value-changed GUI events within module and commit changes to history */
void dt_iop_gui_changed(dt_iop_module_t *module, GtkWidget *widget, gpointer data);
 
// update all bauhaus widgets in an iop module from their params fields
void dt_bauhaus_update_module(dt_iop_module_t *self);
 
// default callback to connect to value-changed signal for bauhaus widgets
// it will automatically call dt_iop_changed for the right module.
void dt_bauhaus_value_changed_default_callback(GtkWidget *widget);
 
 
void dt_iop_compute_module_hash(dt_iop_module_t *module, GList *masks);
 
// Use module fingerprints to determine if two instances are actually the same
gboolean dt_iop_check_modules_equal(dt_iop_module_t *mod_1, dt_iop_module_t *mod_2);
 
 
gboolean dt_iop_get_cache_bypass(dt_iop_module_t *module);
void dt_iop_set_cache_bypass(dt_iop_module_t *module, gboolean state);
 
// after writing data using copy_pixel_nontemporal, it is necessary to
// ensure that the writes have completed before attempting reads from
// a different core.  This function produces the required memory
// fence to ensure proper visibility
static inline void dt_sfence()
{
#if defined(__x86_64__) || defined(__i386__)
  _mm_sfence();
#else
  // the following generates an MFENCE instruction on x86/x64.  We
  // only really need SFENCE, which is less expensive, but none of the
  // other memory orders generate *any* fence instructions on x64.
  __atomic_thread_fence(__ATOMIC_SEQ_CST);
#endif
}
 
// if the copy_pixel_nontemporal() writes were inside an OpenMP
// parallel loop, the OpenMP parallelization will have performed a
// memory fence before resuming single-threaded operation, so a
// dt_sfence would be superfluous.  But if compiled without OpenMP
// parallelization, we should play it safe and emit a memory fence.
// This function should be used right after a parallelized for loop,
// where it will produce a barrier only if needed.
#ifdef _OPENMP
#define dt_omploop_sfence()
#else
#define dt_omploop_sfence() dt_sfence()
#endif
 
#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