More documentation1.0.1

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

1 files changed, 35 insertions, 7 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;