include/freetype/ftlcdfil.h

   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 */