Clutter Engine 0.0.1
Loading...
Searching...
No Matches
ftlcdfil.h
1/***************************************************************************/
2/* */
3/* ftlcdfil.h */
4/* */
5/* FreeType API for color filtering of subpixel bitmap glyphs */
6/* (specification). */
7/* */
8/* Copyright 2006-2016 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
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
33FT_BEGIN_HEADER
34
35 /***************************************************************************
36 *
37 * @section:
38 * lcd_filtering
39 *
40 * @title:
41 * LCD Filtering
42 *
43 * @abstract:
44 * Reduce color fringes of subpixel-rendered bitmaps.
45 *
46 * @description:
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.
56 *
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 and explicitly call @FT_Library_SetLcdFilter
61 * to enable it.
62 *
63 * A filter should have two properties:
64 *
65 * 1) It should be normalized, meaning the sum of the 5~components
66 * should be 256 (0x100). It is possible to go above or under this
67 * target sum, however: going under means tossing out contrast, going
68 * over means invoking clamping and thereby non-linearities that
69 * increase contrast somewhat at the expense of greater distortion
70 * and color-fringing. Contrast is better enhanced through stem
71 * darkening.
72 *
73 * 2) It should be color-balanced, meaning a filter `{~a, b, c, b, a~}'
74 * where a~+ b~=~c. It distributes the computed coverage for one
75 * subpixel to all subpixels equally, sacrificing some won resolution
76 * but drastically reducing color-fringing. Positioning improvements
77 * remain! Note that color-fringing can only really be minimized
78 * when using a color-balanced filter and alpha-blending the glyph
79 * onto a surface in linear space; see @FT_Render_Glyph.
80 *
81 * Regarding the form, a filter can be a `boxy' filter or a `beveled'
82 * filter. Boxy filters are sharper but are less forgiving of non-ideal
83 * gamma curves of a screen (viewing angles!), beveled filters are
84 * fuzzier but more tolerant.
85 *
86 * Examples:
87 *
88 * - [0x10 0x40 0x70 0x40 0x10] is beveled and neither balanced nor
89 * normalized.
90 *
91 * - [0x1A 0x33 0x4D 0x33 0x1A] is beveled and balanced but not
92 * normalized.
93 *
94 * - [0x19 0x33 0x66 0x4c 0x19] is beveled and normalized but not
95 * balanced.
96 *
97 * - [0x00 0x4c 0x66 0x4c 0x00] is boxily beveled and normalized but not
98 * balanced.
99 *
100 * - [0x00 0x55 0x56 0x55 0x00] is boxy, normalized, and almost
101 * balanced.
102 *
103 * - [0x08 0x4D 0x56 0x4D 0x08] is beveled, normalized and, almost
104 * balanced.
105 *
106 * The filter affects glyph bitmaps rendered through @FT_Render_Glyph,
107 * @FT_Load_Glyph, and @FT_Load_Char. It does _not_ affect the output
108 * of @FT_Outline_Render and @FT_Outline_Get_Bitmap.
109 *
110 * If this feature is activated, the dimensions of LCD glyph bitmaps are
111 * either wider or taller than the dimensions of the corresponding
112 * outline with regard to the pixel grid. For example, for
113 * @FT_RENDER_MODE_LCD, the filter adds 3~subpixels to the left, and
114 * 3~subpixels to the right. The bitmap offset values are adjusted
115 * accordingly, so clients shouldn't need to modify their layout and
116 * glyph positioning code when enabling the filter.
117 *
118 * It is important to understand that linear alpha blending and gamma
119 * correction is critical for correctly rendering glyphs onto surfaces
120 * without artifacts and even more critical when subpixel rendering is
121 * involved.
122 *
123 * Each of the 3~alpha values (subpixels) is independently used to blend
124 * one color channel. That is, red alpha blends the red channel of the
125 * text color with the red channel of the background pixel. The
126 * distribution of density values by the color-balanced filter assumes
127 * alpha blending is done in linear space; only then color artifacts
128 * cancel out.
129 */
130
131
132 /****************************************************************************
133 *
134 * @enum:
135 * FT_LcdFilter
136 *
137 * @description:
138 * A list of values to identify various types of LCD filters.
139 *
140 * @values:
141 * FT_LCD_FILTER_NONE ::
142 * Do not perform filtering. When used with subpixel rendering, this
143 * results in sometimes severe color fringes.
144 *
145 * FT_LCD_FILTER_DEFAULT ::
146 * The default filter reduces color fringes considerably, at the cost
147 * of a slight blurriness in the output.
148 *
149 * It is a beveled, normalized, and color-balanced five-tap filter
150 * that is more forgiving to screens with non-ideal gamma curves and
151 * viewing angles. Note that while color-fringing is reduced, it can
152 * only be minimized by using linear alpha blending and gamma
153 * correction to render glyphs onto surfaces. The default filter
154 * weights are [0x08 0x4D 0x56 0x4D 0x08].
155 *
156 * FT_LCD_FILTER_LIGHT ::
157 * The light filter is a variant that is sharper at the cost of
158 * slightly more color fringes than the default one.
159 *
160 * It is a boxy, normalized, and color-balanced three-tap filter that
161 * is less forgiving to screens with non-ideal gamma curves and
162 * viewing angles. This filter works best when the rendering system
163 * uses linear alpha blending and gamma correction to render glyphs
164 * onto surfaces. The light filter weights are
165 * [0x00 0x55 0x56 0x55 0x00].
166 *
167 * FT_LCD_FILTER_LEGACY ::
168 * This filter corresponds to the original libXft color filter. It
169 * provides high contrast output but can exhibit really bad color
170 * fringes if glyphs are not extremely well hinted to the pixel grid.
171 * In other words, it only works well if the TrueType bytecode
172 * interpreter is enabled *and* high-quality hinted fonts are used.
173 *
174 * This filter is only provided for comparison purposes, and might be
175 * disabled or stay unsupported in the future.
176 *
177 * FT_LCD_FILTER_LEGACY1 ::
178 * For historical reasons, the FontConfig library returns a different
179 * enumeration value for legacy LCD filtering. To make code work that
180 * (incorrectly) forwards FontConfig's enumeration value to
181 * @FT_Library_SetLcdFilter without proper mapping, it is thus easiest
182 * to have another enumeration value, which is completely equal to
183 * `FT_LCD_FILTER_LEGACY'.
184 *
185 * @since:
186 * 2.3.0 (`FT_LCD_FILTER_LEGACY1' since 2.6.2)
187 */
188 typedef enum FT_LcdFilter_
189 {
190 FT_LCD_FILTER_NONE = 0,
191 FT_LCD_FILTER_DEFAULT = 1,
192 FT_LCD_FILTER_LIGHT = 2,
193 FT_LCD_FILTER_LEGACY1 = 3,
194 FT_LCD_FILTER_LEGACY = 16,
195
196 FT_LCD_FILTER_MAX /* do not remove */
197
198 } FT_LcdFilter;
199
200
201 /**************************************************************************
202 *
203 * @func:
204 * FT_Library_SetLcdFilter
205 *
206 * @description:
207 * This function is used to apply color filtering to LCD decimated
208 * bitmaps, like the ones used when calling @FT_Render_Glyph with
209 * @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
210 *
211 * @input:
212 * library ::
213 * A handle to the target library instance.
214 *
215 * filter ::
216 * The filter type.
217 *
218 * You can use @FT_LCD_FILTER_NONE here to disable this feature, or
219 * @FT_LCD_FILTER_DEFAULT to use a default filter that should work
220 * well on most LCD screens.
221 *
222 * @return:
223 * FreeType error code. 0~means success.
224 *
225 * @note:
226 * This feature is always disabled by default. Clients must make an
227 * explicit call to this function with a `filter' value other than
228 * @FT_LCD_FILTER_NONE in order to enable it.
229 *
230 * Due to *PATENTS* covering subpixel rendering, this function doesn't
231 * do anything except returning `FT_Err_Unimplemented_Feature' if the
232 * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
233 * defined in your build of the library, which should correspond to all
234 * default builds of FreeType.
235 *
236 * @since:
237 * 2.3.0
238 */
239 FT_EXPORT( FT_Error )
240 FT_Library_SetLcdFilter( FT_Library library,
241 FT_LcdFilter filter );
242
243
244 /**************************************************************************
245 *
246 * @func:
247 * FT_Library_SetLcdFilterWeights
248 *
249 * @description:
250 * This function can be used to enable LCD filter with custom weights,
251 * instead of using presets in @FT_Library_SetLcdFilter.
252 *
253 * @input:
254 * library ::
255 * A handle to the target library instance.
256 *
257 * weights ::
258 * A pointer to an array; the function copies the first five bytes and
259 * uses them to specify the filter weights.
260 *
261 * @return:
262 * FreeType error code. 0~means success.
263 *
264 * @note:
265 * Due to *PATENTS* covering subpixel rendering, this function doesn't
266 * do anything except returning `FT_Err_Unimplemented_Feature' if the
267 * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
268 * defined in your build of the library, which should correspond to all
269 * default builds of FreeType.
270 *
271 * @since:
272 * 2.4.0
273 */
274 FT_EXPORT( FT_Error )
275 FT_Library_SetLcdFilterWeights( FT_Library library,
276 unsigned char *weights );
277
278 /* */
279
280
281FT_END_HEADER
282
283#endif /* FTLCDFIL_H_ */
284
285
286/* END */
Generated by doxygen 1.12.0