sdk/lib/3rdparty/freetype/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-2018 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 FTLCDFIL_H_
  21 #define FTLCDFIL_H_
  22
  23 #include <ft2build.h>
  24 #include FT_FREETYPE_H
  25 #include FT_PARAMETER_TAGS_H
  26
  27 #ifdef FREETYPE_H
  28 #error "freetype.h of FreeType 1 has been loaded!"
  29 #error "Please fix the directory search order for header files"
  30 #error "so that freetype.h of FreeType 2 is found first."
  31 #endif
  32
  33
  34 FT_BEGIN_HEADER
  35
  36   /***************************************************************************
  37    *
  38    * @section:
  39    *   lcd_filtering
  40    *
  41    * @title:
  42    *   LCD Filtering
  43    *
  44    * @abstract:
  45    *   Reduce color fringes of subpixel-rendered bitmaps.
  46    *
  47    * @description:
  48    *   Should you #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your
  49    *   `ftoption.h', which enables patented ClearType-style rendering,
  50    *   the LCD-optimized glyph bitmaps should be filtered to reduce color
  51    *   fringes inherent to this technology.  The default FreeType LCD
  52    *   rendering uses different technology, and API described below,
  53    *   although available, does nothing.
  54    *
  55    *   ClearType-style LCD rendering exploits the color-striped structure of
  56    *   LCD pixels, increasing the available resolution in the direction of
  57    *   the stripe (usually horizontal RGB) by a factor of~3.  Since these
  58    *   subpixels are color pixels, using them unfiltered creates severe
  59    *   color fringes.  Use the @FT_Library_SetLcdFilter API to specify a
  60    *   low-pass filter, which is then applied to subpixel-rendered bitmaps
  61    *   generated through @FT_Render_Glyph.  The filter sacrifices some of
  62    *   the higher resolution to reduce color fringes, making the glyph image
  63    *   slightly blurrier.  Positional improvements will remain.
  64    *
  65    *   A filter should have two properties:
  66    *
  67    *   1) It should be normalized, meaning the sum of the 5~components
  68    *      should be 256 (0x100).  It is possible to go above or under this
  69    *      target sum, however: going under means tossing out contrast, going
  70    *      over means invoking clamping and thereby non-linearities that
  71    *      increase contrast somewhat at the expense of greater distortion
  72    *      and color-fringing.  Contrast is better enhanced through stem
  73    *      darkening.
  74    *
  75    *   2) It should be color-balanced, meaning a filter `{~a, b, c, b, a~}'
  76    *      where a~+ b~=~c.  It distributes the computed coverage for one
  77    *      subpixel to all subpixels equally, sacrificing some won resolution
  78    *      but drastically reducing color-fringing.  Positioning improvements
  79    *      remain!  Note that color-fringing can only really be minimized
  80    *      when using a color-balanced filter and alpha-blending the glyph
  81    *      onto a surface in linear space; see @FT_Render_Glyph.
  82    *
  83    *   Regarding the form, a filter can be a `boxy' filter or a `beveled'
  84    *   filter.  Boxy filters are sharper but are less forgiving of non-ideal
  85    *   gamma curves of a screen (viewing angles!), beveled filters are
  86    *   fuzzier but more tolerant.
  87    *
  88    *   Examples:
  89    *
  90    *   - [0x10 0x40 0x70 0x40 0x10] is beveled and neither balanced nor
  91    *     normalized.
  92    *
  93    *   - [0x1A 0x33 0x4D 0x33 0x1A] is beveled and balanced but not
  94    *     normalized.
  95    *
  96    *   - [0x19 0x33 0x66 0x4c 0x19] is beveled and normalized but not
  97    *     balanced.
  98    *
  99    *   - [0x00 0x4c 0x66 0x4c 0x00] is boxily beveled and normalized but not
 100    *     balanced.
 101    *
 102    *   - [0x00 0x55 0x56 0x55 0x00] is boxy, normalized, and almost
 103    *     balanced.
 104    *
 105    *   - [0x08 0x4D 0x56 0x4D 0x08] is beveled, normalized and, almost
 106    *     balanced.
 107    *
 108    *   The filter affects glyph bitmaps rendered through @FT_Render_Glyph,
 109    *   @FT_Load_Glyph, and @FT_Load_Char.  It does _not_ affect the output
 110    *   of @FT_Outline_Render and @FT_Outline_Get_Bitmap.
 111    *
 112    *   If this feature is activated, the dimensions of LCD glyph bitmaps are
 113    *   either wider or taller than the dimensions of the corresponding
 114    *   outline with regard to the pixel grid.  For example, for
 115    *   @FT_RENDER_MODE_LCD, the filter adds 3~subpixels to the left, and
 116    *   3~subpixels to the right.  The bitmap offset values are adjusted
 117    *   accordingly, so clients shouldn't need to modify their layout and
 118    *   glyph positioning code when enabling the filter.
 119    *
 120    *   It is important to understand that linear alpha blending and gamma
 121    *   correction is critical for correctly rendering glyphs onto surfaces
 122    *   without artifacts and even more critical when subpixel rendering is
 123    *   involved.
 124    *
 125    *   Each of the 3~alpha values (subpixels) is independently used to blend
 126    *   one color channel.  That is, red alpha blends the red channel of the
 127    *   text color with the red channel of the background pixel.  The
 128    *   distribution of density values by the color-balanced filter assumes
 129    *   alpha blending is done in linear space; only then color artifacts
 130    *   cancel out.
 131    */
 132
 133
 134   /****************************************************************************
 135    *
 136    * @enum:
 137    *   FT_LcdFilter
 138    *
 139    * @description:
 140    *   A list of values to identify various types of LCD filters.
 141    *
 142    * @values:
 143    *   FT_LCD_FILTER_NONE ::
 144    *     Do not perform filtering.  When used with subpixel rendering, this
 145    *     results in sometimes severe color fringes.
 146    *
 147    *   FT_LCD_FILTER_DEFAULT ::
 148    *     The default filter reduces color fringes considerably, at the cost
 149    *     of a slight blurriness in the output.
 150    *
 151    *     It is a beveled, normalized, and color-balanced five-tap filter
 152    *     that is more forgiving to screens with non-ideal gamma curves and
 153    *     viewing angles.  Note that while color-fringing is reduced, it can
 154    *     only be minimized by using linear alpha blending and gamma
 155    *     correction to render glyphs onto surfaces.  The default filter
 156    *     weights are [0x08 0x4D 0x56 0x4D 0x08].
 157    *
 158    *   FT_LCD_FILTER_LIGHT ::
 159    *     The light filter is a variant that is sharper at the cost of
 160    *     slightly more color fringes than the default one.
 161    *
 162    *     It is a boxy, normalized, and color-balanced three-tap filter that
 163    *     is less forgiving to screens with non-ideal gamma curves and
 164    *     viewing angles.  This filter works best when the rendering system
 165    *     uses linear alpha blending and gamma correction to render glyphs
 166    *     onto surfaces.  The light filter weights are
 167    *     [0x00 0x55 0x56 0x55 0x00].
 168    *
 169    *   FT_LCD_FILTER_LEGACY ::
 170    *     This filter corresponds to the original libXft color filter.  It
 171    *     provides high contrast output but can exhibit really bad color
 172    *     fringes if glyphs are not extremely well hinted to the pixel grid.
 173    *     In other words, it only works well if the TrueType bytecode
 174    *     interpreter is enabled *and* high-quality hinted fonts are used.
 175    *
 176    *     This filter is only provided for comparison purposes, and might be
 177    *     disabled or stay unsupported in the future.
 178    *
 179    *   FT_LCD_FILTER_LEGACY1 ::
 180    *     For historical reasons, the FontConfig library returns a different
 181    *     enumeration value for legacy LCD filtering.  To make code work that
 182    *     (incorrectly) forwards FontConfig's enumeration value to
 183    *     @FT_Library_SetLcdFilter without proper mapping, it is thus easiest
 184    *     to have another enumeration value, which is completely equal to
 185    *     `FT_LCD_FILTER_LEGACY'.
 186    *
 187    * @since:
 188    *   2.3.0 (`FT_LCD_FILTER_LEGACY1' since 2.6.2)
 189    */
 190   typedef enum  FT_LcdFilter_
 191   {
 192     FT_LCD_FILTER_NONE    = 0,
 193     FT_LCD_FILTER_DEFAULT = 1,
 194     FT_LCD_FILTER_LIGHT   = 2,
 195     FT_LCD_FILTER_LEGACY1 = 3,
 196     FT_LCD_FILTER_LEGACY  = 16,
 197
 198     FT_LCD_FILTER_MAX   /* do not remove */
 199
 200   } FT_LcdFilter;
 201
 202
 203   /**************************************************************************
 204    *
 205    * @func:
 206    *   FT_Library_SetLcdFilter
 207    *
 208    * @description:
 209    *   This function is used to apply color filtering to LCD decimated
 210    *   bitmaps, like the ones used when calling @FT_Render_Glyph with
 211    *   @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
 212    *
 213    * @input:
 214    *   library ::
 215    *     A handle to the target library instance.
 216    *
 217    *   filter ::
 218    *     The filter type.
 219    *
 220    *     You can use @FT_LCD_FILTER_NONE here to disable this feature, or
 221    *     @FT_LCD_FILTER_DEFAULT to use a default filter that should work
 222    *     well on most LCD screens.
 223    *
 224    * @return:
 225    *   FreeType error code.  0~means success.
 226    *
 227    * @note:
 228    *   This feature is always disabled by default.  Clients must make an
 229    *   explicit call to this function with a `filter' value other than
 230    *   @FT_LCD_FILTER_NONE in order to enable it.
 231    *
 232    *   Due to *PATENTS* covering subpixel rendering, this function doesn't
 233    *   do anything except returning `FT_Err_Unimplemented_Feature' if the
 234    *   configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
 235    *   defined in your build of the library, which should correspond to all
 236    *   default builds of FreeType.
 237    *
 238    * @since:
 239    *   2.3.0
 240    */
 241   FT_EXPORT( FT_Error )
 242   FT_Library_SetLcdFilter( FT_Library    library,
 243                            FT_LcdFilter  filter );
 244
 245
 246   /**************************************************************************
 247    *
 248    * @func:
 249    *   FT_Library_SetLcdFilterWeights
 250    *
 251    * @description:
 252    *   This function can be used to enable LCD filter with custom weights,
 253    *   instead of using presets in @FT_Library_SetLcdFilter.
 254    *
 255    * @input:
 256    *   library ::
 257    *     A handle to the target library instance.
 258    *
 259    *   weights ::
 260    *     A pointer to an array; the function copies the first five bytes and
 261    *     uses them to specify the filter weights.
 262    *
 263    * @return:
 264    *   FreeType error code.  0~means success.
 265    *
 266    * @note:
 267    *   Due to *PATENTS* covering subpixel rendering, this function doesn't
 268    *   do anything except returning `FT_Err_Unimplemented_Feature' if the
 269    *   configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
 270    *   defined in your build of the library, which should correspond to all
 271    *   default builds of FreeType.
 272    *
 273    *   LCD filter weights can also be set per face using @FT_Face_Properties
 274    *   with @FT_PARAM_TAG_LCD_FILTER_WEIGHTS.
 275    *
 276    * @since:
 277    *   2.4.0
 278    */
 279   FT_EXPORT( FT_Error )
 280   FT_Library_SetLcdFilterWeights( FT_Library      library,
 281                                   unsigned char  *weights );
 282
 283
 284   /*
 285    * @type:
 286    *   FT_LcdFiveTapFilter
 287    *
 288    * @description:
 289    *   A typedef for passing the five LCD filter weights to
 290    *   @FT_Face_Properties within an @FT_Parameter structure.
 291    *
 292    * @since:
 293    *   2.8
 294    *
 295    */
 296 #define FT_LCD_FILTER_FIVE_TAPS  5
 297
 298   typedef FT_Byte  FT_LcdFiveTapFilter[FT_LCD_FILTER_FIVE_TAPS];
 299
 300
 301   /* */
 302
 303
 304 FT_END_HEADER
 305
 306 #endif /* FTLCDFIL_H_ */
 307
 308
 309 /* END */