Visualization Library 2.0.0-b5

A lightweight C++ OpenGL middleware for 2D/3D graphics

VL     Star     Watch     Fork     Issue

[Download] [Tutorials] [All Classes] [Grouped Classes]
ftlcdfil.h
Go to the documentation of this file.
1 /***************************************************************************/
2 /* */
3 /* ftlcdfil.h */
4 /* */
5 /* FreeType API for color filtering of subpixel bitmap glyphs */
6 /* (specification). */
7 /* */
8 /* Copyright 2006, 2007, 2008, 2010 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 __FT_LCD_FILTER_H__
21 #define __FT_LCD_FILTER_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 
34 
35  /***************************************************************************
36  *
37  * @section:
38  * lcd_filtering
39  *
40  * @title:
41  * LCD Filtering
42  *
43  * @abstract:
44  * Reduce color fringes of LCD-optimized bitmaps.
45  *
46  * @description:
47  * The @FT_Library_SetLcdFilter API can be used to specify a low-pass
48  * filter which is then applied to LCD-optimized bitmaps generated
49  * through @FT_Render_Glyph. This is useful to reduce color fringes
50  * which would occur with unfiltered rendering.
51  *
52  * Note that no filter is active by default, and that this function is
53  * *not* implemented in default builds of the library. You need to
54  * #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your `ftoption.h' file
55  * in order to activate it.
56  *
57  * FreeType generates alpha coverage maps, which are linear by nature.
58  * For instance, the value 0x80 in bitmap representation means that
59  * (within numerical precision) 0x80/0xff fraction of that pixel is
60  * covered by the glyph's outline. The blending function for placing
61  * text over a background is
62  *
63  * {
64  * dst = alpha * src + (1 - alpha) * dst ,
65  * }
66  *
67  * which is known as OVER. However, when calculating the output of the
68  * OVER operator, the source colors should first be transformed to a
69  * linear color space, then alpha blended in that space, and transformed
70  * back to the output color space.
71  *
72  * When linear light blending is used, the default FIR5 filtering
73  * weights (as given by FT_LCD_FILTER_DEFAULT) are no longer optimal, as
74  * they have been designed for black on white rendering while lacking
75  * gamma correction. To preserve color neutrality, weights for a FIR5
76  * filter should be chosen according to two free parameters `a' and `c',
77  * and the FIR weights should be
78  *
79  * {
80  * [a - c, a + c, 2 * a, a + c, a - c] .
81  * }
82  *
83  * This formula generates equal weights for all the color primaries
84  * across the filter kernel, which makes it colorless. One suggested
85  * set of weights is
86  *
87  * {
88  * [0x10, 0x50, 0x60, 0x50, 0x10] ,
89  * }
90  *
91  * where `a' has value 0x30 and `b' value 0x20. The weights in filter
92  * may have a sum larger than 0x100, which increases coloration slightly
93  * but also improves contrast.
94  */
95 
96 
97  /****************************************************************************
98  *
99  * @enum:
100  * FT_LcdFilter
101  *
102  * @description:
103  * A list of values to identify various types of LCD filters.
104  *
105  * @values:
106  * FT_LCD_FILTER_NONE ::
107  * Do not perform filtering. When used with subpixel rendering, this
108  * results in sometimes severe color fringes.
109  *
110  * FT_LCD_FILTER_DEFAULT ::
111  * The default filter reduces color fringes considerably, at the cost
112  * of a slight blurriness in the output.
113  *
114  * FT_LCD_FILTER_LIGHT ::
115  * The light filter is a variant that produces less blurriness at the
116  * cost of slightly more color fringes than the default one. It might
117  * be better, depending on taste, your monitor, or your personal vision.
118  *
119  * FT_LCD_FILTER_LEGACY ::
120  * This filter corresponds to the original libXft color filter. It
121  * provides high contrast output but can exhibit really bad color
122  * fringes if glyphs are not extremely well hinted to the pixel grid.
123  * In other words, it only works well if the TrueType bytecode
124  * interpreter is enabled *and* high-quality hinted fonts are used.
125  *
126  * This filter is only provided for comparison purposes, and might be
127  * disabled or stay unsupported in the future.
128  *
129  * @since:
130  * 2.3.0
131  */
132  typedef enum FT_LcdFilter_
133  {
138 
139  FT_LCD_FILTER_MAX /* do not remove */
140 
141  } FT_LcdFilter;
142 
143 
144  /**************************************************************************
145  *
146  * @func:
147  * FT_Library_SetLcdFilter
148  *
149  * @description:
150  * This function is used to apply color filtering to LCD decimated
151  * bitmaps, like the ones used when calling @FT_Render_Glyph with
152  * @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
153  *
154  * @input:
155  * library ::
156  * A handle to the target library instance.
157  *
158  * filter ::
159  * The filter type.
160  *
161  * You can use @FT_LCD_FILTER_NONE here to disable this feature, or
162  * @FT_LCD_FILTER_DEFAULT to use a default filter that should work
163  * well on most LCD screens.
164  *
165  * @return:
166  * FreeType error code. 0~means success.
167  *
168  * @note:
169  * This feature is always disabled by default. Clients must make an
170  * explicit call to this function with a `filter' value other than
171  * @FT_LCD_FILTER_NONE in order to enable it.
172  *
173  * Due to *PATENTS* covering subpixel rendering, this function doesn't
174  * do anything except returning `FT_Err_Unimplemented_Feature' if the
175  * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
176  * defined in your build of the library, which should correspond to all
177  * default builds of FreeType.
178  *
179  * The filter affects glyph bitmaps rendered through @FT_Render_Glyph,
180  * @FT_Outline_Get_Bitmap, @FT_Load_Glyph, and @FT_Load_Char.
181  *
182  * It does _not_ affect the output of @FT_Outline_Render and
183  * @FT_Outline_Get_Bitmap.
184  *
185  * If this feature is activated, the dimensions of LCD glyph bitmaps are
186  * either larger or taller than the dimensions of the corresponding
187  * outline with regards to the pixel grid. For example, for
188  * @FT_RENDER_MODE_LCD, the filter adds up to 3~pixels to the left, and
189  * up to 3~pixels to the right.
190  *
191  * The bitmap offset values are adjusted correctly, so clients shouldn't
192  * need to modify their layout and glyph positioning code when enabling
193  * the filter.
194  *
195  * @since:
196  * 2.3.0
197  */
201 
202 
203  /**************************************************************************
204  *
205  * @func:
206  * FT_Library_SetLcdFilterWeights
207  *
208  * @description:
209  * Use this function to override the filter weights selected by
210  * @FT_Library_SetLcdFilter. By default, FreeType uses the quintuple
211  * (0x00, 0x55, 0x56, 0x55, 0x00) for FT_LCD_FILTER_LIGHT, and (0x10,
212  * 0x40, 0x70, 0x40, 0x10) for FT_LCD_FILTER_DEFAULT and
213  * FT_LCD_FILTER_LEGACY.
214  *
215  * @input:
216  * library ::
217  * A handle to the target library instance.
218  *
219  * weights ::
220  * A pointer to an array; the function copies the first five bytes and
221  * uses them to specify the filter weights.
222  *
223  * @return:
224  * FreeType error code. 0~means success.
225  *
226  * @note:
227  * Due to *PATENTS* covering subpixel rendering, this function doesn't
228  * do anything except returning `FT_Err_Unimplemented_Feature' if the
229  * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
230  * defined in your build of the library, which should correspond to all
231  * default builds of FreeType.
232  *
233  * This function must be called after @FT_Library_SetLcdFilter to have
234  * any effect.
235  *
236  * @since:
237  * 2.4.0
238  */
241  unsigned char *weights );
242 
243  /* */
244 
245 
247 
248 #endif /* __FT_LCD_FILTER_H__ */
249 
250 
251 /* END */
int FT_Error
Definition: fttypes.h:296
FT_Library_SetLcdFilterWeights(FT_Library library, unsigned char *weights)
Definition: ftlcdfil.c:355
const GLbyte * weights
#define FT_END_HEADER
Definition: ftheader.h:54
FT_Library library
Definition: cffdrivr.c:414
#define FT_BEGIN_HEADER
Definition: ftheader.h:36
GLint GLint GLint GLint GLint GLint GLint GLbitfield GLenum filter
FT_LcdFilter_
Definition: ftlcdfil.h:132
#define FT_EXPORT(x)
Definition: ftconfig.h:269
FT_BEGIN_HEADER enum FT_LcdFilter_ FT_LcdFilter
FT_Library_SetLcdFilter(FT_Library library, FT_LcdFilter filter)
Definition: ftlcdfil.c:366