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