[ft] State of LCD/SubPixel Rendering in FreeType

[David Turner]

Hello,

I've just completed a series of commits related to subpixel rendering.
These are:

 - a new configuration macro, named FT_CONFIG_OPTION_SUBPIXEL_RENDERING
   is now used to control wether the font engine includes support for
   patented techniques for subpixel rendering on LCD display.

   note that this macro SHALL be UNDEFINED on every default build of
   the library. I also STRONGLY advise any distribution packager to NOT
   enable this feature, unless you're 100% sure you're on a different
   patent regime. Which pretty excludes Debian and Ubuntu !!

   undefining the macro doesn't change the FreeType API, only its
   implementation; what this means is that there is no need to change
   client code; instead, the generated glyph images will look like ordinary
   "gray" anti-aliased ones.

   for the record, when using FT_RENDER_MODE_LCD to render glyph images,
   the library will still return bitmaps that are 3 times larger than the
   original outline, but with the additionnal constraint that R=G=B for each
   triplet.


- a new API, named 'FT_Library_SetLcdFilter', defined in the new header
  FT_LCD_FILTER_H, can be used to select a color filter to be applied to
  RGB-decimated glyph bitmaps just after they're rendered by the
  anti-aliased rasterizer.

  this function allows you to disable color filtering, ask for a default
  filter that should work well on many LCD screens, or even provide your
  own 5-tap filter weights to be applied on each bitmap, either horizontally
  or vertically, depending on rendering mode.

  I have modified 'ftview' to support it in the ft2demos module, and it
  seems to work well.

  Note that if FT_CONFIG_OPTION_SUBPIXEL_RENDERER is not defined, the
  function 'FT_Library_SetLcdFilter' will always return the error
  FT_Err_Unimplemented_Feature; testing for it is a good way to determine
  wether your build of FreeType supports subpixel rendering or not in
  client code.

  Finally, note that the color filtering is disabled by default, to avoid
  major surprises to existing clients, including libXft and Cairo which
  already perform some wacky color filtering on top of FreeType.

Please report any problems with this new fresh code. I'll try to provide
patches to libXft and Cairo to get rid of the patent-infringing code in
these libraries, making them rely on these new FreeType "features" instead.

Regards,

- David

PS: Here is the documentation for the macro and the new function:

------------from ftoption.h---------------------------
  /*************************************************************************/
  /*                                                                       */
  /* Uncomment the line below if you want to active sub-pixel rendering    */
  /* (a.k.a. LCD rendering, or ClearType) in this build of the library.    */
  /*                                                                       */
  /* Note that this feature is covered by several Microsoft patents        */
  /* and should not be activated in any default build of the library.      */
  /*                                                                       */
  /* This macro has no impact on the FreeType API, only on its             */
  /* _implementation_.  For example, using FT_RENDER_MODE_LCD when calling */
  /* FT_Render_Glyph still generates a bitmap that is 3 times larger than  */
  /* the original size; the difference will be that each triplet of        */
  /* subpixels has R=G=B.                                                  */
  /*                                                                       */
  /* This is done to allow FreeType clients to run unmodified, forcing     */
  /* them to display normal gray-level anti-aliased glyphs.                */
  /*                                                                       */
/* #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING */



--------------- from ftlcdfil.h ----------------------------------------------
 /**
  * @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  :: handle to target library instance
  *
  *   filter_weights :: a pointer to an array of 5 bytes corresponding
  *                     to the weights of a 5-tap FIR filter. Each
  *                     weight must be positive, and their sum should
  *                     be at least 256 to avoid loss of darkness
  *                     in the rendered glyphs. The sum can be greater
  *                     than 256 to darken the glyphs (el-cheapo gamma)
  *
  *                     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:
  *   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_weights' value other
  *   than @FT_LCD_FILTER_NONE in order to enable it.
  *
  *   due to *PATENTS* covering subpixel rendering, this function will
  *   not do anything except return @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
  *   will be 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 thei layout / glyph positioning code when enabling the filter.
  */
  FT_EXPORT( FT_Error )
  FT_Library_SetLcdFilter( FT_Library       library,
                           const FT_Byte*   filter_weights );


 /**
  * @enum: FT_LCD_FILTER_XXX
  *
  * @desc: a list of constants correspond to useful lcd filter settings to
  *        be used when calling @FT_Library_SetLcdFilter
  *
  * @values:
  *    FT_LCD_FILTER_NONE :: the value NULL is reserved to indicate that
  *                          LCD color filtering should be disabled.
  *
  *    FT_LCD_FILTER_DEFAULT ::
  *       this value is reserved to indicate a default FIR filter that
  *       should work well on most LCD screen. For the really curious,
  *       it corresponds to the array 0x10, 0x40, 0x70, 0x40, 0x10
  */
#define  FT_LCD_FILTER_NONE        ((const FT_Byte*)NULL )

#define  FT_LCD_FILTER_DEFAULT     ((const FT_Byte*)(void*)(ft_ptrdiff_t)1)



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