.TH LIBRED_GET_COLOUR 3 LIBRED
.SH NAME
libred_get_colour \- Calculate a colour temperature
.SH SYNOPSIS
.nf
#include <libred.h>

int \fBlibred_get_colour\fP(long int \fItemp\fP, double *\fIr\fP, double *\fIg\fP, double *\fIb\fP);
int \fBlibred_get_colour_xy\fP(long int \fItemp\fP, double *\fIx\fP, double *\fIy\fP);
.fi
.PP
Link with
.IR -lred .
.SH DESCRIPTION
.BR libred_get_colour ()
gets or interpolates the colour temperature for
.I temp
kelvins, and returns the colour temperature in sRGB, with the
sRGB transfer function applied. The values,
between 0.0 and 1.0, for the \(dqred\(dq, green, and blue channels
are stored in
.IR *r ,
.IR *g ,
and
.IR *b ,
respectively.
.PP
At least one of the values will be 1.0, none will be greater than
1.0, and none will be less than 0.0. It is guaranteed (unless the
resources file has been modified) that
.IR *r ,
.IR *g ,
and
.I *b
all will be 1.0 if
.I temp
is 6500.
.PP
libred has a table of colour temperature values, the
.BR libred_get_colour ()
function interpolates values that are missing. If you
don't want any interpolation the
.I temp
parameter can be specified in one of the following ways:
.TP
floor
.I (temp - LIBRED_LOWEST_TEMPERATURE) / LIBRED_DELTA_TEMPERATURE * LIBRED_DELTA_TEMPERATURE + LIBRED_LOWEST_TEMPERATURE
.TP
ceiling
.I (temp - LIBRED_LOWEST_TEMPERATURE + LIBRED_DELTA_TEMPERATURE - 1) / LIBRED_DELTA_TEMPERATURE * LIBRED_DELTA_TEMPERATURE + LIBRED_LOWEST_TEMPERATURE
.TP
round to nearest
.I (temp - LIBRED_LOWEST_TEMPERATURE + LIBRED_DELTA_TEMPERATURE / 2) / LIBRED_DELTA_TEMPERATURE * LIBRED_DELTA_TEMPERATURE + LIBRED_LOWEST_TEMPERATURE
.PP
The
.BR libred_get_colour_xy ()
function is the same as the
.BR libred_get_colour ()
except it uses the CIE xy colour space instead of sRGB
(of course without any transfer function). This means
that the chroma values x and y are stored in
.I *x
and
.IR *y ,
and the CIE Y value shall be assumed to be 1 for
equivalence with the
.BR libred_get_colour ()
function.
.PP
Neither
.IR r ,
.IR g ,
.IR b ,
.IR x ,
nor
.I y
may be
.IR NULL .
.SH RETURN VALUE
Upon successful completion, the
.BR libred_get_colour ()
and
.BR libred_get_colour_xy ()
function returns 0. On failure, the function returns -1 and sets
.I errno
to indicate the error.
.SH ERRORS
The
.BR libred_get_colour ()
and
.BR libred_get_colour_xy ()
functions may fail if:
.TP
.B EDOM
If
.I temp
is less than
.B LIBRED_LOWEST_TEMPERATURE
(which is 1000).
.SH SEE ALSO
.BR libred.h (0),
.BR libred (7),
.BR libred_get_solar_elevation (3)