Subversion Repositories Kolibri OS

Rev

Go to most recent revision | Blame | Last modification | View Log | RSS feed

  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.  
  33. FT_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.  
  208. FT_END_HEADER
  209.  
  210. #endif /* __FT_LCD_FILTER_H__ */
  211.  
  212.  
  213. /* END */
  214.