123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251 |
- /***************************************************************************/
- /* */
- /* ftlcdfil.h */
- /* */
- /* FreeType API for color filtering of subpixel bitmap glyphs */
- /* (specification). */
- /* */
- /* Copyright 2006-2008, 2010, 2013 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 */
|