/***************************************************************************/ /* */ /* ftttdrv.h */ /* */ /* FreeType API for controlling the TrueType driver */ /* (specification only). */ /* */ /* Copyright 2013-2015 by */ /* David Turner, Robert Wilhelm, and Werner Lemberg. */ /* */ /* This file is part of the FreeType project, and may only be used, */ /* modified, and distributed under the terms of the FreeType project */ /* license, LICENSE.TXT. By continuing to use, modify, or distribute */ /* this file you indicate that you have read the license and */ /* understand and accept it fully. */ /* */ /***************************************************************************/ #ifndef __FTTTDRV_H__ #define __FTTTDRV_H__ #include #include FT_FREETYPE_H #ifdef FREETYPE_H #error "freetype.h of FreeType 1 has been loaded!" #error "Please fix the directory search order for header files" #error "so that freetype.h of FreeType 2 is found first." #endif FT_BEGIN_HEADER /************************************************************************** * * @section: * tt_driver * * @title: * The TrueType driver * * @abstract: * Controlling the TrueType driver module. * * @description: * While FreeType's TrueType driver doesn't expose API functions by * itself, it is possible to control its behaviour with @FT_Property_Set * and @FT_Property_Get. The following lists the available properties * together with the necessary macros and structures. * * The TrueType driver's module name is `truetype'. * */ /************************************************************************** * * @property: * interpreter-version * * @description: * Currently, two versions are available, representing the bytecode * interpreter with and without subpixel hinting support, * respectively. The default is subpixel support if * TT_CONFIG_OPTION_SUBPIXEL_HINTING is defined, and no subpixel * support otherwise (since it isn't available then). * * If subpixel hinting is on, many TrueType bytecode instructions behave * differently compared to B/W or grayscale rendering (except if `native * ClearType' is selected by the font). The main idea is to render at a * much increased horizontal resolution, then sampling down the created * output to subpixel precision. However, many older fonts are not * suited to this and must be specially taken care of by applying * (hardcoded) font-specific tweaks. * * Details on subpixel hinting and some of the necessary tweaks can be * found in Greg Hitchcock's whitepaper at * `http://www.microsoft.com/typography/cleartype/truetypecleartype.aspx'. * * The following example code demonstrates how to activate subpixel * hinting (omitting the error handling). * * { * FT_Library library; * FT_Face face; * FT_UInt interpreter_version = TT_INTERPRETER_VERSION_38; * * * FT_Init_FreeType( &library ); * * FT_Property_Set( library, "truetype", * "interpreter-version", * &interpreter_version ); * } * * @note: * This property can be used with @FT_Property_Get also. * */ /************************************************************************** * * @enum: * TT_INTERPRETER_VERSION_XXX * * @description: * A list of constants used for the @interpreter-version property to * select the hinting engine for Truetype fonts. * * The numeric value in the constant names represents the version * number as returned by the `GETINFO' bytecode instruction. * * @values: * TT_INTERPRETER_VERSION_35 :: * Version~35 corresponds to MS rasterizer v.1.7 as used e.g. in * Windows~98; only grayscale and B/W rasterizing is supported. * * TT_INTERPRETER_VERSION_38 :: * Version~38 corresponds to MS rasterizer v.1.9; it is roughly * equivalent to the hinting provided by DirectWrite ClearType (as * can be found, for example, in the Internet Explorer~9 running on * Windows~7). * * @note: * This property controls the behaviour of the bytecode interpreter * and thus how outlines get hinted. It does *not* control how glyph * get rasterized! In particular, it does not control subpixel color * filtering. * * If FreeType has not been compiled with configuration option * FT_CONFIG_OPTION_SUBPIXEL_HINTING, selecting version~38 causes an * `FT_Err_Unimplemented_Feature' error. * * Depending on the graphics framework, Microsoft uses different * bytecode and rendering engines. As a consequence, the version * numbers returned by a call to the `GETINFO[1]' bytecode instruction * are more convoluted than desired. * * Here are two tables that try to shed some light on the possible * values for the MS rasterizer engine, together with the additional * features introduced by it. * * { * GETINFO framework version feature * ------------------------------------------------------------------- * 3 GDI (Win 3.1), v1.0 16-bit, first version * TrueImage * 33 GDI (Win NT 3.1), v1.5 32-bit * HP Laserjet * 34 GDI (Win 95) v1.6 font smoothing, * new SCANTYPE opcode * 35 GDI (Win 98/2000) v1.7 (UN)SCALED_COMPONENT_OFFSET * bits in composite glyphs * 36 MGDI (Win CE 2) v1.6+ classic ClearType * 37 GDI (XP and later), v1.8 ClearType * GDI+ old (before Vista) * 38 GDI+ old (Vista, Win 7), v1.9 subpixel ClearType, * WPF Y-direction ClearType, * additional error checking * 39 DWrite (before Win 8) v2.0 subpixel ClearType flags * in GETINFO opcode, * bug fixes * 40 GDI+ (after Win 7), v2.1 Y-direction ClearType flag * DWrite (Win 8) in GETINFO opcode, * Gray ClearType * } * * The `version' field gives a rough orientation only, since some * applications provided certain features much earlier (as an example, * Microsoft Reader used subpixel and Y-direction ClearType already in * Windows 2000). Similarly, updates to a given framework might include * improved hinting support. * * { * version sampling rendering comment * x y x y * --------------------------------------------------------------- * v1.0 normal normal B/W B/W bi-level * v1.6 high high gray gray grayscale * v1.8 high normal color-filter B/W (GDI) ClearType * v1.9 high high color-filter gray Color ClearType * v2.1 high normal gray B/W Gray ClearType * v2.1 high high gray gray Gray ClearType * } * * Color and Gray ClearType are the two available variants of * `Y-direction ClearType', meaning grayscale rasterization along the * Y-direction; the name used in the TrueType specification for this * feature is `symmetric smoothing'. `Classic ClearType' is the * original algorithm used before introducing a modified version in * Win~XP. Another name for v1.6's grayscale rendering is `font * smoothing', and `Color ClearType' is sometimes also called `DWrite * ClearType'. To differentiate between today's Color ClearType and the * earlier ClearType variant with B/W rendering along the vertical axis, * the latter is sometimes called `GDI ClearType'. * * `Normal' and `high' sampling describe the (virtual) resolution to * access the rasterized outline after the hinting process. `Normal' * means 1 sample per grid line (i.e., B/W). In the current Microsoft * implementation, `high' means an extra virtual resolution of 16x16 (or * 16x1) grid lines per pixel for bytecode instructions like `MIRP'. * After hinting, these 16 grid lines are mapped to 6x5 (or 6x1) grid * lines for color filtering if Color ClearType is activated. * * Note that `Gray ClearType' is essentially the same as v1.6's * grayscale rendering. However, the GETINFO instruction handles it * differently: v1.6 returns bit~12 (hinting for grayscale), while v2.1 * returns bits~13 (hinting for ClearType), 18 (symmetrical smoothing), * and~19 (Gray ClearType). Also, this mode respects bits 2 and~3 for * the version~1 gasp table exclusively (like Color ClearType), while * v1.6 only respects the values of version~0 (bits 0 and~1). * * FreeType doesn't provide all capabilities of the most recent * ClearType incarnation, thus we identify our subpixel support as * version~38. * */ #define TT_INTERPRETER_VERSION_35 35 #define TT_INTERPRETER_VERSION_38 38 /* */ FT_END_HEADER #endif /* __FTTTDRV_H__ */ /* END */