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
34FT_BEGIN_HEADER
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 {
192 FT_LCD_FILTER_NONE = 0,
193 FT_LCD_FILTER_DEFAULT = 1,
194 FT_LCD_FILTER_LIGHT = 2,
195 FT_LCD_FILTER_LEGACY1 = 3,
196 FT_LCD_FILTER_LEGACY = 16,
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 */
241 FT_EXPORT( FT_Error )
242 FT_Library_SetLcdFilter( FT_Library library,
243 FT_LcdFilter filter );
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 */
279 FT_EXPORT( FT_Error )
280 FT_Library_SetLcdFilterWeights( FT_Library library,
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
298 typedef FT_Byte FT_LcdFiveTapFilter[FT_LCD_FILTER_FIVE_TAPS];
299
300
301 /* */
302
303
304FT_END_HEADER
305
306#endif /* FTLCDFIL_H_ */
307
308
309/* END */
310