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

modules/freetype2/include/ftttdrv.h@b8a032363ba2 (annotated)

modules/freetype2/include/ftttdrv.h

Thu, 22 Jan 2015 13:21:57 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Thu, 22 Jan 2015 13:21:57 +0100

branch

TOR_BUG_9701

changeset 15

b8a032363ba2

permissions

-rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

michael@0	1	/***************************************************************************/
michael@0	2	/* */
michael@0	3	/* ftttdrv.h */
michael@0	4	/* */
michael@0	5	/* FreeType API for controlling the TrueType driver */
michael@0	6	/* (specification only). */
michael@0	7	/* */
michael@0	8	/* Copyright 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 __FTTTDRV_H__
michael@0	21	#define __FTTTDRV_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	*
michael@0	38	* @section:
michael@0	39	* tt_driver
michael@0	40	*
michael@0	41	* @title:
michael@0	42	* The TrueType driver
michael@0	43	*
michael@0	44	* @abstract:
michael@0	45	* Controlling the TrueType driver module.
michael@0	46	*
michael@0	47	* @description:
michael@0	48	* While FreeType's TrueType driver doesn't expose API functions by
michael@0	49	* itself, it is possible to control its behaviour with @FT_Property_Set
michael@0	50	* and @FT_Property_Get. The following lists the available properties
michael@0	51	* together with the necessary macros and structures.
michael@0	52	*
michael@0	53	* The TrueType driver's module name is `truetype'.
michael@0	54	*
michael@0	55	*/
michael@0	56
michael@0	57
michael@0	58	/**************************************************************************
michael@0	59	*
michael@0	60	* @property:
michael@0	61	* interpreter-version
michael@0	62	*
michael@0	63	* @description:
michael@0	64	* Currently, two versions are available, representing the bytecode
michael@0	65	* interpreter with and without subpixel hinting support,
michael@0	66	* respectively. The default is subpixel support if
michael@0	67	* TT_CONFIG_OPTION_SUBPIXEL_HINTING is defined, and no subpixel
michael@0	68	* support otherwise (since it isn't available then).
michael@0	69	*
michael@0	70	* If subpixel hinting is on, many TrueType bytecode instructions
michael@0	71	* behave differently compared to B/W or grayscale rendering. The
michael@0	72	* main idea is to render at a much increased horizontal resolution,
michael@0	73	* then sampling down the created output to subpixel precision.
michael@0	74	* However, many older fonts are not suited to this and must be
michael@0	75	* specially taken care of by applying (hardcoded) font-specific
michael@0	76	* tweaks.
michael@0	77	*
michael@0	78	* Details on subpixel hinting and some of the necessary tweaks can be
michael@0	79	* found in Greg Hitchcock's whitepaper at
michael@0	80	* `http://www.microsoft.com/typography/cleartype/truetypecleartype.aspx'.
michael@0	81	*
michael@0	82	* The following example code demonstrates how to activate subpixel
michael@0	83	* hinting (omitting the error handling).
michael@0	84	*
michael@0	85	* {
michael@0	86	* FT_Library library;
michael@0	87	* FT_Face face;
michael@0	88	* FT_UInt interpreter_version = TT_INTERPRETER_VERSION_38;
michael@0	89	*
michael@0	90	*
michael@0	91	* FT_Init_FreeType( &library );
michael@0	92	*
michael@0	93	* FT_Property_Set( library, "truetype",
michael@0	94	* "interpreter-version",
michael@0	95	* &interpreter_version );
michael@0	96	* }
michael@0	97	*
michael@0	98	* @note:
michael@0	99	* This property can be used with @FT_Property_Get also.
michael@0	100	*
michael@0	101	*/
michael@0	102
michael@0	103
michael@0	104	/**************************************************************************
michael@0	105	*
michael@0	106	* @enum:
michael@0	107	* TT_INTERPRETER_VERSION_XXX
michael@0	108	*
michael@0	109	* @description:
michael@0	110	* A list of constants used for the @interpreter-version property to
michael@0	111	* select the hinting engine for Truetype fonts.
michael@0	112	*
michael@0	113	* The numeric value in the constant names represents the version
michael@0	114	* number as returned by the `GETINFO' bytecode instruction.
michael@0	115	*
michael@0	116	* @values:
michael@0	117	* TT_INTERPRETER_VERSION_35 ::
michael@0	118	* Version~35 corresponds to MS rasterizer v.1.7 as used e.g. in
michael@0	119	* Windows~98; only grayscale and B/W rasterizing is supported.
michael@0	120	*
michael@0	121	* TT_INTERPRETER_VERSION_38 ::
michael@0	122	* Version~38 corresponds to MS rasterizer v.1.9; it is roughly
michael@0	123	* equivalent to the hinting provided by DirectWrite ClearType (as
michael@0	124	* can be found, for example, in the Internet Explorer~9 running on
michael@0	125	* Windows~7).
michael@0	126	*
michael@0	127	* @note:
michael@0	128	* This property controls the behaviour of the bytecode interpreter
michael@0	129	* and thus how outlines get hinted. It does *not* control how glyph
michael@0	130	* get rasterized! In particular, it does not control subpixel color
michael@0	131	* filtering.
michael@0	132	*
michael@0	133	* If FreeType has not been compiled with configuration option
michael@0	134	* FT_CONFIG_OPTION_SUBPIXEL_HINTING, selecting version~38 causes an
michael@0	135	* `FT_Err_Unimplemented_Feature' error.
michael@0	136	*
michael@0	137	* Depending on the graphics framework, Microsoft uses different
michael@0	138	* bytecode engines. As a consequence, the version numbers returned by
michael@0	139	* a call to the `GETINFO[1]' bytecode instruction are more convoluted
michael@0	140	* than desired.
michael@0	141	*
michael@0	142	* {
michael@0	143	* framework Windows version result of GETINFO[1]
michael@0	144	* ----------------------------------------------------
michael@0	145	* GDI before XP 35
michael@0	146	* GDI XP and later 37
michael@0	147	* GDI+ old before Vista 37
michael@0	148	* GDI+ old Vista, 7 38
michael@0	149	* GDI+ after 7 40
michael@0	150	* DWrite before 8 39
michael@0	151	* DWrite 8 and later 40
michael@0	152	* }
michael@0	153	*
michael@0	154	* Since FreeType doesn't provide all capabilities of DWrite ClearType,
michael@0	155	* using version~38 seems justified.
michael@0	156	*
michael@0	157	*/
michael@0	158	#define TT_INTERPRETER_VERSION_35 35
michael@0	159	#define TT_INTERPRETER_VERSION_38 38
michael@0	160
michael@0	161
michael@0	162	/* */
michael@0	163
michael@0	164	FT_END_HEADER
michael@0	165
michael@0	166
michael@0	167	#endif /* __FTTTDRV_H__ */
michael@0	168
michael@0	169
michael@0	170	/* END */