1 /***************************************************************************/
2 /*                                                                         */
3 /*  ftlcdfil.h                                                             */
4 /*                                                                         */
5 /*    FreeType API for color filtering of subpixel bitmap glyphs           */
6 /*    (specification).                                                     */
7 /*                                                                         */
8 /*  Copyright 2006-2008, 2010, 2013 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 FT_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 
33 FT_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    *   that 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 
246 FT_END_HEADER
247 
248 #endif /* __FT_LCD_FILTER_H__ */
249 
250 
251 /* END */
252