1 /***************************************************************************/
5 /* FreeType API for color filtering of subpixel bitmap glyphs */
8 /* Copyright 2006-2015 by */
9 /* David Turner, Robert Wilhelm, and Werner Lemberg. */
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. */
17 /***************************************************************************/
20 #ifndef __FT_LCD_FILTER_H__
21 #define __FT_LCD_FILTER_H__
24 #include FT_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."
35 /***************************************************************************
44 * Reduce color fringes of subpixel-rendered bitmaps.
47 * Subpixel rendering exploits the color-striped structure of LCD
48 * pixels, increasing the available resolution in the direction of the
49 * stripe (usually horizontal RGB) by a factor of~3. Since these
50 * subpixels are color pixels, using them unfiltered creates severe
51 * color fringes. Use the @FT_Library_SetLcdFilter API to specify a
52 * low-pass filter, which is then applied to subpixel-rendered bitmaps
53 * generated through @FT_Render_Glyph. The filter sacrifices some of
54 * the higher resolution to reduce color fringes, making the glyph image
55 * slightly blurrier. Positional improvements will remain.
57 * Note that no filter is active by default, and that this function is
58 * *not* implemented in default builds of the library. You need to
59 * #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your `ftoption.h' file
60 * in order to activate it.
62 * A filter should have two properties:
64 * 1) It should be normalized, meaning the sum of the 5~components
65 * should be 256 (0x100). It is possible to go above or under this
66 * target sum, however: going under means tossing out contrast, going
67 * over means invoking clamping and thereby non-linearities that
68 * increase contrast somewhat at the expense of greater distortion
69 * and color-fringing. Contrast is better enhanced through stem
72 * 2) It should be color-balanced, meaning a filter `{~a, b, c, b, a~}'
73 * where a~+ b~=~c. It distributes the computed coverage for one
74 * subpixel to all subpixels equally, sacrificing some won resolution
75 * but drastically reducing color-fringing. Positioning improvements
76 * remain! Note that color-fringing can only really be minimized
77 * when using a color-balanced filter and alpha-blending the glyph
78 * onto a surface in linear space; see @FT_Render_Glyph.
80 * Regarding the form, a filter can be a `boxy' filter or a `beveled'
81 * filter. Boxy filters are sharper but are less forgiving of non-ideal
82 * gamma curves of a screen (viewing angles!), beveled filters are
83 * fuzzier but more tolerant.
87 * - [0x10 0x40 0x70 0x40 0x10] is beveled and neither balanced nor
90 * - [0x1A 0x33 0x4D 0x33 0x1A] is beveled and balanced but not
93 * - [0x19 0x33 0x66 0x4c 0x19] is beveled and normalized but not
96 * - [0x00 0x4c 0x66 0x4c 0x00] is boxily beveled and normalized but not
99 * - [0x00 0x55 0x56 0x55 0x00] is boxy, normalized, and almost
102 * - [0x08 0x4D 0x56 0x4D 0x08] is beveled, normalized and, almost
105 * It is important to understand that linear alpha blending and gamma
106 * correction is critical for correctly rendering glyphs onto surfaces
107 * without artifacts and even more critical when subpixel rendering is
110 * Each of the 3~alpha values (subpixels) is independently used to blend
111 * one color channel. That is, red alpha blends the red channel of the
112 * text color with the red channel of the background pixel. The
113 * distribution of density values by the color-balanced filter assumes
114 * alpha blending is done in linear space; only then color artifacts
119 /****************************************************************************
125 * A list of values to identify various types of LCD filters.
128 * FT_LCD_FILTER_NONE ::
129 * Do not perform filtering. When used with subpixel rendering, this
130 * results in sometimes severe color fringes.
132 * FT_LCD_FILTER_DEFAULT ::
133 * The default filter reduces color fringes considerably, at the cost
134 * of a slight blurriness in the output.
136 * It is a beveled, normalized, and color-balanced five-tap filter
137 * that is more forgiving to screens with non-ideal gamma curves and
138 * viewing angles. Note that while color-fringing is reduced, it can
139 * only be minimized by using linear alpha blending and gamma
140 * correction to render glyphs onto surfaces.
142 * FT_LCD_FILTER_LIGHT ::
143 * The light filter is a variant that is sharper at the cost of
144 * slightly more color fringes than the default one.
146 * It is a boxy, normalized, and color-balanced three-tap filter that
147 * is less forgiving to screens with non-ideal gamma curves and
148 * viewing angles. This filter works best when the rendering system
149 * uses linear alpha blending and gamma correction to render glyphs
152 * FT_LCD_FILTER_LEGACY ::
153 * This filter corresponds to the original libXft color filter. It
154 * provides high contrast output but can exhibit really bad color
155 * fringes if glyphs are not extremely well hinted to the pixel grid.
156 * In other words, it only works well if the TrueType bytecode
157 * interpreter is enabled *and* high-quality hinted fonts are used.
159 * This filter is only provided for comparison purposes, and might be
160 * disabled or stay unsupported in the future.
162 * FT_LCD_FILTER_LEGACY1 ::
163 * For historical reasons, the FontConfig library returns a different
164 * enumeration value for legacy LCD filtering. To make code work that
165 * (incorrectly) forwards FontConfig's enumeration value to
166 * @FT_Library_SetLcdFilter without proper mapping, it is thus easiest
167 * to have another enumeration value, which is completely equal to
168 * `FT_LCD_FILTER_LEGACY'.
171 * 2.3.0 (`FT_LCD_FILTER_LEGACY1' since 2.6.2)
173 typedef enum FT_LcdFilter_
175 FT_LCD_FILTER_NONE
= 0,
176 FT_LCD_FILTER_DEFAULT
= 1,
177 FT_LCD_FILTER_LIGHT
= 2,
178 FT_LCD_FILTER_LEGACY1
= 3,
179 FT_LCD_FILTER_LEGACY
= 16,
181 FT_LCD_FILTER_MAX
/* do not remove */
186 /**************************************************************************
189 * FT_Library_SetLcdFilter
192 * This function is used to apply color filtering to LCD decimated
193 * bitmaps, like the ones used when calling @FT_Render_Glyph with
194 * @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
198 * A handle to the target library instance.
203 * You can use @FT_LCD_FILTER_NONE here to disable this feature, or
204 * @FT_LCD_FILTER_DEFAULT to use a default filter that should work
205 * well on most LCD screens.
208 * FreeType error code. 0~means success.
211 * This feature is always disabled by default. Clients must make an
212 * explicit call to this function with a `filter' value other than
213 * @FT_LCD_FILTER_NONE in order to enable it.
215 * Due to *PATENTS* covering subpixel rendering, this function doesn't
216 * do anything except returning `FT_Err_Unimplemented_Feature' if the
217 * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
218 * defined in your build of the library, which should correspond to all
219 * default builds of FreeType.
221 * The filter affects glyph bitmaps rendered through @FT_Render_Glyph,
222 * @FT_Outline_Get_Bitmap, @FT_Load_Glyph, and @FT_Load_Char.
224 * It does _not_ affect the output of @FT_Outline_Render and
225 * @FT_Outline_Get_Bitmap.
227 * If this feature is activated, the dimensions of LCD glyph bitmaps are
228 * either larger or taller than the dimensions of the corresponding
229 * outline with regards to the pixel grid. For example, for
230 * @FT_RENDER_MODE_LCD, the filter adds up to 3~pixels to the left, and
231 * up to 3~pixels to the right.
233 * The bitmap offset values are adjusted correctly, so clients shouldn't
234 * need to modify their layout and glyph positioning code when enabling
240 FT_EXPORT( FT_Error
)
241 FT_Library_SetLcdFilter( FT_Library library
,
242 FT_LcdFilter filter
);
245 /**************************************************************************
248 * FT_Library_SetLcdFilterWeights
251 * Use this function to override the filter weights selected by
252 * @FT_Library_SetLcdFilter. By default, FreeType uses the quintuple
253 * (0x00, 0x55, 0x56, 0x55, 0x00) for FT_LCD_FILTER_LIGHT, and (0x10,
254 * 0x40, 0x70, 0x40, 0x10) for FT_LCD_FILTER_DEFAULT and
255 * FT_LCD_FILTER_LEGACY.
259 * A handle to the target library instance.
262 * A pointer to an array; the function copies the first five bytes and
263 * uses them to specify the filter weights.
266 * FreeType error code. 0~means success.
269 * Due to *PATENTS* covering subpixel rendering, this function doesn't
270 * do anything except returning `FT_Err_Unimplemented_Feature' if the
271 * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
272 * defined in your build of the library, which should correspond to all
273 * default builds of FreeType.
275 * This function must be called after @FT_Library_SetLcdFilter to have
281 FT_EXPORT( FT_Error
)
282 FT_Library_SetLcdFilterWeights( FT_Library library
,
283 unsigned char *weights
);
290 #endif /* __FT_LCD_FILTER_H__ */