From cdd24fd459d15b8a00498b284d00c202cf872022 Mon Sep 17 00:00:00 2001
From: Ben Harris <bjh21@bjh21.me.uk>
Date: Sat, 17 Dec 2022 22:50:52 +0000
Subject: [PATCH] Expose colour_mix() to backends (and others)

Quite a few backends currently generate colours by multiplying the
foreground colour by a fraction, effectively mixing it with black.  On a
black background, this might be reasonably replaced by mixing the
background colour with white, but that's rather arithmetically fiddly.
Happily, I already have a function for that and just need to expose it.
---
 devel.but | 14 ++++++++++++++
 misc.c    |  3 +--
 puzzles.h |  3 +++
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/devel.but b/devel.but
index 93fd84e..b390ec4 100644
--- a/devel.but
+++ b/devel.but
@@ -4937,6 +4937,20 @@ more flexible than standard \cw{qsort()}: it lets you vary the sorting
 criterion in a dynamic manner without having to write global variables
 in the caller for the compare function to read.
 
+\S{utils-colour-mix} \cw{colour_mix()}
+
+\c void colour_mix(const float src1[3], const float src2[3], float p,
+\c                 float dst[3]);
+
+This function mixes the colours \c{src1} and \c{src2} in specified
+proportions, producing \c{dst}.  \c{p} is the proportion of \c{src2}
+in the result.  So if \c{p} is \cw{1.0}, \cw{dst} will be the same as
+\c{src2}.  If \c{p} is \cw{0.0}, \cw{dst} will be the same as
+\c{src1}.  And if \{p} is somewhere in between, so will \c{dst} be.
+\c{p} is not restricted to the range \cw{0.0} to \cw{1.0}.  Values
+outside that range will produce extrapolated colours, which may be
+useful for some purposes, but may also produce impossible colours.
+
 \S{utils-game-mkhighlight} \cw{game_mkhighlight()}
 
 \c void game_mkhighlight(frontend *fe, float *ret,
diff --git a/misc.c b/misc.c
index aaabb39..c4c4b69 100644
--- a/misc.c
+++ b/misc.c
@@ -207,8 +207,7 @@ static float colour_distance(const float a[3], const float b[3])
                        (a[2]-b[2]) * (a[2]-b[2]));
 }
 
-static void colour_mix(const float src1[3], const float src2[3],
-                       float p, float dst[3])
+void colour_mix(const float src1[3], const float src2[3], float p, float dst[3])
 {
     int i;
     for (i = 0; i < 3; i++)
diff --git a/puzzles.h b/puzzles.h
index 9d02cd5..cbe7f88 100644
--- a/puzzles.h
+++ b/puzzles.h
@@ -374,6 +374,9 @@ char *fgetline(FILE *fp);
 char *bin2hex(const unsigned char *in, int inlen);
 unsigned char *hex2bin(const char *in, int outlen);
 
+/* Mixes two colours in specified proportions. */
+void colour_mix(const float src1[3], const float src2[3], float p,
+                float dst[3]);
 /* Sets (and possibly dims) background from frontend default colour,
  * and auto-generates highlight and lowlight colours too. */
 void game_mkhighlight(frontend *fe, float *ret,