|
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 |
|
58 |
|
59 /**************************************************************************** |
|
60 * |
|
61 * @enum: |
|
62 * FT_LcdFilter |
|
63 * |
|
64 * @description: |
|
65 * A list of values to identify various types of LCD filters. |
|
66 * |
|
67 * @values: |
|
68 * FT_LCD_FILTER_NONE :: |
|
69 * Do not perform filtering. When used with subpixel rendering, this |
|
70 * results in sometimes severe color fringes. |
|
71 * |
|
72 * FT_LCD_FILTER_DEFAULT :: |
|
73 * The default filter reduces color fringes considerably, at the cost |
|
74 * of a slight blurriness in the output. |
|
75 * |
|
76 * FT_LCD_FILTER_LIGHT :: |
|
77 * The light filter is a variant that produces less blurriness at the |
|
78 * cost of slightly more color fringes than the default one. It might |
|
79 * be better, depending on taste, your monitor, or your personal vision. |
|
80 * |
|
81 * FT_LCD_FILTER_LEGACY :: |
|
82 * This filter corresponds to the original libXft color filter. It |
|
83 * provides high contrast output but can exhibit really bad color |
|
84 * fringes if glyphs are not extremely well hinted to the pixel grid. |
|
85 * In other words, it only works well if the TrueType bytecode |
|
86 * interpreter is enabled *and* high-quality hinted fonts are used. |
|
87 * |
|
88 * This filter is only provided for comparison purposes, and might be |
|
89 * disabled or stay unsupported in the future. |
|
90 * |
|
91 * @since: |
|
92 * 2.3.0 |
|
93 */ |
|
94 typedef enum FT_LcdFilter_ |
|
95 { |
|
96 FT_LCD_FILTER_NONE = 0, |
|
97 FT_LCD_FILTER_DEFAULT = 1, |
|
98 FT_LCD_FILTER_LIGHT = 2, |
|
99 FT_LCD_FILTER_LEGACY = 16, |
|
100 |
|
101 FT_LCD_FILTER_MAX /* do not remove */ |
|
102 |
|
103 } FT_LcdFilter; |
|
104 |
|
105 |
|
106 /************************************************************************** |
|
107 * |
|
108 * @func: |
|
109 * FT_Library_SetLcdFilter |
|
110 * |
|
111 * @description: |
|
112 * This function is used to apply color filtering to LCD decimated |
|
113 * bitmaps, like the ones used when calling @FT_Render_Glyph with |
|
114 * @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V. |
|
115 * |
|
116 * @input: |
|
117 * library :: |
|
118 * A handle to the target library instance. |
|
119 * |
|
120 * filter :: |
|
121 * The filter type. |
|
122 * |
|
123 * You can use @FT_LCD_FILTER_NONE here to disable this feature, or |
|
124 * @FT_LCD_FILTER_DEFAULT to use a default filter that should work |
|
125 * well on most LCD screens. |
|
126 * |
|
127 * @return: |
|
128 * FreeType error code. 0~means success. |
|
129 * |
|
130 * @note: |
|
131 * This feature is always disabled by default. Clients must make an |
|
132 * explicit call to this function with a `filter' value other than |
|
133 * @FT_LCD_FILTER_NONE in order to enable it. |
|
134 * |
|
135 * Due to *PATENTS* covering subpixel rendering, this function doesn't |
|
136 * do anything except returning `FT_Err_Unimplemented_Feature' if the |
|
137 * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not |
|
138 * defined in your build of the library, which should correspond to all |
|
139 * default builds of FreeType. |
|
140 * |
|
141 * The filter affects glyph bitmaps rendered through @FT_Render_Glyph, |
|
142 * @FT_Outline_Get_Bitmap, @FT_Load_Glyph, and @FT_Load_Char. |
|
143 * |
|
144 * It does _not_ affect the output of @FT_Outline_Render and |
|
145 * @FT_Outline_Get_Bitmap. |
|
146 * |
|
147 * If this feature is activated, the dimensions of LCD glyph bitmaps are |
|
148 * either larger or taller than the dimensions of the corresponding |
|
149 * outline with regards to the pixel grid. For example, for |
|
150 * @FT_RENDER_MODE_LCD, the filter adds up to 3~pixels to the left, and |
|
151 * up to 3~pixels to the right. |
|
152 * |
|
153 * The bitmap offset values are adjusted correctly, so clients shouldn't |
|
154 * need to modify their layout and glyph positioning code when enabling |
|
155 * the filter. |
|
156 * |
|
157 * @since: |
|
158 * 2.3.0 |
|
159 */ |
|
160 FT_EXPORT( FT_Error ) |
|
161 FT_Library_SetLcdFilter( FT_Library library, |
|
162 FT_LcdFilter filter ); |
|
163 |
|
164 |
|
165 /************************************************************************** |
|
166 * |
|
167 * @func: |
|
168 * FT_Library_SetLcdFilterWeights |
|
169 * |
|
170 * @description: |
|
171 * Use this function to override the filter weights selected by |
|
172 * @FT_Library_SetLcdFilter. By default, FreeType uses the quintuple |
|
173 * (0x00, 0x55, 0x56, 0x55, 0x00) for FT_LCD_FILTER_LIGHT, and (0x10, |
|
174 * 0x40, 0x70, 0x40, 0x10) for FT_LCD_FILTER_DEFAULT and |
|
175 * FT_LCD_FILTER_LEGACY. |
|
176 * |
|
177 * @input: |
|
178 * library :: |
|
179 * A handle to the target library instance. |
|
180 * |
|
181 * weights :: |
|
182 * A pointer to an array; the function copies the first five bytes and |
|
183 * uses them to specify the filter weights. |
|
184 * |
|
185 * @return: |
|
186 * FreeType error code. 0~means success. |
|
187 * |
|
188 * @note: |
|
189 * Due to *PATENTS* covering subpixel rendering, this function doesn't |
|
190 * do anything except returning `FT_Err_Unimplemented_Feature' if the |
|
191 * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not |
|
192 * defined in your build of the library, which should correspond to all |
|
193 * default builds of FreeType. |
|
194 * |
|
195 * This function must be called after @FT_Library_SetLcdFilter to have |
|
196 * any effect. |
|
197 * |
|
198 * @since: |
|
199 * 2.4.0 |
|
200 */ |
|
201 FT_EXPORT( FT_Error ) |
|
202 FT_Library_SetLcdFilterWeights( FT_Library library, |
|
203 unsigned char *weights ); |
|
204 |
|
205 /* */ |
|
206 |
|
207 |
|
208 FT_END_HEADER |
|
209 |
|
210 #endif /* __FT_LCD_FILTER_H__ */ |
|
211 |
|
212 |
|
213 /* END */ |