1 /****************************************************************************
2 *
3 * ftlcdfil.h
4 *
5 * FreeType API for color filtering of subpixel bitmap glyphs
6 * (specification).
7 *
8 * Copyright (C) 2006-2020 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
34 FT_BEGIN_HEADER
35
36 /**************************************************************************
37 *
38 * @section:
39 * lcd_rendering
40 *
41 * @title:
42 * Subpixel Rendering
43 *
44 * @abstract:
45 * API to control subpixel rendering.
46 *
47 * @description:
48 * FreeType provides two alternative subpixel rendering technologies.
49 * Should you define `FT_CONFIG_OPTION_SUBPIXEL_RENDERING` in your
50 * `ftoption.h` file, this enables patented ClearType-style rendering.
51 * Otherwise, Harmony LCD rendering is enabled. These technologies are
52 * controlled differently and API described below, although always
53 * available, performs its function when appropriate method is enabled
54 * and does nothing otherwise.
55 *
56 * ClearType-style LCD rendering exploits the color-striped structure of
57 * LCD pixels, increasing the available resolution in the direction of
58 * the stripe (usually horizontal RGB) by a factor of~3. Using the
59 * subpixels coverages unfiltered can create severe color fringes
60 * especially when rendering thin features. Indeed, to produce
61 * black-on-white text, the nearby color subpixels must be dimmed
62 * equally.
63 *
64 * A good 5-tap FIR filter should be applied to subpixel coverages
65 * regardless of pixel boundaries and should have these properties:
66 *
67 * 1. It should be symmetrical, like {~a, b, c, b, a~}, to avoid
68 * any shifts in appearance.
69 *
70 * 2. It should be color-balanced, meaning a~+ b~=~c, to reduce color
71 * fringes by distributing the computed coverage for one subpixel to
72 * all subpixels equally.
73 *
74 * 3. It should be normalized, meaning 2a~+ 2b~+ c~=~1.0 to maintain
75 * overall brightness.
76 *
77 * Boxy 3-tap filter {0, 1/3, 1/3, 1/3, 0} is sharper but is less
78 * forgiving of non-ideal gamma curves of a screen (and viewing angles),
79 * beveled filters are fuzzier but more tolerant.
80 *
81 * Use the @FT_Library_SetLcdFilter or @FT_Library_SetLcdFilterWeights
82 * API to specify a low-pass filter, which is then applied to
83 * subpixel-rendered bitmaps generated through @FT_Render_Glyph.
84 *
85 * Harmony LCD rendering is suitable to panels with any regular subpixel
86 * structure, not just monitors with 3 color striped subpixels, as long
87 * as the color subpixels have fixed positions relative to the pixel
88 * center. In this case, each color channel is then rendered separately
89 * after shifting the outline opposite to the subpixel shift so that the
90 * coverage maps are aligned. This method is immune to color fringes
91 * because the shifts do not change integral coverage.
92 *
93 * The subpixel geometry must be specified by xy-coordinates for each
94 * subpixel. By convention they may come in the RGB order: {{-1/3, 0},
95 * {0, 0}, {1/3, 0}} for standard RGB striped panel or {{-1/6, 1/4},
96 * {-1/6, -1/4}, {1/3, 0}} for a certain PenTile panel.
97 *
98 * Use the @FT_Library_SetLcdGeometry API to specify subpixel positions.
99 * If one follows the RGB order convention, the same order applies to the
100 * resulting @FT_PIXEL_MODE_LCD and @FT_PIXEL_MODE_LCD_V bitmaps. Note,
101 * however, that the coordinate frame for the latter must be rotated
102 * clockwise. Harmony with default LCD geometry is equivalent to
103 * ClearType with light filter.
104 *
105 * As a result of ClearType filtering or Harmony rendering, the
106 * dimensions of LCD bitmaps can be either wider or taller than the
107 * dimensions of the corresponding outline with regard to the pixel grid.
108 * For example, for @FT_RENDER_MODE_LCD, the filter adds 2~subpixels to
109 * the left, and 2~subpixels to the right. The bitmap offset values are
110 * adjusted accordingly, so clients shouldn't need to modify their layout
111 * and glyph positioning code when enabling the filter.
112 *
113 * The ClearType and Harmony rendering is applicable to glyph bitmaps
114 * rendered through @FT_Render_Glyph, @FT_Load_Glyph, @FT_Load_Char, and
115 * @FT_Glyph_To_Bitmap, when @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V
116 * is specified. This API does not control @FT_Outline_Render and
117 * @FT_Outline_Get_Bitmap.
118 *
119 * The described algorithms can completely remove color artefacts when
120 * combined with gamma-corrected alpha blending in linear space. Each of
121 * the 3~alpha values (subpixels) must by independently used to blend one
122 * color channel. That is, red alpha blends the red channel of the text
123 * color with the red channel of the background pixel.
124 */
125
126
127 /**************************************************************************
128 *
129 * @enum:
130 * FT_LcdFilter
131 *
132 * @description:
133 * A list of values to identify various types of LCD filters.
134 *
135 * @values:
136 * FT_LCD_FILTER_NONE ::
137 * Do not perform filtering. When used with subpixel rendering, this
138 * results in sometimes severe color fringes.
139 *
140 * FT_LCD_FILTER_DEFAULT ::
141 * This is a beveled, normalized, and color-balanced five-tap filter
142 * with weights of [0x08 0x4D 0x56 0x4D 0x08] in 1/256th units.
143 *
144 * FT_LCD_FILTER_LIGHT ::
145 * this is a boxy, normalized, and color-balanced three-tap filter with
146 * weights of [0x00 0x55 0x56 0x55 0x00] in 1/256th units.
147 *
148 * FT_LCD_FILTER_LEGACY ::
149 * FT_LCD_FILTER_LEGACY1 ::
150 * This filter corresponds to the original libXft color filter. It
151 * provides high contrast output but can exhibit really bad color
152 * fringes if glyphs are not extremely well hinted to the pixel grid.
153 * This filter is only provided for comparison purposes, and might be
154 * disabled or stay unsupported in the future. The second value is
155 * provided for compatibility with FontConfig, which historically used
156 * different enumeration, sometimes incorrectly forwarded to FreeType.
157 *
158 * @since:
159 * 2.3.0 (`FT_LCD_FILTER_LEGACY1` since 2.6.2)
160 */
161 typedef enum FT_LcdFilter_
162 {
163 FT_LCD_FILTER_NONE = 0,
164 FT_LCD_FILTER_DEFAULT = 1,
165 FT_LCD_FILTER_LIGHT = 2,
166 FT_LCD_FILTER_LEGACY1 = 3,
167 FT_LCD_FILTER_LEGACY = 16,
168
169 FT_LCD_FILTER_MAX /* do not remove */
170
171 } FT_LcdFilter;
172
173
174 /**************************************************************************
175 *
176 * @function:
177 * FT_Library_SetLcdFilter
178 *
179 * @description:
180 * This function is used to apply color filtering to LCD decimated
181 * bitmaps, like the ones used when calling @FT_Render_Glyph with
182 * @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
183 *
184 * @input:
185 * library ::
186 * A handle to the target library instance.
187 *
188 * filter ::
189 * The filter type.
190 *
191 * You can use @FT_LCD_FILTER_NONE here to disable this feature, or
192 * @FT_LCD_FILTER_DEFAULT to use a default filter that should work well
193 * on most LCD screens.
194 *
195 * @return:
196 * FreeType error code. 0~means success.
197 *
198 * @note:
199 * This feature is always disabled by default. Clients must make an
200 * explicit call to this function with a `filter` value other than
201 * @FT_LCD_FILTER_NONE in order to enable it.
202 *
203 * Due to **PATENTS** covering subpixel rendering, this function doesn't
204 * do anything except returning `FT_Err_Unimplemented_Feature` if the
205 * configuration macro `FT_CONFIG_OPTION_SUBPIXEL_RENDERING` is not
206 * defined in your build of the library, which should correspond to all
207 * default builds of FreeType.
208 *
209 * @since:
210 * 2.3.0
211 */
212 FT_EXPORT( FT_Error )
213 FT_Library_SetLcdFilter( FT_Library library,
214 FT_LcdFilter filter );
215
216
217 /**************************************************************************
218 *
219 * @function:
220 * FT_Library_SetLcdFilterWeights
221 *
222 * @description:
223 * This function can be used to enable LCD filter with custom weights,
224 * instead of using presets in @FT_Library_SetLcdFilter.
225 *
226 * @input:
227 * library ::
228 * A handle to the target library instance.
229 *
230 * weights ::
231 * A pointer to an array; the function copies the first five bytes and
232 * uses them to specify the filter weights in 1/256th units.
233 *
234 * @return:
235 * FreeType error code. 0~means success.
236 *
237 * @note:
238 * Due to **PATENTS** covering subpixel rendering, this function doesn't
239 * do anything except returning `FT_Err_Unimplemented_Feature` if the
240 * configuration macro `FT_CONFIG_OPTION_SUBPIXEL_RENDERING` is not
241 * defined in your build of the library, which should correspond to all
242 * default builds of FreeType.
243 *
244 * LCD filter weights can also be set per face using @FT_Face_Properties
245 * with @FT_PARAM_TAG_LCD_FILTER_WEIGHTS.
246 *
247 * @since:
248 * 2.4.0
249 */
250 FT_EXPORT( FT_Error )
251 FT_Library_SetLcdFilterWeights( FT_Library library,
252 unsigned char *weights );
253
254
255 /**************************************************************************
256 *
257 * @type:
258 * FT_LcdFiveTapFilter
259 *
260 * @description:
261 * A typedef for passing the five LCD filter weights to
262 * @FT_Face_Properties within an @FT_Parameter structure.
263 *
264 * @since:
265 * 2.8
266 *
267 */
268 #define FT_LCD_FILTER_FIVE_TAPS 5
269
270 typedef FT_Byte FT_LcdFiveTapFilter[FT_LCD_FILTER_FIVE_TAPS];
271
272
273 /**************************************************************************
274 *
275 * @function:
276 * FT_Library_SetLcdGeometry
277 *
278 * @description:
279 * This function can be used to modify default positions of color
280 * subpixels, which controls Harmony LCD rendering.
281 *
282 * @input:
283 * library ::
284 * A handle to the target library instance.
285 *
286 * sub ::
287 * A pointer to an array of 3 vectors in 26.6 fractional pixel format;
288 * the function modifies the default values, see the note below.
289 *
290 * @return:
291 * FreeType error code. 0~means success.
292 *
293 * @note:
294 * Subpixel geometry examples:
295 *
296 * - {{-21, 0}, {0, 0}, {21, 0}} is the default, corresponding to 3 color
297 * stripes shifted by a third of a pixel. This could be an RGB panel.
298 *
299 * - {{21, 0}, {0, 0}, {-21, 0}} looks the same as the default but can
300 * specify a BGR panel instead, while keeping the bitmap in the same
301 * RGB888 format.
302 *
303 * - {{0, 21}, {0, 0}, {0, -21}} is the vertical RGB, but the bitmap
304 * stays RGB888 as a result.
305 *
306 * - {{-11, 16}, {-11, -16}, {22, 0}} is a certain PenTile arrangement.
307 *
308 * This function does nothing and returns `FT_Err_Unimplemented_Feature`
309 * in the context of ClearType-style subpixel rendering when
310 * `FT_CONFIG_OPTION_SUBPIXEL_RENDERING` is defined in your build of the
311 * library.
312 *
313 * @since:
314 * 2.10.0
315 */
316 FT_EXPORT( FT_Error )
317 FT_Library_SetLcdGeometry( FT_Library library,
318 FT_Vector sub[3] );
319
320 /* */
321
322
323 FT_END_HEADER
324
325 #endif /* FTLCDFIL_H_ */
326
327
328 /* END */