add libred_get_colour.3

Signed-off-by: Mattias Andrée <maandree@member.fsf.org>

1 files changed, 93 insertions, 0 deletions

diff --git a/doc/man/libred_get_colour.3 b/doc/man/libred_get_colour.3
new file mode 100644
index 0000000..5220067
--- /dev/null
+++ b/doc/man/libred_get_colour.3
@@ -0,0 +1,93 @@
+.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>.
+