ReactOS  0.4.13-dev-982-g9853eab
ftlcdfil.h
Go to the documentation of this file.
1 /***************************************************************************/
2 /* */
3 /* ftlcdfil.h */
4 /* */
5 /* FreeType API for color filtering of subpixel bitmap glyphs */
6 /* (specification). */
7 /* */
8 /* Copyright 2006-2018 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 FTLCDFIL_H_
21 #define FTLCDFIL_H_
22 
23 #include <ft2build.h>
24 #include FT_FREETYPE_H
25 #include FT_PARAMETER_TAGS_H
26 
27 #ifdef FREETYPE_H
28 #error "freetype.h of FreeType 1 has been loaded!"
29 #error "Please fix the directory search order for header files"
30 #error "so that freetype.h of FreeType 2 is found first."
31 #endif
32 
33 
35 
36  /***************************************************************************
37  *
38  * @section:
39  * lcd_filtering
40  *
41  * @title:
42  * LCD Filtering
43  *
44  * @abstract:
45  * Reduce color fringes of subpixel-rendered bitmaps.
46  *
47  * @description:
48  * Should you #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your
49  * `ftoption.h', which enables patented ClearType-style rendering,
50  * the LCD-optimized glyph bitmaps should be filtered to reduce color
51  * fringes inherent to this technology. The default FreeType LCD
52  * rendering uses different technology, and API described below,
53  * although available, does nothing.
54  *
55  * ClearType-style LCD rendering exploits the color-striped structure of
56  * LCD pixels, increasing the available resolution in the direction of
57  * the stripe (usually horizontal RGB) by a factor of~3. Since these
58  * subpixels are color pixels, using them unfiltered creates severe
59  * color fringes. Use the @FT_Library_SetLcdFilter API to specify a
60  * low-pass filter, which is then applied to subpixel-rendered bitmaps
61  * generated through @FT_Render_Glyph. The filter sacrifices some of
62  * the higher resolution to reduce color fringes, making the glyph image
63  * slightly blurrier. Positional improvements will remain.
64  *
65  * A filter should have two properties:
66  *
67  * 1) It should be normalized, meaning the sum of the 5~components
68  * should be 256 (0x100). It is possible to go above or under this
69  * target sum, however: going under means tossing out contrast, going
70  * over means invoking clamping and thereby non-linearities that
71  * increase contrast somewhat at the expense of greater distortion
72  * and color-fringing. Contrast is better enhanced through stem
73  * darkening.
74  *
75  * 2) It should be color-balanced, meaning a filter `{~a, b, c, b, a~}'
76  * where a~+ b~=~c. It distributes the computed coverage for one
77  * subpixel to all subpixels equally, sacrificing some won resolution
78  * but drastically reducing color-fringing. Positioning improvements
79  * remain! Note that color-fringing can only really be minimized
80  * when using a color-balanced filter and alpha-blending the glyph
81  * onto a surface in linear space; see @FT_Render_Glyph.
82  *
83  * Regarding the form, a filter can be a `boxy' filter or a `beveled'
84  * filter. Boxy filters are sharper but are less forgiving of non-ideal
85  * gamma curves of a screen (viewing angles!), beveled filters are
86  * fuzzier but more tolerant.
87  *
88  * Examples:
89  *
90  * - [0x10 0x40 0x70 0x40 0x10] is beveled and neither balanced nor
91  * normalized.
92  *
93  * - [0x1A 0x33 0x4D 0x33 0x1A] is beveled and balanced but not
94  * normalized.
95  *
96  * - [0x19 0x33 0x66 0x4c 0x19] is beveled and normalized but not
97  * balanced.
98  *
99  * - [0x00 0x4c 0x66 0x4c 0x00] is boxily beveled and normalized but not
100  * balanced.
101  *
102  * - [0x00 0x55 0x56 0x55 0x00] is boxy, normalized, and almost
103  * balanced.
104  *
105  * - [0x08 0x4D 0x56 0x4D 0x08] is beveled, normalized and, almost
106  * balanced.
107  *
108  * The filter affects glyph bitmaps rendered through @FT_Render_Glyph,
109  * @FT_Load_Glyph, and @FT_Load_Char. It does _not_ affect the output
110  * of @FT_Outline_Render and @FT_Outline_Get_Bitmap.
111  *
112  * If this feature is activated, the dimensions of LCD glyph bitmaps are
113  * either wider or taller than the dimensions of the corresponding
114  * outline with regard to the pixel grid. For example, for
115  * @FT_RENDER_MODE_LCD, the filter adds 3~subpixels to the left, and
116  * 3~subpixels to the right. The bitmap offset values are adjusted
117  * accordingly, so clients shouldn't need to modify their layout and
118  * glyph positioning code when enabling the filter.
119  *
120  * It is important to understand that linear alpha blending and gamma
121  * correction is critical for correctly rendering glyphs onto surfaces
122  * without artifacts and even more critical when subpixel rendering is
123  * involved.
124  *
125  * Each of the 3~alpha values (subpixels) is independently used to blend
126  * one color channel. That is, red alpha blends the red channel of the
127  * text color with the red channel of the background pixel. The
128  * distribution of density values by the color-balanced filter assumes
129  * alpha blending is done in linear space; only then color artifacts
130  * cancel out.
131  */
132 
133 
134  /****************************************************************************
135  *
136  * @enum:
137  * FT_LcdFilter
138  *
139  * @description:
140  * A list of values to identify various types of LCD filters.
141  *
142  * @values:
143  * FT_LCD_FILTER_NONE ::
144  * Do not perform filtering. When used with subpixel rendering, this
145  * results in sometimes severe color fringes.
146  *
147  * FT_LCD_FILTER_DEFAULT ::
148  * The default filter reduces color fringes considerably, at the cost
149  * of a slight blurriness in the output.
150  *
151  * It is a beveled, normalized, and color-balanced five-tap filter
152  * that is more forgiving to screens with non-ideal gamma curves and
153  * viewing angles. Note that while color-fringing is reduced, it can
154  * only be minimized by using linear alpha blending and gamma
155  * correction to render glyphs onto surfaces. The default filter
156  * weights are [0x08 0x4D 0x56 0x4D 0x08].
157  *
158  * FT_LCD_FILTER_LIGHT ::
159  * The light filter is a variant that is sharper at the cost of
160  * slightly more color fringes than the default one.
161  *
162  * It is a boxy, normalized, and color-balanced three-tap filter that
163  * is less forgiving to screens with non-ideal gamma curves and
164  * viewing angles. This filter works best when the rendering system
165  * uses linear alpha blending and gamma correction to render glyphs
166  * onto surfaces. The light filter weights are
167  * [0x00 0x55 0x56 0x55 0x00].
168  *
169  * FT_LCD_FILTER_LEGACY ::
170  * This filter corresponds to the original libXft color filter. It
171  * provides high contrast output but can exhibit really bad color
172  * fringes if glyphs are not extremely well hinted to the pixel grid.
173  * In other words, it only works well if the TrueType bytecode
174  * interpreter is enabled *and* high-quality hinted fonts are used.
175  *
176  * This filter is only provided for comparison purposes, and might be
177  * disabled or stay unsupported in the future.
178  *
179  * FT_LCD_FILTER_LEGACY1 ::
180  * For historical reasons, the FontConfig library returns a different
181  * enumeration value for legacy LCD filtering. To make code work that
182  * (incorrectly) forwards FontConfig's enumeration value to
183  * @FT_Library_SetLcdFilter without proper mapping, it is thus easiest
184  * to have another enumeration value, which is completely equal to
185  * `FT_LCD_FILTER_LEGACY'.
186  *
187  * @since:
188  * 2.3.0 (`FT_LCD_FILTER_LEGACY1' since 2.6.2)
189  */
190  typedef enum FT_LcdFilter_
191  {
197 
198  FT_LCD_FILTER_MAX /* do not remove */
199 
200  } FT_LcdFilter;
201 
202 
203  /**************************************************************************
204  *
205  * @func:
206  * FT_Library_SetLcdFilter
207  *
208  * @description:
209  * This function is used to apply color filtering to LCD decimated
210  * bitmaps, like the ones used when calling @FT_Render_Glyph with
211  * @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
212  *
213  * @input:
214  * library ::
215  * A handle to the target library instance.
216  *
217  * filter ::
218  * The filter type.
219  *
220  * You can use @FT_LCD_FILTER_NONE here to disable this feature, or
221  * @FT_LCD_FILTER_DEFAULT to use a default filter that should work
222  * well on most LCD screens.
223  *
224  * @return:
225  * FreeType error code. 0~means success.
226  *
227  * @note:
228  * This feature is always disabled by default. Clients must make an
229  * explicit call to this function with a `filter' value other than
230  * @FT_LCD_FILTER_NONE in order to enable it.
231  *
232  * Due to *PATENTS* covering subpixel rendering, this function doesn't
233  * do anything except returning `FT_Err_Unimplemented_Feature' if the
234  * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
235  * defined in your build of the library, which should correspond to all
236  * default builds of FreeType.
237  *
238  * @since:
239  * 2.3.0
240  */
244 
245 
246  /**************************************************************************
247  *
248  * @func:
249  * FT_Library_SetLcdFilterWeights
250  *
251  * @description:
252  * This function can be used to enable LCD filter with custom weights,
253  * instead of using presets in @FT_Library_SetLcdFilter.
254  *
255  * @input:
256  * library ::
257  * A handle to the target library instance.
258  *
259  * weights ::
260  * A pointer to an array; the function copies the first five bytes and
261  * uses them to specify the filter weights.
262  *
263  * @return:
264  * FreeType error code. 0~means success.
265  *
266  * @note:
267  * Due to *PATENTS* covering subpixel rendering, this function doesn't
268  * do anything except returning `FT_Err_Unimplemented_Feature' if the
269  * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
270  * defined in your build of the library, which should correspond to all
271  * default builds of FreeType.
272  *
273  * LCD filter weights can also be set per face using @FT_Face_Properties
274  * with @FT_PARAM_TAG_LCD_FILTER_WEIGHTS.
275  *
276  * @since:
277  * 2.4.0
278  */
281  unsigned char *weights );
282 
283 
284  /*
285  * @type:
286  * FT_LcdFiveTapFilter
287  *
288  * @description:
289  * A typedef for passing the five LCD filter weights to
290  * @FT_Face_Properties within an @FT_Parameter structure.
291  *
292  * @since:
293  * 2.8
294  *
295  */
296 #define FT_LCD_FILTER_FIVE_TAPS 5
297 
299 
300 
301  /* */
302 
303 
305 
306 #endif /* FTLCDFIL_H_ */
307 
308 
309 /* END */
int FT_Error
Definition: fttypes.h:300
FT_Library_SetLcdFilterWeights(FT_Library library, unsigned char *weights)
Definition: ftlcdfil.c:360
#define FT_END_HEADER
Definition: ftheader.h:54
FT_Library library
Definition: cffdrivr.c:654
#define FT_LCD_FILTER_FIVE_TAPS
Definition: ftlcdfil.h:296
unsigned char FT_Byte
Definition: fttypes.h:154
#define FT_BEGIN_HEADER
Definition: ftheader.h:36
FT_Byte FT_LcdFiveTapFilter[FT_LCD_FILTER_FIVE_TAPS]
Definition: ftlcdfil.h:298
FT_LcdFilter_
Definition: ftlcdfil.h:190
#define FT_EXPORT(x)
Definition: ftconfig.h:461
FT_BEGIN_HEADER enum FT_LcdFilter_ FT_LcdFilter
const GLbyte * weights
Definition: glext.h:6523
FT_Library_SetLcdFilter(FT_Library library, FT_LcdFilter filter)
Definition: ftlcdfil.c:371
GLint GLint GLint GLint GLint GLint GLint GLbitfield GLenum filter
Definition: glext.h:7005