1/***************************************************************************/
2/*                                                                         */
3/*  ftlcdfil.h                                                             */
4/*                                                                         */
5/*    FreeType API for color filtering of subpixel bitmap glyphs           */
6/*    (specification).                                                     */
7/*                                                                         */
8/*  Copyright 2006, 2007, 2008, 2010 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
33FT_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   *   which 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
58
59  /****************************************************************************
60   *
61   * @enum:
62   *   FT_LcdFilter
63   *
64   * @description:
65   *   A list of values to identify various types of LCD filters.
66   *
67   * @values:
68   *   FT_LCD_FILTER_NONE ::
69   *     Do not perform filtering.  When used with subpixel rendering, this
70   *     results in sometimes severe color fringes.
71   *
72   *   FT_LCD_FILTER_DEFAULT ::
73   *     The default filter reduces color fringes considerably, at the cost
74   *     of a slight blurriness in the output.
75   *
76   *   FT_LCD_FILTER_LIGHT ::
77   *     The light filter is a variant that produces less blurriness at the
78   *     cost of slightly more color fringes than the default one.  It might
79   *     be better, depending on taste, your monitor, or your personal vision.
80   *
81   *   FT_LCD_FILTER_LEGACY ::
82   *     This filter corresponds to the original libXft color filter.  It
83   *     provides high contrast output but can exhibit really bad color
84   *     fringes if glyphs are not extremely well hinted to the pixel grid.
85   *     In other words, it only works well if the TrueType bytecode
86   *     interpreter is enabled *and* high-quality hinted fonts are used.
87   *
88   *     This filter is only provided for comparison purposes, and might be
89   *     disabled or stay unsupported in the future.
90   *
91   * @since:
92   *   2.3.0
93   */
94  typedef enum  FT_LcdFilter_
95  {
96    FT_LCD_FILTER_NONE    = 0,
97    FT_LCD_FILTER_DEFAULT = 1,
98    FT_LCD_FILTER_LIGHT   = 2,
99    FT_LCD_FILTER_LEGACY  = 16,
100
101    FT_LCD_FILTER_MAX   /* do not remove */
102
103  } FT_LcdFilter;
104
105
106  /**************************************************************************
107   *
108   * @func:
109   *   FT_Library_SetLcdFilter
110   *
111   * @description:
112   *   This function is used to apply color filtering to LCD decimated
113   *   bitmaps, like the ones used when calling @FT_Render_Glyph with
114   *   @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
115   *
116   * @input:
117   *   library ::
118   *     A handle to the target library instance.
119   *
120   *   filter ::
121   *     The filter type.
122   *
123   *     You can use @FT_LCD_FILTER_NONE here to disable this feature, or
124   *     @FT_LCD_FILTER_DEFAULT to use a default filter that should work
125   *     well on most LCD screens.
126   *
127   * @return:
128   *   FreeType error code.  0~means success.
129   *
130   * @note:
131   *   This feature is always disabled by default.  Clients must make an
132   *   explicit call to this function with a `filter' value other than
133   *   @FT_LCD_FILTER_NONE in order to enable it.
134   *
135   *   Due to *PATENTS* covering subpixel rendering, this function doesn't
136   *   do anything except returning `FT_Err_Unimplemented_Feature' if the
137   *   configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
138   *   defined in your build of the library, which should correspond to all
139   *   default builds of FreeType.
140   *
141   *   The filter affects glyph bitmaps rendered through @FT_Render_Glyph,
142   *   @FT_Outline_Get_Bitmap, @FT_Load_Glyph, and @FT_Load_Char.
143   *
144   *   It does _not_ affect the output of @FT_Outline_Render and
145   *   @FT_Outline_Get_Bitmap.
146   *
147   *   If this feature is activated, the dimensions of LCD glyph bitmaps are
148   *   either larger or taller than the dimensions of the corresponding
149   *   outline with regards to the pixel grid.  For example, for
150   *   @FT_RENDER_MODE_LCD, the filter adds up to 3~pixels to the left, and
151   *   up to 3~pixels to the right.
152   *
153   *   The bitmap offset values are adjusted correctly, so clients shouldn't
154   *   need to modify their layout and glyph positioning code when enabling
155   *   the filter.
156   *
157   * @since:
158   *   2.3.0
159   */
160  FT_EXPORT( FT_Error )
161  FT_Library_SetLcdFilter( FT_Library    library,
162                           FT_LcdFilter  filter );
163
164
165  /**************************************************************************
166   *
167   * @func:
168   *   FT_Library_SetLcdFilterWeights
169   *
170   * @description:
171   *   Use this function to override the filter weights selected by
172   *   @FT_Library_SetLcdFilter.  By default, FreeType uses the quintuple
173   *   (0x00, 0x55, 0x56, 0x55, 0x00) for FT_LCD_FILTER_LIGHT, and (0x10,
174   *   0x40, 0x70, 0x40, 0x10) for FT_LCD_FILTER_DEFAULT and
175   *   FT_LCD_FILTER_LEGACY.
176   *
177   * @input:
178   *   library ::
179   *     A handle to the target library instance.
180   *
181   *   weights ::
182   *     A pointer to an array; the function copies the first five bytes and
183   *     uses them to specify the filter weights.
184   *
185   * @return:
186   *   FreeType error code.  0~means success.
187   *
188   * @note:
189   *   Due to *PATENTS* covering subpixel rendering, this function doesn't
190   *   do anything except returning `FT_Err_Unimplemented_Feature' if the
191   *   configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
192   *   defined in your build of the library, which should correspond to all
193   *   default builds of FreeType.
194   *
195   *   This function must be called after @FT_Library_SetLcdFilter to have
196   *   any effect.
197   *
198   * @since:
199   *   2.4.0
200   */
201  FT_EXPORT( FT_Error )
202  FT_Library_SetLcdFilterWeights( FT_Library      library,
203                                  unsigned char  *weights );
204
205  /* */
206
207
208FT_END_HEADER
209
210#endif /* __FT_LCD_FILTER_H__ */
211
212
213/* END */
214