From a9a38b5d18bddcc25cb616275cb163afe3c1ed5e Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Thu, 10 Oct 2019 12:11:54 +0200 Subject: More documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- blackbody.c | 42 +++++++++++++++++++++++++++++++++++------- generate-table.c | 7 ++++--- libred.h | 27 ++++++++++++++++++++++++++- libred_get_colour.3 | 16 ++++++++++++++++ 4 files changed, 81 insertions(+), 11 deletions(-) diff --git a/blackbody.c b/blackbody.c index 9dfe1a8..e654c9d 100644 --- a/blackbody.c +++ b/blackbody.c @@ -11,14 +11,17 @@ #include -struct xy {double x, y;}; -struct rgb {double r, g, b;}; - -static struct xy xy_table[] = { +/** + * Colour temperatures in CIE xy (xyY without Y) + */ +static struct xy {double x, y;} xy_table[] = { #include "10deg-xy.i" }; -static struct rgb rgb_table[] = { +/** + * Colour temperatures in sRGB + */ +static struct rgb {double r, g, b;} rgb_table[] = { #include "10deg-rgb.i" }; @@ -105,12 +108,37 @@ interpolate(double x1, double y1, double x2, double y2, double temp, double *r, /** * Get the [0, 1] sRGB values of a colour temperature * + * libred has a table of colour temperature values, this + * function interpolates values that are missing. If you + * don't want any interpolation the `temp` parameter can + * be specified in one of the following ways: + * + * - floor: + * (temp - LIBRED_LOWEST_TEMPERATURE) / + * LIBRED_DELTA_TEMPERATURE * + * LIBRED_DELTA_TEMPERATURE + + * LIBRED_LOWEST_TEMPERATURE + * + * - ceiling: + * (temp - LIBRED_LOWEST_TEMPERATURE + + * LIBRED_DELTA_TEMPERATURE - 1) / + * LIBRED_DELTA_TEMPERATURE * + * LIBRED_DELTA_TEMPERATURE + + * LIBRED_LOWEST_TEMPERATURE + * + * - round to nearest: + * (temp - LIBRED_LOWEST_TEMPERATURE + + * LIBRED_DELTA_TEMPERATURE / 2) / + * LIBRED_DELTA_TEMPERATURE * + * LIBRED_DELTA_TEMPERATURE + + * LIBRED_LOWEST_TEMPERATURE + * * @param temp The desired colour temperature * @param r Output parameter for the “red” value * @param g Output parameter for the green value * @param b Output parameter for the blue value * @return 0 on succeess, -1 on error - * @throws EDOM The selected temperature is below 1000 K + * @throws EDOM The selected temperature is below 1000K */ int libred_get_colour(long int temp, double *r, double *g, double *b) @@ -126,7 +154,7 @@ libred_get_colour(long int temp, double *r, double *g, double *b) return -1; } - if (temp % LIBRED_DELTA_TEMPERATURE) { /* TODO make optional */ + if (temp % LIBRED_DELTA_TEMPERATURE) { i = (temp - LIBRED_LOWEST_TEMPERATURE) / LIBRED_DELTA_TEMPERATURE; x1 = xy_table[i].x; y1 = xy_table[i].y; diff --git a/generate-table.c b/generate-table.c index ac89af7..7be406f 100644 --- a/generate-table.c +++ b/generate-table.c @@ -9,9 +9,10 @@ # pragma GCC diagnostic ignored "-Wfloat-equal" #endif -struct xy {double x, y;}; - -static struct xy xy_table[] = { +/** + * Colour temperatures in CIE xy (xyY without Y) + */ +static struct xy {double x, y;} xy_table[] = { #include "10deg-xy.i" }; diff --git a/libred.h b/libred.h index 57b17c7..3a52388 100644 --- a/libred.h +++ b/libred.h @@ -176,13 +176,38 @@ int libred_check_timetravel(void); /** * Get the [0, 1] sRGB values of a colour temperature * + * libred has a table of colour temperature values, this + * function interpolates values that are missing. If you + * don't want any interpolation the `temp` parameter can + * be specified in one of the following ways: + * + * - floor: + * (temp - LIBRED_LOWEST_TEMPERATURE) / + * LIBRED_DELTA_TEMPERATURE * + * LIBRED_DELTA_TEMPERATURE + + * LIBRED_LOWEST_TEMPERATURE + * + * - ceiling: + * (temp - LIBRED_LOWEST_TEMPERATURE + + * LIBRED_DELTA_TEMPERATURE - 1) / + * LIBRED_DELTA_TEMPERATURE * + * LIBRED_DELTA_TEMPERATURE + + * LIBRED_LOWEST_TEMPERATURE + * + * - round to nearest: + * (temp - LIBRED_LOWEST_TEMPERATURE + + * LIBRED_DELTA_TEMPERATURE / 2) / + * LIBRED_DELTA_TEMPERATURE * + * LIBRED_DELTA_TEMPERATURE + + * LIBRED_LOWEST_TEMPERATURE + * * @param temp The desired colour temperature * @param r Output parameter for the “red” value * @param g Output parameter for the green value * @param b Output parameter for the blue value * @return 0 on succeess, -1 on error * - * @throws EDOM The selected temperature is below 1000 K + * @throws EDOM The selected temperature is below 1000K */ int libred_get_colour(long int, double *, double *, double *); diff --git a/libred_get_colour.3 b/libred_get_colour.3 index d169a60..afd0a7f 100644 --- a/libred_get_colour.3 +++ b/libred_get_colour.3 @@ -33,6 +33,22 @@ and 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 .SH RETURN VALUE Upon successful completion, the .BR libred_get_colour () -- cgit v1.2.3-70-g09d2