compat-28: Add color-dark-p

4 files changed, 46 insertions, 2 deletions

diff --git a/NEWS.org b/NEWS.org
index 6335fb2..9452ecf 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -4,6 +4,7 @@
 
 - compat-27: Add ~date-ordinal-to-time~.
 - compat-27: Add ~make-decoded-time~.
+- compat-28: Add ~color-dark-p~.
 
 * Release of "Compat" Version 29.1.2.0
 
diff --git a/compat-28.el b/compat-28.el
index dec2d8c..55e0b75 100644
--- a/compat-28.el
+++ b/compat-28.el
@@ -635,6 +635,37 @@ is included in the return value."
                   default)))
    ": "))
 
+;;;; Defined in faces.el
+
+(compat-defvar color-luminance-dark-limit 0.325 ;; <compat-tests:color-dark-p>
+  "The relative luminance below which a color is considered \"dark\".
+A \"dark\" color in this sense provides better contrast with white
+than with black; see `color-dark-p'.
+This value was determined experimentally."
+  :constant t)
+
+(compat-defun color-dark-p (rgb) ;; <compat-tests:color-dark-p>
+  "Whether RGB is more readable against white than black.
+RGB is a 3-element list (R G B), each component in the range [0,1].
+This predicate can be used both for determining a suitable (black or white)
+contrast color with RGB as background and as foreground."
+  (unless (<= 0 (apply #'min rgb) (apply #'max rgb) 1)
+    (error "RGB components %S not in [0,1]" rgb))
+  ;; Compute the relative luminance after gamma-correcting (assuming sRGB),
+  ;; and compare to a cut-off value determined experimentally.
+  ;; See https://en.wikipedia.org/wiki/Relative_luminance for details.
+  (let* ((sr (nth 0 rgb))
+         (sg (nth 1 rgb))
+         (sb (nth 2 rgb))
+         ;; Gamma-correct the RGB components to linear values.
+         ;; Use the power 2.2 as an approximation to sRGB gamma;
+         ;; it should be good enough for the purpose of this function.
+         (r (expt sr 2.2))
+         (g (expt sg 2.2))
+         (b (expt sb 2.2))
+         (y (+ (* r 0.2126) (* g 0.7152) (* b 0.0722))))
+    (< y color-luminance-dark-limit)))
+
 ;;;; Defined in windows.el
 
 (compat-defun count-windows (&optional minibuf all-frames) ;; <compat-tests:count-windows>
diff --git a/compat-tests.el b/compat-tests.el
index 98c10d4..cad2b45 100644
--- a/compat-tests.el
+++ b/compat-tests.el
@@ -2263,6 +2263,12 @@
     (goto-char (point-max))
     (should-not (text-property-search-backward 'non-existant))))
 
+(ert-deftest color-dark-p ()
+  (should (color-dark-p '(0 0 0)))
+  (should (color-dark-p '(0.5 0.5 0.5)))
+  (should-not (color-dark-p '(0.5 0.7 0.5)))
+  (should-not (color-dark-p '(1 1 1 ))))
+
 (ert-deftest color-values-from-color-spec ()
   ;; #RGB notation
   (should-equal '(0 0 0) (color-values-from-color-spec "#000"))
diff --git a/compat.texi b/compat.texi
index 0f8fa12..353de31 100644
--- a/compat.texi
+++ b/compat.texi
@@ -1776,6 +1776,14 @@ environment variable and @var{value} is that variable's value.
 @xref{System Environment,System Environment,,elisp}.
 @end defmac
 
+@c based on lisp/faces.el
+@defun color-dark-p rgb
+Whether @var{rgb} is more readable against white than black. @var{rgb}
+is a 3-element list (R G B), each component in the range [0,1].  This
+predicate can be used both for determining a suitable (black or white)
+contrast color with RGB as background and as foreground.
+@end defun
+
 @c based on src/xfaces.c
 @defun color-values-from-color-spec spec
 Convert the textual color specification @var{spec} to a color triple
@@ -1970,8 +1978,6 @@ The function @code{split-string-shell-command}.
 @item
 The function @code{string-limit}.
 @item
-The function @code{color-dark-p}.
-@item
 The function @code{innermost-minibuffer-p}.
 @item
 The function @code{max-mini-window-lines}.