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.

1 files changed, 14 insertions, 0 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,