More documentation1.0.1

Signed-off-by: Mattias Andrée <maandree@kth.se>

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 <stddef.h>
 
 
-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 ()