• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /****************************************************************************
2  *
3  * ftlcdfil.h
4  *
5  *   FreeType API for color filtering of subpixel bitmap glyphs
6  *   (specification).
7  *
8  * Copyright 2006-2018 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 FTLCDFIL_H_
21 #define FTLCDFIL_H_
22 
23 #include <ft2build.h>
24 #include FT_FREETYPE_H
25 #include FT_PARAMETER_TAGS_H
26 
27 #ifdef FREETYPE_H
28 #error "freetype.h of FreeType 1 has been loaded!"
29 #error "Please fix the directory search order for header files"
30 #error "so that freetype.h of FreeType 2 is found first."
31 #endif
32 
33 
34 FT_BEGIN_HEADER
35 
36   /***************************************************************************
37    *
38    * @section:
39    *   lcd_rendering
40    *
41    * @title:
42    *   Subpixel Rendering
43    *
44    * @abstract:
45    *   API to control subpixel rendering.
46    *
47    * @description:
48    *   FreeType provides two alternative subpixel rendering technologies.
49    *   Should you #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your
50    *   `ftoption.h', this enables patented ClearType-style rendering.
51    *   Otherwise, Harmony LCD rendering is enabled.  These technologies are
52    *   controlled differently and API described below, although always
53    *   available, performs its function when appropriate method is enabled
54    *   and does nothing otherwise.
55    *
56    *   ClearType-style LCD rendering exploits the color-striped structure of
57    *   LCD pixels, increasing the available resolution in the direction of
58    *   the stripe (usually horizontal RGB) by a factor of~3.  Using the
59    *   subpixels coverages unfiltered can create severe color fringes
60    *   especially when rendering thin features.  Indeed, to produce
61    *   black-on-white text, the nearby color subpixels must be dimmed equally.
62    *
63    *   A good 5-tap FIR filter should be applied to subpixel coverages
64    *   regardless of pixel boundaries and should have these properties:
65    *
66    *   1) It should be symmetrical, like {~a, b, c, b, a~}, to avoid
67    *      any shifts in appearance.
68    *
69    *   2) It should be color-balanced, meaning a~+ b~=~c, to reduce color
70    *      fringes by distributing the computed coverage for one subpixel to
71    *      all subpixels equally.
72    *
73    *   3) It should be normalized, meaning 2a~+ 2b~+ c~=~1.0 to maintain
74    *      overall brightness.
75    *
76    *   Boxy 3-tap filter {0, 1/3, 1/3, 1/3, 0} is sharper but is less
77    *   forgiving of non-ideal gamma curves of a screen (and viewing angles),
78    *   beveled filters are fuzzier but more tolerant.
79    *
80    *   Use the @FT_Library_SetLcdFilter or @FT_Library_SetLcdFilterWeights
81    *   API to specify a low-pass filter, which is then applied to
82    *   subpixel-rendered bitmaps generated through @FT_Render_Glyph.
83    *
84    *   Harmony LCD rendering is suitable to panels with any regular subpixel
85    *   structure, not just monitors with 3 color striped subpixels, as long as
86    *   the color subpixels have fixed positions relative to the pixel center.
87    *   In this case, each color channel is then rendered separately after
88    *   shifting the outline opposite to the subpixel shift so that the
89    *   coverage maps are aligned.  This method is immune to color fringes
90    *   because the shifts do not change integral coverage.
91    *
92    *   The subpixel geometry must be specified by xy-coordinates for each
93    *   subpixel. By convention they may come in the RGB order:
94    *   {{-1/3, 0}, {0, 0}, {1/3, 0}} for standard RGB striped panel or
95    *   {{-1/6, 1/4}, {-1/6, -1/4}, {1/3, 0}} for a certain PenTile panel.
96    *
97    *   Use the @FT_Library_SetLcdGeometry API to specify subpixel positions.
98    *   If one follows the RGB order convention, the same order applies
99    *   to the resulting @FT_PIXEL_MODE_LCD and @FT_PIXEL_MODE_LCD_V bitmaps.
100    *   Note, however, that the coordinate frame for the latter must be rotated
101    *   clockwise.  Harmony with default LCD geometry is equivalent to
102    *   ClearType with light filter.
103    *
104    *   As a result of ClearType filtering or Harmony rendering, the dimensions
105    *   of LCD bitmaps can be either wider or taller than the dimensions of
106    *   the corresponding outline with regard to the pixel grid.  For example,
107    *   for @FT_RENDER_MODE_LCD, the filter adds 2~subpixels to the left, and
108    *   2~subpixels to the right.  The bitmap offset values are adjusted
109    *   accordingly, so clients shouldn't need to modify their layout and
110    *   glyph positioning code when enabling the filter.
111    *
112    *   The ClearType and Harmony rendering is applicable to glyph bitmaps
113    *   rendered through @FT_Render_Glyph, @FT_Load_Glyph, @FT_Load_Char, and
114    *   @FT_Glyph_To_Bitmap, when @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V
115    *   is specified.  This API does not control @FT_Outline_Render and
116    *   @FT_Outline_Get_Bitmap.
117    *
118    *   The described algorithms can completely remove color artefacts when
119    *   combined with gamma-corrected alpha blending in linear space.
120    *   Each of the 3~alpha values (subpixels) must by independently used to
121    *   blend one color channel.  That is, red alpha blends the red channel of
122    *   the text color with the red channel of the background pixel.
123    */
124 
125 
126   /****************************************************************************
127    *
128    * @enum:
129    *   FT_LcdFilter
130    *
131    * @description:
132    *   A list of values to identify various types of LCD filters.
133    *
134    * @values:
135    *   FT_LCD_FILTER_NONE ::
136    *     Do not perform filtering.  When used with subpixel rendering, this
137    *     results in sometimes severe color fringes.
138    *
139    *   FT_LCD_FILTER_DEFAULT ::
140    *     This is a beveled, normalized, and color-balanced five-tap filter
141    *     with weights of [0x08 0x4D 0x56 0x4D 0x08] in 1/256th units.
142    *
143    *   FT_LCD_FILTER_LIGHT ::
144    *     this is a boxy, normalized, and color-balanced three-tap filter
145    *     with weights of [0x00 0x55 0x56 0x55 0x00] in 1/256th units.
146    *
147    *   FT_LCD_FILTER_LEGACY ::
148    *   FT_LCD_FILTER_LEGACY1 ::
149    *     This filter corresponds to the original libXft color filter.  It
150    *     provides high contrast output but can exhibit really bad color
151    *     fringes if glyphs are not extremely well hinted to the pixel grid.
152    *     This filter is only provided for comparison purposes, and might be
153    *     disabled or stay unsupported in the future. The second value is
154    *     provided for compatibility with FontConfig, which historically
155    *     used different enumeration, sometimes incorrectly forwarded to
156    *     FreeType.
157    *
158    * @since:
159    *   2.3.0 (`FT_LCD_FILTER_LEGACY1' since 2.6.2)
160    */
161   typedef enum  FT_LcdFilter_
162   {
163     FT_LCD_FILTER_NONE    = 0,
164     FT_LCD_FILTER_DEFAULT = 1,
165     FT_LCD_FILTER_LIGHT   = 2,
166     FT_LCD_FILTER_LEGACY1 = 3,
167     FT_LCD_FILTER_LEGACY  = 16,
168 
169     FT_LCD_FILTER_MAX   /* do not remove */
170 
171   } FT_LcdFilter;
172 
173 
174   /**************************************************************************
175    *
176    * @function:
177    *   FT_Library_SetLcdFilter
178    *
179    * @description:
180    *   This function is used to apply color filtering to LCD decimated
181    *   bitmaps, like the ones used when calling @FT_Render_Glyph with
182    *   @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
183    *
184    * @input:
185    *   library ::
186    *     A handle to the target library instance.
187    *
188    *   filter ::
189    *     The filter type.
190    *
191    *     You can use @FT_LCD_FILTER_NONE here to disable this feature, or
192    *     @FT_LCD_FILTER_DEFAULT to use a default filter that should work
193    *     well on most LCD screens.
194    *
195    * @return:
196    *   FreeType error code.  0~means success.
197    *
198    * @note:
199    *   This feature is always disabled by default.  Clients must make an
200    *   explicit call to this function with a `filter' value other than
201    *   @FT_LCD_FILTER_NONE in order to enable it.
202    *
203    *   Due to *PATENTS* covering subpixel rendering, this function doesn't
204    *   do anything except returning `FT_Err_Unimplemented_Feature' if the
205    *   configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
206    *   defined in your build of the library, which should correspond to all
207    *   default builds of FreeType.
208    *
209    * @since:
210    *   2.3.0
211    */
212   FT_EXPORT( FT_Error )
213   FT_Library_SetLcdFilter( FT_Library    library,
214                            FT_LcdFilter  filter );
215 
216 
217   /**************************************************************************
218    *
219    * @function:
220    *   FT_Library_SetLcdFilterWeights
221    *
222    * @description:
223    *   This function can be used to enable LCD filter with custom weights,
224    *   instead of using presets in @FT_Library_SetLcdFilter.
225    *
226    * @input:
227    *   library ::
228    *     A handle to the target library instance.
229    *
230    *   weights ::
231    *     A pointer to an array; the function copies the first five bytes and
232    *     uses them to specify the filter weights in 1/256th units.
233    *
234    * @return:
235    *   FreeType error code.  0~means success.
236    *
237    * @note:
238    *   Due to *PATENTS* covering subpixel rendering, this function doesn't
239    *   do anything except returning `FT_Err_Unimplemented_Feature' if the
240    *   configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
241    *   defined in your build of the library, which should correspond to all
242    *   default builds of FreeType.
243    *
244    *   LCD filter weights can also be set per face using @FT_Face_Properties
245    *   with @FT_PARAM_TAG_LCD_FILTER_WEIGHTS.
246    *
247    * @since:
248    *   2.4.0
249    */
250   FT_EXPORT( FT_Error )
251   FT_Library_SetLcdFilterWeights( FT_Library      library,
252                                   unsigned char  *weights );
253 
254 
255   /**************************************************************************
256    *
257    * @type:
258    *   FT_LcdFiveTapFilter
259    *
260    * @description:
261    *   A typedef for passing the five LCD filter weights to
262    *   @FT_Face_Properties within an @FT_Parameter structure.
263    *
264    * @since:
265    *   2.8
266    *
267    */
268 #define FT_LCD_FILTER_FIVE_TAPS  5
269 
270   typedef FT_Byte  FT_LcdFiveTapFilter[FT_LCD_FILTER_FIVE_TAPS];
271 
272 
273   /**************************************************************************
274    *
275    * @function:
276    *   FT_Library_SetLcdGeometry
277    *
278    * @description:
279    *   This function can be used to modify default positions of color
280    *   subpixels, which controls Harmony LCD rendering.
281    *
282    * @input:
283    *   library ::
284    *     A handle to the target library instance.
285    *
286    *   sub ::
287    *     A pointer to an array of 3 vectors in 26.6 fractional pixel format;
288    *     the function modifies the default values, see the note below.
289    *
290    * @return:
291    *   FreeType error code.  0~means success.
292    *
293    * @note:
294    *   Subpixel geometry examples:
295    *
296    *   - {{-21, 0}, {0, 0}, {21, 0}} is the default, corresponding to 3 color
297    *   stripes shifted by a third of a pixel. This could be an RGB panel.
298    *
299    *   - {{21, 0}, {0, 0}, {-21, 0}} looks the same as the default but
300    *   can specify a BGR panel instead, while keeping the bitmap in the same
301    *   RGB888 format.
302    *
303    *   - {{0, 21}, {0, 0}, {0, -21}} is the vertical RGB, but the bitmap
304    *   stays RGB888 as a result.
305    *
306    *   - {{-11, 16}, {-11, -16}, {22, 0}} is a certain PenTile arrangement.
307    *
308    *   This function does nothing and returns `FT_Err_Unimplemented_Feature'
309    *   in the context of ClearType-style subpixel rendering when
310    *   FT_CONFIG_OPTION_SUBPIXEL_RENDERING is defined in your build of the
311    *   library.
312    *
313    * @since:
314    *   2.10.0
315    */
316   FT_EXPORT( FT_Error )
317   FT_Library_SetLcdGeometry( FT_Library  library,
318                              FT_Vector   sub[3] );
319 
320   /* */
321 
322 
323 FT_END_HEADER
324 
325 #endif /* FTLCDFIL_H_ */
326 
327 
328 /* END */
329