1 /***************************************************************************/
5 /* FreeType API for color filtering of subpixel bitmap glyphs */
8 /* Copyright 2006, 2007 by */
9 /* David Turner, Robert Wilhelm, and Werner Lemberg. */
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. */
17 /***************************************************************************/
20 #ifndef __FT_LCD_FILTER_H__
21 #define __FT_LCD_FILTER_H__
24 #include FT_FREETYPE_H
29 /***************************************************************************
38 * Reduce color fringes of LCD-optimized bitmaps.
41 * The @FT_Library_SetLcdFilter API can be used to specify a low-pass
42 * filter which is then applied to LCD-optimized bitmaps generated
43 * through @FT_Render_Glyph. This is useful to reduce color fringes
44 * which would occur with unfiltered rendering.
46 * Note that no filter is active by default, and that this function is
47 * *not* implemented in default builds of the library. You need to
48 * #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your `ftoption.h' file
49 * in order to activate it.
53 /****************************************************************************
59 * A list of values to identify various types of LCD filters.
62 * FT_LCD_FILTER_NONE ::
63 * Do not perform filtering. When used with subpixel rendering, this
64 * results in sometimes severe color fringes.
66 * FT_LCD_FILTER_DEFAULT ::
67 * The default filter reduces color fringes considerably, at the cost
68 * of a slight blurriness in the output.
70 * FT_LCD_FILTER_LIGHT ::
71 * The light filter is a variant that produces less blurriness at the
72 * cost of slightly more color fringes than the default one. It might
73 * be better, depending on taste, your monitor, or your personal vision.
75 * FT_LCD_FILTER_LEGACY ::
76 * This filter corresponds to the original libXft color filter. It
77 * provides high contrast output but can exhibit really bad color
78 * fringes if glyphs are not extremely well hinted to the pixel grid.
79 * In other words, it only works well if the TrueType bytecode
80 * interpreter is enabled *and* high-quality hinted fonts are used.
82 * This filter is only provided for comparison purposes, and might be
83 * disabled or stay unsupported in the future.
90 FT_LCD_FILTER_NONE
= 0,
91 FT_LCD_FILTER_DEFAULT
= 1,
92 FT_LCD_FILTER_LIGHT
= 2,
93 FT_LCD_FILTER_LEGACY
= 16,
95 FT_LCD_FILTER_MAX
/* do not remove */
100 /**************************************************************************
103 * FT_Library_SetLcdFilter
106 * This function is used to apply color filtering to LCD decimated
107 * bitmaps, like the ones used when calling @FT_Render_Glyph with
108 * @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
112 * A handle to the target library instance.
117 * You can use @FT_LCD_FILTER_NONE here to disable this feature, or
118 * @FT_LCD_FILTER_DEFAULT to use a default filter that should work
119 * well on most LCD screens.
122 * FreeType error code. 0 means success.
125 * This feature is always disabled by default. Clients must make an
126 * explicit call to this function with a `filter' value other than
127 * @FT_LCD_FILTER_NONE in order to enable it.
129 * Due to *PATENTS* covering subpixel rendering, this function doesn't
130 * do anything except returning `FT_Err_Unimplemented_Feature' if the
131 * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
132 * defined in your build of the library, which should correspond to all
133 * default builds of FreeType.
135 * The filter affects glyph bitmaps rendered through @FT_Render_Glyph,
136 * @FT_Outline_Get_Bitmap, @FT_Load_Glyph, and @FT_Load_Char.
138 * It does _not_ affect the output of @FT_Outline_Render and
139 * @FT_Outline_Get_Bitmap.
141 * If this feature is activated, the dimensions of LCD glyph bitmaps are
142 * either larger or taller than the dimensions of the corresponding
143 * outline with regards to the pixel grid. For example, for
144 * @FT_RENDER_MODE_LCD, the filter adds up to 3 pixels to the left, and
145 * up to 3 pixels to the right.
147 * The bitmap offset values are adjusted correctly, so clients shouldn't
148 * need to modify their layout and glyph positioning code when enabling
154 FT_EXPORT( FT_Error
)
155 FT_Library_SetLcdFilter( FT_Library library
,
156 FT_LcdFilter filter
);
163 #endif /* __FT_LCD_FILTER_H__ */