include/freetype/ftgasp.h

   1 /****************************************************************************
   2  *
   3  * ftgasp.h
   4  *
   5  *   Access of TrueType's 'gasp' table (specification).
   6  *
   7  * Copyright (C) 2007-2023 by
   8  * David Turner, Robert Wilhelm, and Werner Lemberg.
   9  *
  10  * This file is part of the FreeType project, and may only be used,
  11  * modified, and distributed under the terms of the FreeType project
  12  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
  13  * this file you indicate that you have read the license and
  14  * understand and accept it fully.
  15  *
  16  */
  17
  18
  19 #ifndef FTGASP_H_
  20 #define FTGASP_H_
  21
  22 #include <freetype/freetype.h>
  23
  24 #ifdef FREETYPE_H
  25 #error "freetype.h of FreeType 1 has been loaded!"
  26 #error "Please fix the directory search order for header files"
  27 #error "so that freetype.h of FreeType 2 is found first."
  28 #endif
  29
  30
  31 FT_BEGIN_HEADER
  32
  33
  34   /**************************************************************************
  35    *
  36    * @section:
  37    *   gasp_table
  38    *
  39    * @title:
  40    *   Gasp Table
  41    *
  42    * @abstract:
  43    *   Retrieving TrueType 'gasp' table entries.
  44    *
  45    * @description:
  46    *   The function @FT_Get_Gasp can be used to query a TrueType or OpenType
  47    *   font for specific entries in its 'gasp' table, if any.  This is mainly
  48    *   useful when implementing native TrueType hinting with the bytecode
  49    *   interpreter to duplicate the Windows text rendering results.
  50    */
  51
  52   /**************************************************************************
  53    *
  54    * @enum:
  55    *   FT_GASP_XXX
  56    *
  57    * @description:
  58    *   A list of values and/or bit-flags returned by the @FT_Get_Gasp
  59    *   function.
  60    *
  61    * @values:
  62    *   FT_GASP_NO_TABLE ::
  63    *     This special value means that there is no GASP table in this face.
  64    *     It is up to the client to decide what to do.
  65    *
  66    *   FT_GASP_DO_GRIDFIT ::
  67    *     Grid-fitting and hinting should be performed at the specified ppem.
  68    *     This **really** means TrueType bytecode interpretation.  If this bit
  69    *     is not set, no hinting gets applied.
  70    *
  71    *   FT_GASP_DO_GRAY ::
  72    *     Anti-aliased rendering should be performed at the specified ppem.
  73    *     If not set, do monochrome rendering.
  74    *
  75    *   FT_GASP_SYMMETRIC_SMOOTHING ::
  76    *     If set, smoothing along multiple axes must be used with ClearType.
  77    *
  78    *   FT_GASP_SYMMETRIC_GRIDFIT ::
  79    *     Grid-fitting must be used with ClearType's symmetric smoothing.
  80    *
  81    * @note:
  82    *   The bit-flags `FT_GASP_DO_GRIDFIT` and `FT_GASP_DO_GRAY` are to be
  83    *   used for standard font rasterization only.  Independently of that,
  84    *   `FT_GASP_SYMMETRIC_SMOOTHING` and `FT_GASP_SYMMETRIC_GRIDFIT` are to
  85    *   be used if ClearType is enabled (and `FT_GASP_DO_GRIDFIT` and
  86    *   `FT_GASP_DO_GRAY` are consequently ignored).
  87    *
  88    *   'ClearType' is Microsoft's implementation of LCD rendering, partly
  89    *   protected by patents.
  90    *
  91    * @since:
  92    *   2.3.0
  93    */
  94 #define FT_GASP_NO_TABLE               -1
  95 #define FT_GASP_DO_GRIDFIT           0x01
  96 #define FT_GASP_DO_GRAY              0x02
  97 #define FT_GASP_SYMMETRIC_GRIDFIT    0x04
  98 #define FT_GASP_SYMMETRIC_SMOOTHING  0x08
  99
 100
 101   /**************************************************************************
 102    *
 103    * @function:
 104    *   FT_Get_Gasp
 105    *
 106    * @description:
 107    *   For a TrueType or OpenType font file, return the rasterizer behaviour
 108    *   flags from the font's 'gasp' table corresponding to a given character
 109    *   pixel size.
 110    *
 111    * @input:
 112    *   face ::
 113    *     The source face handle.
 114    *
 115    *   ppem ::
 116    *     The vertical character pixel size.
 117    *
 118    * @return:
 119    *   Bit flags (see @FT_GASP_XXX), or @FT_GASP_NO_TABLE if there is no
 120    *   'gasp' table in the face.
 121    *
 122    * @note:
 123    *   If you want to use the MM functionality of OpenType variation fonts
 124    *   (i.e., using @FT_Set_Var_Design_Coordinates and friends), call this
 125    *   function **after** setting an instance since the return values can
 126    *   change.
 127    *
 128    * @since:
 129    *   2.3.0
 130    */
 131   FT_EXPORT( FT_Int )
 132   FT_Get_Gasp( FT_Face  face,
 133                FT_UInt  ppem );
 134
 135   /* */
 136
 137
 138 FT_END_HEADER
 139
 140 #endif /* FTGASP_H_ */
 141
 142
 143 /* END */