FreeType-2.8 API Reference

LCD Filtering

Synopsis

Subpixel rendering exploits the color-striped structure of LCD pixels, increasing the available resolution in the direction of the stripe (usually horizontal RGB) by a factor of 3. Since these subpixels are color pixels, using them unfiltered creates severe color fringes. Use the FT_Library_SetLcdFilter API to specify a low-pass filter, which is then applied to subpixel-rendered bitmaps generated through FT_Render_Glyph. The filter sacrifices some of the higher resolution to reduce color fringes, making the glyph image slightly blurrier. Positional improvements will remain.

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 and explicitly call FT_Library_SetLcdFilter to enable it.

A filter should have two properties:

1) It should be normalized, meaning the sum of the 5 components should be 256 (0x100). It is possible to go above or under this target sum, however: going under means tossing out contrast, going over means invoking clamping and thereby non-linearities that increase contrast somewhat at the expense of greater distortion and color-fringing. Contrast is better enhanced through stem darkening.

2) It should be color-balanced, meaning a filter ‘{ a, b, c, b, a }’ where a + b = c. It distributes the computed coverage for one subpixel to all subpixels equally, sacrificing some won resolution but drastically reducing color-fringing. Positioning improvements remain! Note that color-fringing can only really be minimized when using a color-balanced filter and alpha-blending the glyph onto a surface in linear space; see FT_Render_Glyph.

Regarding the form, a filter can be a ‘boxy’ filter or a ‘beveled’ filter. Boxy filters are sharper but are less forgiving of non-ideal gamma curves of a screen (viewing angles!), beveled filters are fuzzier but more tolerant.

Examples:

- [0x10 0x40 0x70 0x40 0x10] is beveled and neither balanced nor normalized.

- [0x1A 0x33 0x4D 0x33 0x1A] is beveled and balanced but not normalized.

- [0x19 0x33 0x66 0x4c 0x19] is beveled and normalized but not balanced.

- [0x00 0x4c 0x66 0x4c 0x00] is boxily beveled and normalized but not balanced.

- [0x00 0x55 0x56 0x55 0x00] is boxy, normalized, and almost balanced.

- [0x08 0x4D 0x56 0x4D 0x08] is beveled, normalized and, almost balanced.

The filter affects glyph bitmaps rendered through FT_Render_Glyph, 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 wider or taller than the dimensions of the corresponding outline with regard to the pixel grid. For example, for FT_RENDER_MODE_LCD, the filter adds 3 subpixels to the left, and 3 subpixels to the right. The bitmap offset values are adjusted accordingly, so clients shouldn't need to modify their layout and glyph positioning code when enabling the filter.

It is important to understand that linear alpha blending and gamma correction is critical for correctly rendering glyphs onto surfaces without artifacts and even more critical when subpixel rendering is involved.

Each of the 3 alpha values (subpixels) is independently used to blend one color channel. That is, red alpha blends the red channel of the text color with the red channel of the background pixel. The distribution of density values by the color-balanced filter assumes alpha blending is done in linear space; only then color artifacts cancel out.

  typedef enum  FT_LcdFilter_
  {
    FT_LCD_FILTER_NONE    = 0,
    FT_LCD_FILTER_DEFAULT = 1,
    FT_LCD_FILTER_LIGHT   = 2,
    FT_LCD_FILTER_LEGACY1 = 3,
    FT_LCD_FILTER_LEGACY  = 16,

    FT_LCD_FILTER_MAX   /* do not remove */

  } FT_LcdFilter;

  FT_EXPORT( FT_Error )
  FT_Library_SetLcdFilter( FT_Library    library,
                           FT_LcdFilter  filter );

  FT_EXPORT( FT_Error )
  FT_Library_SetLcdFilterWeights( FT_Library      library,
                                  unsigned char  *weights );

#define FT_PARAM_TAG_LCD_FILTER_WEIGHTS \
          FT_MAKE_TAG( 'l', 'c', 'd', 'f' )


  /*
   * @type:
   *   FT_LcdFiveTapFilter
   *
   * @description:
   *   A typedef for passing the five LCD filter weights to
   *   @FT_Face_Properties within an @FT_Parameter structure.
   *
   */
#define FT_LCD_FILTER_FIVE_TAPS  5

  typedef FT_Byte  FT_LcdFiveTapFilter[FT_LCD_FILTER_FIVE_TAPS];