colorspaces.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2010 Henrik Andersson.
    Copyright (C) 2010-2012, 2017 johannes hanika.
    Copyright (C) 2010 José Carlos García Sogo.
    Copyright (C) 2011 Bruce Guenter.
    Copyright (C) 2011 Robert Bieber.
    Copyright (C) 2012, 2014 Pascal de Bruijn.
    Copyright (C) 2012 Richard Wonka.
    Copyright (C) 2013-2017 Tobias Ellinghaus.
    Copyright (C) 2014, 2019-2022 Pascal Obry.
    Copyright (C) 2014-2016 Roman Lebedev.
    Copyright (C) 2014 Ulrich Pegelow.
    Copyright (C) 2015-2016 Pedro Côrte-Real.
    Copyright (C) 2018-2019 Edgardo Hoszowski.
    Copyright (C) 2019 Philippe Weyland.
    Copyright (C) 2020, 2022-2025 Aurélien PIERRE.
    Copyright (C) 2020 Dan Torop.
    Copyright (C) 2021 Hubert Kowalski.
    Copyright (C) 2021 Miloš Komarčević.
    Copyright (C) 2021 Ralf Brown.
    Copyright (C) 2021 Sakari Kapanen.
    Copyright (C) 2022 Martin Bařinka.
    Copyright (C) 2023, 2025 Alynx Zhou.
    
    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/>.
*/
 
#ifndef DT_COLORPROFILES_COLORSPACES_H
#define DT_COLORPROFILES_COLORSPACES_H
 
#include "colorprofiles/profile_types.h"
#include "math/matrices.h"
#include "system/simd.h"
 
#include <glib.h>
#include <lcms2.h>
#include <pthread.h>
 
typedef struct _GtkWidget GtkWidget;
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define LUT_SAMPLES 0x10000
 
#ifndef TYPE_XYZA_FLT
  #define TYPE_XYZA_FLT (FLOAT_SH(1)|COLORSPACE_SH(PT_XYZ)|EXTRA_SH(1)|CHANNELS_SH(3)|BYTES_SH(4))
#endif
 
 
typedef struct dt_colorspaces_t
{
  GList *profiles;
 
  // xatom color profile:
  gchar *colord_profile_file;
  uint8_t *xprofile_data;
  int xprofile_size;
 
  // the current set of selected profiles
  dt_colorspaces_color_profile_type_t display_type;
  dt_colorspaces_color_profile_type_t softproof_type;
  char display_filename[512];
  char softproof_filename[512];
  dt_iop_color_intent_t display_intent;
  dt_iop_color_intent_t softproof_intent;
 
  dt_colorspaces_color_mode_t mode;
  cmsHTRANSFORM transform_srgb_to_display, transform_adobe_rgb_to_display, transform_xyz_to_display, transform_display_to_adobe_rgb;
 
} dt_colorspaces_t;
 
typedef struct dt_colorspaces_color_profile_t
{
  pthread_rwlock_t lock;
  gboolean owns_profile;
  dt_colorspaces_color_profile_type_t type; 
  char filename[DT_IOP_COLOR_ICC_LEN];      
  char name[512];                           
  cmsHPROFILE profile;                      
  dt_colorspaces_profile_role_t roles;
} dt_colorspaces_color_profile_t;
 
typedef struct dt_colorspaces_cicp_t
{
    dt_colorspaces_cicp_color_primaries_t color_primaries;
    dt_colorspaces_cicp_transfer_characteristics_t transfer_characteristics;
    dt_colorspaces_cicp_matrix_coefficients_t matrix_coefficients;
} dt_colorspaces_cicp_t;
 
int mat3inv_float(float *const dst, const float *const src);
 
int mat3inv(float *const dst, const float *const src);
 
 
/* --- lifecycle ----------------------------------------------------------- */
 
void dt_colorprofiles_init(void);
 
void dt_colorprofiles_cleanup(void);
 
 
 
/* --- CRUDE: the metadata half ------------------------------------------------
 *
 * Everything here answers a question ABOUT a profile and answers it with plain values.
 * No cmsHPROFILE crosses this boundary, and no caller iterates the list: enumeration
 * hands back a value array, everything else is a lookup.
 *
 * THE ROLE PREDICATE. `role` is mandatory and is not a nicety.
 * DT_COLORSPACE_SRGB is registered TWICE -- a v4 parametric-curve profile valid only as
 * input, and a v2 point-TRC profile valid for output/monitor/working -- and nothing else
 * distinguishes them. A multi-bit mask resolves to the first match in registration order,
 * which for sRGB is the v4 input entry; that is what DT_PROFILE_ROLE_ANY does.
 *
 * The predicate tests the entry's role mask, and the three NULL-profile category entries
 * have an empty one -- which is what makes them unreachable (see
 * dt_colorspaces_color_profile_t). MONITOR is not an optical direction at all; it is the eligibility
 * list for the monitor-profile menu, and it diverges from OUTPUT on 5 of the 21 built-in
 * entries.
 *
 * The index-valued calls REQUIRE a single-bit role and return -1 / FALSE otherwise:
 * an index means nothing outside the enumeration that produced it, and an index taken from
 * INPUT|OUTPUT equals neither menu's row number.
 *
 * None of these takes a lock, deliberately: the list is built once at init and the only
 * datum that mutates afterwards is the DT_COLORSPACE_DISPLAY entry's cmsHPROFILE, which
 * none of them reads. Adding a lock would put one on every call site to protect fields
 * nobody writes. */
 
typedef struct dt_colorprofile_desc_t
{
  dt_colorspaces_color_profile_type_t type; 
  char filename[DT_IOP_COLOR_ICC_LEN];  
  char name[512];                       
} dt_colorprofile_desc_t;
 
/* --- LOCK: pin ONE profile's handle while deriving from it ------------------
 *
 * Per profile, not per module: several pipelines and the GUI derive from profiles at the
 * same time, and a module-wide lock would make a thumbnail conversion against sRGB stand
 * between a monitor-profile change and the display entry.
 *
 * Hold this across "resolve a profile, then derive from it" -- a matrix extraction, a
 * cmsCreateTransform -- and release once the derived artifact no longer refers to the
 * profile. An LCMS transform does not retain its source profiles, so that is the create
 * call, not the transform's lifetime.
 *
 * Read ::dt_colorspaces_color_profile_t::profile only AFTER taking the lock: the entry
 * pointer is stable for the life of the process, but its handle is not. */
void dt_colorspaces_lock_profile(const dt_colorspaces_color_profile_t *const profile);
void dt_colorspaces_unlock_profile(const dt_colorspaces_color_profile_t *const profile);
 
size_t dt_colorspaces_enumerate_profiles(const dt_colorspaces_profile_role_t role,
                                         dt_colorprofile_desc_t **out);
 
int dt_colorspaces_profile_index(const dt_colorspaces_profile_role_t role,
                                 const dt_colorspaces_color_profile_type_t type,
                                 const char *const filename);
 
gboolean dt_colorspaces_profile_at(const dt_colorspaces_profile_role_t role,
                                   const int index,
                                   dt_colorprofile_desc_t *const out);
 
gboolean dt_colorspaces_profile_exists(const dt_colorspaces_profile_role_t role,
                                       const dt_colorspaces_color_profile_type_t type,
                                       const char *const filename);
 
cmsHPROFILE dt_colorspaces_create_xyzimatrix_profile(float cam_xyz[3][3]);
 
cmsHPROFILE dt_colorspaces_create_darktable_profile(const char *makermodel);
 
cmsHPROFILE dt_colorspaces_create_vendor_profile(const char *makermodel);
 
cmsHPROFILE dt_colorspaces_create_alternate_profile(const char *makermodel);
 
void dt_colorspaces_transform_rgba_float_row(const cmsHTRANSFORM transform, const float *in, float *out,
                                             const int width);
 
void dt_colorspaces_transform_rgba_float_image(const cmsHTRANSFORM transform, const float *image_in, float *image_out,
                                               const int width, const int height);
 
 
/* --- prepared display transforms: the cmsHTRANSFORM never leaves the module ---
 *
 * The four cached transforms are deleted and rebuilt whenever the monitor profile or
 * the display intent changes, so a borrowed handle can be freed under its user. These
 * functions take the read lock internally, for the whole conversion -- which is what
 * keeps the handle alive while the pixels are being converted. */
 
void dt_colorprofiles_xyz_to_display(const dt_aligned_pixel_t XYZ, dt_aligned_pixel_t RGB);
 
gboolean dt_colorprofiles_rgba8_to_display_bgra8(const uint8_t *const in, uint8_t *const out,
                                                 const int width, const int height,
                                                 const dt_colorspaces_color_profile_type_t src_space);
 
gboolean dt_colorprofiles_bgra8_to_adobergb_rgba8(const uint8_t *const in, uint8_t *const out,
                                                  const int width, const int height,
                                                  const dt_colorspaces_color_profile_type_t src_space);
 
gboolean dt_colorprofiles_srgb_to_display_strided(uint8_t *const pixels, const int width, const int height,
                                                  const int rowstride, const int n_channels,
                                                  const gboolean has_alpha);
 
 
/* --- display and soft-proofing settings: whole struct in, whole struct out --- */
 
typedef struct dt_colorprofiles_settings_t
{
  dt_colorspaces_color_mode_t mode;                    
  dt_colorspaces_color_profile_type_t display_type;    
  char display_filename[DT_IOP_COLOR_ICC_LEN];         
  dt_iop_color_intent_t display_intent;                
  dt_colorspaces_color_profile_type_t softproof_type;  
  char softproof_filename[DT_IOP_COLOR_ICC_LEN];       
  dt_iop_color_intent_t softproof_intent;              
 
  uint64_t generation;
} dt_colorprofiles_settings_t;
 
void dt_colorprofiles_get_settings(dt_colorprofiles_settings_t *const out);
 
gboolean dt_colorprofiles_set_display_profile_choice(const dt_colorspaces_color_profile_type_t type,
                                                     const char *const filename);
 
gboolean dt_colorprofiles_set_display_intent(const dt_iop_color_intent_t intent);
 
gboolean dt_colorprofiles_set_softproof_profile_choice(const dt_colorspaces_color_profile_type_t type,
                                                       const char *const filename);
 
gboolean dt_colorprofiles_set_softproof_intent(const dt_iop_color_intent_t intent);
 
gboolean dt_colorprofiles_set_mode(const dt_colorspaces_color_mode_t mode);
 
dt_colorspaces_color_mode_t dt_colorprofiles_toggle_mode(const dt_colorspaces_color_mode_t mode);
 
 
cmsHPROFILE dt_colorspaces_get_rgb_profile_from_mem(uint8_t *data, uint32_t size);
 
void dt_colorspaces_cleanup_profile(cmsHPROFILE p);
 
int dt_colorspaces_get_matrix_from_input_profile(cmsHPROFILE prof, dt_colormatrix_t matrix, float *lutr, float *lutg,
                                                 float *lutb, const int lutsize);
 
int dt_colorspaces_get_matrix_from_output_profile(cmsHPROFILE prof, dt_colormatrix_t matrix, float *lutr, float *lutg,
                                                  float *lutb, const int lutsize);
 
void dt_colorspaces_get_profile_name(cmsHPROFILE p, const char *language, const char *country, char *name,
                                     size_t len);
 
const char *dt_colorspaces_get_name(dt_colorspaces_color_profile_type_t type, const char *filename);
 
void rgb2hsl(const dt_aligned_pixel_t rgb, float *h, float *s, float *l);
 
void hsl2rgb(dt_aligned_pixel_t rgb, float h, float s, float l);
 
struct dt_colorspaces_color_profile_t *dt_colorspaces_new_image_profile(
    dt_colorspaces_color_profile_type_t type, cmsHPROFILE profile, gboolean owns_profile);
 
void dt_colorspaces_free_image_profile(struct dt_colorspaces_color_profile_t *profile);
 
typedef void (*dt_colorspaces_profile_changed_handler_t)(void);
 
void dt_colorspaces_set_profile_changed_handler(dt_colorspaces_profile_changed_handler_t handler);
 
void dt_colorspaces_set_display_profile(const dt_colorspaces_color_profile_type_t profile_type,
                                       GtkWidget *widget);
 
const dt_colorspaces_color_profile_t *
dt_colorspaces_get_profile(dt_colorspaces_color_profile_type_t type, const char *filename,
                           dt_colorspaces_profile_role_t role);
 
gboolean  dt_colorspaces_is_profile_equal(const char *fullname, const char *filename);
 
 
void dt_colorspaces_update_display_transforms();
 
int dt_colorspaces_conversion_matrices_xyz(const float adobe_XYZ_to_CAM[4][3], float in_XYZ_to_CAM[9], double XYZ_to_CAM[4][3], double CAM_to_XYZ[3][4]);
 
/* RGB_to_CAM, CAM_to_RGB and mul are OPTIONAL -- the implementation guards each with a NULL
 * check, and both in-tree callers pass NULL for the first two. They are therefore declared as
 * pointers, NOT as double[4][3] / double[3][4] / double[4]. A declared array bound on a
 * parameter is an access contract to GCC (-Wstringop-overflow reads it as "must point to at
 * least this many elements"), so the array spelling asserts a minimum size that NULL cannot
 * satisfy, and every call warned. Do not restore the array bounds. */
/* adobe_XYZ_to_CAM is 12 consecutive floats, row-major, 4 rows of 3 -- pass &m[0][0].
 *
 * It is a FLAT pointer rather than float[4][3] on purpose. As a 2D array parameter it decays
 * to pointer-to-row, and GCC then sizes the accessible region as a single row and reports
 * every call as an overflow: "accessing 48 bytes in a region of size 12". The 48 is right and
 * the 12 is not -- a _Static_assert on sizeof(((dt_image_t *)0)->adobe_XYZ_to_CAM) == 48
 * compiles clean. Four other spellings were tried and none silenced it: pointer-to-row, the
 * C99 [static 4][3] bound, a #pragma GCC diagnostic at the call site (the warning comes from
 * the middle end, which ignores it), and __attribute__((noclone)).
 *
 * RGB_to_CAM, CAM_to_RGB and mul are OPTIONAL -- each is NULL-checked, and both in-tree
 * callers pass NULL for the first two. They are pointers for the same reason: a declared
 * array bound is an access contract GCC reads as "must point to at least this many
 * elements", which NULL cannot satisfy. Do not restore array bounds to any of these. */
int dt_colorspaces_conversion_matrices_rgb(const float *adobe_XYZ_to_CAM, double (*RGB_to_CAM)[3], double (*CAM_to_RGB)[4], const float *embedded_matrix, double *mul);
 
// FIXME: CRITICAL: why is this function NOT used anywhere ???
void dt_colorspaces_cygm_apply_coeffs_to_rgb(float *out, const float *in, int num, double RGB_to_CAM[4][3], double CAM_to_RGB[3][4], dt_aligned_pixel_t coeffs);
 
void dt_colorspaces_cygm_to_rgb(float *out, int num, double CAM_to_RGB[3][4]);
 
void dt_colorspaces_rgb_to_cygm(float *out, int num, double RGB_to_CAM[4][3]);
 
 
 
 
 
 
 
#ifdef __cplusplus
}
#endif
 
#endif // DT_COLORPROFILES_COLORSPACES_H
 
// 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