Home | History | Annotate | Download | only in freetype
      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