1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/modules/freetype2/include/ftlcdfil.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,251 @@
1.4 +/***************************************************************************/
1.5 +/* */
1.6 +/* ftlcdfil.h */
1.7 +/* */
1.8 +/* FreeType API for color filtering of subpixel bitmap glyphs */
1.9 +/* (specification). */
1.10 +/* */
1.11 +/* Copyright 2006-2008, 2010, 2013 by */
1.12 +/* David Turner, Robert Wilhelm, and Werner Lemberg. */
1.13 +/* */
1.14 +/* This file is part of the FreeType project, and may only be used, */
1.15 +/* modified, and distributed under the terms of the FreeType project */
1.16 +/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
1.17 +/* this file you indicate that you have read the license and */
1.18 +/* understand and accept it fully. */
1.19 +/* */
1.20 +/***************************************************************************/
1.21 +
1.22 +
1.23 +#ifndef __FT_LCD_FILTER_H__
1.24 +#define __FT_LCD_FILTER_H__
1.25 +
1.26 +#include <ft2build.h>
1.27 +#include FT_FREETYPE_H
1.28 +
1.29 +#ifdef FREETYPE_H
1.30 +#error "freetype.h of FreeType 1 has been loaded!"
1.31 +#error "Please fix the directory search order for header files"
1.32 +#error "so that freetype.h of FreeType 2 is found first."
1.33 +#endif
1.34 +
1.35 +
1.36 +FT_BEGIN_HEADER
1.37 +
1.38 + /***************************************************************************
1.39 + *
1.40 + * @section:
1.41 + * lcd_filtering
1.42 + *
1.43 + * @title:
1.44 + * LCD Filtering
1.45 + *
1.46 + * @abstract:
1.47 + * Reduce color fringes of LCD-optimized bitmaps.
1.48 + *
1.49 + * @description:
1.50 + * The @FT_Library_SetLcdFilter API can be used to specify a low-pass
1.51 + * filter, which is then applied to LCD-optimized bitmaps generated
1.52 + * through @FT_Render_Glyph. This is useful to reduce color fringes
1.53 + * that would occur with unfiltered rendering.
1.54 + *
1.55 + * Note that no filter is active by default, and that this function is
1.56 + * *not* implemented in default builds of the library. You need to
1.57 + * #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your `ftoption.h' file
1.58 + * in order to activate it.
1.59 + *
1.60 + * FreeType generates alpha coverage maps, which are linear by nature.
1.61 + * For instance, the value 0x80 in bitmap representation means that
1.62 + * (within numerical precision) 0x80/0xff fraction of that pixel is
1.63 + * covered by the glyph's outline. The blending function for placing
1.64 + * text over a background is
1.65 + *
1.66 + * {
1.67 + * dst = alpha * src + (1 - alpha) * dst ,
1.68 + * }
1.69 + *
1.70 + * which is known as OVER. However, when calculating the output of the
1.71 + * OVER operator, the source colors should first be transformed to a
1.72 + * linear color space, then alpha blended in that space, and transformed
1.73 + * back to the output color space.
1.74 + *
1.75 + * When linear light blending is used, the default FIR5 filtering
1.76 + * weights (as given by FT_LCD_FILTER_DEFAULT) are no longer optimal, as
1.77 + * they have been designed for black on white rendering while lacking
1.78 + * gamma correction. To preserve color neutrality, weights for a FIR5
1.79 + * filter should be chosen according to two free parameters `a' and `c',
1.80 + * and the FIR weights should be
1.81 + *
1.82 + * {
1.83 + * [a - c, a + c, 2 * a, a + c, a - c] .
1.84 + * }
1.85 + *
1.86 + * This formula generates equal weights for all the color primaries
1.87 + * across the filter kernel, which makes it colorless. One suggested
1.88 + * set of weights is
1.89 + *
1.90 + * {
1.91 + * [0x10, 0x50, 0x60, 0x50, 0x10] ,
1.92 + * }
1.93 + *
1.94 + * where `a' has value 0x30 and `b' value 0x20. The weights in filter
1.95 + * may have a sum larger than 0x100, which increases coloration slightly
1.96 + * but also improves contrast.
1.97 + */
1.98 +
1.99 +
1.100 + /****************************************************************************
1.101 + *
1.102 + * @enum:
1.103 + * FT_LcdFilter
1.104 + *
1.105 + * @description:
1.106 + * A list of values to identify various types of LCD filters.
1.107 + *
1.108 + * @values:
1.109 + * FT_LCD_FILTER_NONE ::
1.110 + * Do not perform filtering. When used with subpixel rendering, this
1.111 + * results in sometimes severe color fringes.
1.112 + *
1.113 + * FT_LCD_FILTER_DEFAULT ::
1.114 + * The default filter reduces color fringes considerably, at the cost
1.115 + * of a slight blurriness in the output.
1.116 + *
1.117 + * FT_LCD_FILTER_LIGHT ::
1.118 + * The light filter is a variant that produces less blurriness at the
1.119 + * cost of slightly more color fringes than the default one. It might
1.120 + * be better, depending on taste, your monitor, or your personal vision.
1.121 + *
1.122 + * FT_LCD_FILTER_LEGACY ::
1.123 + * This filter corresponds to the original libXft color filter. It
1.124 + * provides high contrast output but can exhibit really bad color
1.125 + * fringes if glyphs are not extremely well hinted to the pixel grid.
1.126 + * In other words, it only works well if the TrueType bytecode
1.127 + * interpreter is enabled *and* high-quality hinted fonts are used.
1.128 + *
1.129 + * This filter is only provided for comparison purposes, and might be
1.130 + * disabled or stay unsupported in the future.
1.131 + *
1.132 + * @since:
1.133 + * 2.3.0
1.134 + */
1.135 + typedef enum FT_LcdFilter_
1.136 + {
1.137 + FT_LCD_FILTER_NONE = 0,
1.138 + FT_LCD_FILTER_DEFAULT = 1,
1.139 + FT_LCD_FILTER_LIGHT = 2,
1.140 + FT_LCD_FILTER_LEGACY = 16,
1.141 +
1.142 + FT_LCD_FILTER_MAX /* do not remove */
1.143 +
1.144 + } FT_LcdFilter;
1.145 +
1.146 +
1.147 + /**************************************************************************
1.148 + *
1.149 + * @func:
1.150 + * FT_Library_SetLcdFilter
1.151 + *
1.152 + * @description:
1.153 + * This function is used to apply color filtering to LCD decimated
1.154 + * bitmaps, like the ones used when calling @FT_Render_Glyph with
1.155 + * @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
1.156 + *
1.157 + * @input:
1.158 + * library ::
1.159 + * A handle to the target library instance.
1.160 + *
1.161 + * filter ::
1.162 + * The filter type.
1.163 + *
1.164 + * You can use @FT_LCD_FILTER_NONE here to disable this feature, or
1.165 + * @FT_LCD_FILTER_DEFAULT to use a default filter that should work
1.166 + * well on most LCD screens.
1.167 + *
1.168 + * @return:
1.169 + * FreeType error code. 0~means success.
1.170 + *
1.171 + * @note:
1.172 + * This feature is always disabled by default. Clients must make an
1.173 + * explicit call to this function with a `filter' value other than
1.174 + * @FT_LCD_FILTER_NONE in order to enable it.
1.175 + *
1.176 + * Due to *PATENTS* covering subpixel rendering, this function doesn't
1.177 + * do anything except returning `FT_Err_Unimplemented_Feature' if the
1.178 + * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
1.179 + * defined in your build of the library, which should correspond to all
1.180 + * default builds of FreeType.
1.181 + *
1.182 + * The filter affects glyph bitmaps rendered through @FT_Render_Glyph,
1.183 + * @FT_Outline_Get_Bitmap, @FT_Load_Glyph, and @FT_Load_Char.
1.184 + *
1.185 + * It does _not_ affect the output of @FT_Outline_Render and
1.186 + * @FT_Outline_Get_Bitmap.
1.187 + *
1.188 + * If this feature is activated, the dimensions of LCD glyph bitmaps are
1.189 + * either larger or taller than the dimensions of the corresponding
1.190 + * outline with regards to the pixel grid. For example, for
1.191 + * @FT_RENDER_MODE_LCD, the filter adds up to 3~pixels to the left, and
1.192 + * up to 3~pixels to the right.
1.193 + *
1.194 + * The bitmap offset values are adjusted correctly, so clients shouldn't
1.195 + * need to modify their layout and glyph positioning code when enabling
1.196 + * the filter.
1.197 + *
1.198 + * @since:
1.199 + * 2.3.0
1.200 + */
1.201 + FT_EXPORT( FT_Error )
1.202 + FT_Library_SetLcdFilter( FT_Library library,
1.203 + FT_LcdFilter filter );
1.204 +
1.205 +
1.206 + /**************************************************************************
1.207 + *
1.208 + * @func:
1.209 + * FT_Library_SetLcdFilterWeights
1.210 + *
1.211 + * @description:
1.212 + * Use this function to override the filter weights selected by
1.213 + * @FT_Library_SetLcdFilter. By default, FreeType uses the quintuple
1.214 + * (0x00, 0x55, 0x56, 0x55, 0x00) for FT_LCD_FILTER_LIGHT, and (0x10,
1.215 + * 0x40, 0x70, 0x40, 0x10) for FT_LCD_FILTER_DEFAULT and
1.216 + * FT_LCD_FILTER_LEGACY.
1.217 + *
1.218 + * @input:
1.219 + * library ::
1.220 + * A handle to the target library instance.
1.221 + *
1.222 + * weights ::
1.223 + * A pointer to an array; the function copies the first five bytes and
1.224 + * uses them to specify the filter weights.
1.225 + *
1.226 + * @return:
1.227 + * FreeType error code. 0~means success.
1.228 + *
1.229 + * @note:
1.230 + * Due to *PATENTS* covering subpixel rendering, this function doesn't
1.231 + * do anything except returning `FT_Err_Unimplemented_Feature' if the
1.232 + * configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
1.233 + * defined in your build of the library, which should correspond to all
1.234 + * default builds of FreeType.
1.235 + *
1.236 + * This function must be called after @FT_Library_SetLcdFilter to have
1.237 + * any effect.
1.238 + *
1.239 + * @since:
1.240 + * 2.4.0
1.241 + */
1.242 + FT_EXPORT( FT_Error )
1.243 + FT_Library_SetLcdFilterWeights( FT_Library library,
1.244 + unsigned char *weights );
1.245 +
1.246 + /* */
1.247 +
1.248 +
1.249 +FT_END_HEADER
1.250 +
1.251 +#endif /* __FT_LCD_FILTER_H__ */
1.252 +
1.253 +
1.254 +/* END */
