• file
• revisions
• annotate
• diff
• comparison
• raw

modules/freetype2/include/ftlcdfil.h@6474c204b198 (annotated)

modules/freetype2/include/ftlcdfil.h

Wed, 31 Dec 2014 06:09:35 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Wed, 31 Dec 2014 06:09:35 +0100

changeset 0

6474c204b198

permissions

-rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

michael@0	1	/***************************************************************************/
michael@0	2	/* */
michael@0	3	/* ftlcdfil.h */
michael@0	4	/* */
michael@0	5	/* FreeType API for color filtering of subpixel bitmap glyphs */
michael@0	6	/* (specification). */
michael@0	7	/* */
michael@0	8	/* Copyright 2006-2008, 2010, 2013 by */
michael@0	9	/* David Turner, Robert Wilhelm, and Werner Lemberg. */
michael@0	10	/* */
michael@0	11	/* This file is part of the FreeType project, and may only be used, */
michael@0	12	/* modified, and distributed under the terms of the FreeType project */
michael@0	13	/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
michael@0	14	/* this file you indicate that you have read the license and */
michael@0	15	/* understand and accept it fully. */
michael@0	16	/* */
michael@0	17	/***************************************************************************/
michael@0	18
michael@0	19
michael@0	20	#ifndef __FT_LCD_FILTER_H__
michael@0	21	#define __FT_LCD_FILTER_H__
michael@0	22
michael@0	23	#include <ft2build.h>
michael@0	24	#include FT_FREETYPE_H
michael@0	25
michael@0	26	#ifdef FREETYPE_H
michael@0	27	#error "freetype.h of FreeType 1 has been loaded!"
michael@0	28	#error "Please fix the directory search order for header files"
michael@0	29	#error "so that freetype.h of FreeType 2 is found first."
michael@0	30	#endif
michael@0	31
michael@0	32
michael@0	33	FT_BEGIN_HEADER
michael@0	34
michael@0	35	/***************************************************************************
michael@0	36	*
michael@0	37	* @section:
michael@0	38	* lcd_filtering
michael@0	39	*
michael@0	40	* @title:
michael@0	41	* LCD Filtering
michael@0	42	*
michael@0	43	* @abstract:
michael@0	44	* Reduce color fringes of LCD-optimized bitmaps.
michael@0	45	*
michael@0	46	* @description:
michael@0	47	* The @FT_Library_SetLcdFilter API can be used to specify a low-pass
michael@0	48	* filter, which is then applied to LCD-optimized bitmaps generated
michael@0	49	* through @FT_Render_Glyph. This is useful to reduce color fringes
michael@0	50	* that would occur with unfiltered rendering.
michael@0	51	*
michael@0	52	* Note that no filter is active by default, and that this function is
michael@0	53	* *not* implemented in default builds of the library. You need to
michael@0	54	* #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your `ftoption.h' file
michael@0	55	* in order to activate it.
michael@0	56	*
michael@0	57	* FreeType generates alpha coverage maps, which are linear by nature.
michael@0	58	* For instance, the value 0x80 in bitmap representation means that
michael@0	59	* (within numerical precision) 0x80/0xff fraction of that pixel is
michael@0	60	* covered by the glyph's outline. The blending function for placing
michael@0	61	* text over a background is
michael@0	62	*
michael@0	63	* {
michael@0	64	* dst = alpha * src + (1 - alpha) * dst ,
michael@0	65	* }
michael@0	66	*
michael@0	67	* which is known as OVER. However, when calculating the output of the
michael@0	68	* OVER operator, the source colors should first be transformed to a
michael@0	69	* linear color space, then alpha blended in that space, and transformed
michael@0	70	* back to the output color space.
michael@0	71	*
michael@0	72	* When linear light blending is used, the default FIR5 filtering
michael@0	73	* weights (as given by FT_LCD_FILTER_DEFAULT) are no longer optimal, as
michael@0	74	* they have been designed for black on white rendering while lacking
michael@0	75	* gamma correction. To preserve color neutrality, weights for a FIR5
michael@0	76	* filter should be chosen according to two free parameters `a' and `c',
michael@0	77	* and the FIR weights should be
michael@0	78	*
michael@0	79	* {
michael@0	80	* [a - c, a + c, 2 * a, a + c, a - c] .
michael@0	81	* }
michael@0	82	*
michael@0	83	* This formula generates equal weights for all the color primaries
michael@0	84	* across the filter kernel, which makes it colorless. One suggested
michael@0	85	* set of weights is
michael@0	86	*
michael@0	87	* {
michael@0	88	* [0x10, 0x50, 0x60, 0x50, 0x10] ,
michael@0	89	* }
michael@0	90	*
michael@0	91	* where `a' has value 0x30 and `b' value 0x20. The weights in filter
michael@0	92	* may have a sum larger than 0x100, which increases coloration slightly
michael@0	93	* but also improves contrast.
michael@0	94	*/
michael@0	95
michael@0	96
michael@0	97	/****************************************************************************
michael@0	98	*
michael@0	99	* @enum:
michael@0	100	* FT_LcdFilter
michael@0	101	*
michael@0	102	* @description:
michael@0	103	* A list of values to identify various types of LCD filters.
michael@0	104	*
michael@0	105	* @values:
michael@0	106	* FT_LCD_FILTER_NONE ::
michael@0	107	* Do not perform filtering. When used with subpixel rendering, this
michael@0	108	* results in sometimes severe color fringes.
michael@0	109	*
michael@0	110	* FT_LCD_FILTER_DEFAULT ::
michael@0	111	* The default filter reduces color fringes considerably, at the cost
michael@0	112	* of a slight blurriness in the output.
michael@0	113	*
michael@0	114	* FT_LCD_FILTER_LIGHT ::
michael@0	115	* The light filter is a variant that produces less blurriness at the
michael@0	116	* cost of slightly more color fringes than the default one. It might
michael@0	117	* be better, depending on taste, your monitor, or your personal vision.
michael@0	118	*
michael@0	119	* FT_LCD_FILTER_LEGACY ::
michael@0	120	* This filter corresponds to the original libXft color filter. It
michael@0	121	* provides high contrast output but can exhibit really bad color
michael@0	122	* fringes if glyphs are not extremely well hinted to the pixel grid.
michael@0	123	* In other words, it only works well if the TrueType bytecode
michael@0	124	* interpreter is enabled *and* high-quality hinted fonts are used.
michael@0	125	*
michael@0	126	* This filter is only provided for comparison purposes, and might be
michael@0	127	* disabled or stay unsupported in the future.
michael@0	128	*
michael@0	129	* @since:
michael@0	130	* 2.3.0
michael@0	131	*/
michael@0	132	typedef enum FT_LcdFilter_
michael@0	133	{
michael@0	134	FT_LCD_FILTER_NONE = 0,
michael@0	135	FT_LCD_FILTER_DEFAULT = 1,
michael@0	136	FT_LCD_FILTER_LIGHT = 2,
michael@0	137	FT_LCD_FILTER_LEGACY = 16,
michael@0	138
michael@0	139	FT_LCD_FILTER_MAX /* do not remove */
michael@0	140
michael@0	141	} FT_LcdFilter;
michael@0	142
michael@0	143
michael@0	144	/**************************************************************************
michael@0	145	*
michael@0	146	* @func:
michael@0	147	* FT_Library_SetLcdFilter
michael@0	148	*
michael@0	149	* @description:
michael@0	150	* This function is used to apply color filtering to LCD decimated
michael@0	151	* bitmaps, like the ones used when calling @FT_Render_Glyph with
michael@0	152	* @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V.
michael@0	153	*
michael@0	154	* @input:
michael@0	155	* library ::
michael@0	156	* A handle to the target library instance.
michael@0	157	*
michael@0	158	* filter ::
michael@0	159	* The filter type.
michael@0	160	*
michael@0	161	* You can use @FT_LCD_FILTER_NONE here to disable this feature, or
michael@0	162	* @FT_LCD_FILTER_DEFAULT to use a default filter that should work
michael@0	163	* well on most LCD screens.
michael@0	164	*
michael@0	165	* @return:
michael@0	166	* FreeType error code. 0~means success.
michael@0	167	*
michael@0	168	* @note:
michael@0	169	* This feature is always disabled by default. Clients must make an
michael@0	170	* explicit call to this function with a `filter' value other than
michael@0	171	* @FT_LCD_FILTER_NONE in order to enable it.
michael@0	172	*
michael@0	173	* Due to *PATENTS* covering subpixel rendering, this function doesn't
michael@0	174	* do anything except returning `FT_Err_Unimplemented_Feature' if the
michael@0	175	* configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
michael@0	176	* defined in your build of the library, which should correspond to all
michael@0	177	* default builds of FreeType.
michael@0	178	*
michael@0	179	* The filter affects glyph bitmaps rendered through @FT_Render_Glyph,
michael@0	180	* @FT_Outline_Get_Bitmap, @FT_Load_Glyph, and @FT_Load_Char.
michael@0	181	*
michael@0	182	* It does _not_ affect the output of @FT_Outline_Render and
michael@0	183	* @FT_Outline_Get_Bitmap.
michael@0	184	*
michael@0	185	* If this feature is activated, the dimensions of LCD glyph bitmaps are
michael@0	186	* either larger or taller than the dimensions of the corresponding
michael@0	187	* outline with regards to the pixel grid. For example, for
michael@0	188	* @FT_RENDER_MODE_LCD, the filter adds up to 3~pixels to the left, and
michael@0	189	* up to 3~pixels to the right.
michael@0	190	*
michael@0	191	* The bitmap offset values are adjusted correctly, so clients shouldn't
michael@0	192	* need to modify their layout and glyph positioning code when enabling
michael@0	193	* the filter.
michael@0	194	*
michael@0	195	* @since:
michael@0	196	* 2.3.0
michael@0	197	*/
michael@0	198	FT_EXPORT( FT_Error )
michael@0	199	FT_Library_SetLcdFilter( FT_Library library,
michael@0	200	FT_LcdFilter filter );
michael@0	201
michael@0	202
michael@0	203	/**************************************************************************
michael@0	204	*
michael@0	205	* @func:
michael@0	206	* FT_Library_SetLcdFilterWeights
michael@0	207	*
michael@0	208	* @description:
michael@0	209	* Use this function to override the filter weights selected by
michael@0	210	* @FT_Library_SetLcdFilter. By default, FreeType uses the quintuple
michael@0	211	* (0x00, 0x55, 0x56, 0x55, 0x00) for FT_LCD_FILTER_LIGHT, and (0x10,
michael@0	212	* 0x40, 0x70, 0x40, 0x10) for FT_LCD_FILTER_DEFAULT and
michael@0	213	* FT_LCD_FILTER_LEGACY.
michael@0	214	*
michael@0	215	* @input:
michael@0	216	* library ::
michael@0	217	* A handle to the target library instance.
michael@0	218	*
michael@0	219	* weights ::
michael@0	220	* A pointer to an array; the function copies the first five bytes and
michael@0	221	* uses them to specify the filter weights.
michael@0	222	*
michael@0	223	* @return:
michael@0	224	* FreeType error code. 0~means success.
michael@0	225	*
michael@0	226	* @note:
michael@0	227	* Due to *PATENTS* covering subpixel rendering, this function doesn't
michael@0	228	* do anything except returning `FT_Err_Unimplemented_Feature' if the
michael@0	229	* configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
michael@0	230	* defined in your build of the library, which should correspond to all
michael@0	231	* default builds of FreeType.
michael@0	232	*
michael@0	233	* This function must be called after @FT_Library_SetLcdFilter to have
michael@0	234	* any effect.
michael@0	235	*
michael@0	236	* @since:
michael@0	237	* 2.4.0
michael@0	238	*/
michael@0	239	FT_EXPORT( FT_Error )
michael@0	240	FT_Library_SetLcdFilterWeights( FT_Library library,
michael@0	241	unsigned char *weights );
michael@0	242
michael@0	243	/* */
michael@0	244
michael@0	245
michael@0	246	FT_END_HEADER
michael@0	247
michael@0	248	#endif /* __FT_LCD_FILTER_H__ */
michael@0	249
michael@0	250
michael@0	251	/* END */