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 33 FT_BEGIN_HEADER 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 58 59 /**************************************************************************** 60 * 61 * @enum: 62 * FT_LcdFilter 63 * 64 * @description: 65 * A list of values to identify various types of LCD filters. 66 * 67 * @values: 68 * FT_LCD_FILTER_NONE :: 69 * Do not perform filtering. When used with subpixel rendering, this 70 * results in sometimes severe color fringes. 71 * 72 * FT_LCD_FILTER_DEFAULT :: 73 * The default filter reduces color fringes considerably, at the cost 74 * of a slight blurriness in the output. 75 * 76 * FT_LCD_FILTER_LIGHT :: 77 * The light filter is a variant that produces less blurriness at the 78 * cost of slightly more color fringes than the default one. It might 79 * be better, depending on taste, your monitor, or your personal vision. 80 * 81 * FT_LCD_FILTER_LEGACY :: 82 * This filter corresponds to the original libXft color filter. It 83 * provides high contrast output but can exhibit really bad color 84 * fringes if glyphs are not extremely well hinted to the pixel grid. 85 * In other words, it only works well if the TrueType bytecode 86 * interpreter is enabled *and* high-quality hinted fonts are used. 87 * 88 * This filter is only provided for comparison purposes, and might be 89 * disabled or stay unsupported in the future. 90 * 91 * @since: 92 * 2.3.0 93 */ 94 typedef enum FT_LcdFilter_ 95 { 96 FT_LCD_FILTER_NONE = 0, 97 FT_LCD_FILTER_DEFAULT = 1, 98 FT_LCD_FILTER_LIGHT = 2, 99 FT_LCD_FILTER_LEGACY = 16, 100 101 FT_LCD_FILTER_MAX /* do not remove */ 102 103 } FT_LcdFilter; 104 105 106 /************************************************************************** 107 * 108 * @func: 109 * FT_Library_SetLcdFilter 110 * 111 * @description: 112 * This function is used to apply color filtering to LCD decimated 113 * bitmaps, like the ones used when calling @FT_Render_Glyph with 114 * @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V. 115 * 116 * @input: 117 * library :: 118 * A handle to the target library instance. 119 * 120 * filter :: 121 * The filter type. 122 * 123 * You can use @FT_LCD_FILTER_NONE here to disable this feature, or 124 * @FT_LCD_FILTER_DEFAULT to use a default filter that should work 125 * well on most LCD screens. 126 * 127 * @return: 128 * FreeType error code. 0~means success. 129 * 130 * @note: 131 * This feature is always disabled by default. Clients must make an 132 * explicit call to this function with a `filter' value other than 133 * @FT_LCD_FILTER_NONE in order to enable it. 134 * 135 * Due to *PATENTS* covering subpixel rendering, this function doesn't 136 * do anything except returning `FT_Err_Unimplemented_Feature' if the 137 * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not 138 * defined in your build of the library, which should correspond to all 139 * default builds of FreeType. 140 * 141 * The filter affects glyph bitmaps rendered through @FT_Render_Glyph, 142 * @FT_Outline_Get_Bitmap, @FT_Load_Glyph, and @FT_Load_Char. 143 * 144 * It does _not_ affect the output of @FT_Outline_Render and 145 * @FT_Outline_Get_Bitmap. 146 * 147 * If this feature is activated, the dimensions of LCD glyph bitmaps are 148 * either larger or taller than the dimensions of the corresponding 149 * outline with regards to the pixel grid. For example, for 150 * @FT_RENDER_MODE_LCD, the filter adds up to 3~pixels to the left, and 151 * up to 3~pixels to the right. 152 * 153 * The bitmap offset values are adjusted correctly, so clients shouldn't 154 * need to modify their layout and glyph positioning code when enabling 155 * the filter. 156 * 157 * @since: 158 * 2.3.0 159 */ 160 FT_EXPORT( FT_Error ) 161 FT_Library_SetLcdFilter( FT_Library library, 162 FT_LcdFilter filter ); 163 164 165 /************************************************************************** 166 * 167 * @func: 168 * FT_Library_SetLcdFilterWeights 169 * 170 * @description: 171 * Use this function to override the filter weights selected by 172 * @FT_Library_SetLcdFilter. By default, FreeType uses the quintuple 173 * (0x00, 0x55, 0x56, 0x55, 0x00) for FT_LCD_FILTER_LIGHT, and (0x10, 174 * 0x40, 0x70, 0x40, 0x10) for FT_LCD_FILTER_DEFAULT and 175 * FT_LCD_FILTER_LEGACY. 176 * 177 * @input: 178 * library :: 179 * A handle to the target library instance. 180 * 181 * weights :: 182 * A pointer to an array; the function copies the first five bytes and 183 * uses them to specify the filter weights. 184 * 185 * @return: 186 * FreeType error code. 0~means success. 187 * 188 * @note: 189 * Due to *PATENTS* covering subpixel rendering, this function doesn't 190 * do anything except returning `FT_Err_Unimplemented_Feature' if the 191 * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not 192 * defined in your build of the library, which should correspond to all 193 * default builds of FreeType. 194 * 195 * This function must be called after @FT_Library_SetLcdFilter to have 196 * any effect. 197 * 198 * @since: 199 * 2.4.0 200 */ 201 FT_EXPORT( FT_Error ) 202 FT_Library_SetLcdFilterWeights( FT_Library library, 203 unsigned char *weights ); 204 205 /* */ 206 207 208 FT_END_HEADER 209 210 #endif /* __FT_LCD_FILTER_H__ */ 211 212 213 /* END */ 214