1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
|
/****************************************************************************
*
* ftlcdfil.h
*
* FreeType API for color filtering of subpixel bitmap glyphs
* (specification).
*
* Copyright 2006-2018 by
* David Turner, Robert Wilhelm, and Werner Lemberg.
*
* This file is part of the FreeType project, and may only be used,
* modified, and distributed under the terms of the FreeType project
* license, LICENSE.TXT. By continuing to use, modify, or distribute
* this file you indicate that you have read the license and
* understand and accept it fully.
*
*/
#ifndef FTLCDFIL_H_
#define FTLCDFIL_H_
#include <ft2build.h>
#include FT_FREETYPE_H
#include FT_PARAMETER_TAGS_H
#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif
FT_BEGIN_HEADER
/***************************************************************************
*
* @section:
* lcd_filtering
*
* @title:
* LCD Filtering
*
* @abstract:
* Remove color fringes of subpixel-rendered bitmaps.
*
* @description:
* Should you #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your
* `ftoption.h', which enables patented ClearType-style rendering,
* the LCD-optimized glyph bitmaps should be filtered to reduce color
* fringes inherent to this technology. The default FreeType LCD
* rendering uses different technology, and API described below,
* although available, does nothing.
*
* ClearType-style LCD rendering exploits the color-striped structure of
* LCD pixels, increasing the available resolution in the direction of
* the stripe (usually horizontal RGB) by a factor of~3. Using the
* subpixels coverages unfiltered can create severe color fringes
* especially when rendering thin features. Indeed, to produce
* black-on-white text, the color components must be dimmed equally.
*
* A good 5-tap FIR filter should be applied to subpixel coverages
* regardless of pixel boundaries and should have these properties:
*
* 1) It should be symmetrical, like {~a, b, c, b, a~}, to avoid
* any shifts in appearance.
*
* 2) It should be color-balanced, meaning a~+ b~=~c, to reduce color
* fringes by distributing the computed coverage for one subpixel to
* all subpixels equally.
*
* 3) It should be normalized, meaning 2a~+ 2b~+ c~=~1.0 to maintain
* overall brightness.
*
* Use the @FT_Library_SetLcdFilter API to specify a low-pass filter,
* which is then applied to subpixel-rendered bitmaps generated through
* @FT_Render_Glyph. The filter affects glyph bitmaps rendered through
* @FT_Render_Glyph, @FT_Load_Glyph, and @FT_Load_Char. It does _not_
* affect the output of @FT_Outline_Render and @FT_Outline_Get_Bitmap.
*
* If this feature is activated, the dimensions of LCD glyph bitmaps are
* either wider or taller than the dimensions of the corresponding
* outline with regard to the pixel grid. For example, for
* @FT_RENDER_MODE_LCD, the filter adds 2~subpixels to the left, and
* 2~subpixels to the right. The bitmap offset values are adjusted
* accordingly, so clients shouldn't need to modify their layout and
* glyph positioning code when enabling the filter.
*
* Only filtering along with gamma-corrected alpha blending can completely
* remove color fringes. Boxy 3-tap filter {0, 1/3, 1/3, 1/3, 0} is
* sharper but is less forgiving of non-ideal gamma curves of a screen
* (viewing angles!), beveled filters are fuzzier but more tolerant.
*
* Each of the 3~alpha values (subpixels) is independently used to blend
* one color channel. That is, red alpha blends the red channel of the
* text color with the red channel of the background pixel. The
* distribution of density values by the color-balanced filter assumes
* alpha blending is done in linear space; only then color artifacts
* cancel out.
*/
/****************************************************************************
*
* @enum:
* FT_LcdFilter
*
* @description:
* A list of values to identify various types of LCD filters.
*
* @values:
* FT_LCD_FILTER_NONE ::
* Do not perform filtering. When used with subpixel rendering, this
* results in sometimes severe color fringes.
*
* FT_LCD_FILTER_DEFAULT ::
* This is a beveled, normalized, and color-balanced five-tap filter
* with weights of [0x08 0x4D 0x56 0x4D 0x08] in 1/256th units.
*
* FT_LCD_FILTER_LIGHT ::
* this is a boxy, normalized, and color-balanced three-tap filter
* with weights of [0x00 0x55 0x56 0x55 0x00] in 1/256th units.
*
* FT_LCD_FILTER_LEGACY ::
* FT_LCD_FILTER_LEGACY1 ::
* This filter corresponds to the original libXft color filter. It
* provides high contrast output but can exhibit really bad color
* fringes if glyphs are not extremely well hinted to the pixel grid.
* This filter is only provided for comparison purposes, and might be
* disabled or stay unsupported in the future. The second value is
* provided for compatibility with FontConfig, which historically
* used different enumeration, sometimes incorrectly forwarded to
* FreeType.
*
* @since:
* 2.3.0 (`FT_LCD_FILTER_LEGACY1' since 2.6.2)
*/
typedef enum FT_LcdFilter_
{
FT_LCD_FILTER_NONE = 0,
FT_LCD_FILTER_DEFAULT = 1,
FT_LCD_FILTER_LIGHT = 2,
FT_LCD_FILTER_LEGACY1 = 3,
FT_LCD_FILTER_LEGACY = 16,
FT_LCD_FILTER_MAX /* do not remove */
} FT_LcdFilter;
/**************************************************************************
*
* @func:
* FT_Library_SetLcdFilter
*
* @description:
* This function is used to apply color filtering to LCD decimated
* bitmaps, like the ones used when calling @FT_Render_Glyph with
* @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
*
* @input:
* library ::
* A handle to the target library instance.
*
* filter ::
* The filter type.
*
* You can use @FT_LCD_FILTER_NONE here to disable this feature, or
* @FT_LCD_FILTER_DEFAULT to use a default filter that should work
* well on most LCD screens.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* This feature is always disabled by default. Clients must make an
* explicit call to this function with a `filter' value other than
* @FT_LCD_FILTER_NONE in order to enable it.
*
* Due to *PATENTS* covering subpixel rendering, this function doesn't
* do anything except returning `FT_Err_Unimplemented_Feature' if the
* configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
* defined in your build of the library, which should correspond to all
* default builds of FreeType.
*
* @since:
* 2.3.0
*/
FT_EXPORT( FT_Error )
FT_Library_SetLcdFilter( FT_Library library,
FT_LcdFilter filter );
/**************************************************************************
*
* @func:
* FT_Library_SetLcdFilterWeights
*
* @description:
* This function can be used to enable LCD filter with custom weights,
* instead of using presets in @FT_Library_SetLcdFilter.
*
* @input:
* library ::
* A handle to the target library instance.
*
* weights ::
* A pointer to an array; the function copies the first five bytes and
* uses them to specify the filter weights in 1/256th units.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* Due to *PATENTS* covering subpixel rendering, this function doesn't
* do anything except returning `FT_Err_Unimplemented_Feature' if the
* configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
* defined in your build of the library, which should correspond to all
* default builds of FreeType.
*
* LCD filter weights can also be set per face using @FT_Face_Properties
* with @FT_PARAM_TAG_LCD_FILTER_WEIGHTS.
*
* @since:
* 2.4.0
*/
FT_EXPORT( FT_Error )
FT_Library_SetLcdFilterWeights( FT_Library library,
unsigned char *weights );
/**************************************************************************
*
* @type:
* FT_LcdFiveTapFilter
*
* @description:
* A typedef for passing the five LCD filter weights to
* @FT_Face_Properties within an @FT_Parameter structure.
*
* @since:
* 2.8
*
*/
#define FT_LCD_FILTER_FIVE_TAPS 5
typedef FT_Byte FT_LcdFiveTapFilter[FT_LCD_FILTER_FIVE_TAPS];
/* */
FT_END_HEADER
#endif /* FTLCDFIL_H_ */
/* END */
|
