1 files changed, 74 insertions, 0 deletions
diff --git a/man/libred_get_colour.3 b/man/libred_get_colour.3
new file mode 100644
index 0000000..fd32eb3
--- /dev/null
+++ b/man/libred_get_colour.3
@@ -0,0 +1,74 @@
+.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.
+.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)