Edit
kc3-lang/freetype/include/ftlcdfil.h
Werner Lemberg
- include/ftlcdfil.h
-
/***************************************************************************/ /* */ /* ftlcdfil.h */ /* */ /* FreeType API for color filtering of subpixel bitmap glyphs */ /* (specification). */ /* */ /* Copyright 2006-2015 by */ /* David Turner, Robert Wilhelm, and Werner Lemberg. */ /* */ /* This file is part of the FreeType project, and may only be used, */ /* modified, and distributed under the terms of the FreeType project */ /* license, LICENSE.TXT. By continuing to use, modify, or distribute */ /* this file you indicate that you have read the license and */ /* understand and accept it fully. */ /* */ /***************************************************************************/ #ifndef __FT_LCD_FILTER_H__ #define __FT_LCD_FILTER_H__ #include <ft2build.h> #include FT_FREETYPE_H #ifdef FREETYPE_H #error "freetype.h of FreeType 1 has been loaded!" #error "Please fix the directory search order for header files" #error "so that freetype.h of FreeType 2 is found first." #endif FT_BEGIN_HEADER /*************************************************************************** * * @section: * lcd_filtering * * @title: * LCD Filtering * * @abstract: * Reduce color fringes of LCD-optimized bitmaps. * * @description: * The @FT_Library_SetLcdFilter API can be used to specify a low-pass * filter, which is then applied to LCD-optimized bitmaps generated * through @FT_Render_Glyph. This is useful to reduce color fringes * that would occur with unfiltered rendering. * * Note that no filter is active by default, and that this function is * *not* implemented in default builds of the library. You need to * #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your `ftoption.h' file * in order to activate it. * * FreeType generates alpha coverage maps, which are linear by nature. * For instance, the value 0x80 in bitmap representation means that * (within numerical precision) 0x80/0xFF fraction of that pixel is * covered by the glyph's outline. The blending function for placing * text over a background is * * { * dst = alpha * src + (1 - alpha) * dst , * } * * which is known as OVER. However, when calculating the output of the * OVER operator, the source colors should first be transformed to a * linear color space, then alpha blended in that space, and transformed * back to the output color space. * * When linear light blending is used, the default FIR5 filtering * weights (as given by FT_LCD_FILTER_DEFAULT) are no longer optimal, as * they have been designed for black on white rendering while lacking * gamma correction. To preserve color neutrality, weights for a FIR5 * filter should be chosen according to two free parameters `a' and `c', * and the FIR weights should be * * { * [a - c, a + c, 2 * a, a + c, a - c] . * } * * This formula generates equal weights for all the color primaries * across the filter kernel, which makes it colorless. One suggested * set of weights is * * { * [0x10, 0x50, 0x60, 0x50, 0x10] , * } * * where `a' has value 0x30 and `b' value 0x20. The weights in filter * may have a sum larger than 0x100, which increases coloration slightly * but also improves contrast. */ /**************************************************************************** * * @enum: * FT_LcdFilter * * @description: * A list of values to identify various types of LCD filters. * * @values: * FT_LCD_FILTER_NONE :: * Do not perform filtering. When used with subpixel rendering, this * results in sometimes severe color fringes. * * FT_LCD_FILTER_DEFAULT :: * The default filter reduces color fringes considerably, at the cost * of a slight blurriness in the output. * * FT_LCD_FILTER_LIGHT :: * The light filter is a variant that produces less blurriness at the * cost of slightly more color fringes than the default one. It might * be better, depending on taste, your monitor, or your personal vision. * * FT_LCD_FILTER_LEGACY :: * This filter corresponds to the original libXft color filter. It * provides high contrast output but can exhibit really bad color * fringes if glyphs are not extremely well hinted to the pixel grid. * In other words, it only works well if the TrueType bytecode * interpreter is enabled *and* high-quality hinted fonts are used. * * This filter is only provided for comparison purposes, and might be * disabled or stay unsupported in the future. * * @since: * 2.3.0 */ typedef enum FT_LcdFilter_ { FT_LCD_FILTER_NONE = 0, FT_LCD_FILTER_DEFAULT = 1, FT_LCD_FILTER_LIGHT = 2, FT_LCD_FILTER_LEGACY = 16, FT_LCD_FILTER_MAX /* do not remove */ } FT_LcdFilter; /************************************************************************** * * @func: * FT_Library_SetLcdFilter * * @description: * This function is used to apply color filtering to LCD decimated * bitmaps, like the ones used when calling @FT_Render_Glyph with * @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V. * * @input: * library :: * A handle to the target library instance. * * filter :: * The filter type. * * You can use @FT_LCD_FILTER_NONE here to disable this feature, or * @FT_LCD_FILTER_DEFAULT to use a default filter that should work * well on most LCD screens. * * @return: * FreeType error code. 0~means success. * * @note: * This feature is always disabled by default. Clients must make an * explicit call to this function with a `filter' value other than * @FT_LCD_FILTER_NONE in order to enable it. * * Due to *PATENTS* covering subpixel rendering, this function doesn't * do anything except returning `FT_Err_Unimplemented_Feature' if the * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not * defined in your build of the library, which should correspond to all * default builds of FreeType. * * The filter affects glyph bitmaps rendered through @FT_Render_Glyph, * @FT_Outline_Get_Bitmap, @FT_Load_Glyph, and @FT_Load_Char. * * It does _not_ affect the output of @FT_Outline_Render and * @FT_Outline_Get_Bitmap. * * If this feature is activated, the dimensions of LCD glyph bitmaps are * either larger or taller than the dimensions of the corresponding * outline with regards to the pixel grid. For example, for * @FT_RENDER_MODE_LCD, the filter adds up to 3~pixels to the left, and * up to 3~pixels to the right. * * The bitmap offset values are adjusted correctly, so clients shouldn't * need to modify their layout and glyph positioning code when enabling * the filter. * * @since: * 2.3.0 */ FT_EXPORT( FT_Error ) FT_Library_SetLcdFilter( FT_Library library, FT_LcdFilter filter ); /************************************************************************** * * @func: * FT_Library_SetLcdFilterWeights * * @description: * Use this function to override the filter weights selected by * @FT_Library_SetLcdFilter. By default, FreeType uses the quintuple * (0x00, 0x55, 0x56, 0x55, 0x00) for FT_LCD_FILTER_LIGHT, and (0x10, * 0x40, 0x70, 0x40, 0x10) for FT_LCD_FILTER_DEFAULT and * FT_LCD_FILTER_LEGACY. * * @input: * library :: * A handle to the target library instance. * * weights :: * A pointer to an array; the function copies the first five bytes and * uses them to specify the filter weights. * * @return: * FreeType error code. 0~means success. * * @note: * Due to *PATENTS* covering subpixel rendering, this function doesn't * do anything except returning `FT_Err_Unimplemented_Feature' if the * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not * defined in your build of the library, which should correspond to all * default builds of FreeType. * * This function must be called after @FT_Library_SetLcdFilter to have * any effect. * * @since: * 2.4.0 */ FT_EXPORT( FT_Error ) FT_Library_SetLcdFilterWeights( FT_Library library, unsigned char *weights ); /* */ FT_END_HEADER #endif /* __FT_LCD_FILTER_H__ */ /* END */