nuclear@0: /***************************************************************************/
nuclear@0: /*                                                                         */
nuclear@0: /*  ftlcdfil.h                                                             */
nuclear@0: /*                                                                         */
nuclear@0: /*    FreeType API for color filtering of subpixel bitmap glyphs           */
nuclear@0: /*    (specification).                                                     */
nuclear@0: /*                                                                         */
nuclear@0: /*  Copyright 2006, 2007, 2008, 2010 by                                    */
nuclear@0: /*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
nuclear@0: /*                                                                         */
nuclear@0: /*  This file is part of the FreeType project, and may only be used,       */
nuclear@0: /*  modified, and distributed under the terms of the FreeType project      */
nuclear@0: /*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
nuclear@0: /*  this file you indicate that you have read the license and              */
nuclear@0: /*  understand and accept it fully.                                        */
nuclear@0: /*                                                                         */
nuclear@0: /***************************************************************************/
nuclear@0: 
nuclear@0: 
nuclear@0: #ifndef __FT_LCD_FILTER_H__
nuclear@0: #define __FT_LCD_FILTER_H__
nuclear@0: 
nuclear@0: #include <ft2build.h>
nuclear@0: #include FT_FREETYPE_H
nuclear@0: 
nuclear@0: #ifdef FREETYPE_H
nuclear@0: #error "freetype.h of FreeType 1 has been loaded!"
nuclear@0: #error "Please fix the directory search order for header files"
nuclear@0: #error "so that freetype.h of FreeType 2 is found first."
nuclear@0: #endif
nuclear@0: 
nuclear@0: 
nuclear@0: FT_BEGIN_HEADER
nuclear@0: 
nuclear@0:   /***************************************************************************
nuclear@0:    *
nuclear@0:    * @section:
nuclear@0:    *   lcd_filtering
nuclear@0:    *
nuclear@0:    * @title:
nuclear@0:    *   LCD Filtering
nuclear@0:    *
nuclear@0:    * @abstract:
nuclear@0:    *   Reduce color fringes of LCD-optimized bitmaps.
nuclear@0:    *
nuclear@0:    * @description:
nuclear@0:    *   The @FT_Library_SetLcdFilter API can be used to specify a low-pass
nuclear@0:    *   filter which is then applied to LCD-optimized bitmaps generated
nuclear@0:    *   through @FT_Render_Glyph.  This is useful to reduce color fringes
nuclear@0:    *   which would occur with unfiltered rendering.
nuclear@0:    *
nuclear@0:    *   Note that no filter is active by default, and that this function is
nuclear@0:    *   *not* implemented in default builds of the library.  You need to
nuclear@0:    *   #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your `ftoption.h' file
nuclear@0:    *   in order to activate it.
nuclear@0:    */
nuclear@0: 
nuclear@0: 
nuclear@0:   /****************************************************************************
nuclear@0:    *
nuclear@0:    * @enum:
nuclear@0:    *   FT_LcdFilter
nuclear@0:    *
nuclear@0:    * @description:
nuclear@0:    *   A list of values to identify various types of LCD filters.
nuclear@0:    *
nuclear@0:    * @values:
nuclear@0:    *   FT_LCD_FILTER_NONE ::
nuclear@0:    *     Do not perform filtering.  When used with subpixel rendering, this
nuclear@0:    *     results in sometimes severe color fringes.
nuclear@0:    *
nuclear@0:    *   FT_LCD_FILTER_DEFAULT ::
nuclear@0:    *     The default filter reduces color fringes considerably, at the cost
nuclear@0:    *     of a slight blurriness in the output.
nuclear@0:    *
nuclear@0:    *   FT_LCD_FILTER_LIGHT ::
nuclear@0:    *     The light filter is a variant that produces less blurriness at the
nuclear@0:    *     cost of slightly more color fringes than the default one.  It might
nuclear@0:    *     be better, depending on taste, your monitor, or your personal vision.
nuclear@0:    *
nuclear@0:    *   FT_LCD_FILTER_LEGACY ::
nuclear@0:    *     This filter corresponds to the original libXft color filter.  It
nuclear@0:    *     provides high contrast output but can exhibit really bad color
nuclear@0:    *     fringes if glyphs are not extremely well hinted to the pixel grid.
nuclear@0:    *     In other words, it only works well if the TrueType bytecode
nuclear@0:    *     interpreter is enabled *and* high-quality hinted fonts are used.
nuclear@0:    *
nuclear@0:    *     This filter is only provided for comparison purposes, and might be
nuclear@0:    *     disabled or stay unsupported in the future.
nuclear@0:    *
nuclear@0:    * @since:
nuclear@0:    *   2.3.0
nuclear@0:    */
nuclear@0:   typedef enum  FT_LcdFilter_
nuclear@0:   {
nuclear@0:     FT_LCD_FILTER_NONE    = 0,
nuclear@0:     FT_LCD_FILTER_DEFAULT = 1,
nuclear@0:     FT_LCD_FILTER_LIGHT   = 2,
nuclear@0:     FT_LCD_FILTER_LEGACY  = 16,
nuclear@0: 
nuclear@0:     FT_LCD_FILTER_MAX   /* do not remove */
nuclear@0: 
nuclear@0:   } FT_LcdFilter;
nuclear@0: 
nuclear@0: 
nuclear@0:   /**************************************************************************
nuclear@0:    *
nuclear@0:    * @func:
nuclear@0:    *   FT_Library_SetLcdFilter
nuclear@0:    *
nuclear@0:    * @description:
nuclear@0:    *   This function is used to apply color filtering to LCD decimated
nuclear@0:    *   bitmaps, like the ones used when calling @FT_Render_Glyph with
nuclear@0:    *   @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
nuclear@0:    *
nuclear@0:    * @input:
nuclear@0:    *   library ::
nuclear@0:    *     A handle to the target library instance.
nuclear@0:    *
nuclear@0:    *   filter ::
nuclear@0:    *     The filter type.
nuclear@0:    *
nuclear@0:    *     You can use @FT_LCD_FILTER_NONE here to disable this feature, or
nuclear@0:    *     @FT_LCD_FILTER_DEFAULT to use a default filter that should work
nuclear@0:    *     well on most LCD screens.
nuclear@0:    *
nuclear@0:    * @return:
nuclear@0:    *   FreeType error code.  0~means success.
nuclear@0:    *
nuclear@0:    * @note:
nuclear@0:    *   This feature is always disabled by default.  Clients must make an
nuclear@0:    *   explicit call to this function with a `filter' value other than
nuclear@0:    *   @FT_LCD_FILTER_NONE in order to enable it.
nuclear@0:    *
nuclear@0:    *   Due to *PATENTS* covering subpixel rendering, this function doesn't
nuclear@0:    *   do anything except returning `FT_Err_Unimplemented_Feature' if the
nuclear@0:    *   configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
nuclear@0:    *   defined in your build of the library, which should correspond to all
nuclear@0:    *   default builds of FreeType.
nuclear@0:    *
nuclear@0:    *   The filter affects glyph bitmaps rendered through @FT_Render_Glyph,
nuclear@0:    *   @FT_Outline_Get_Bitmap, @FT_Load_Glyph, and @FT_Load_Char.
nuclear@0:    *
nuclear@0:    *   It does _not_ affect the output of @FT_Outline_Render and
nuclear@0:    *   @FT_Outline_Get_Bitmap.
nuclear@0:    *
nuclear@0:    *   If this feature is activated, the dimensions of LCD glyph bitmaps are
nuclear@0:    *   either larger or taller than the dimensions of the corresponding
nuclear@0:    *   outline with regards to the pixel grid.  For example, for
nuclear@0:    *   @FT_RENDER_MODE_LCD, the filter adds up to 3~pixels to the left, and
nuclear@0:    *   up to 3~pixels to the right.
nuclear@0:    *
nuclear@0:    *   The bitmap offset values are adjusted correctly, so clients shouldn't
nuclear@0:    *   need to modify their layout and glyph positioning code when enabling
nuclear@0:    *   the filter.
nuclear@0:    *
nuclear@0:    * @since:
nuclear@0:    *   2.3.0
nuclear@0:    */
nuclear@0:   FT_EXPORT( FT_Error )
nuclear@0:   FT_Library_SetLcdFilter( FT_Library    library,
nuclear@0:                            FT_LcdFilter  filter );
nuclear@0: 
nuclear@0: 
nuclear@0:   /**************************************************************************
nuclear@0:    *
nuclear@0:    * @func:
nuclear@0:    *   FT_Library_SetLcdFilterWeights
nuclear@0:    *
nuclear@0:    * @description:
nuclear@0:    *   Use this function to override the filter weights selected by
nuclear@0:    *   @FT_Library_SetLcdFilter.  By default, FreeType uses the quintuple
nuclear@0:    *   (0x00, 0x55, 0x56, 0x55, 0x00) for FT_LCD_FILTER_LIGHT, and (0x10,
nuclear@0:    *   0x40, 0x70, 0x40, 0x10) for FT_LCD_FILTER_DEFAULT and
nuclear@0:    *   FT_LCD_FILTER_LEGACY.
nuclear@0:    *
nuclear@0:    * @input:
nuclear@0:    *   library ::
nuclear@0:    *     A handle to the target library instance.
nuclear@0:    *
nuclear@0:    *   weights ::
nuclear@0:    *     A pointer to an array; the function copies the first five bytes and
nuclear@0:    *     uses them to specify the filter weights.
nuclear@0:    *
nuclear@0:    * @return:
nuclear@0:    *   FreeType error code.  0~means success.
nuclear@0:    *
nuclear@0:    * @note:
nuclear@0:    *   Due to *PATENTS* covering subpixel rendering, this function doesn't
nuclear@0:    *   do anything except returning `FT_Err_Unimplemented_Feature' if the
nuclear@0:    *   configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
nuclear@0:    *   defined in your build of the library, which should correspond to all
nuclear@0:    *   default builds of FreeType.
nuclear@0:    *
nuclear@0:    *   This function must be called after @FT_Library_SetLcdFilter to have
nuclear@0:    *   any effect.
nuclear@0:    *
nuclear@0:    * @since:
nuclear@0:    *   2.4.0
nuclear@0:    */
nuclear@0:   FT_EXPORT( FT_Error )
nuclear@0:   FT_Library_SetLcdFilterWeights( FT_Library      library,
nuclear@0:                                   unsigned char  *weights );
nuclear@0: 
nuclear@0:   /* */
nuclear@0: 
nuclear@0: 
nuclear@0: FT_END_HEADER
nuclear@0: 
nuclear@0: #endif /* __FT_LCD_FILTER_H__ */
nuclear@0: 
nuclear@0: 
nuclear@0: /* END */