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 "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 33FT_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 * 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 { 134 FT_LCD_FILTER_NONE = 0, 135 FT_LCD_FILTER_DEFAULT = 1, 136 FT_LCD_FILTER_LIGHT = 2, 137 FT_LCD_FILTER_LEGACY = 16, 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 */ 198 FT_EXPORT( FT_Error ) 199 FT_Library_SetLcdFilter( FT_Library library, 200 FT_LcdFilter filter ); 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 */ 239 FT_EXPORT( FT_Error ) 240 FT_Library_SetLcdFilterWeights( FT_Library library, 241 unsigned char *weights ); 242 243 /* */ 244 245 246FT_END_HEADER 247 248#endif /* __FT_LCD_FILTER_H__ */ 249 250 251/* END */ 252