// // Color contrast functions for the Fast Light Tool Kit (FLTK). // // Copyright 1998-2024 by Bill Spitzak and others. // // This library is free software. Distribution and use rights are outlined in // the file "COPYING" which should have been included with this file. If this // file is missing or damaged, see the license at: // // https://www.fltk.org/COPYING.php // // Please see the following page on how to report bugs and issues: // // https://www.fltk.org/bugs.php // /** \file fl_contrast.cxx \brief Color contrast handling Implementation of fl_contrast() and its variants. */ #include #include #ifndef DEBUG_CONTRAST_LEGACY #define DEBUG_CONTRAST_LEGACY 0 #endif // DEBUG_CONTRAST_LEGACY // Initial values of global/static variables defined by fl_contrast_* functions. // This defines the default contrast mode since FLTK 1.4.0 static int fl_contrast_mode_ = FL_CONTRAST_CIELAB; // This defines the default contrast level per contrast mode static int fl_contrast_level_[10] = { 0, // 0 = FL_CONTRAST_NONE 50, // 1 = FL_CONTRAST_LEGACY 39, // 2 = FL_CONTRAST_CIELAB 0, // 3 = FL_CONTRAST_CUSTOM 0 // 4-9 = not yet defined }; // There is no default custom contrast function static Fl_Contrast_Function *fl_contrast_function_ = 0; // The following function is (and must be!) the same as Fl::get_color() but // can be inlined. We need this additional implementation because all contrast // related functions have been moved from fl_color.cxx to fl_contrast.cxx // or have been directly implemented in fl_contrast.cxx (new functions). // Inlining will hopefully prevent an extra function call. extern unsigned fl_cmap[256]; // defined in fl_color.cxx inline unsigned get_color(Fl_Color i) { // see Fl::get_color() ! if (i & 0xffffff00) return (i); else return fl_cmap[i]; } /** \addtogroup fl_attributes \{ */ /** Return the raw / physical luminance of a color. This function calculates the physical luminance of Fl_Color \p color. The returned luminance value (aka \p Y) is the physical luminance of the Fl_Color \p color. The result is in the range 0.0 (black) to 1.0 (white). \note This is probably not what you want if you are interested in perceived contrast or lightness calculation because the luminance \p Y is \b not linear with respect to human perception. See fl_lightness(Fl_Color) for a function that returns the perceived lightness of a color which can be used directly for contrast calculation. \param[in] color Fl_Color value \return Raw (physical) luminance (0.0 .. 1.0) \since 1.4.0 \see fl_lightness(Fl_Color) */ double fl_luminance(Fl_Color color) { // Get the sRGB (0xrrggbb) components of the FLTK color unsigned col = get_color(color) >> 8; int r = (col & 0xFF0000) >> 16; int g = (col & 0x00FF00) >> 8; int b = (col & 0x0000FF); return (0.2126729 * pow(r/255.0, 2.4) + 0.7151522 * pow(g/255.0, 2.4) + 0.0721750 * pow(b/255.0, 2.4)); } /** Return the perceived lightness of a color. This function calculates the perceived lightness of Fl_Color \p color. The returned lightness value \p Lstar according to the CIELAB (L*a*b*) color model is almost linear with respect to human perception. It is in the range 0 (black) to 100 (white). The result values of two colors can be compared directly and the difference is their perceived contrast. \param[in] color Fl_Color value \return perceived lightness (0 .. 100) \since 1.4.0 */ double fl_lightness(Fl_Color color) { // compute the raw luminance Y (0.0 .. 1.0) double Y = fl_luminance(color); // return the perceived lightness L* (Lstar) if (Y <= (216/24389.)) return Y * (24389/27.); else return pow(Y, (1/3.)) * 116 - 16; } /** Set the contrast level (sensitivity) of the fl_contrast() method. This can be used to tune the legacy fl_contrast() function to achieve slightly better results. The default value is defined per contrast mode (see below). Values between 50 and 70 may be useful for the legacy contrast mode but you can raise it up to 100. Lower values than 50 are probably not useful. The contrast \p level affects not only the legacy (1.3.x) fl_contrast() function but also the new CIELAB contrast mode which is the default since FLTK 1.4.0. See default value below. Other contrast modes are currently not affected by the contrast level. You may use the contrast level if you define your own custom contrast function in mode FL_CONTRAST_CUSTOM. \note All contrast modes store their own contrast level because the behavior is slightly different. You must change the contrast mode fl_contrast_mode() \b before you set or get the contrast level. The default contrast level is - 50 in mode FL_CONTRAST_LEGACY (compatible with FLTK 1.3.x) - 39 in mode FL_CONTRAST_CIELAB (similar threshold as in FLTK 1.3.x) - 0 (undefined) for all other modes See the description of fl_contrast_mode(int mode) for more information about the contrast level per mode. Example: \code fl_contrast_mode(FL_CONTRAST_LEGACY); fl_contrast_level(60); \endcode A \p level greater than 50 (probably best in the range 50 to 70) may achieve better results of the legacy fl_contrast() function in some border cases of low contrast between foreground and background colors but we recommend to use the new default algorithm \c FL_CONTRAST_CIELAB unless you need strict backwards compatibility or use a CPU constrained embedded system. \param[in] level valid range is 0 to 100 \since 1.4.0 */ void fl_contrast_level(int level) { if (level < 0) level = 0; else if (level > 100) level = 100; fl_contrast_level_[fl_contrast_mode_] = level; } /** Get the contrast level (sensitivity) of the fl_contrast() method. This returns the level of the currently selected contrast mode. \return The current contrast level. \see fl_contrast_level(int level) \see fl_contrast_mode(int mode) \since 1.4.0 */ int fl_contrast_level() { return fl_contrast_level_[fl_contrast_mode_]; } /** Set the contrast algorithm (mode). You can use one of - FL_CONTRAST_NONE (not recommended: returns the foreground color) - FL_CONTRAST_LEGACY (same as in FLTK 1.3.x) - FL_CONTRAST_CIELAB (better, this is the default since FLTK 1.4.0) - FL_CONTRAST_CUSTOM (you must define your own contrast algorithm) If you set FL_CONTRAST_CUSTOM you must also register your custom contrast function by calling fl_contrast_function(). You may set the contrast level fl_contrast_level(int) after setting the contrast mode. This affects the contrast algorithm as described below: - FL_CONTRAST_LEGACY: default level is 50 which is compatible with FLTK 1.3.x and older. This mode is no longer the default and is not recommended because it doesn't take human contrast perception into account and doesn't properly handle sRGB color values. You may get better contrasts if you set the level higher than 50. Values in the range 50 to 70 may be useful. Higher values result in higher contrast, i.e. the algorithm switches "earlier" to black or white mode. - FL_CONTRAST_CIELAB: defaut level is 39 which appears to be a good value. The higher the level is, the more contrast is to be expected. Values in the range below 39 accept lower contrast and values above 39 switch "earlier" to black or white. Values between 36 and 46 may yield usable contrast experience. \note The goal of fl_contrast() is to achieve a "sufficient" contrast between text and background. Level 39 in CIELAB mode means that the accepted contrast is about 39% of the lightness difference between both colors. This can be perceived as very low contrast in some cases, but the text should at least be readable. Note that the highest possible contrast value on a medium gray background is 50% (either black or white). Bill Spitzak wrote on May 16, 2024 in fltk.general in thread "FLTK 1.4 Menu Bar Style": "I would certainly aim for a function that does not alter color combinations where it is physically possible to read the text, even if squinting is needed."\n See https://groups.google.com/g/fltkgeneral/c/EkWI4HTHSLA/m/rsZunZ1vAwAJ \param[in] mode if invalid, FL_CONTRAST_CIELAB will be selected \since 1.4.0 \see fl_contrast_function(Fl_Contrast_Function *) \see fl_contrast_level(int) */ void fl_contrast_mode(int mode) { if (mode >= 0 && mode < FL_CONTRAST_LAST) fl_contrast_mode_ = mode; else fl_contrast_mode_ = FL_CONTRAST_CIELAB; } /** Return the current contrast algorithm (mode). \return Contrast algorithm (mode). \since 1.4.0 \see fl_contrast_mode(int) */ int fl_contrast_mode() { return fl_contrast_mode_; } /** Register a custom contrast function. Your custom contrast function will be called when fl_contrast() is called if and only if you previously registered your function and called fl_contrast_mode(FL_CONTRAST_CUSTOM) . Your custom contrast function must provide the signature \code Fl_Color my_contrast_function(Fl_Color fg, Fl_Color bg, int context, int size) \endcode The arguments are the same as for the full fl_contrast() function since FLTK 1.4. You can use the supplied \p size to modify the result. Depending on the caller the \p size parameter can be 0 (default) or a valid size. In the context of text, i.e. \p context == 0, the \p size parameter is the fontsize. The \p context parameter is not yet used and will always be 0 unless included in a call to fl_contrast(). The value 0 must be interpreted as text. In the future the \p context argument will be used to supply a different context than text (small icons, large icons, etc.). The exact usage is not yet specified. Your function may also use fl_contrast_level() to modify the result accordingly. \since 1.4.0 \see fl_contrast_mode(int) \see fl_contrast_level(int) \see fl_contrast() */ void fl_contrast_function(Fl_Contrast_Function *f) { fl_contrast_function_ = f; } /* Returns a color that contrasts with the background color. This is functionally identical to the algorithm used in FLTK 1.3.x, modified only to utilize fl_contrast_level() (since 1.4.0). *** This function is intentionally not public and not documented. *** Do not change this except for level adjustment (backwards compatibility). Note: this is fast but *inaccurate* WRT human contrast perception. The default since FLTK 1.4 is to use fl_contrast_cielab(). \param[in] fg,bg foreground and background colors \param[in] fs,context fontsize and context (unused) \return contrasting color */ static Fl_Color fl_contrast_legacy(Fl_Color fg, Fl_Color bg, int context, int size) { (void) context; // currently ignored (void) size; // currently ignored // internal static variables, recalculated only if fl_contrast_level() is changed static int level = 50; // default, compatible with FLTK 1.3.x static int tc = 99; // sufficient contrast threshold (99 <=> 38.82 %) static int tbw = 127; // black/white threshold (127 <=> 49.80 %) // new in FLTK 1.4: adjust thresholds if fl_contrast_level() was changed if (fl_contrast_level() != level) { level = fl_contrast_level(); if (level == 100) tc = 256; else if (level == 0) tc = 0; else if (level > 50) tc = 99 + ((level - 50) * (255 - 99) / 50); else tc = 99 - ((50 - level) * 99 / 50); } // Get the real sRGB values for each color... unsigned cfg = get_color(fg); unsigned cbg = get_color(bg); // Compute the luminance for each color (0 .. 255) // Note: FLTK 1.3 compatible, don't change this! int lfg = ((cfg >> 24) * 30 + ((cfg >> 16) & 255) * 59 + ((cfg >> 8) & 255) * 11) / 100; int lbg = ((cbg >> 24) * 30 + ((cbg >> 16) & 255) * 59 + ((cbg >> 8) & 255) * 11) / 100; int lc = lfg - lbg; // calculated contrast (-255 .. 255) #if DEBUG_CONTRAST_LEGACY const char *rv = "?"; // return value as text (init) if (lc > tc || lc < -tc) rv = "fg"; // sufficient contrast else if (lbg > tbw) rv = "BLACK"; // light background else rv = "WHITE"; // dark background printf("fl_contrast_legacy: lfg %4d (%7.2f) lbg %4d (%7.2f) lc %4d (%7.2f) => %s\n", lfg, lfg/255.*100, lbg, lbg/255.*100, lc, lc/255.*100, rv); #endif // DEBUG_CONTRAST_LEGACY // Compare and return the contrasting color... if (lc > tc || lc < -tc) return fg; // sufficient contrast if (lbg > tbw) return FL_BLACK; // light background return FL_WHITE; // dark background } /* Returns a color that contrasts with the background color. ** This function is intentionally not public and not documented. ** This is an improved algorithm compared to the one used in FLTK 1.3.x. It is slower (uses floating point and pow()) but is much more accurate WRT human contrast perception. \param[in] fg,bg foreground and background colors \param[in] fs,context unused: fontsize and context \return contrasting color */ static Fl_Color fl_contrast_cielab(Fl_Color fg, Fl_Color bg, int context, int size) { (void) context; // currently ignored (void) size; // currently ignored double tc = (double)fl_contrast_level(); // sufficient contrast threshold double tbw = 50.; // black/white threshold // Compute the perceived lightness L* (Lstar) and the contrast double lfg = fl_lightness(fg); double lbg = fl_lightness(bg); double lc = lfg - lbg; // Compare and return the contrasting color... if (lc >= tc || lc <= -tc) return fg; // sufficient contrast if (lbg > tbw) return (Fl_Color)FL_BLACK; // black return (Fl_Color)FL_WHITE; // white } /** Returns a color that contrasts with the background color. This will be the foreground color if it contrasts sufficiently with the background color. Otherwise, returns \p FL_WHITE or \p FL_BLACK depending on which color provides the best contrast. FLTK 1.4.0 uses a different default contrast function than earlier releases (1.3.x) but you can use the old "legacy" contrast function by calling \code fl_contrast_mode(FL_CONTRAST_LEGACY); \endcode early in your main program. \note It is a known issue that static initialization using fl_contrast() may already have been executed before you call this function in main(). You should be aware of this and, if necessary, write your own (static) contrast initialization function. This should rarely be necessary. You can change the behavior of fl_contrast() in several ways: - Change the "level" (sensitivity) for contrast calculation, see fl_contrast_level(). Valid levels are 0 - 100, the default "medium" value depends on the contrast mode. If you raise the level above the default value the overall contrast will generally be higher, i.e. the required contrast to return the foreground color is raised and therefore the calculated color switches "earlier" to either black or white. In other words, using the following values: - 0 always uses the foreground color - the default, unmodified algorithm allows a sufficient contrast such that the text is readable - 100 will always use black or white Changing the \p level is particularly useful and intended for the "legacy mode" to improve the results partially. Values slightly above 50 (50 - 70) will likely return the best results (50 is the default, as used in FLTK 1.3.x). \note Different contrast modes (algorithms) can use their own values and defaults of fl_contrast_level(). - Change the used contrast calculation function. You can either use the old (FLTK 1.3.x) function or use the better but slower function based on the CIELAB (L*a*b*) color model, or you can define your own custom contrast function if you need even better contrast results. The following contrast functions are available: - FL_CONTRAST_LEGACY, the old FLTK 1.3.x compatible function. This is the fastest function (using integer arithmetic) but it provides worse results in border cases. You may want to use this on embedded or otherwise CPU constrained systems or if you need strict backwards compatibility. For slightly better results you may utilize the new fl_contrast_level(int) function (since 1.4.0) to increase the contrast sensitivity. This will provide slightly better results than FLTK 1.3.x and earlier but we recommend to use the new default function: - FL_CONTRAST_CIELAB, based on the CIELAB (L*a*b*) color model. This function is superior regarding the human contrast perception but may be slightly slower - which should not matter on a modern CPU. The default contrast level in this mode is 39 which results in a very similar experience as the old contrast function but avoids unreadable border cases. This is the default since FLTK 1.4.0. - FL_CONTRAST_CUSTOM, your own contrast calculation function. In the future we \b may provide even more (and superior) contrast algorithms. The new parameters \p context and \p size (since 1.4.0) are defined for future extensions and are currently not used. Default values are 0. - The \p context is intended to differentiate text and other kinds of objects, e.g. radio buttons, check marks, or icon types. - The \p size parameter is an unspecified (object) size that may be used to calculate the required contrast. In text mode this must be the font size. Rule: the larger the object (font), the lower the required contrast. \note These new optional parameters must be provided in the custom contrast function which is the reason why they are added now. In the future we may use the (font) size to adjust the calculated contrast, and users defining their own contrast functions may use them in their functions. \param[in] fg foreground (text) color \param[in] bg background color \param[in] context graphical context (optional, default = 0 == text) \param[in] size unspecified size (optional, default = 0 == undefined) \return contrasting color: \p fg, \p FL_BLACK, or \p FL_WHITE \see fl_contrast_level(int) \see fl_contrast_mode(int) \see fl_contrast_function() */ Fl_Color fl_contrast(Fl_Color fg, Fl_Color bg, int context, int size) { switch (fl_contrast_mode_) { case FL_CONTRAST_LEGACY: return fl_contrast_legacy(fg, bg, context, size); case FL_CONTRAST_CUSTOM: if (fl_contrast_function_) return (fl_contrast_function_)(fg, bg, context, size); // FALLTHROUGH case FL_CONTRAST_CIELAB: return fl_contrast_cielab(fg, bg, context, size); default: // unknown (none): return fg break; } return fg; } // fl_contrast() /** \} */