reactos/lib/3rdparty/freetype/include/ftttdrv.h

   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
  33 FT_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
 164 FT_END_HEADER
 165
 166
 167 #endif /* __FTTTDRV_H__ */
 168
 169
 170 /* END */