colorprofiles/iop_profile.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2018-2019 Edgardo Hoszowski.
    Copyright (C) 2019-2021, 2025 Aurélien PIERRE.
    Copyright (C) 2019 Hanno Schwalm.
    Copyright (C) 2019 luzpaz.
    Copyright (C) 2019 Marcus Rückert.
    Copyright (C) 2019-2020 Pascal Obry.
    Copyright (C) 2020-2021 Dan Torop.
    Copyright (C) 2020 Harold le Clément de Saint-Marcq.
    Copyright (C) 2021 Heiko Bauke.
    Copyright (C) 2021 Hubert Kowalski.
    Copyright (C) 2021 Ralf Brown.
    Copyright (C) 2021 Sakari Kapanen.
    Copyright (C) 2022 Martin Bařinka.
    
    darktable is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser 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 Lesser General Public License for more details.
    
    You should have received a copy of the GNU Lesser General Public License
    along with darktable.  If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef DT_COLORPROFILES_IOP_PROFILE_H
#define DT_COLORPROFILES_IOP_PROFILE_H
 
#include "pixel/format.h"   // dt_iop_colorspace_type_t
#include "common/colorspaces_inline_conversions.h"
#include "colorprofiles/profile_types.h"
/* develop/imageop.h is deliberately NOT included. Including it made common/ depend on
 * develop/ (a layering inversion) and closed a 6-node include cycle with common/opencl.h.
 * It used to be needed for four iop/pixelpipe types used as POINTERS, which were then
 * tag-declared here instead; those declarations have since moved out with the
 * pipeline-facing half, and no declaration below names an iop or pipe type at all. The
 * `dt_iop_*` names that remain (dt_iop_colorspace_type_t, dt_iop_color_intent_t) are pixel
 * and profile vocabulary, from pixel/format.h and colorprofiles/profile_types.h. */
 
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
 
#ifdef HAVE_OPENCL
#include <CL/cl.h>           // for cl_mem
#endif
 
 
typedef struct dt_iop_order_iccprofile_info_t
{
  dt_colorspaces_color_profile_type_t type;
  char filename[DT_IOP_COLOR_ICC_LEN];
  dt_iop_color_intent_t intent;
  dt_colormatrix_t matrix_in; // don't align on more than 16 bits or OpenCL will fail
  dt_colormatrix_t matrix_out;
  int lutsize;
  float *lut_in[3];
  float *lut_out[3];
  float unbounded_coeffs_in[3][3] DT_ALIGNED_PIXEL;
  float unbounded_coeffs_out[3][3] DT_ALIGNED_PIXEL;
  int nonlinearlut;
  float grey;
  dt_colormatrix_t matrix_in_transposed;  // same as matrix_in, but stored such as to permit vectorization
  dt_colormatrix_t matrix_out_transposed; // same as matrix_out, but stored such as to permit vectorization
} dt_iop_order_iccprofile_info_t;
 
void dt_ioppr_init_profile_info(dt_iop_order_iccprofile_info_t *profile_info, const int lutsize);
void dt_ioppr_cleanup_profile_info(dt_iop_order_iccprofile_info_t **profile_info);
dt_iop_order_iccprofile_info_t *
dt_colorspaces_add_profile(const dt_colorspaces_color_profile_type_t profile_type,
                           const char *profile_filename,
                           const int intent);
 
void dt_colorspaces_flush_profile_memo(void);
 
void dt_colorspaces_invalidate_display_profile_memo(void);
 
/* --- APPLY: the pixel loop ------------------------------------------------
 *
 * Convert a buffer between colour spaces. Branches internally on what the profile is:
 * a matrix-shaper with tone curves takes our own vectorised matrix + LUT path, anything
 * else falls back to lcms2. Callers neither choose nor see which.
 *
 * `op_name`/`instance_name` label the -d perf trace only, and are plain strings rather
 * than the dt_iop_module_t they come from: this module sits below develop/ and cannot
 * name an iop. */
 
void dt_colorspaces_apply_profile(const char *const op_name, const char *const instance_name,
                                  const float *const image_in, float *const image_out,
                                  const int width, const int height,
                                  const int cst_from, const int cst_to, int *converted_cst,
                                  const dt_iop_order_iccprofile_info_t *const profile_info);
 
#ifdef HAVE_OPENCL
int dt_colorspaces_apply_profile_cl(const char *const op_name, const char *const instance_name,
                                    const int devid, cl_mem dev_img_in, cl_mem dev_img_out,
                                    const int width, const int height,
                                    const int cst_from, const int cst_to, int *converted_cst,
                                    const dt_iop_order_iccprofile_info_t *const profile_info);
#endif
 
void dt_ioppr_transform_image_colorspace_rgb(const float *const image_in, float *const image_out, const int width,
                                             const int height,
                                             const dt_iop_order_iccprofile_info_t *const profile_info_from,
                                             const dt_iop_order_iccprofile_info_t *const profile_info_to,
                                             const char *message);
 
#ifdef HAVE_OPENCL
typedef struct dt_colorspaces_cl_global_t
{
  int kernel_colorspaces_transform_lab_to_rgb_matrix;
  int kernel_colorspaces_transform_rgb_matrix_to_lab;
  int kernel_colorspaces_transform_rgb_matrix_to_rgb;
} dt_colorspaces_cl_global_t;
 
// must be in synch with colorspaces.cl dt_colorspaces_iccprofile_info_cl_t
typedef struct dt_colorspaces_iccprofile_info_cl_t
{
  cl_float matrix_in[9];
  cl_float matrix_out[9];
  cl_int lutsize;
  cl_float unbounded_coeffs_in[3][3];
  cl_float unbounded_coeffs_out[3][3];
  cl_int nonlinearlut;
  cl_float grey;
} dt_colorspaces_iccprofile_info_cl_t;
 
void dt_colorspaces_init_cl_global(void);
void dt_colorspaces_free_cl_global(void);
 
void dt_ioppr_get_profile_info_cl(const dt_iop_order_iccprofile_info_t *const profile_info, dt_colorspaces_iccprofile_info_cl_t *profile_info_cl);
cl_float *dt_ioppr_get_trc_cl(const dt_iop_order_iccprofile_info_t *const profile_info);
 
cl_int dt_ioppr_build_iccprofile_params_cl(const dt_iop_order_iccprofile_info_t *const profile_info,
                                           const int devid, dt_colorspaces_iccprofile_info_cl_t **_profile_info_cl,
                                           cl_float **_profile_lut_cl, cl_mem *_dev_profile_info,
                                           cl_mem *_dev_profile_lut);
void dt_ioppr_free_iccprofile_params_cl(dt_colorspaces_iccprofile_info_cl_t **_profile_info_cl,
                                        cl_float **_profile_lut_cl, cl_mem *_dev_profile_info,
                                        cl_mem *_dev_profile_lut);
int dt_ioppr_transform_image_colorspace_rgb_cl(const int devid, cl_mem dev_img_in, cl_mem dev_img_out,
                                               const int width, const int height,
                                               const dt_iop_order_iccprofile_info_t *const profile_info_from,
                                               const dt_iop_order_iccprofile_info_t *const profile_info_to,
                                               const char *message);
#endif
 
/* --- The per-pixel primitives -------------------------------------------------------
 *
 * the following must have the matrix_in and matrix_out generated
 *
 * Everything below is `static inline` and published as inline code on purpose: these run
 * once per pixel per module, so a call would dominate the work. That is the one legitimate
 * reason a header carries an implementation, and it is why this header includes
 * common/colorspaces_inline_conversions.h -- a deliberate performance trade, not a
 * convenience.
 *
 * They all take the profile's fields as SEPARATE arguments rather than the struct, so the
 * OpenMP `uniform`/`aligned` clauses can promise the vectoriser that the matrix and the LUTs
 * are loop-invariant and aligned. Passing `profile_info` instead would forfeit that.
 *
 * NONE of them checks the "is this a matrix profile" sentinel: they assume the matrices are
 * real, which is what the leading comment means. Call them only on a profile that came back
 * from dt_colorspaces_add_profile() with `!isnan(matrix_in[0][0])`.
 */
 
__OMP_DECLARE_SIMD__(aligned(lut:64) uniform(lut))
static inline __attribute__((always_inline)) float extrapolate_lut(const float *const lut, const float v, const int lutsize)
{
  // TODO: check if optimization is worthwhile!
  const float ft = CLAMPS(v * (lutsize - 1), 0, lutsize - 1);
  const int t = (ft < lutsize - 2) ? ft : lutsize - 2;
  const float f = ft - t;
  const float l1 = lut[t];
  const float l2 = lut[t + 1];
  return l1 * (1.0f - f) + l2 * f;
}
 
 
__OMP_DECLARE_SIMD__(uniform(coeff))
static inline __attribute__((always_inline)) float eval_exp(const float coeff[3], const float x)
{
  return coeff[1] * powf(x * coeff[0], coeff[2]);
}
 
__OMP_DECLARE_SIMD__(aligned(lut:64) uniform(lut, coeff))
static inline __attribute__((always_inline)) float dt_ioppr_eval_trc(const float x, const float *const lut, const float coeff[3], const int lutsize)
{
  return (x < 1.0f) ? extrapolate_lut(lut, x, lutsize) : eval_exp(coeff, x);
}
#ifdef _OPENMP
#pragma omp declare simd \
  aligned(rgb_in, rgb_out, unbounded_coeffs:16) \
  aligned(lut:64) \
  uniform(lut, unbounded_coeffs)
#endif
static inline __attribute__((always_inline)) void
_apply_trc(const dt_aligned_pixel_t rgb_in, dt_aligned_pixel_t rgb_out, float *const lut[3],
           const float unbounded_coeffs[3][3], const int lutsize)
{
  for(int c = 0; c < 3; c++)
  {
    rgb_out[c] = (!IS_NULL_PTR(lut[c]) && lut[c][0] >= 0.0f) ? dt_ioppr_eval_trc(rgb_in[c], lut[c], unbounded_coeffs[c], lutsize)
                                                              : rgb_in[c];
  }
}
 
#ifdef _OPENMP
#pragma omp declare simd \
  aligned(rgb:16) \
  aligned(matrix_in:64) \
  aligned(unbounded_coeffs_in:16) \
  aligned(lut_in:64) \
  uniform(matrix_in, lut_in, unbounded_coeffs_in)
#endif
static inline float dt_ioppr_get_rgb_matrix_luminance(const dt_aligned_pixel_t rgb,
                                                      const dt_colormatrix_t matrix_in, float *const lut_in[3],
                                                      const float unbounded_coeffs_in[3][3],
                                                      const int lutsize, const int nonlinearlut)
{
  float luminance = 0.f;
 
  if(nonlinearlut)
  {
    dt_aligned_pixel_t linear_rgb;
    _apply_trc(rgb, linear_rgb, lut_in, unbounded_coeffs_in, lutsize);
    luminance = matrix_in[1][0] * linear_rgb[0] + matrix_in[1][1] * linear_rgb[1] + matrix_in[1][2] * linear_rgb[2];
  }
  else
    luminance = matrix_in[1][0] * rgb[0] + matrix_in[1][1] * rgb[1] + matrix_in[1][2] * rgb[2];
 
  return luminance;
}
 
 
#ifdef _OPENMP
#pragma omp declare simd \
  aligned(rgb, xyz:16) \
  aligned(matrix_in_transposed:64) \
  aligned(unbounded_coeffs_in:16) \
  aligned(lut_in:64) \
  uniform(matrix_in_transposed, lut_in, unbounded_coeffs_in)
#endif
static inline void dt_ioppr_rgb_matrix_to_xyz(const dt_aligned_pixel_t rgb, dt_aligned_pixel_t xyz,
                                              const dt_colormatrix_t matrix_in_transposed, float *const lut_in[3],
                                              const float unbounded_coeffs_in[3][3],
                                              const int lutsize, const int nonlinearlut)
{
  if(nonlinearlut)
  {
    dt_aligned_pixel_t linear_rgb;
    _apply_trc(rgb, linear_rgb, lut_in, unbounded_coeffs_in, lutsize);
    dt_apply_transposed_color_matrix(linear_rgb, matrix_in_transposed, xyz);
  }
  else
    dt_apply_transposed_color_matrix(rgb, matrix_in_transposed, xyz);
}
 
#ifdef _OPENMP
#pragma omp declare simd \
  aligned(lab, rgb:16) \
  aligned(matrix_out_transposed:64) \
  aligned(unbounded_coeffs_out:16) \
  aligned(lut_out:64) \
  uniform(matrix_out_transposed, lut_out, unbounded_coeffs_out)
#endif
static inline void dt_ioppr_lab_to_rgb_matrix(const dt_aligned_pixel_t lab, dt_aligned_pixel_t rgb,
                                              const dt_colormatrix_t matrix_out_transposed, float *const lut_out[3],
                                              const float unbounded_coeffs_out[3][3],
                                              const int lutsize, const int nonlinearlut)
{
  dt_aligned_pixel_t xyz;
  dt_Lab_to_XYZ(lab, xyz);
 
  if(nonlinearlut)
  {
    dt_aligned_pixel_t linear_rgb;
    dt_apply_transposed_color_matrix(xyz, matrix_out_transposed, linear_rgb);
    _apply_trc(linear_rgb, rgb, lut_out, unbounded_coeffs_out, lutsize);
  }
  else
  {
    dt_apply_transposed_color_matrix(xyz, matrix_out_transposed, rgb);
  }
}
 
#ifdef _OPENMP
#pragma omp declare simd \
  aligned(rgb, lab:16) \
  aligned(matrix_in_transposed:64) \
  aligned(unbounded_coeffs_in:16) \
  aligned(lut_in:64) \
  uniform(matrix_in_transposed, lut_in, unbounded_coeffs_in)
#endif
static inline void dt_ioppr_rgb_matrix_to_lab(const dt_aligned_pixel_t rgb, dt_aligned_pixel_t lab,
                                              const dt_colormatrix_t matrix_in_transposed, float *const lut_in[3],
                                              const float unbounded_coeffs_in[3][3],
                                              const int lutsize, const int nonlinearlut)
{
  dt_aligned_pixel_t xyz = { 0.f };
  dt_ioppr_rgb_matrix_to_xyz(rgb, xyz, matrix_in_transposed, lut_in, unbounded_coeffs_in, lutsize, nonlinearlut);
  dt_XYZ_to_Lab(xyz, lab);
}
 
static inline float dt_ioppr_get_profile_info_middle_grey(const dt_iop_order_iccprofile_info_t *const profile_info)
{
  return profile_info->grey;
}
 
__OMP_DECLARE_SIMD__(uniform(profile_info))
static inline float dt_ioppr_compensate_middle_grey(const float x, const dt_iop_order_iccprofile_info_t *const profile_info)
{
  // we transform the curve nodes from the image colorspace to lab
  dt_aligned_pixel_t lab = { 0.0f };
  const dt_aligned_pixel_t rgb = { x, x, x };
  dt_ioppr_rgb_matrix_to_lab(rgb, lab, profile_info->matrix_in_transposed, profile_info->lut_in,
                             profile_info->unbounded_coeffs_in, profile_info->lutsize, profile_info->nonlinearlut);
  return lab[0] * .01f;
}
 
__OMP_DECLARE_SIMD__(uniform(profile_info))
static inline float dt_ioppr_uncompensate_middle_grey(const float x, const dt_iop_order_iccprofile_info_t *const profile_info)
{
  // we transform the curve nodes from lab to the image colorspace
  const dt_aligned_pixel_t lab = { x * 100.f, 0.0f, 0.0f };
  dt_aligned_pixel_t rgb = { 0.0f };
 
  dt_ioppr_lab_to_rgb_matrix(lab, rgb, profile_info->matrix_out_transposed, profile_info->lut_out,
                             profile_info->unbounded_coeffs_out, profile_info->lutsize, profile_info->nonlinearlut);
  return rgb[0];
}
 
 
/* --- The transform core, unwrapped ---------------------------------------------------
 *
 * Shared with the pipeline-facing half in develop/iop_profile.c. These were static; they are
 * the transform core both sides drive, not either side's private business. The two transform workers
 * take the module's name strings, not the module: naming it in a log line was the only use,
 * and a pointer would have kept this header reaching into develop/.
 *
 * These are the two branches dt_colorspaces_apply_profile() picks between, plus the three
 * builders that decide which branch a profile lands on, exposed for code that must build or
 * fix up a ::dt_iop_order_iccprofile_info_t by hand -- an image-derived input profile, say,
 * whose matrices come from iop/colorin.c rather than from a file. Prefer
 * dt_colorspaces_apply_profile(): calling a worker directly means choosing the branch
 * yourself, and choosing it wrong is silently wrong output rather than an error.
 *
 * As of this writing the tree has no caller for any of these five outside
 * colorprofiles/iop_profile.c itself.
 */
 
void dt_ioppr_mark_as_nonmatrix_profile(dt_iop_order_iccprofile_info_t *profile_info);
void dt_ioppr_clear_lut_curves(dt_iop_order_iccprofile_info_t *profile_info);
int dt_ioppr_init_unbounded_coeffs(float *lutr, float *lutg, float *lutb,
                                    float *unbounded_coeffsr, float *unbounded_coeffsg,
                                    float *unbounded_coeffsb, const int lutsize);
void dt_ioppr_transform_lcms2(const char *op, const char *multi_name, const float *const image_in,
                              float *const image_out, const int width, const int height,
                              const dt_iop_colorspace_type_t cst_from,
                              const dt_iop_colorspace_type_t cst_to,
                              dt_iop_colorspace_type_t *converted_cst,
                              const dt_iop_order_iccprofile_info_t *const profile_info);
void dt_ioppr_transform_matrix(const char *op, const char *multi_name, const float *const image_in,
                               float *const image_out, const int width, const int height,
                               const dt_iop_colorspace_type_t cst_from,
                               const dt_iop_colorspace_type_t cst_to,
                               dt_iop_colorspace_type_t *converted_cst,
                               const dt_iop_order_iccprofile_info_t *const profile_info);
 
#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