[ft-devel] LCD Filtering changes

[David Turner]

Hello,

I commited some subtle changes to the LCD filtering API.

First of all, the API has changed slightly, it's not longer possible to pass
an array of custom filter weights; I prefer not to make this feature available
to normal client programs at the moment.

On the other hand, I've implemented two new filters for you to test:

  FT_LCD_FILTER_LIGHT ::
    is a lighter lcd filter, this is just a [1/3,1/3,1/3] 3-tap FIR filter
    that produces less blurry text, with slightly more color artefacts though;
    wether this is best or worse than the default filter really depends on your
    monitor and personal vision, and I though I'd be nice to have it as an
    option. As an example, it's really ok on a 24" Dell, but looks quite colored
    on my personal laptop's screen.

  FT_LCD_FILTER_LEGACY ::
    this is nothing else that the "old" filter used by libXft and Cairo, i.e.
    one that produces very high-contrast text, but also severe color fringes
    in certain cases. I do not recommend using it, but the filter is here for
    comparison purposes; it's only valuable when you have severely hinted
    text, which usually means the bytecode interpreter enabled and high-quality
    TrueType fonts; in most other cases, you'll regret using it

    It will probably go away in later releases of the library

Interestingly, the API change doesn't affect source and binary compatibility of
the patched libXft and Cairo you may already be using; I have thus not updated
my patches.

Normally, integrating these changes would mean hacking fontconfig (to add a new
"lcdfilter" attribute and corresponding values), libXft and Cairo (to have them
understand the new attribute and call FT_Library_SetLcdFilter accordingly), and
probably OpenOffice and a few other things (GNUStep, poppler, etc.. ??)

To make testing either, there are two configuration macros you can use when
building the library:

  FT_FORCE_LIGHT_LCD_FILTER
  FT_FORCE_LEGACY_LCD_FILTER

their names are, I believe, quite explicit :-)

Let me know your opinion about these new filters. I believe that the legacy 
filter
should go; I really can't stand the yellow and light-gray edges it generates in 
too
many cases...

You'll find the new API documentation below.

Regards,

- David Turner
- The FreeType Project  (www.freetype.org)

----------------------------------cut 
here------------------------------------------
 /****************************************************************************
  *
  * @func:
  *   FT_LcdFilter
  *
  * @description:
  *    a list of values used to identify various types of LCD filters
  *
  * @values:
  *   FT_LCD_FILTER_NONE :: value 0 means do not perform filtering. when
  *     used with subpixel rendering, this will result in sometimes severe
  *     color fringes
  *
  *   FT_LCD_FILTER_DEFAULT ::
  *      the default filter reduces color fringes considerably, at the cost of
  *      a slight bluriness in the output
  *
  *   FT_LCD_FILTER_LIGHT ::
  *      the light filter is a variant that produces less bluriness
  *      at the cost of slightly more color fringes than the default one. It
  *      might be better than the default one, depending on your monitor and
  *      personal vision.
  *
  *   FT_LCD_FILTER_LEGACY ::
  *      this filter corresponds to the original libXft color filter, this
  *      provides high contrast output, but can exhibit really bad color fringes
  *      if your glyphs are not extremely well hinted to the pixel grid. In
  *      other words, it only works well when enabling the TrueType bytecode
  *      interpreter *and* using high-quality hinted fonts. It will suck for
  *      all other cases.
  *
  *      this filter is only provided for comparison purposes, and might be
  *      disabled/unsupported in the future...
  */
  typedef enum
  {
    FT_LCD_FILTER_NONE    = 0,
    FT_LCD_FILTER_DEFAULT = 1,
    FT_LCD_FILTER_LIGHT   = 2,
    FT_LCD_FILTER_LEGACY  = 16,

    FT_LCD_FILTER_MAX   /* do not remove */

  } FT_LcdFilter;


  /**************************************************************************
   *
   * @func:
   *   FT_Library_SetLcdFilter
   *
   * @description:
   *   This function is used to apply color filtering to LCD decimated
   *   bitmaps, like the ones used when calling @FT_Render_Glyph with
   *   @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
   *
   * @input:
   *   library :: A handle to the target library instance.
   *
   *   filter  :: filter type.
   *
   *     You can use @FT_LCD_FILTER_NONE here to disable this feature, or
   *     @FT_LCD_FILTER_DEFAULT to use a default filter that should work
   *     well on most LCD screens.
   *
   * @return:
   *   FreeType error code.  0 means success.
   *
   * @note:
   *   This feature is always disabled by default.  Clients must make an
   *   explicit call to this function with a `filter' value other
   *   than @FT_LCD_FILTER_NONE in order to enable it.
   *
   *   Due to *PATENTS* covering subpixel rendering, this function doesn't
   *   do anything except returning @FT_Err_Unimplemented_Feature if the
   *   configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
   *   defined in your build of the library, which should correspond to all
   *   default builds of the library.
   *
   *   The filter affects glyph bitmaps rendered through FT_Render_Glyph,
   *   @@FT_Glyph_Get_Bitmap, @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 larger or taller than the dimensions of the corresponding
   *   outline with regards to the pixel grid.  For example, for
   *   @FT_RENDER_MODE_LCD, the filter adds up to 3 pixels to the left, and
   *   up to 3 pixels to the right.
   *
   *   The bitmap offset values are adjusted correctly, so clients shouldn't
   *   need to modify their layout and glyph positioning code when enabling
   *   the filter.
   *
   */
  FT_EXPORT( FT_Error )
  FT_Library_SetLcdFilter( FT_Library    library,
                           FT_LcdFilter  filter );