Getting `:distant-foreground` face attribute to work

Question

Emacs's faces let you set :distant-foreground, which according to the docs, "is like :foreground but the color is only used as a foreground when the background color is near to the foreground that would have been used."

I'm not really sure how "near" is computed, but it doesn't seem to be good enough. I would like to use it with my region face, so that the text is in the same face it's normally in, except when it's unreadable. My region is currently set to :background "lightgoldenrod2". Selecting some white text with this makes it unreadable. When I set :distant-foreground "black", it doesn't change.

How is "near" calculated here? How can I adjust this calculation to be a more reasonable contrast calculation?

Answer 1

I found part of the answer by reading the source code. In xfaces.c, there is (in load_face_colors)

  dfg = attrs[LFACE_DISTANT_FOREGROUND_INDEX];
  if (!NILP (dfg) && !UNSPECIFIEDP (dfg)
      && color_distance (&xbg, &xfg) < NEAR_SAME_COLOR_THRESHOLD)
    {
      if (EQ (attrs[LFACE_INVERSE_INDEX], Qt))
        face->background = load_color (f, face, dfg, LFACE_BACKGROUND_INDEX);
      else
        face->foreground = load_color (f, face, dfg, LFACE_FOREGROUND_INDEX);
    }

where

/* Returns the `distance' between the colors X and Y.  */

static int
color_distance (XColor *x, XColor *y)
{
  /* This formula is from a paper titled `Colour metric' by Thiadmer Riemersma.
     Quoting from that paper:

     This formula has results that are very close to L*u*v* (with the
     modified lightness curve) and, more importantly, it is a more even
     algorithm: it does not have a range of colors where it suddenly
     gives far from optimal results.

     See <http://www.compuphase.com/cmetric.htm> for more info.  */

  long r = (x->red   - y->red)   >> 8;
  long g = (x->green - y->green) >> 8;
  long b = (x->blue  - y->blue)  >> 8;
  long r_mean = (x->red + y->red) >> 9;

  return
    (((512 + r_mean) * r * r) >> 8)
    + 4 * g * g
    + (((767 - r_mean) * b * b) >> 8);
}

and

#define NEAR_SAME_COLOR_THRESHOLD 30000

Since this is in C, I think this means that this is not really customizable (maybe by rewriting the C function in lisp).

Doing some research, it would be nice to get an algorithm that uses http://web.mst.edu/~rhall/web_design/color_readability.html (the "Algorithm" section), which gives a formula and a good recommended contrast ratio from W3C.

Answer 2

It works for me, but yes, you need to pick a color that is "nearer" than that for it to take effect. From emacs -Q.

I set face default to have a white foreground and a background of #000000004. And I set face region to have a distant foreground of black and a background of #ffffffff3.

Selecting white text shows the region with black text (foreground). Selecting another color of text (e.g. green foreground) shows the region with that same color (green) as foreground.

Try closer colors to see if it at least works in your Emacs version. I'm on MS Windows and using a dev version of Emacs 25 from last October (2014).

And while you're at it, you might consider filing an Emacs bug (M-x report-emacs-bug) for (at least) insufficient doc. If there isn't already (and I couldn't find any in the doc or in NEWS), there should perhaps be a user option, to let you control how close "near" needs to be for :distant-foreground to kick in.