.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);
.fi
.PP
Link with
.IR -lred .
.SH DESCRIPTION
.B libred_get_colour
gets or interpolates the colour temperature for
.I temp
kelvins, and returns the colour temperature in sRGB. The values,
between 0.0 and 1.0, for the "red", 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
You must call
.BR libred_init_colour (3)
before the first use of this function,
and you should call
.BR libred_term_colour (3)
after the last use of this function.
.SH "RETURN VALUE"
Upon successful completion, the function returns 0. On failure,
the function returns -1 and sets
.B errno
appropriately.
.SH ERRORS
The function may fail if:
.TP
.B EOVERFLOW
The colour temperature lookup table is smaller than it should be.
.TP
.B EDOM
If
.I temp
is less than
.B LIBRED_LOWEST_TEMPERATURE
(which is 1000.)
.PP
The function may also fail for any reason specified for
.BR pread (3),
and set the value of
.B errno
to the same values.
.B errno
is always set to 0 on success.
.SH "FUTURE DIRECTIONS"
It is possible that the behaviour is changed to loading the
colour temperature lookup table rather than just open a
file descriptor to it.
.SH "SEE ALSO"
.BR libred.h (0),
.BR libred (7),
.BR libred_init_colour (3),
.BR libred_term_colour (3)
.SH LICENSE
Copyright \(co 2016 Mattias Andrée
.br
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
.br
This is free software: you are free to change and redistribute it.
.br
There is NO WARRANTY, to the extent permitted by law.
.PP
Copying and distribution of this manual, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved. This file is offered as-is,
without any warranty.
.SH BUGS
Please report bugs to <https://github.com/maandree/libred/issues>
or to <maandree@member.fsf.org>.
