* include/freetype/ftlcdfil.h: Add description of color filtering. Based on a contribution from Antti S. Lankila <alankila@bel.fi>.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
diff --git a/ChangeLog b/ChangeLog
index 1f1fd5f..bc3b11f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2013-03-29 Werner Lemberg <wl@gnu.org>
+
+ * include/freetype/ftlcdfil.h: Add description of color filtering.
+
+ Based on a contribution from Antti S. Lankila <alankila@bel.fi>.
+
2013-03-23 Werner Lemberg <wl@gnu.org>
[autofit] Minor.
diff --git a/include/freetype/ftlcdfil.h b/include/freetype/ftlcdfil.h
index 0b55ebe..8b253f1 100644
--- a/include/freetype/ftlcdfil.h
+++ b/include/freetype/ftlcdfil.h
@@ -53,6 +53,44 @@ FT_BEGIN_HEADER
* *not* implemented in default builds of the library. You need to
* #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your `ftoption.h' file
* in order to activate it.
+ *
+ * FreeType generates alpha coverage maps, which are linear by nature.
+ * For instance, the value 0x80 in bitmap representation means that
+ * (within numerical precision) 0x80/0xff fraction of that pixel is
+ * covered by the glyph's outline. The blending function for placing
+ * text over a background is
+ *
+ * {
+ * dst = alpha * src + (1 - alpha) * dst ,
+ * }
+ *
+ * which is known as OVER. However, when calculating the output of the
+ * OVER operator, the source colors should first be transformed to a
+ * linear color space, then alpha blended in that space, and transformed
+ * back to the output color space.
+ *
+ * When linear light blending is used, the default FIR5 filtering
+ * weights (as given by FT_LCD_FILTER_DEFAULT) are no longer optimal, as
+ * they have been designed for black on white rendering while lacking
+ * gamma correction. To preserve color neutrality, weights for a FIR5
+ * filter should be chosen according to two free parameters `a' and `c',
+ * and the FIR weights should be
+ *
+ * {
+ * [a - c, a + c, 2 * a, a + c, a - c] .
+ * }
+ *
+ * This formula generates equal weights for all the color primaries
+ * across the filter kernel, which makes it colorless. One suggested
+ * set of weights is
+ *
+ * {
+ * [0x10, 0x50, 0x60, 0x50, 0x10] ,
+ * }
+ *
+ * where `a' has value 0x30 and `b' value 0x20. The weights in filter
+ * may have a sum larger than 0x100, which increases coloration slightly
+ * but also improves contrast.
*/