freetype2/freetype/ftgasp.h

0001 /****************************************************************************
0002  *
0003  * ftgasp.h
0004  *
0005  *   Access of TrueType's 'gasp' table (specification).
0006  *
0007  * Copyright (C) 2007-2023 by
0008  * David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018
0019 #ifndef FTGASP_H_
0020 #define FTGASP_H_
0021
0022 #include <freetype/freetype.h>
0023
0024 #ifdef FREETYPE_H
0025 #error "freetype.h of FreeType 1 has been loaded!"
0026 #error "Please fix the directory search order for header files"
0027 #error "so that freetype.h of FreeType 2 is found first."
0028 #endif
0029
0030
0031 FT_BEGIN_HEADER
0032
0033
0034   /**************************************************************************
0035    *
0036    * @section:
0037    *   gasp_table
0038    *
0039    * @title:
0040    *   Gasp Table
0041    *
0042    * @abstract:
0043    *   Retrieving TrueType 'gasp' table entries.
0044    *
0045    * @description:
0046    *   The function @FT_Get_Gasp can be used to query a TrueType or OpenType
0047    *   font for specific entries in its 'gasp' table, if any.  This is mainly
0048    *   useful when implementing native TrueType hinting with the bytecode
0049    *   interpreter to duplicate the Windows text rendering results.
0050    */
0051
0052   /**************************************************************************
0053    *
0054    * @enum:
0055    *   FT_GASP_XXX
0056    *
0057    * @description:
0058    *   A list of values and/or bit-flags returned by the @FT_Get_Gasp
0059    *   function.
0060    *
0061    * @values:
0062    *   FT_GASP_NO_TABLE ::
0063    *     This special value means that there is no GASP table in this face.
0064    *     It is up to the client to decide what to do.
0065    *
0066    *   FT_GASP_DO_GRIDFIT ::
0067    *     Grid-fitting and hinting should be performed at the specified ppem.
0068    *     This **really** means TrueType bytecode interpretation.  If this bit
0069    *     is not set, no hinting gets applied.
0070    *
0071    *   FT_GASP_DO_GRAY ::
0072    *     Anti-aliased rendering should be performed at the specified ppem.
0073    *     If not set, do monochrome rendering.
0074    *
0075    *   FT_GASP_SYMMETRIC_SMOOTHING ::
0076    *     If set, smoothing along multiple axes must be used with ClearType.
0077    *
0078    *   FT_GASP_SYMMETRIC_GRIDFIT ::
0079    *     Grid-fitting must be used with ClearType's symmetric smoothing.
0080    *
0081    * @note:
0082    *   The bit-flags `FT_GASP_DO_GRIDFIT` and `FT_GASP_DO_GRAY` are to be
0083    *   used for standard font rasterization only.  Independently of that,
0084    *   `FT_GASP_SYMMETRIC_SMOOTHING` and `FT_GASP_SYMMETRIC_GRIDFIT` are to
0085    *   be used if ClearType is enabled (and `FT_GASP_DO_GRIDFIT` and
0086    *   `FT_GASP_DO_GRAY` are consequently ignored).
0087    *
0088    *   'ClearType' is Microsoft's implementation of LCD rendering, partly
0089    *   protected by patents.
0090    *
0091    * @since:
0092    *   2.3.0
0093    */
0094 #define FT_GASP_NO_TABLE               -1
0095 #define FT_GASP_DO_GRIDFIT           0x01
0096 #define FT_GASP_DO_GRAY              0x02
0097 #define FT_GASP_SYMMETRIC_GRIDFIT    0x04
0098 #define FT_GASP_SYMMETRIC_SMOOTHING  0x08
0099
0100
0101   /**************************************************************************
0102    *
0103    * @function:
0104    *   FT_Get_Gasp
0105    *
0106    * @description:
0107    *   For a TrueType or OpenType font file, return the rasterizer behaviour
0108    *   flags from the font's 'gasp' table corresponding to a given character
0109    *   pixel size.
0110    *
0111    * @input:
0112    *   face ::
0113    *     The source face handle.
0114    *
0115    *   ppem ::
0116    *     The vertical character pixel size.
0117    *
0118    * @return:
0119    *   Bit flags (see @FT_GASP_XXX), or @FT_GASP_NO_TABLE if there is no
0120    *   'gasp' table in the face.
0121    *
0122    * @note:
0123    *   If you want to use the MM functionality of OpenType variation fonts
0124    *   (i.e., using @FT_Set_Var_Design_Coordinates and friends), call this
0125    *   function **after** setting an instance since the return values can
0126    *   change.
0127    *
0128    * @since:
0129    *   2.3.0
0130    */
0131   FT_EXPORT( FT_Int )
0132   FT_Get_Gasp( FT_Face  face,
0133                FT_UInt  ppem );
0134
0135   /* */
0136
0137
0138 FT_END_HEADER
0139
0140 #endif /* FTGASP_H_ */
0141
0142
0143 /* END */