1/***************************************************************************/
2/* */
3/* ftlcdfil.h */
4/* */
5/* FreeType API for color filtering of subpixel bitmap glyphs */
6/* (specification). */
7/* */
8/* Copyright 2006-2008, 2010, 2013 by */
9/* David Turner, Robert Wilhelm, and Werner Lemberg. */
10/* */
11/* This file is part of the FreeType project, and may only be used, */
12/* modified, and distributed under the terms of the FreeType project */
13/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
14/* this file you indicate that you have read the license and */
15/* understand and accept it fully. */
16/* */
17/***************************************************************************/
18
19
20#ifndef __FT_LCD_FILTER_H__
21#define __FT_LCD_FILTER_H__
22
23#include <ft2build.h>
24#include FT_FREETYPE_H
25
26#ifdef FREETYPE_H
27#error "freetype.h of FreeType 1 has been loaded!"
28#error "Please fix the directory search order for header files"
29#error "so that freetype.h of FreeType 2 is found first."
30#endif
31
32
33FT_BEGIN_HEADER
34
35 /***************************************************************************
36 *
37 * @section:
38 * lcd_filtering
39 *
40 * @title:
41 * LCD Filtering
42 *
43 * @abstract:
44 * Reduce color fringes of LCD-optimized bitmaps.
45 *
46 * @description:
47 * The @FT_Library_SetLcdFilter API can be used to specify a low-pass
48 * filter, which is then applied to LCD-optimized bitmaps generated
49 * through @FT_Render_Glyph. This is useful to reduce color fringes
50 * that would occur with unfiltered rendering.
51 *
52 * Note that no filter is active by default, and that this function is
53 * *not* implemented in default builds of the library. You need to
54 * #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your `ftoption.h' file
55 * in order to activate it.
56 *
57 * FreeType generates alpha coverage maps, which are linear by nature.
58 * For instance, the value 0x80 in bitmap representation means that
59 * (within numerical precision) 0x80/0xff fraction of that pixel is
60 * covered by the glyph's outline. The blending function for placing
61 * text over a background is
62 *
63 * {
64 * dst = alpha * src + (1 - alpha) * dst ,
65 * }
66 *
67 * which is known as OVER. However, when calculating the output of the
68 * OVER operator, the source colors should first be transformed to a
69 * linear color space, then alpha blended in that space, and transformed
70 * back to the output color space.
71 *
72 * When linear light blending is used, the default FIR5 filtering
73 * weights (as given by FT_LCD_FILTER_DEFAULT) are no longer optimal, as
74 * they have been designed for black on white rendering while lacking
75 * gamma correction. To preserve color neutrality, weights for a FIR5
76 * filter should be chosen according to two free parameters `a' and `c',
77 * and the FIR weights should be
78 *
79 * {
80 * [a - c, a + c, 2 * a, a + c, a - c] .
81 * }
82 *
83 * This formula generates equal weights for all the color primaries
84 * across the filter kernel, which makes it colorless. One suggested
85 * set of weights is
86 *
87 * {
88 * [0x10, 0x50, 0x60, 0x50, 0x10] ,
89 * }
90 *
91 * where `a' has value 0x30 and `b' value 0x20. The weights in filter
92 * may have a sum larger than 0x100, which increases coloration slightly
93 * but also improves contrast.
94 */
95
96
97 /****************************************************************************
98 *
99 * @enum:
100 * FT_LcdFilter
101 *
102 * @description:
103 * A list of values to identify various types of LCD filters.
104 *
105 * @values:
106 * FT_LCD_FILTER_NONE ::
107 * Do not perform filtering. When used with subpixel rendering, this
108 * results in sometimes severe color fringes.
109 *
110 * FT_LCD_FILTER_DEFAULT ::
111 * The default filter reduces color fringes considerably, at the cost
112 * of a slight blurriness in the output.
113 *
114 * FT_LCD_FILTER_LIGHT ::
115 * The light filter is a variant that produces less blurriness at the
116 * cost of slightly more color fringes than the default one. It might
117 * be better, depending on taste, your monitor, or your personal vision.
118 *
119 * FT_LCD_FILTER_LEGACY ::
120 * This filter corresponds to the original libXft color filter. It
121 * provides high contrast output but can exhibit really bad color
122 * fringes if glyphs are not extremely well hinted to the pixel grid.
123 * In other words, it only works well if the TrueType bytecode
124 * interpreter is enabled *and* high-quality hinted fonts are used.
125 *
126 * This filter is only provided for comparison purposes, and might be
127 * disabled or stay unsupported in the future.
128 *
129 * @since:
130 * 2.3.0
131 */
132 typedef enum FT_LcdFilter_
133 {
134 FT_LCD_FILTER_NONE = 0,
135 FT_LCD_FILTER_DEFAULT = 1,
136 FT_LCD_FILTER_LIGHT = 2,
137 FT_LCD_FILTER_LEGACY = 16,
138
139 FT_LCD_FILTER_MAX /* do not remove */
140
141 } FT_LcdFilter;
142
143
144 /**************************************************************************
145 *
146 * @func:
147 * FT_Library_SetLcdFilter
148 *
149 * @description:
150 * This function is used to apply color filtering to LCD decimated
151 * bitmaps, like the ones used when calling @FT_Render_Glyph with
152 * @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
153 *
154 * @input:
155 * library ::
156 * A handle to the target library instance.
157 *
158 * filter ::
159 * The filter type.
160 *
161 * You can use @FT_LCD_FILTER_NONE here to disable this feature, or
162 * @FT_LCD_FILTER_DEFAULT to use a default filter that should work
163 * well on most LCD screens.
164 *
165 * @return:
166 * FreeType error code. 0~means success.
167 *
168 * @note:
169 * This feature is always disabled by default. Clients must make an
170 * explicit call to this function with a `filter' value other than
171 * @FT_LCD_FILTER_NONE in order to enable it.
172 *
173 * Due to *PATENTS* covering subpixel rendering, this function doesn't
174 * do anything except returning `FT_Err_Unimplemented_Feature' if the
175 * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
176 * defined in your build of the library, which should correspond to all
177 * default builds of FreeType.
178 *
179 * The filter affects glyph bitmaps rendered through @FT_Render_Glyph,
180 * @FT_Outline_Get_Bitmap, @FT_Load_Glyph, and @FT_Load_Char.
181 *
182 * It does _not_ affect the output of @FT_Outline_Render and
183 * @FT_Outline_Get_Bitmap.
184 *
185 * If this feature is activated, the dimensions of LCD glyph bitmaps are
186 * either larger or taller than the dimensions of the corresponding
187 * outline with regards to the pixel grid. For example, for
188 * @FT_RENDER_MODE_LCD, the filter adds up to 3~pixels to the left, and
189 * up to 3~pixels to the right.
190 *
191 * The bitmap offset values are adjusted correctly, so clients shouldn't
192 * need to modify their layout and glyph positioning code when enabling
193 * the filter.
194 *
195 * @since:
196 * 2.3.0
197 */
198 FT_EXPORT( FT_Error )
199 FT_Library_SetLcdFilter( FT_Library library,
200 FT_LcdFilter filter );
201
202
203 /**************************************************************************
204 *
205 * @func:
206 * FT_Library_SetLcdFilterWeights
207 *
208 * @description:
209 * Use this function to override the filter weights selected by
210 * @FT_Library_SetLcdFilter. By default, FreeType uses the quintuple
211 * (0x00, 0x55, 0x56, 0x55, 0x00) for FT_LCD_FILTER_LIGHT, and (0x10,
212 * 0x40, 0x70, 0x40, 0x10) for FT_LCD_FILTER_DEFAULT and
213 * FT_LCD_FILTER_LEGACY.
214 *
215 * @input:
216 * library ::
217 * A handle to the target library instance.
218 *
219 * weights ::
220 * A pointer to an array; the function copies the first five bytes and
221 * uses them to specify the filter weights.
222 *
223 * @return:
224 * FreeType error code. 0~means success.
225 *
226 * @note:
227 * Due to *PATENTS* covering subpixel rendering, this function doesn't
228 * do anything except returning `FT_Err_Unimplemented_Feature' if the
229 * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
230 * defined in your build of the library, which should correspond to all
231 * default builds of FreeType.
232 *
233 * This function must be called after @FT_Library_SetLcdFilter to have
234 * any effect.
235 *
236 * @since:
237 * 2.4.0
238 */
239 FT_EXPORT( FT_Error )
240 FT_Library_SetLcdFilterWeights( FT_Library library,
241 unsigned char *weights );
242
243 /* */
244
245
246FT_END_HEADER
247
248#endif /* __FT_LCD_FILTER_H__ */
249
250
251/* END */
252