]>
Commit | Line | Data |
---|---|---|
7407ac7f BB |
1 | /***************************************************************************/ |
2 | /* */ | |
3 | /* ftlcdfil.h */ | |
4 | /* */ | |
5 | /* FreeType API for color filtering of subpixel bitmap glyphs */ | |
6 | /* (specification). */ | |
7 | /* */ | |
8 | /* Copyright 2006, 2007, 2008, 2010 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 | ||
33 | FT_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 | * which 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 | ||
246 | FT_END_HEADER | |
247 | ||
248 | #endif /* __FT_LCD_FILTER_H__ */ | |
249 | ||
250 | ||
251 | /* END */ |