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