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 */