mirror of
https://github.com/fltk/fltk.git
synced 2026-05-14 12:38:40 +08:00
Albrecht Schlosser
d0922792ae
- swap 3rd and 4th parameter of fl_contrast() - change 'Fl_Fontsize fs' to a neutral 'int size' parameter - clarify documentation of fl_contrast_level() and that different contrast algorithms use different level values - clarify that level 39 for the CIELAB mode results in "sufficient" contrast, i.e. /readable/ text which is the only intention of fl_contrast(). Reasoning: swapping the arguments looks more natural, i.e. the context before another argument (size) is what one would usually expect. Since the 'size' argument doesn't have be a font size, making it a simple 'int size' is more flexible and correct for future extensions.
532 lines
19 KiB
C++
532 lines
19 KiB
C++
//
|
|
// 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 <FL/Fl.H>
|
|
#include <math.h>
|
|
|
|
#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>"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."</i>\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.
|
|
<b>This is the default since FLTK 1.4.0.</b>
|
|
|
|
- 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()
|
|
|
|
/**
|
|
\}
|
|
*/
|