text:
/****************************************************************************
 *
 * ftsnames.h
 *
 *   Simple interface to access SFNT 'name' tables (which are used
 *   to hold font names, copyright info, notices, etc.) (specification).
 *
 *   This is _not_ used to retrieve glyph names!
 *
 * Copyright (C) 1996-2020 by
 * David Turner, Robert Wilhelm, and Werner Lemberg.
 *
 * This file is part of the FreeType project, and may only be used,
 * modified, and distributed under the terms of the FreeType project
 * license, LICENSE.TXT.  By continuing to use, modify, or distribute
 * this file you indicate that you have read the license and
 * understand and accept it fully.
 *
 */

#ifndef FTSNAMES_H_
#define FTSNAMES_H_

#include <ft2build.h>
#include FT_FREETYPE_H
#include FT_PARAMETER_TAGS_H

#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif

FT_BEGIN_HEADER

  /**************************************************************************
   *
   * @section:
   *   sfnt_names
   *
   * @title:
   *   SFNT Names
   *
   * @abstract:
   *   Access the names embedded in TrueType and OpenType files.
   *
   * @description:
   *   The TrueType and OpenType specifications allow the inclusion of a
   *   special names table ('name') in font files.  This table contains
   *   textual (and internationalized) information regarding the font, like
   *   family name, copyright, version, etc.
   *
   *   The definitions below are used to access them if available.
   *
   *   Note that this has nothing to do with glyph names!
   *
   */

  /**************************************************************************
   *
   * @struct:
   *   FT_SfntName
   *
   * @description:
   *   A structure used to model an SFNT 'name' table entry.
   *
   * @fields:
   *   platform_id ::
   *     The platform ID for `string`.  See @TT_PLATFORM_XXX for possible
   *     values.
   *
   *   encoding_id ::
   *     The encoding ID for `string`.  See @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX,
   *     @TT_ISO_ID_XXX, @TT_MS_ID_XXX, and @TT_ADOBE_ID_XXX for possible
   *     values.
   *
   *   language_id ::
   *     The language ID for `string`.  See @TT_MAC_LANGID_XXX and
   *     @TT_MS_LANGID_XXX for possible values.
   *
   *     Registered OpenType values for `language_id` are always smaller than
   *     0x8000; values equal or larger than 0x8000 usually indicate a
   *     language tag string (introduced in OpenType version 1.6).  Use
   *     function @FT_Get_Sfnt_LangTag with `language_id` as its argument to
   *     retrieve the associated language tag.
   *
   *   name_id ::
   *     An identifier for `string`.  See @TT_NAME_ID_XXX for possible
   *     values.
   *
   *   string ::
   *     The 'name' string.  Note that its format differs depending on the
   *     (platform,encoding) pair, being either a string of bytes (without a
   *     terminating `NULL` byte) or containing UTF-16BE entities.
   *
   *   string_len ::
   *     The length of `string` in bytes.
   *
   * @note:
   *   Please refer to the TrueType or OpenType specification for more
   *   details.
   */
  typedef struct  FT_SfntName_
  {
    FT_UShort  platform_id;
    FT_UShort  encoding_id;
    FT_UShort  language_id;
    FT_UShort  name_id;

    FT_Byte*   string;      /* this string is *not* null-terminated! */
    FT_UInt    string_len;  /* in bytes                              */

  } FT_SfntName;

  /**************************************************************************
   *
   * @function:
   *   FT_Get_Sfnt_Name_Count
   *
   * @description:
   *   Retrieve the number of name strings in the SFNT 'name' table.
   *
   * @input:
   *   face ::
   *     A handle to the source face.
   *
   * @return:
   *   The number of strings in the 'name' table.
   *
   * @note:
   *   This function always returns an error if the config macro
   *   `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`.
   */
  FT_EXPORT( FT_UInt )
  FT_Get_Sfnt_Name_Count( FT_Face  face );

  /**************************************************************************
   *
   * @function:
   *   FT_Get_Sfnt_Name
   *
   * @description:
   *   Retrieve a string of the SFNT 'name' table for a given index.
   *
   * @input:
   *   face ::
   *     A handle to the source face.
   *
   *   idx ::
   *     The index of the 'name' string.
   *
   * @output:
   *   aname ::
   *     The indexed @FT_SfntName structure.
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The `string` array returned in the `aname` structure is not
   *   null-terminated.  Note that you don't have to deallocate `string` by
   *   yourself; FreeType takes care of it if you call @FT_Done_Face.
   *
   *   Use @FT_Get_Sfnt_Name_Count to get the total number of available
   *   'name' table entries, then do a loop until you get the right platform,
   *   encoding, and name ID.
   *
   *   'name' table format~1 entries can use language tags also, see
   *   @FT_Get_Sfnt_LangTag.
   *
   *   This function always returns an error if the config macro
   *   `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`.
   */
  FT_EXPORT( FT_Error )
  FT_Get_Sfnt_Name( FT_Face       face,
                    FT_UInt       idx,
                    FT_SfntName  *aname );

  /**************************************************************************
   *
   * @struct:
   *   FT_SfntLangTag
   *
   * @description:
   *   A structure to model a language tag entry from an SFNT 'name' table.
   *
   * @fields:
   *   string ::
   *     The language tag string, encoded in UTF-16BE (without trailing
   *     `NULL` bytes).
   *
   *   string_len ::
   *     The length of `string` in **bytes**.
   *
   * @note:
   *   Please refer to the TrueType or OpenType specification for more
   *   details.
   *
   * @since:
   *   2.8
   */
  typedef struct  FT_SfntLangTag_
  {
    FT_Byte*  string;      /* this string is *not* null-terminated! */
    FT_UInt   string_len;  /* in bytes                              */

  } FT_SfntLangTag;

  /**************************************************************************
   *
   * @function:
   *   FT_Get_Sfnt_LangTag
   *
   * @description:
   *   Retrieve the language tag associated with a language ID of an SFNT
   *   'name' table entry.
   *
   * @input:
   *   face ::
   *     A handle to the source face.
   *
   *   langID ::
   *     The language ID, as returned by @FT_Get_Sfnt_Name.  This is always a
   *     value larger than 0x8000.
   *
   * @output:
   *   alangTag ::
   *     The language tag associated with the 'name' table entry's language
   *     ID.
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The `string` array returned in the `alangTag` structure is not
   *   null-terminated.  Note that you don't have to deallocate `string` by
   *   yourself; FreeType takes care of it if you call @FT_Done_Face.
   *
   *   Only 'name' table format~1 supports language tags.  For format~0
   *   tables, this function always returns FT_Err_Invalid_Table.  For
   *   invalid format~1 language ID values, FT_Err_Invalid_Argument is
   *   returned.
   *
   *   This function always returns an error if the config macro
   *   `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`.
   *
   * @since:
   *   2.8
   */
  FT_EXPORT( FT_Error )
  FT_Get_Sfnt_LangTag( FT_Face          face,
                       FT_UInt          langID,
                       FT_SfntLangTag  *alangTag );

  /* */

FT_END_HEADER

#endif /* FTSNAMES_H_ */

/* END */

repo_language: C

mime_type: text/x-c


text:
/****************************************************************************
 *
 * ftbzip2.h
 *
 *   Bzip2-compressed stream support.
 *
 * Copyright (C) 2010-2020 by
 * Joel Klinghed.
 *
 * This file is part of the FreeType project, and may only be used,
 * modified, and distributed under the terms of the FreeType project
 * license, LICENSE.TXT.  By continuing to use, modify, or distribute
 * this file you indicate that you have read the license and
 * understand and accept it fully.
 *
 */

#ifndef FTBZIP2_H_
#define FTBZIP2_H_

#include <ft2build.h>
#include FT_FREETYPE_H

#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif

FT_BEGIN_HEADER

  /**************************************************************************
   *
   * @section:
   *   bzip2
   *
   * @title:
   *   BZIP2 Streams
   *
   * @abstract:
   *   Using bzip2-compressed font files.
   *
   * @description:
   *   This section contains the declaration of Bzip2-specific functions.
   *
   */

  /**************************************************************************
   *
   * @function:
   *   FT_Stream_OpenBzip2
   *
   * @description:
   *   Open a new stream to parse bzip2-compressed font files.  This is
   *   mainly used to support the compressed `*.pcf.bz2` fonts that come with
   *   XFree86.
   *
   * @input:
   *   stream ::
   *     The target embedding stream.
   *
   *   source ::
   *     The source stream.
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The source stream must be opened _before_ calling this function.
   *
   *   Calling the internal function `FT_Stream_Close` on the new stream will
   *   **not** call `FT_Stream_Close` on the source stream.  None of the
   *   stream objects will be released to the heap.
   *
   *   The stream implementation is very basic and resets the decompression
   *   process each time seeking backwards is needed within the stream.
   *
   *   In certain builds of the library, bzip2 compression recognition is
   *   automatically handled when calling @FT_New_Face or @FT_Open_Face.
   *   This means that if no font driver is capable of handling the raw
   *   compressed file, the library will try to open a bzip2 compressed
   *   stream from it and re-open the face with it.
   *
   *   This function may return `FT_Err_Unimplemented_Feature` if your build
   *   of FreeType was not compiled with bzip2 support.
   */
  FT_EXPORT( FT_Error )
  FT_Stream_OpenBzip2( FT_Stream  stream,
                       FT_Stream  source );

  /* */

FT_END_HEADER

#endif /* FTBZIP2_H_ */

/* END */


text:
/****************************************************************************
 *
 * ftotval.h
 *
 *   FreeType API for validating OpenType tables (specification).
 *
 * Copyright (C) 2004-2020 by
 * David Turner, Robert Wilhelm, and Werner Lemberg.
 *
 * This file is part of the FreeType project, and may only be used,
 * modified, and distributed under the terms of the FreeType project
 * license, LICENSE.TXT.  By continuing to use, modify, or distribute
 * this file you indicate that you have read the license and
 * understand and accept it fully.
 *
 */

/****************************************************************************
 *
 *
 * Warning: This module might be moved to a different library in the
 *          future to avoid a tight dependency between FreeType and the
 *          OpenType specification.
 *
 *
 */

#ifndef FTOTVAL_H_
#define FTOTVAL_H_

#include <ft2build.h>
#include FT_FREETYPE_H

#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif

FT_BEGIN_HEADER

  /**************************************************************************
   *
   * @section:
   *   ot_validation
   *
   * @title:
   *   OpenType Validation
   *
   * @abstract:
   *   An API to validate OpenType tables.
   *
   * @description:
   *   This section contains the declaration of functions to validate some
   *   OpenType tables (BASE, GDEF, GPOS, GSUB, JSTF, MATH).
   *
   * @order:
   *   FT_OpenType_Validate
   *   FT_OpenType_Free
   *
   *   FT_VALIDATE_OTXXX
   *
   */

  /**************************************************************************
   *
   * @enum:
   *    FT_VALIDATE_OTXXX
   *
   * @description:
   *    A list of bit-field constants used with @FT_OpenType_Validate to
   *    indicate which OpenType tables should be validated.
   *
   * @values:
   *    FT_VALIDATE_BASE ::
   *      Validate BASE table.
   *
   *    FT_VALIDATE_GDEF ::
   *      Validate GDEF table.
   *
   *    FT_VALIDATE_GPOS ::
   *      Validate GPOS table.
   *
   *    FT_VALIDATE_GSUB ::
   *      Validate GSUB table.
   *
   *    FT_VALIDATE_JSTF ::
   *      Validate JSTF table.
   *
   *    FT_VALIDATE_MATH ::
   *      Validate MATH table.
   *
   *    FT_VALIDATE_OT ::
   *      Validate all OpenType tables (BASE, GDEF, GPOS, GSUB, JSTF, MATH).
   *
   */
#define FT_VALIDATE_BASE  0x0100
#define FT_VALIDATE_GDEF  0x0200
#define FT_VALIDATE_GPOS  0x0400
#define FT_VALIDATE_GSUB  0x0800
#define FT_VALIDATE_JSTF  0x1000
#define FT_VALIDATE_MATH  0x2000

#define FT_VALIDATE_OT  ( FT_VALIDATE_BASE | \
                          FT_VALIDATE_GDEF | \
                          FT_VALIDATE_GPOS | \
                          FT_VALIDATE_GSUB | \
                          FT_VALIDATE_JSTF | \
                          FT_VALIDATE_MATH )

  /**************************************************************************
   *
   * @function:
   *    FT_OpenType_Validate
   *
   * @description:
   *    Validate various OpenType tables to assure that all offsets and
   *    indices are valid.  The idea is that a higher-level library that
   *    actually does the text layout can access those tables without error
   *    checking (which can be quite time consuming).
   *
   * @input:
   *    face ::
   *      A handle to the input face.
   *
   *    validation_flags ::
   *      A bit field that specifies the tables to be validated.  See
   *      @FT_VALIDATE_OTXXX for possible values.
   *
   * @output:
   *    BASE_table ::
   *      A pointer to the BASE table.
   *
   *    GDEF_table ::
   *      A pointer to the GDEF table.
   *
   *    GPOS_table ::
   *      A pointer to the GPOS table.
   *
   *    GSUB_table ::
   *      A pointer to the GSUB table.
   *
   *    JSTF_table ::
   *      A pointer to the JSTF table.
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   This function only works with OpenType fonts, returning an error
   *   otherwise.
   *
   *   After use, the application should deallocate the five tables with
   *   @FT_OpenType_Free.  A `NULL` value indicates that the table either
   *   doesn't exist in the font, or the application hasn't asked for
   *   validation.
   */
  FT_EXPORT( FT_Error )
  FT_OpenType_Validate( FT_Face    face,
                        FT_UInt    validation_flags,
                        FT_Bytes  *BASE_table,
                        FT_Bytes  *GDEF_table,
                        FT_Bytes  *GPOS_table,
                        FT_Bytes  *GSUB_table,
                        FT_Bytes  *JSTF_table );

  /**************************************************************************
   *
   * @function:
   *    FT_OpenType_Free
   *
   * @description:
   *    Free the buffer allocated by OpenType validator.
   *
   * @input:
   *    face ::
   *      A handle to the input face.
   *
   *    table ::
   *      The pointer to the buffer that is allocated by
   *      @FT_OpenType_Validate.
   *
   * @note:
   *   This function must be used to free the buffer allocated by
   *   @FT_OpenType_Validate only.
   */
  FT_EXPORT( void )
  FT_OpenType_Free( FT_Face   face,
                    FT_Bytes  table );

  /* */

FT_END_HEADER

#endif /* FTOTVAL_H_ */

/* END */


text:
/****************************************************************************
 *
 * fttrigon.h
 *
 *   FreeType trigonometric functions (specification).
 *
 * Copyright (C) 2001-2020 by
 * David Turner, Robert Wilhelm, and Werner Lemberg.
 *
 * This file is part of the FreeType project, and may only be used,
 * modified, and distributed under the terms of the FreeType project
 * license, LICENSE.TXT.  By continuing to use, modify, or distribute
 * this file you indicate that you have read the license and
 * understand and accept it fully.
 *
 */

#ifndef FTTRIGON_H_
#define FTTRIGON_H_

#include FT_FREETYPE_H

#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif

FT_BEGIN_HEADER

  /**************************************************************************
   *
   * @section:
   *  computations
   *
   */

  /**************************************************************************
   *
   * @type:
   *   FT_Angle
   *
   * @description:
   *   This type is used to model angle values in FreeType.  Note that the
   *   angle is a 16.16 fixed-point value expressed in degrees.
   *
   */
  typedef FT_Fixed  FT_Angle;

  /**************************************************************************
   *
   * @macro:
   *   FT_ANGLE_PI
   *
   * @description:
   *   The angle pi expressed in @FT_Angle units.
   *
   */
#define FT_ANGLE_PI  ( 180L << 16 )

  /**************************************************************************
   *
   * @macro:
   *   FT_ANGLE_2PI
   *
   * @description:
   *   The angle 2*pi expressed in @FT_Angle units.
   *
   */
#define FT_ANGLE_2PI  ( FT_ANGLE_PI * 2 )

  /**************************************************************************
   *
   * @macro:
   *   FT_ANGLE_PI2
   *
   * @description:
   *   The angle pi/2 expressed in @FT_Angle units.
   *
   */
#define FT_ANGLE_PI2  ( FT_ANGLE_PI / 2 )

  /**************************************************************************
   *
   * @macro:
   *   FT_ANGLE_PI4
   *
   * @description:
   *   The angle pi/4 expressed in @FT_Angle units.
   *
   */
#define FT_ANGLE_PI4  ( FT_ANGLE_PI / 4 )

  /**************************************************************************
   *
   * @function:
   *   FT_Sin
   *
   * @description:
   *   Return the sinus of a given angle in fixed-point format.
   *
   * @input:
   *   angle ::
   *     The input angle.
   *
   * @return:
   *   The sinus value.
   *
   * @note:
   *   If you need both the sinus and cosinus for a given angle, use the
   *   function @FT_Vector_Unit.
   *
   */
  FT_EXPORT( FT_Fixed )
  FT_Sin( FT_Angle  angle );

  /**************************************************************************
   *
   * @function:
   *   FT_Cos
   *
   * @description:
   *   Return the cosinus of a given angle in fixed-point format.
   *
   * @input:
   *   angle ::
   *     The input angle.
   *
   * @return:
   *   The cosinus value.
   *
   * @note:
   *   If you need both the sinus and cosinus for a given angle, use the
   *   function @FT_Vector_Unit.
   *
   */
  FT_EXPORT( FT_Fixed )
  FT_Cos( FT_Angle  angle );

  /**************************************************************************
   *
   * @function:
   *   FT_Tan
   *
   * @description:
   *   Return the tangent of a given angle in fixed-point format.
   *
   * @input:
   *   angle ::
   *     The input angle.
   *
   * @return:
   *   The tangent value.
   *
   */
  FT_EXPORT( FT_Fixed )
  FT_Tan( FT_Angle  angle );

  /**************************************************************************
   *
   * @function:
   *   FT_Atan2
   *
   * @description:
   *   Return the arc-tangent corresponding to a given vector (x,y) in the 2d
   *   plane.
   *
   * @input:
   *   x ::
   *     The horizontal vector coordinate.
   *
   *   y ::
   *     The vertical vector coordinate.
   *
   * @return:
   *   The arc-tangent value (i.e. angle).
   *
   */
  FT_EXPORT( FT_Angle )
  FT_Atan2( FT_Fixed  x,
            FT_Fixed  y );

  /**************************************************************************
   *
   * @function:
   *   FT_Angle_Diff
   *
   * @description:
   *   Return the difference between two angles.  The result is always
   *   constrained to the ]-PI..PI] interval.
   *
   * @input:
   *   angle1 ::
   *     First angle.
   *
   *   angle2 ::
   *     Second angle.
   *
   * @return:
   *   Constrained value of `angle2-angle1`.
   *
   */
  FT_EXPORT( FT_Angle )
  FT_Angle_Diff( FT_Angle  angle1,
                 FT_Angle  angle2 );

  /**************************************************************************
   *
   * @function:
   *   FT_Vector_Unit
   *
   * @description:
   *   Return the unit vector corresponding to a given angle.  After the
   *   call, the value of `vec.x` will be `cos(angle)`, and the value of
   *   `vec.y` will be `sin(angle)`.
   *
   *   This function is useful to retrieve both the sinus and cosinus of a
   *   given angle quickly.
   *
   * @output:
   *   vec ::
   *     The address of target vector.
   *
   * @input:
   *   angle ::
   *     The input angle.
   *
   */
  FT_EXPORT( void )
  FT_Vector_Unit( FT_Vector*  vec,
                  FT_Angle    angle );

  /**************************************************************************
   *
   * @function:
   *   FT_Vector_Rotate
   *
   * @description:
   *   Rotate a vector by a given angle.
   *
   * @inout:
   *   vec ::
   *     The address of target vector.
   *
   * @input:
   *   angle ::
   *     The input angle.
   *
   */
  FT_EXPORT( void )
  FT_Vector_Rotate( FT_Vector*  vec,
                    FT_Angle    angle );

  /**************************************************************************
   *
   * @function:
   *   FT_Vector_Length
   *
   * @description:
   *   Return the length of a given vector.
   *
   * @input:
   *   vec ::
   *     The address of target vector.
   *
   * @return:
   *   The vector length, expressed in the same units that the original
   *   vector coordinates.
   *
   */
  FT_EXPORT( FT_Fixed )
  FT_Vector_Length( FT_Vector*  vec );

  /**************************************************************************
   *
   * @function:
   *   FT_Vector_Polarize
   *
   * @description:
   *   Compute both the length and angle of a given vector.
   *
   * @input:
   *   vec ::
   *     The address of source vector.
   *
   * @output:
   *   length ::
   *     The vector length.
   *
   *   angle ::
   *     The vector angle.
   *
   */
  FT_EXPORT( void )
  FT_Vector_Polarize( FT_Vector*  vec,
                      FT_Fixed   *length,
                      FT_Angle   *angle );

  /**************************************************************************
   *
   * @function:
   *   FT_Vector_From_Polar
   *
   * @description:
   *   Compute vector coordinates from a length and angle.
   *
   * @output:
   *   vec ::
   *     The address of source vector.
   *
   * @input:
   *   length ::
   *     The vector length.
   *
   *   angle ::
   *     The vector angle.
   *
   */
  FT_EXPORT( void )
  FT_Vector_From_Polar( FT_Vector*  vec,
                        FT_Fixed    length,
                        FT_Angle    angle );

  /* */

FT_END_HEADER

#endif /* FTTRIGON_H_ */

/* END */


text:
/****************************************************************************
 *
 * This file defines the structure of the FreeType reference.
 * It is used by the python script that generates the HTML files.
 *
 */

  /**************************************************************************
   *
   * @chapter:
   *   general_remarks
   *
   * @title:
   *   General Remarks
   *
   * @sections:
   *   header_inclusion
   *   user_allocation
   *
   */

  /**************************************************************************
   *
   * @chapter:
   *   core_api
   *
   * @title:
   *   Core API
   *
   * @sections:
   *   version
   *   basic_types
   *   base_interface
   *   glyph_variants
   *   color_management
   *   layer_management
   *   glyph_management
   *   mac_specific
   *   sizes_management
   *   header_file_macros
   *
   */

  /**************************************************************************
   *
   * @chapter:
   *   format_specific
   *
   * @title:
   *   Format-Specific API
   *
   * @sections:
   *   multiple_masters
   *   truetype_tables
   *   type1_tables
   *   sfnt_names
   *   bdf_fonts
   *   cid_fonts
   *   pfr_fonts
   *   winfnt_fonts
   *   font_formats
   *   gasp_table
   *
   */

  /**************************************************************************
   *
   * @chapter:
   *   module_specific
   *
   * @title:
   *   Controlling FreeType Modules
   *
   * @sections:
   *   auto_hinter
   *   cff_driver
   *   t1_cid_driver
   *   tt_driver
   *   pcf_driver
   *   properties
   *   parameter_tags
   *   lcd_rendering
   *
   */

  /**************************************************************************
   *
   * @chapter:
   *   cache_subsystem
   *
   * @title:
   *   Cache Sub-System
   *
   * @sections:
   *   cache_subsystem
   *
   */

  /**************************************************************************
   *
   * @chapter:
   *   support_api
   *
   * @title:
   *   Support API
   *
   * @sections:
   *   computations
   *   list_processing
   *   outline_processing
   *   quick_advance
   *   bitmap_handling
   *   raster
   *   glyph_stroker
   *   system_interface
   *   module_management
   *   gzip
   *   lzw
   *   bzip2
   *
   */

  /**************************************************************************
   *
   * @chapter:
   *   error_codes
   *
   * @title:
   *   Error Codes
   *
   * @sections:
   *   error_enumerations
   *   error_code_values
   *
   */

/* END */


text:
/****************************************************************************
 *
 * ftsynth.h
 *
 *   FreeType synthesizing code for emboldening and slanting
 *   (specification).
 *
 * Copyright (C) 2000-2020 by
 * David Turner, Robert Wilhelm, and Werner Lemberg.
 *
 * This file is part of the FreeType project, and may only be used,
 * modified, and distributed under the terms of the FreeType project
 * license, LICENSE.TXT.  By continuing to use, modify, or distribute
 * this file you indicate that you have read the license and
 * understand and accept it fully.
 *
 */

  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/
  /*********                                                       *********/
  /*********        WARNING, THIS IS ALPHA CODE!  THIS API         *********/
  /*********    IS DUE TO CHANGE UNTIL STRICTLY NOTIFIED BY THE    *********/
  /*********            FREETYPE DEVELOPMENT TEAM                  *********/
  /*********                                                       *********/
  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/

  /* Main reason for not lifting the functions in this module to a  */
  /* 'standard' API is that the used parameters for emboldening and */
  /* slanting are not configurable.  Consider the functions as a    */
  /* code resource that should be copied into the application and   */
  /* adapted to the particular needs.                               */

#ifndef FTSYNTH_H_
#define FTSYNTH_H_

#include <ft2build.h>
#include FT_FREETYPE_H

#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif

FT_BEGIN_HEADER

  /* Embolden a glyph by a 'reasonable' value (which is highly a matter of */
  /* taste).  This function is actually a convenience function, providing  */
  /* a wrapper for @FT_Outline_Embolden and @FT_Bitmap_Embolden.           */
  /*                                                                       */
  /* For emboldened outlines the height, width, and advance metrics are    */
  /* increased by the strength of the emboldening -- this even affects     */
  /* mono-width fonts!                                                     */
  /*                                                                       */
  /* You can also call @FT_Outline_Get_CBox to get precise values.         */
  FT_EXPORT( void )
  FT_GlyphSlot_Embolden( FT_GlyphSlot  slot );

  /* Slant an outline glyph to the right by about 12 degrees. */
  FT_EXPORT( void )
  FT_GlyphSlot_Oblique( FT_GlyphSlot  slot );

  /* */

FT_END_HEADER

#endif /* FTSYNTH_H_ */

/* END */


text:
/****************************************************************************
 *
 * ftgxval.h
 *
 *   FreeType API for validating TrueTypeGX/AAT tables (specification).
 *
 * Copyright (C) 2004-2020 by
 * Masatake YAMATO, Redhat K.K,
 * David Turner, Robert Wilhelm, and Werner Lemberg.
 *
 * This file is part of the FreeType project, and may only be used,
 * modified, and distributed under the terms of the FreeType project
 * license, LICENSE.TXT.  By continuing to use, modify, or distribute
 * this file you indicate that you have read the license and
 * understand and accept it fully.
 *
 */

/****************************************************************************
 *
 * gxvalid is derived from both gxlayout module and otvalid module.
 * Development of gxlayout is supported by the Information-technology
 * Promotion Agency(IPA), Japan.
 *
 */

#ifndef FTGXVAL_H_
#define FTGXVAL_H_

#include <ft2build.h>
#include FT_FREETYPE_H

#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif

FT_BEGIN_HEADER

  /**************************************************************************
   *
   * @section:
   *   gx_validation
   *
   * @title:
   *   TrueTypeGX/AAT Validation
   *
   * @abstract:
   *   An API to validate TrueTypeGX/AAT tables.
   *
   * @description:
   *   This section contains the declaration of functions to validate some
   *   TrueTypeGX tables (feat, mort, morx, bsln, just, kern, opbd, trak,
   *   prop, lcar).
   *
   * @order:
   *   FT_TrueTypeGX_Validate
   *   FT_TrueTypeGX_Free
   *
   *   FT_ClassicKern_Validate
   *   FT_ClassicKern_Free
   *
   *   FT_VALIDATE_GX_LENGTH
   *   FT_VALIDATE_GXXXX
   *   FT_VALIDATE_CKERNXXX
   *
   */

  /**************************************************************************
   *
   *
   * Warning: Use `FT_VALIDATE_XXX` to validate a table.
   *          Following definitions are for gxvalid developers.
   *
   *
   */

#define FT_VALIDATE_feat_INDEX     0
#define FT_VALIDATE_mort_INDEX     1
#define FT_VALIDATE_morx_INDEX     2
#define FT_VALIDATE_bsln_INDEX     3
#define FT_VALIDATE_just_INDEX     4
#define FT_VALIDATE_kern_INDEX     5
#define FT_VALIDATE_opbd_INDEX     6
#define FT_VALIDATE_trak_INDEX     7
#define FT_VALIDATE_prop_INDEX     8
#define FT_VALIDATE_lcar_INDEX     9
#define FT_VALIDATE_GX_LAST_INDEX  FT_VALIDATE_lcar_INDEX

  /**************************************************************************
   *
   * @macro:
   *   FT_VALIDATE_GX_LENGTH
   *
   * @description:
   *   The number of tables checked in this module.  Use it as a parameter
   *   for the `table-length` argument of function @FT_TrueTypeGX_Validate.
   */
#define FT_VALIDATE_GX_LENGTH  ( FT_VALIDATE_GX_LAST_INDEX + 1 )

  /* */

  /* Up to 0x1000 is used by otvalid.
     Ox2xxx is reserved for feature OT extension. */
#define FT_VALIDATE_GX_START  0x4000
#define FT_VALIDATE_GX_BITFIELD( tag ) \
          ( FT_VALIDATE_GX_START << FT_VALIDATE_##tag##_INDEX )

  /**************************************************************************
   *
   * @enum:
   *    FT_VALIDATE_GXXXX
   *
   * @description:
   *    A list of bit-field constants used with @FT_TrueTypeGX_Validate to
   *    indicate which TrueTypeGX/AAT Type tables should be validated.
   *
   * @values:
   *    FT_VALIDATE_feat ::
   *      Validate 'feat' table.
   *
   *    FT_VALIDATE_mort ::
   *      Validate 'mort' table.
   *
   *    FT_VALIDATE_morx ::
   *      Validate 'morx' table.
   *
   *    FT_VALIDATE_bsln ::
   *      Validate 'bsln' table.
   *
   *    FT_VALIDATE_just ::
   *      Validate 'just' table.
   *
   *    FT_VALIDATE_kern ::
   *      Validate 'kern' table.
   *
   *    FT_VALIDATE_opbd ::
   *      Validate 'opbd' table.
   *
   *    FT_VALIDATE_trak ::
   *      Validate 'trak' table.
   *
   *    FT_VALIDATE_prop ::
   *      Validate 'prop' table.
   *
   *    FT_VALIDATE_lcar ::
   *      Validate 'lcar' table.
   *
   *    FT_VALIDATE_GX ::
   *      Validate all TrueTypeGX tables (feat, mort, morx, bsln, just, kern,
   *      opbd, trak, prop and lcar).
   *
   */

#define FT_VALIDATE_feat  FT_VALIDATE_GX_BITFIELD( feat )
#define FT_VALIDATE_mort  FT_VALIDATE_GX_BITFIELD( mort )
#define FT_VALIDATE_morx  FT_VALIDATE_GX_BITFIELD( morx )
#define FT_VALIDATE_bsln  FT_VALIDATE_GX_BITFIELD( bsln )
#define FT_VALIDATE_just  FT_VALIDATE_GX_BITFIELD( just )
#define FT_VALIDATE_kern  FT_VALIDATE_GX_BITFIELD( kern )
#define FT_VALIDATE_opbd  FT_VALIDATE_GX_BITFIELD( opbd )
#define FT_VALIDATE_trak  FT_VALIDATE_GX_BITFIELD( trak )
#define FT_VALIDATE_prop  FT_VALIDATE_GX_BITFIELD( prop )
#define FT_VALIDATE_lcar  FT_VALIDATE_GX_BITFIELD( lcar )

#define FT_VALIDATE_GX  ( FT_VALIDATE_feat | \
                          FT_VALIDATE_mort | \
                          FT_VALIDATE_morx | \
                          FT_VALIDATE_bsln | \
                          FT_VALIDATE_just | \
                          FT_VALIDATE_kern | \
                          FT_VALIDATE_opbd | \
                          FT_VALIDATE_trak | \
                          FT_VALIDATE_prop | \
                          FT_VALIDATE_lcar )

  /**************************************************************************
   *
   * @function:
   *    FT_TrueTypeGX_Validate
   *
   * @description:
   *    Validate various TrueTypeGX tables to assure that all offsets and
   *    indices are valid.  The idea is that a higher-level library that
   *    actually does the text layout can access those tables without error
   *    checking (which can be quite time consuming).
   *
   * @input:
   *    face ::
   *      A handle to the input face.
   *
   *    validation_flags ::
   *      A bit field that specifies the tables to be validated.  See
   *      @FT_VALIDATE_GXXXX for possible values.
   *
   *    table_length ::
   *      The size of the `tables` array.  Normally, @FT_VALIDATE_GX_LENGTH
   *      should be passed.
   *
   * @output:
   *    tables ::
   *      The array where all validated sfnt tables are stored.  The array
   *      itself must be allocated by a client.
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   This function only works with TrueTypeGX fonts, returning an error
   *   otherwise.
   *
   *   After use, the application should deallocate the buffers pointed to by
   *   each `tables` element, by calling @FT_TrueTypeGX_Free.  A `NULL` value
   *   indicates that the table either doesn't exist in the font, the
   *   application hasn't asked for validation, or the validator doesn't have
   *   the ability to validate the sfnt table.
   */
  FT_EXPORT( FT_Error )
  FT_TrueTypeGX_Validate( FT_Face   face,
                          FT_UInt   validation_flags,
                          FT_Bytes  tables[FT_VALIDATE_GX_LENGTH],
                          FT_UInt   table_length );

  /**************************************************************************
   *
   * @function:
   *    FT_TrueTypeGX_Free
   *
   * @description:
   *    Free the buffer allocated by TrueTypeGX validator.
   *
   * @input:
   *    face ::
   *      A handle to the input face.
   *
   *    table ::
   *      The pointer to the buffer allocated by @FT_TrueTypeGX_Validate.
   *
   * @note:
   *   This function must be used to free the buffer allocated by
   *   @FT_TrueTypeGX_Validate only.
   */
  FT_EXPORT( void )
  FT_TrueTypeGX_Free( FT_Face   face,
                      FT_Bytes  table );

  /**************************************************************************
   *
   * @enum:
   *    FT_VALIDATE_CKERNXXX
   *
   * @description:
   *    A list of bit-field constants used with @FT_ClassicKern_Validate to
   *    indicate the classic kern dialect or dialects.  If the selected type
   *    doesn't fit, @FT_ClassicKern_Validate regards the table as invalid.
   *
   * @values:
   *    FT_VALIDATE_MS ::
   *      Handle the 'kern' table as a classic Microsoft kern table.
   *
   *    FT_VALIDATE_APPLE ::
   *      Handle the 'kern' table as a classic Apple kern table.
   *
   *    FT_VALIDATE_CKERN ::
   *      Handle the 'kern' as either classic Apple or Microsoft kern table.
   */
#define FT_VALIDATE_MS     ( FT_VALIDATE_GX_START << 0 )
#define FT_VALIDATE_APPLE  ( FT_VALIDATE_GX_START << 1 )

#define FT_VALIDATE_CKERN  ( FT_VALIDATE_MS | FT_VALIDATE_APPLE )

  /**************************************************************************
   *
   * @function:
   *    FT_ClassicKern_Validate
   *
   * @description:
   *    Validate classic (16-bit format) kern table to assure that the
   *    offsets and indices are valid.  The idea is that a higher-level
   *    library that actually does the text layout can access those tables
   *    without error checking (which can be quite time consuming).
   *
   *    The 'kern' table validator in @FT_TrueTypeGX_Validate deals with both
   *    the new 32-bit format and the classic 16-bit format, while
   *    FT_ClassicKern_Validate only supports the classic 16-bit format.
   *
   * @input:
   *    face ::
   *      A handle to the input face.
   *
   *    validation_flags ::
   *      A bit field that specifies the dialect to be validated.  See
   *      @FT_VALIDATE_CKERNXXX for possible values.
   *
   * @output:
   *    ckern_table ::
   *      A pointer to the kern table.
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   After use, the application should deallocate the buffers pointed to by
   *   `ckern_table`, by calling @FT_ClassicKern_Free.  A `NULL` value
   *   indicates that the table doesn't exist in the font.
   */
  FT_EXPORT( FT_Error )
  FT_ClassicKern_Validate( FT_Face    face,
                           FT_UInt    validation_flags,
                           FT_Bytes  *ckern_table );

  /**************************************************************************
   *
   * @function:
   *    FT_ClassicKern_Free
   *
   * @description:
   *    Free the buffer allocated by classic Kern validator.
   *
   * @input:
   *    face ::
   *      A handle to the input face.
   *
   *    table ::
   *      The pointer to the buffer that is allocated by
   *      @FT_ClassicKern_Validate.
   *
   * @note:
   *   This function must be used to free the buffer allocated by
   *   @FT_ClassicKern_Validate only.
   */
  FT_EXPORT( void )
  FT_ClassicKern_Free( FT_Face   face,
                       FT_Bytes  table );

  /* */

FT_END_HEADER

#endif /* FTGXVAL_H_ */

/* END */


text:
/****************************************************************************
 *
 * ftcache.h
 *
 *   FreeType Cache subsystem (specification).
 *
 * Copyright (C) 1996-2020 by
 * David Turner, Robert Wilhelm, and Werner Lemberg.
 *
 * This file is part of the FreeType project, and may only be used,
 * modified, and distributed under the terms of the FreeType project
 * license, LICENSE.TXT.  By continuing to use, modify, or distribute
 * this file you indicate that you have read the license and
 * understand and accept it fully.
 *
 */

#ifndef FTCACHE_H_
#define FTCACHE_H_

#include <ft2build.h>
#include FT_GLYPH_H

FT_BEGIN_HEADER

  /**************************************************************************
   *
   * @section:
   *   cache_subsystem
   *
   * @title:
   *   Cache Sub-System
   *
   * @abstract:
   *   How to cache face, size, and glyph data with FreeType~2.
   *
   * @description:
   *   This section describes the FreeType~2 cache sub-system, which is used
   *   to limit the number of concurrently opened @FT_Face and @FT_Size
   *   objects, as well as caching information like character maps and glyph
   *   images while limiting their maximum memory usage.
   *
   *   Note that all types and functions begin with the `FTC_` prefix.
   *
   *   The cache is highly portable and thus doesn't know anything about the
   *   fonts installed on your system, or how to access them.  This implies
   *   the following scheme:
   *
   *   First, available or installed font faces are uniquely identified by
   *   @FTC_FaceID values, provided to the cache by the client.  Note that
   *   the cache only stores and compares these values, and doesn't try to
   *   interpret them in any way.
   *
   *   Second, the cache calls, only when needed, a client-provided function
   *   to convert an @FTC_FaceID into a new @FT_Face object.  The latter is
   *   then completely managed by the cache, including its termination
   *   through @FT_Done_Face.  To monitor termination of face objects, the
   *   finalizer callback in the `generic` field of the @FT_Face object can
   *   be used, which might also be used to store the @FTC_FaceID of the
   *   face.
   *
   *   Clients are free to map face IDs to anything else.  The most simple
   *   usage is to associate them to a (pathname,face_index) pair that is
   *   used to call @FT_New_Face.  However, more complex schemes are also
   *   possible.
   *
   *   Note that for the cache to work correctly, the face ID values must be
   *   **persistent**, which means that the contents they point to should not
   *   change at runtime, or that their value should not become invalid.
   *
   *   If this is unavoidable (e.g., when a font is uninstalled at runtime),
   *   you should call @FTC_Manager_RemoveFaceID as soon as possible, to let
   *   the cache get rid of any references to the old @FTC_FaceID it may keep
   *   internally.  Failure to do so will lead to incorrect behaviour or even
   *   crashes.
   *
   *   To use the cache, start with calling @FTC_Manager_New to create a new
   *   @FTC_Manager object, which models a single cache instance.  You can
   *   then look up @FT_Face and @FT_Size objects with
   *   @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively.
   *
   *   If you want to use the charmap caching, call @FTC_CMapCache_New, then
   *   later use @FTC_CMapCache_Lookup to perform the equivalent of
   *   @FT_Get_Char_Index, only much faster.
   *
   *   If you want to use the @FT_Glyph caching, call @FTC_ImageCache, then
   *   later use @FTC_ImageCache_Lookup to retrieve the corresponding
   *   @FT_Glyph objects from the cache.
   *
   *   If you need lots of small bitmaps, it is much more memory efficient to
   *   call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup.  This
   *   returns @FTC_SBitRec structures, which are used to store small bitmaps
   *   directly.  (A small bitmap is one whose metrics and dimensions all fit
   *   into 8-bit integers).
   *
   *   We hope to also provide a kerning cache in the near future.
   *
   *
   * @order:
   *   FTC_Manager
   *   FTC_FaceID
   *   FTC_Face_Requester
   *
   *   FTC_Manager_New
   *   FTC_Manager_Reset
   *   FTC_Manager_Done
   *   FTC_Manager_LookupFace
   *   FTC_Manager_LookupSize
   *   FTC_Manager_RemoveFaceID
   *
   *   FTC_Node
   *   FTC_Node_Unref
   *
   *   FTC_ImageCache
   *   FTC_ImageCache_New
   *   FTC_ImageCache_Lookup
   *
   *   FTC_SBit
   *   FTC_SBitCache
   *   FTC_SBitCache_New
   *   FTC_SBitCache_Lookup
   *
   *   FTC_CMapCache
   *   FTC_CMapCache_New
   *   FTC_CMapCache_Lookup
   *
   *************************************************************************/

  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/
  /*****                                                               *****/
  /*****                    BASIC TYPE DEFINITIONS                     *****/
  /*****                                                               *****/
  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/

  /**************************************************************************
   *
   * @type:
   *   FTC_FaceID
   *
   * @description:
   *   An opaque pointer type that is used to identity face objects.  The
   *   contents of such objects is application-dependent.
   *
   *   These pointers are typically used to point to a user-defined structure
   *   containing a font file path, and face index.
   *
   * @note:
   *   Never use `NULL` as a valid @FTC_FaceID.
   *
   *   Face IDs are passed by the client to the cache manager that calls,
   *   when needed, the @FTC_Face_Requester to translate them into new
   *   @FT_Face objects.
   *
   *   If the content of a given face ID changes at runtime, or if the value
   *   becomes invalid (e.g., when uninstalling a font), you should
   *   immediately call @FTC_Manager_RemoveFaceID before any other cache
   *   function.
   *
   *   Failure to do so will result in incorrect behaviour or even memory
   *   leaks and crashes.
   */
  typedef FT_Pointer  FTC_FaceID;

  /**************************************************************************
   *
   * @functype:
   *   FTC_Face_Requester
   *
   * @description:
   *   A callback function provided by client applications.  It is used by
   *   the cache manager to translate a given @FTC_FaceID into a new valid
   *   @FT_Face object, on demand.
   *
   * @input:
   *   face_id ::
   *     The face ID to resolve.
   *
   *   library ::
   *     A handle to a FreeType library object.
   *
   *   req_data ::
   *     Application-provided request data (see note below).
   *
   * @output:
   *   aface ::
   *     A new @FT_Face handle.
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The third parameter `req_data` is the same as the one passed by the
   *   client when @FTC_Manager_New is called.
   *
   *   The face requester should not perform funny things on the returned
   *   face object, like creating a new @FT_Size for it, or setting a
   *   transformation through @FT_Set_Transform!
   */
  typedef FT_Error
  (*FTC_Face_Requester)( FTC_FaceID  face_id,
                         FT_Library  library,
                         FT_Pointer  req_data,
                         FT_Face*    aface );

  /* */

  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/
  /*****                                                               *****/
  /*****                      CACHE MANAGER OBJECT                     *****/
  /*****                                                               *****/
  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/

  /**************************************************************************
   *
   * @type:
   *   FTC_Manager
   *
   * @description:
   *   This object corresponds to one instance of the cache-subsystem.  It is
   *   used to cache one or more @FT_Face objects, along with corresponding
   *   @FT_Size objects.
   *
   *   The manager intentionally limits the total number of opened @FT_Face
   *   and @FT_Size objects to control memory usage.  See the `max_faces` and
   *   `max_sizes` parameters of @FTC_Manager_New.
   *
   *   The manager is also used to cache 'nodes' of various types while
   *   limiting their total memory usage.
   *
   *   All limitations are enforced by keeping lists of managed objects in
   *   most-recently-used order, and flushing old nodes to make room for new
   *   ones.
   */
  typedef struct FTC_ManagerRec_*  FTC_Manager;

  /**************************************************************************
   *
   * @type:
   *   FTC_Node
   *
   * @description:
   *   An opaque handle to a cache node object.  Each cache node is
   *   reference-counted.  A node with a count of~0 might be flushed out of a
   *   full cache whenever a lookup request is performed.
   *
   *   If you look up nodes, you have the ability to 'acquire' them, i.e., to
   *   increment their reference count.  This will prevent the node from
   *   being flushed out of the cache until you explicitly 'release' it (see
   *   @FTC_Node_Unref).
   *
   *   See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup.
   */
  typedef struct FTC_NodeRec_*  FTC_Node;

  /**************************************************************************
   *
   * @function:
   *   FTC_Manager_New
   *
   * @description:
   *   Create a new cache manager.
   *
   * @input:
   *   library ::
   *     The parent FreeType library handle to use.
   *
   *   max_faces ::
   *     Maximum number of opened @FT_Face objects managed by this cache
   *     instance.  Use~0 for defaults.
   *
   *   max_sizes ::
   *     Maximum number of opened @FT_Size objects managed by this cache
   *     instance.  Use~0 for defaults.
   *
   *   max_bytes ::
   *     Maximum number of bytes to use for cached data nodes.  Use~0 for
   *     defaults.  Note that this value does not account for managed
   *     @FT_Face and @FT_Size objects.
   *
   *   requester ::
   *     An application-provided callback used to translate face IDs into
   *     real @FT_Face objects.
   *
   *   req_data ::
   *     A generic pointer that is passed to the requester each time it is
   *     called (see @FTC_Face_Requester).
   *
   * @output:
   *   amanager ::
   *     A handle to a new manager object.  0~in case of failure.
   *
   * @return:
   *   FreeType error code.  0~means success.
   */
  FT_EXPORT( FT_Error )
  FTC_Manager_New( FT_Library          library,
                   FT_UInt             max_faces,
                   FT_UInt             max_sizes,
                   FT_ULong            max_bytes,
                   FTC_Face_Requester  requester,
                   FT_Pointer          req_data,
                   FTC_Manager        *amanager );

  /**************************************************************************
   *
   * @function:
   *   FTC_Manager_Reset
   *
   * @description:
   *   Empty a given cache manager.  This simply gets rid of all the
   *   currently cached @FT_Face and @FT_Size objects within the manager.
   *
   * @inout:
   *   manager ::
   *     A handle to the manager.
   */
  FT_EXPORT( void )
  FTC_Manager_Reset( FTC_Manager  manager );

  /**************************************************************************
   *
   * @function:
   *   FTC_Manager_Done
   *
   * @description:
   *   Destroy a given manager after emptying it.
   *
   * @input:
   *   manager ::
   *     A handle to the target cache manager object.
   */
  FT_EXPORT( void )
  FTC_Manager_Done( FTC_Manager  manager );

  /**************************************************************************
   *
   * @function:
   *   FTC_Manager_LookupFace
   *
   * @description:
   *   Retrieve the @FT_Face object that corresponds to a given face ID
   *   through a cache manager.
   *
   * @input:
   *   manager ::
   *     A handle to the cache manager.
   *
   *   face_id ::
   *     The ID of the face object.
   *
   * @output:
   *   aface ::
   *     A handle to the face object.
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The returned @FT_Face object is always owned by the manager.  You
   *   should never try to discard it yourself.
   *
   *   The @FT_Face object doesn't necessarily have a current size object
   *   (i.e., face->size can be~0).  If you need a specific 'font size', use
   *   @FTC_Manager_LookupSize instead.
   *
   *   Never change the face's transformation matrix (i.e., never call the
   *   @FT_Set_Transform function) on a returned face!  If you need to
   *   transform glyphs, do it yourself after glyph loading.
   *
   *   When you perform a lookup, out-of-memory errors are detected _within_
   *   the lookup and force incremental flushes of the cache until enough
   *   memory is released for the lookup to succeed.
   *
   *   If a lookup fails with `FT_Err_Out_Of_Memory` the cache has already
   *   been completely flushed, and still no memory was available for the
   *   operation.
   */
  FT_EXPORT( FT_Error )
  FTC_Manager_LookupFace( FTC_Manager  manager,
                          FTC_FaceID   face_id,
                          FT_Face     *aface );

  /**************************************************************************
   *
   * @struct:
   *   FTC_ScalerRec
   *
   * @description:
   *   A structure used to describe a given character size in either pixels
   *   or points to the cache manager.  See @FTC_Manager_LookupSize.
   *
   * @fields:
   *   face_id ::
   *     The source face ID.
   *
   *   width ::
   *     The character width.
   *
   *   height ::
   *     The character height.
   *
   *   pixel ::
   *     A Boolean.  If 1, the `width` and `height` fields are interpreted as
   *     integer pixel character sizes.  Otherwise, they are expressed as
   *     1/64th of points.
   *
   *   x_res ::
   *     Only used when `pixel` is value~0 to indicate the horizontal
   *     resolution in dpi.
   *
   *   y_res ::
   *     Only used when `pixel` is value~0 to indicate the vertical
   *     resolution in dpi.
   *
   * @note:
   *   This type is mainly used to retrieve @FT_Size objects through the
   *   cache manager.
   */
  typedef struct  FTC_ScalerRec_
  {
    FTC_FaceID  face_id;
    FT_UInt     width;
    FT_UInt     height;
    FT_Int      pixel;
    FT_UInt     x_res;
    FT_UInt     y_res;

  } FTC_ScalerRec;

  /**************************************************************************
   *
   * @struct:
   *   FTC_Scaler
   *
   * @description:
   *   A handle to an @FTC_ScalerRec structure.
   */
  typedef struct FTC_ScalerRec_*  FTC_Scaler;

  /**************************************************************************
   *
   * @function:
   *   FTC_Manager_LookupSize
   *
   * @description:
   *   Retrieve the @FT_Size object that corresponds to a given
   *   @FTC_ScalerRec pointer through a cache manager.
   *
   * @input:
   *   manager ::
   *     A handle to the cache manager.
   *
   *   scaler ::
   *     A scaler handle.
   *
   * @output:
   *   asize ::
   *     A handle to the size object.
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The returned @FT_Size object is always owned by the manager.  You
   *   should never try to discard it by yourself.
   *
   *   You can access the parent @FT_Face object simply as `size->face` if
   *   you need it.  Note that this object is also owned by the manager.
   *
   * @note:
   *   When you perform a lookup, out-of-memory errors are detected _within_
   *   the lookup and force incremental flushes of the cache until enough
   *   memory is released for the lookup to succeed.
   *
   *   If a lookup fails with `FT_Err_Out_Of_Memory` the cache has already
   *   been completely flushed, and still no memory is available for the
   *   operation.
   */
  FT_EXPORT( FT_Error )
  FTC_Manager_LookupSize( FTC_Manager  manager,
                          FTC_Scaler   scaler,
                          FT_Size     *asize );

  /**************************************************************************
   *
   * @function:
   *   FTC_Node_Unref
   *
   * @description:
   *   Decrement a cache node's internal reference count.  When the count
   *   reaches 0, it is not destroyed but becomes eligible for subsequent
   *   cache flushes.
   *
   * @input:
   *   node ::
   *     The cache node handle.
   *
   *   manager ::
   *     The cache manager handle.
   */
  FT_EXPORT( void )
  FTC_Node_Unref( FTC_Node     node,
                  FTC_Manager  manager );

  /**************************************************************************
   *
   * @function:
   *   FTC_Manager_RemoveFaceID
   *
   * @description:
   *   A special function used to indicate to the cache manager that a given
   *   @FTC_FaceID is no longer valid, either because its content changed, or
   *   because it was deallocated or uninstalled.
   *
   * @input:
   *   manager ::
   *     The cache manager handle.
   *
   *   face_id ::
   *     The @FTC_FaceID to be removed.
   *
   * @note:
   *   This function flushes all nodes from the cache corresponding to this
   *   `face_id`, with the exception of nodes with a non-null reference
   *   count.
   *
   *   Such nodes are however modified internally so as to never appear in
   *   later lookups with the same `face_id` value, and to be immediately
   *   destroyed when released by all their users.
   *
   */
  FT_EXPORT( void )
  FTC_Manager_RemoveFaceID( FTC_Manager  manager,
                            FTC_FaceID   face_id );

  /**************************************************************************
   *
   * @type:
   *   FTC_CMapCache
   *
   * @description:
   *   An opaque handle used to model a charmap cache.  This cache is to hold
   *   character codes -> glyph indices mappings.
   *
   */
  typedef struct FTC_CMapCacheRec_*  FTC_CMapCache;

  /**************************************************************************
   *
   * @function:
   *   FTC_CMapCache_New
   *
   * @description:
   *   Create a new charmap cache.
   *
   * @input:
   *   manager ::
   *     A handle to the cache manager.
   *
   * @output:
   *   acache ::
   *     A new cache handle.  `NULL` in case of error.
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   Like all other caches, this one will be destroyed with the cache
   *   manager.
   *
   */
  FT_EXPORT( FT_Error )
  FTC_CMapCache_New( FTC_Manager     manager,
                     FTC_CMapCache  *acache );

  /**************************************************************************
   *
   * @function:
   *   FTC_CMapCache_Lookup
   *
   * @description:
   *   Translate a character code into a glyph index, using the charmap
   *   cache.
   *
   * @input:
   *   cache ::
   *     A charmap cache handle.
   *
   *   face_id ::
   *     The source face ID.
   *
   *   cmap_index ::
   *     The index of the charmap in the source face.  Any negative value
   *     means to use the cache @FT_Face's default charmap.
   *
   *   char_code ::
   *     The character code (in the corresponding charmap).
   *
   * @return:
   *    Glyph index.  0~means 'no glyph'.
   *
   */
  FT_EXPORT( FT_UInt )
  FTC_CMapCache_Lookup( FTC_CMapCache  cache,
                        FTC_FaceID     face_id,
                        FT_Int         cmap_index,
                        FT_UInt32      char_code );

  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/
  /*****                                                               *****/
  /*****                       IMAGE CACHE OBJECT                      *****/
  /*****                                                               *****/
  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/

  /**************************************************************************
   *
   * @struct:
   *   FTC_ImageTypeRec
   *
   * @description:
   *   A structure used to model the type of images in a glyph cache.
   *
   * @fields:
   *   face_id ::
   *     The face ID.
   *
   *   width ::
   *     The width in pixels.
   *
   *   height ::
   *     The height in pixels.
   *
   *   flags ::
   *     The load flags, as in @FT_Load_Glyph.
   *
   */
  typedef struct  FTC_ImageTypeRec_
  {
    FTC_FaceID  face_id;
    FT_UInt     width;
    FT_UInt     height;
    FT_Int32    flags;

  } FTC_ImageTypeRec;

  /**************************************************************************
   *
   * @type:
   *   FTC_ImageType
   *
   * @description:
   *   A handle to an @FTC_ImageTypeRec structure.
   *
   */
  typedef struct FTC_ImageTypeRec_*  FTC_ImageType;

  /* */

#define FTC_IMAGE_TYPE_COMPARE( d1, d2 )      \
          ( (d1)->face_id == (d2)->face_id && \
            (d1)->width   == (d2)->width   && \
            (d1)->flags   == (d2)->flags   )

  /**************************************************************************
   *
   * @type:
   *   FTC_ImageCache
   *
   * @description:
   *   A handle to a glyph image cache object.  They are designed to hold
   *   many distinct glyph images while not exceeding a certain memory
   *   threshold.
   */
  typedef struct FTC_ImageCacheRec_*  FTC_ImageCache;

  /**************************************************************************
   *
   * @function:
   *   FTC_ImageCache_New
   *
   * @description:
   *   Create a new glyph image cache.
   *
   * @input:
   *   manager ::
   *     The parent manager for the image cache.
   *
   * @output:
   *   acache ::
   *     A handle to the new glyph image cache object.
   *
   * @return:
   *   FreeType error code.  0~means success.
   */
  FT_EXPORT( FT_Error )
  FTC_ImageCache_New( FTC_Manager      manager,
                      FTC_ImageCache  *acache );

  /**************************************************************************
   *
   * @function:
   *   FTC_ImageCache_Lookup
   *
   * @description:
   *   Retrieve a given glyph image from a glyph image cache.
   *
   * @input:
   *   cache ::
   *     A handle to the source glyph image cache.
   *
   *   type ::
   *     A pointer to a glyph image type descriptor.
   *
   *   gindex ::
   *     The glyph index to retrieve.
   *
   * @output:
   *   aglyph ::
   *     The corresponding @FT_Glyph object.  0~in case of failure.
   *
   *   anode ::
   *     Used to return the address of the corresponding cache node after
   *     incrementing its reference count (see note below).
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The returned glyph is owned and managed by the glyph image cache.
   *   Never try to transform or discard it manually!  You can however create
   *   a copy with @FT_Glyph_Copy and modify the new one.
   *
   *   If `anode` is _not_ `NULL`, it receives the address of the cache node
   *   containing the glyph image, after increasing its reference count.
   *   This ensures that the node (as well as the @FT_Glyph) will always be
   *   kept in the cache until you call @FTC_Node_Unref to 'release' it.
   *
   *   If `anode` is `NULL`, the cache node is left unchanged, which means
   *   that the @FT_Glyph could be flushed out of the cache on the next call
   *   to one of the caching sub-system APIs.  Don't assume that it is
   *   persistent!
   */
  FT_EXPORT( FT_Error )
  FTC_ImageCache_Lookup( FTC_ImageCache  cache,
                         FTC_ImageType   type,
                         FT_UInt         gindex,
                         FT_Glyph       *aglyph,
                         FTC_Node       *anode );

  /**************************************************************************
   *
   * @function:
   *   FTC_ImageCache_LookupScaler
   *
   * @description:
   *   A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec to
   *   specify the face ID and its size.
   *
   * @input:
   *   cache ::
   *     A handle to the source glyph image cache.
   *
   *   scaler ::
   *     A pointer to a scaler descriptor.
   *
   *   load_flags ::
   *     The corresponding load flags.
   *
   *   gindex ::
   *     The glyph index to retrieve.
   *
   * @output:
   *   aglyph ::
   *     The corresponding @FT_Glyph object.  0~in case of failure.
   *
   *   anode ::
   *     Used to return the address of the corresponding cache node after
   *     incrementing its reference count (see note below).
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The returned glyph is owned and managed by the glyph image cache.
   *   Never try to transform or discard it manually!  You can however create
   *   a copy with @FT_Glyph_Copy and modify the new one.
   *
   *   If `anode` is _not_ `NULL`, it receives the address of the cache node
   *   containing the glyph image, after increasing its reference count.
   *   This ensures that the node (as well as the @FT_Glyph) will always be
   *   kept in the cache until you call @FTC_Node_Unref to 'release' it.
   *
   *   If `anode` is `NULL`, the cache node is left unchanged, which means
   *   that the @FT_Glyph could be flushed out of the cache on the next call
   *   to one of the caching sub-system APIs.  Don't assume that it is
   *   persistent!
   *
   *   Calls to @FT_Set_Char_Size and friends have no effect on cached
   *   glyphs; you should always use the FreeType cache API instead.
   */
  FT_EXPORT( FT_Error )
  FTC_ImageCache_LookupScaler( FTC_ImageCache  cache,
                               FTC_Scaler      scaler,
                               FT_ULong        load_flags,
                               FT_UInt         gindex,
                               FT_Glyph       *aglyph,
                               FTC_Node       *anode );

  /**************************************************************************
   *
   * @type:
   *   FTC_SBit
   *
   * @description:
   *   A handle to a small bitmap descriptor.  See the @FTC_SBitRec structure
   *   for details.
   */
  typedef struct FTC_SBitRec_*  FTC_SBit;

  /**************************************************************************
   *
   * @struct:
   *   FTC_SBitRec
   *
   * @description:
   *   A very compact structure used to describe a small glyph bitmap.
   *
   * @fields:
   *   width ::
   *     The bitmap width in pixels.
   *
   *   height ::
   *     The bitmap height in pixels.
   *
   *   left ::
   *     The horizontal distance from the pen position to the left bitmap
   *     border (a.k.a. 'left side bearing', or 'lsb').
   *
   *   top ::
   *     The vertical distance from the pen position (on the baseline) to the
   *     upper bitmap border (a.k.a. 'top side bearing').  The distance is
   *     positive for upwards y~coordinates.
   *
   *   format ::
   *     The format of the glyph bitmap (monochrome or gray).
   *
   *   max_grays ::
   *     Maximum gray level value (in the range 1 to~255).
   *
   *   pitch ::
   *     The number of bytes per bitmap line.  May be positive or negative.
   *
   *   xadvance ::
   *     The horizontal advance width in pixels.
   *
   *   yadvance ::
   *     The vertical advance height in pixels.
   *
   *   buffer ::
   *     A pointer to the bitmap pixels.
   */
  typedef struct  FTC_SBitRec_
  {
    FT_Byte   width;
    FT_Byte   height;
    FT_Char   left;
    FT_Char   top;

    FT_Byte   format;
    FT_Byte   max_grays;
    FT_Short  pitch;
    FT_Char   xadvance;
    FT_Char   yadvance;

    FT_Byte*  buffer;

  } FTC_SBitRec;

  /**************************************************************************
   *
   * @type:
   *   FTC_SBitCache
   *
   * @description:
   *   A handle to a small bitmap cache.  These are special cache objects
   *   used to store small glyph bitmaps (and anti-aliased pixmaps) in a much
   *   more efficient way than the traditional glyph image cache implemented
   *   by @FTC_ImageCache.
   */
  typedef struct FTC_SBitCacheRec_*  FTC_SBitCache;

  /**************************************************************************
   *
   * @function:
   *   FTC_SBitCache_New
   *
   * @description:
   *   Create a new cache to store small glyph bitmaps.
   *
   * @input:
   *   manager ::
   *     A handle to the source cache manager.
   *
   * @output:
   *   acache ::
   *     A handle to the new sbit cache.  `NULL` in case of error.
   *
   * @return:
   *   FreeType error code.  0~means success.
   */
  FT_EXPORT( FT_Error )
  FTC_SBitCache_New( FTC_Manager     manager,
                     FTC_SBitCache  *acache );

  /**************************************************************************
   *
   * @function:
   *   FTC_SBitCache_Lookup
   *
   * @description:
   *   Look up a given small glyph bitmap in a given sbit cache and 'lock' it
   *   to prevent its flushing from the cache until needed.
   *
   * @input:
   *   cache ::
   *     A handle to the source sbit cache.
   *
   *   type ::
   *     A pointer to the glyph image type descriptor.
   *
   *   gindex ::
   *     The glyph index.
   *
   * @output:
   *   sbit ::
   *     A handle to a small bitmap descriptor.
   *
   *   anode ::
   *     Used to return the address of the corresponding cache node after
   *     incrementing its reference count (see note below).
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The small bitmap descriptor and its bit buffer are owned by the cache
   *   and should never be freed by the application.  They might as well
   *   disappear from memory on the next cache lookup, so don't treat them as
   *   persistent data.
   *
   *   The descriptor's `buffer` field is set to~0 to indicate a missing
   *   glyph bitmap.
   *
   *   If `anode` is _not_ `NULL`, it receives the address of the cache node
   *   containing the bitmap, after increasing its reference count.  This
   *   ensures that the node (as well as the image) will always be kept in
   *   the cache until you call @FTC_Node_Unref to 'release' it.
   *
   *   If `anode` is `NULL`, the cache node is left unchanged, which means
   *   that the bitmap could be flushed out of the cache on the next call to
   *   one of the caching sub-system APIs.  Don't assume that it is
   *   persistent!
   */
  FT_EXPORT( FT_Error )
  FTC_SBitCache_Lookup( FTC_SBitCache    cache,
                        FTC_ImageType    type,
                        FT_UInt          gindex,
                        FTC_SBit        *sbit,
                        FTC_Node        *anode );

  /**************************************************************************
   *
   * @function:
   *   FTC_SBitCache_LookupScaler
   *
   * @description:
   *   A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec to
   *   specify the face ID and its size.
   *
   * @input:
   *   cache ::
   *     A handle to the source sbit cache.
   *
   *   scaler ::
   *     A pointer to the scaler descriptor.
   *
   *   load_flags ::
   *     The corresponding load flags.
   *
   *   gindex ::
   *     The glyph index.
   *
   * @output:
   *   sbit ::
   *     A handle to a small bitmap descriptor.
   *
   *   anode ::
   *     Used to return the address of the corresponding cache node after
   *     incrementing its reference count (see note below).
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The small bitmap descriptor and its bit buffer are owned by the cache
   *   and should never be freed by the application.  They might as well
   *   disappear from memory on the next cache lookup, so don't treat them as
   *   persistent data.
   *
   *   The descriptor's `buffer` field is set to~0 to indicate a missing
   *   glyph bitmap.
   *
   *   If `anode` is _not_ `NULL`, it receives the address of the cache node
   *   containing the bitmap, after increasing its reference count.  This
   *   ensures that the node (as well as the image) will always be kept in
   *   the cache until you call @FTC_Node_Unref to 'release' it.
   *
   *   If `anode` is `NULL`, the cache node is left unchanged, which means
   *   that the bitmap could be flushed out of the cache on the next call to
   *   one of the caching sub-system APIs.  Don't assume that it is
   *   persistent!
   */
  FT_EXPORT( FT_Error )
  FTC_SBitCache_LookupScaler( FTC_SBitCache  cache,
                              FTC_Scaler     scaler,
                              FT_ULong       load_flags,
                              FT_UInt        gindex,
                              FTC_SBit      *sbit,
                              FTC_Node      *anode );

  /* */

FT_END_HEADER

#endif /* FTCACHE_H_ */

/* END */


text:
/****************************************************************************
 *
 * tttables.h
 *
 *   Basic SFNT/TrueType tables definitions and interface
 *   (specification only).
 *
 * Copyright (C) 1996-2020 by
 * David Turner, Robert Wilhelm, and Werner Lemberg.
 *
 * This file is part of the FreeType project, and may only be used,
 * modified, and distributed under the terms of the FreeType project
 * license, LICENSE.TXT.  By continuing to use, modify, or distribute
 * this file you indicate that you have read the license and
 * understand and accept it fully.
 *
 */

#ifndef TTTABLES_H_
#define TTTABLES_H_

#include <ft2build.h>
#include FT_FREETYPE_H

#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif

FT_BEGIN_HEADER

  /**************************************************************************
   *
   * @section:
   *   truetype_tables
   *
   * @title:
   *   TrueType Tables
   *
   * @abstract:
   *   TrueType-specific table types and functions.
   *
   * @description:
   *   This section contains definitions of some basic tables specific to
   *   TrueType and OpenType as well as some routines used to access and
   *   process them.
   *
   * @order:
   *   TT_Header
   *   TT_HoriHeader
   *   TT_VertHeader
   *   TT_OS2
   *   TT_Postscript
   *   TT_PCLT
   *   TT_MaxProfile
   *
   *   FT_Sfnt_Tag
   *   FT_Get_Sfnt_Table
   *   FT_Load_Sfnt_Table
   *   FT_Sfnt_Table_Info
   *
   *   FT_Get_CMap_Language_ID
   *   FT_Get_CMap_Format
   *
   *   FT_PARAM_TAG_UNPATENTED_HINTING
   *
   */

  /**************************************************************************
   *
   * @struct:
   *   TT_Header
   *
   * @description:
   *   A structure to model a TrueType font header table.  All fields follow
   *   the OpenType specification.  The 64-bit timestamps are stored in
   *   two-element arrays `Created` and `Modified`, first the upper then
   *   the lower 32~bits.
   */
  typedef struct  TT_Header_
  {
    FT_Fixed   Table_Version;
    FT_Fixed   Font_Revision;

    FT_Long    CheckSum_Adjust;
    FT_Long    Magic_Number;

    FT_UShort  Flags;
    FT_UShort  Units_Per_EM;

    FT_ULong   Created [2];
    FT_ULong   Modified[2];

    FT_Short   xMin;
    FT_Short   yMin;
    FT_Short   xMax;
    FT_Short   yMax;

    FT_UShort  Mac_Style;
    FT_UShort  Lowest_Rec_PPEM;

    FT_Short   Font_Direction;
    FT_Short   Index_To_Loc_Format;
    FT_Short   Glyph_Data_Format;

  } TT_Header;

  /**************************************************************************
   *
   * @struct:
   *   TT_HoriHeader
   *
   * @description:
   *   A structure to model a TrueType horizontal header, the 'hhea' table,
   *   as well as the corresponding horizontal metrics table, 'hmtx'.
   *
   * @fields:
   *   Version ::
   *     The table version.
   *
   *   Ascender ::
   *     The font's ascender, i.e., the distance from the baseline to the
   *     top-most of all glyph points found in the font.
   *
   *     This value is invalid in many fonts, as it is usually set by the
   *     font designer, and often reflects only a portion of the glyphs found
   *     in the font (maybe ASCII).
   *
   *     You should use the `sTypoAscender` field of the 'OS/2' table instead
   *     if you want the correct one.
   *
   *   Descender ::
   *     The font's descender, i.e., the distance from the baseline to the
   *     bottom-most of all glyph points found in the font.  It is negative.
   *
   *     This value is invalid in many fonts, as it is usually set by the
   *     font designer, and often reflects only a portion of the glyphs found
   *     in the font (maybe ASCII).
   *
   *     You should use the `sTypoDescender` field of the 'OS/2' table
   *     instead if you want the correct one.
   *
   *   Line_Gap ::
   *     The font's line gap, i.e., the distance to add to the ascender and
   *     descender to get the BTB, i.e., the baseline-to-baseline distance
   *     for the font.
   *
   *   advance_Width_Max ::
   *     This field is the maximum of all advance widths found in the font.
   *     It can be used to compute the maximum width of an arbitrary string
   *     of text.
   *
   *   min_Left_Side_Bearing ::
   *     The minimum left side bearing of all glyphs within the font.
   *
   *   min_Right_Side_Bearing ::
   *     The minimum right side bearing of all glyphs within the font.
   *
   *   xMax_Extent ::
   *     The maximum horizontal extent (i.e., the 'width' of a glyph's
   *     bounding box) for all glyphs in the font.
   *
   *   caret_Slope_Rise ::
   *     The rise coefficient of the cursor's slope of the cursor
   *     (slope=rise/run).
   *
   *   caret_Slope_Run ::
   *     The run coefficient of the cursor's slope.
   *
   *   caret_Offset ::
   *     The cursor's offset for slanted fonts.
   *
   *   Reserved ::
   *     8~reserved bytes.
   *
   *   metric_Data_Format ::
   *     Always~0.
   *
   *   number_Of_HMetrics ::
   *     Number of HMetrics entries in the 'hmtx' table -- this value can be
   *     smaller than the total number of glyphs in the font.
   *
   *   long_metrics ::
   *     A pointer into the 'hmtx' table.
   *
   *   short_metrics ::
   *     A pointer into the 'hmtx' table.
   *
   * @note:
   *   For an OpenType variation font, the values of the following fields can
   *   change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
   *   the font contains an 'MVAR' table: `caret_Slope_Rise`,
   *   `caret_Slope_Run`, and `caret_Offset`.
   */
  typedef struct  TT_HoriHeader_
  {
    FT_Fixed   Version;
    FT_Short   Ascender;
    FT_Short   Descender;
    FT_Short   Line_Gap;

    FT_UShort  advance_Width_Max;      /* advance width maximum */

    FT_Short   min_Left_Side_Bearing;  /* minimum left-sb       */
    FT_Short   min_Right_Side_Bearing; /* minimum right-sb      */
    FT_Short   xMax_Extent;            /* xmax extents          */
    FT_Short   caret_Slope_Rise;
    FT_Short   caret_Slope_Run;
    FT_Short   caret_Offset;

    FT_Short   Reserved[4];

    FT_Short   metric_Data_Format;
    FT_UShort  number_Of_HMetrics;

    /* The following fields are not defined by the OpenType specification */
    /* but they are used to connect the metrics header to the relevant    */
    /* 'hmtx' table.                                                      */

    void*      long_metrics;
    void*      short_metrics;

  } TT_HoriHeader;

  /**************************************************************************
   *
   * @struct:
   *   TT_VertHeader
   *
   * @description:
   *   A structure used to model a TrueType vertical header, the 'vhea'
   *   table, as well as the corresponding vertical metrics table, 'vmtx'.
   *
   * @fields:
   *   Version ::
   *     The table version.
   *
   *   Ascender ::
   *     The font's ascender, i.e., the distance from the baseline to the
   *     top-most of all glyph points found in the font.
   *
   *     This value is invalid in many fonts, as it is usually set by the
   *     font designer, and often reflects only a portion of the glyphs found
   *     in the font (maybe ASCII).
   *
   *     You should use the `sTypoAscender` field of the 'OS/2' table instead
   *     if you want the correct one.
   *
   *   Descender ::
   *     The font's descender, i.e., the distance from the baseline to the
   *     bottom-most of all glyph points found in the font.  It is negative.
   *
   *     This value is invalid in many fonts, as it is usually set by the
   *     font designer, and often reflects only a portion of the glyphs found
   *     in the font (maybe ASCII).
   *
   *     You should use the `sTypoDescender` field of the 'OS/2' table
   *     instead if you want the correct one.
   *
   *   Line_Gap ::
   *     The font's line gap, i.e., the distance to add to the ascender and
   *     descender to get the BTB, i.e., the baseline-to-baseline distance
   *     for the font.
   *
   *   advance_Height_Max ::
   *     This field is the maximum of all advance heights found in the font.
   *     It can be used to compute the maximum height of an arbitrary string
   *     of text.
   *
   *   min_Top_Side_Bearing ::
   *     The minimum top side bearing of all glyphs within the font.
   *
   *   min_Bottom_Side_Bearing ::
   *     The minimum bottom side bearing of all glyphs within the font.
   *
   *   yMax_Extent ::
   *     The maximum vertical extent (i.e., the 'height' of a glyph's
   *     bounding box) for all glyphs in the font.
   *
   *   caret_Slope_Rise ::
   *     The rise coefficient of the cursor's slope of the cursor
   *     (slope=rise/run).
   *
   *   caret_Slope_Run ::
   *     The run coefficient of the cursor's slope.
   *
   *   caret_Offset ::
   *     The cursor's offset for slanted fonts.
   *
   *   Reserved ::
   *     8~reserved bytes.
   *
   *   metric_Data_Format ::
   *     Always~0.
   *
   *   number_Of_VMetrics ::
   *     Number of VMetrics entries in the 'vmtx' table -- this value can be
   *     smaller than the total number of glyphs in the font.
   *
   *   long_metrics ::
   *     A pointer into the 'vmtx' table.
   *
   *   short_metrics ::
   *     A pointer into the 'vmtx' table.
   *
   * @note:
   *   For an OpenType variation font, the values of the following fields can
   *   change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
   *   the font contains an 'MVAR' table: `Ascender`, `Descender`,
   *   `Line_Gap`, `caret_Slope_Rise`, `caret_Slope_Run`, and `caret_Offset`.
   */
  typedef struct  TT_VertHeader_
  {
    FT_Fixed   Version;
    FT_Short   Ascender;
    FT_Short   Descender;
    FT_Short   Line_Gap;

    FT_UShort  advance_Height_Max;      /* advance height maximum */

    FT_Short   min_Top_Side_Bearing;    /* minimum top-sb          */
    FT_Short   min_Bottom_Side_Bearing; /* minimum bottom-sb       */
    FT_Short   yMax_Extent;             /* ymax extents            */
    FT_Short   caret_Slope_Rise;
    FT_Short   caret_Slope_Run;
    FT_Short   caret_Offset;

    FT_Short   Reserved[4];

    FT_Short   metric_Data_Format;
    FT_UShort  number_Of_VMetrics;

    /* The following fields are not defined by the OpenType specification */
    /* but they are used to connect the metrics header to the relevant    */
    /* 'vmtx' table.                                                      */

    void*      long_metrics;
    void*      short_metrics;

  } TT_VertHeader;

  /**************************************************************************
   *
   * @struct:
   *   TT_OS2
   *
   * @description:
   *   A structure to model a TrueType 'OS/2' table.  All fields comply to
   *   the OpenType specification.
   *
   *   Note that we now support old Mac fonts that do not include an 'OS/2'
   *   table.  In this case, the `version` field is always set to 0xFFFF.
   *
   * @note:
   *   For an OpenType variation font, the values of the following fields can
   *   change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
   *   the font contains an 'MVAR' table: `sCapHeight`, `sTypoAscender`,
   *   `sTypoDescender`, `sTypoLineGap`, `sxHeight`, `usWinAscent`,
   *   `usWinDescent`, `yStrikeoutPosition`, `yStrikeoutSize`,
   *   `ySubscriptXOffset`, `ySubScriptXSize`, `ySubscriptYOffset`,
   *   `ySubscriptYSize`, `ySuperscriptXOffset`, `ySuperscriptXSize`,
   *   `ySuperscriptYOffset`, and `ySuperscriptYSize`.
   *
   *   Possible values for bits in the `ulUnicodeRangeX` fields are given by
   *   the @TT_UCR_XXX macros.
   */

  typedef struct  TT_OS2_
  {
    FT_UShort  version;                /* 0x0001 - more or 0xFFFF */
    FT_Short   xAvgCharWidth;
    FT_UShort  usWeightClass;
    FT_UShort  usWidthClass;
    FT_UShort  fsType;
    FT_Short   ySubscriptXSize;
    FT_Short   ySubscriptYSize;
    FT_Short   ySubscriptXOffset;
    FT_Short   ySubscriptYOffset;
    FT_Short   ySuperscriptXSize;
    FT_Short   ySuperscriptYSize;
    FT_Short   ySuperscriptXOffset;
    FT_Short   ySuperscriptYOffset;
    FT_Short   yStrikeoutSize;
    FT_Short   yStrikeoutPosition;
    FT_Short   sFamilyClass;

    FT_Byte    panose[10];

    FT_ULong   ulUnicodeRange1;        /* Bits 0-31   */
    FT_ULong   ulUnicodeRange2;        /* Bits 32-63  */
    FT_ULong   ulUnicodeRange3;        /* Bits 64-95  */
    FT_ULong   ulUnicodeRange4;        /* Bits 96-127 */

    FT_Char    achVendID[4];

    FT_UShort  fsSelection;
    FT_UShort  usFirstCharIndex;
    FT_UShort  usLastCharIndex;
    FT_Short   sTypoAscender;
    FT_Short   sTypoDescender;
    FT_Short   sTypoLineGap;
    FT_UShort  usWinAscent;
    FT_UShort  usWinDescent;

    /* only version 1 and higher: */

    FT_ULong   ulCodePageRange1;       /* Bits 0-31   */
    FT_ULong   ulCodePageRange2;       /* Bits 32-63  */

    /* only version 2 and higher: */

    FT_Short   sxHeight;
    FT_Short   sCapHeight;
    FT_UShort  usDefaultChar;
    FT_UShort  usBreakChar;
    FT_UShort  usMaxContext;

    /* only version 5 and higher: */

    FT_UShort  usLowerOpticalPointSize;       /* in twips (1/20th points) */
    FT_UShort  usUpperOpticalPointSize;       /* in twips (1/20th points) */

  } TT_OS2;

  /**************************************************************************
   *
   * @struct:
   *   TT_Postscript
   *
   * @description:
   *   A structure to model a TrueType 'post' table.  All fields comply to
   *   the OpenType specification.  This structure does not reference a
   *   font's PostScript glyph names; use @FT_Get_Glyph_Name to retrieve
   *   them.
   *
   * @note:
   *   For an OpenType variation font, the values of the following fields can
   *   change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
   *   the font contains an 'MVAR' table: `underlinePosition` and
   *   `underlineThickness`.
   */
  typedef struct  TT_Postscript_
  {
    FT_Fixed  FormatType;
    FT_Fixed  italicAngle;
    FT_Short  underlinePosition;
    FT_Short  underlineThickness;
    FT_ULong  isFixedPitch;
    FT_ULong  minMemType42;
    FT_ULong  maxMemType42;
    FT_ULong  minMemType1;
    FT_ULong  maxMemType1;

    /* Glyph names follow in the 'post' table, but we don't */
    /* load them by default.                                */

  } TT_Postscript;

  /**************************************************************************
   *
   * @struct:
   *   TT_PCLT
   *
   * @description:
   *   A structure to model a TrueType 'PCLT' table.  All fields comply to
   *   the OpenType specification.
   */
  typedef struct  TT_PCLT_
  {
    FT_Fixed   Version;
    FT_ULong   FontNumber;
    FT_UShort  Pitch;
    FT_UShort  xHeight;
    FT_UShort  Style;
    FT_UShort  TypeFamily;
    FT_UShort  CapHeight;
    FT_UShort  SymbolSet;
    FT_Char    TypeFace[16];
    FT_Char    CharacterComplement[8];
    FT_Char    FileName[6];
    FT_Char    StrokeWeight;
    FT_Char    WidthType;
    FT_Byte    SerifStyle;
    FT_Byte    Reserved;

  } TT_PCLT;

  /**************************************************************************
   *
   * @struct:
   *   TT_MaxProfile
   *
   * @description:
   *   The maximum profile ('maxp') table contains many max values, which can
   *   be used to pre-allocate arrays for speeding up glyph loading and
   *   hinting.
   *
   * @fields:
   *   version ::
   *     The version number.
   *
   *   numGlyphs ::
   *     The number of glyphs in this TrueType font.
   *
   *   maxPoints ::
   *     The maximum number of points in a non-composite TrueType glyph.  See
   *     also `maxCompositePoints`.
   *
   *   maxContours ::
   *     The maximum number of contours in a non-composite TrueType glyph.
   *     See also `maxCompositeContours`.
   *
   *   maxCompositePoints ::
   *     The maximum number of points in a composite TrueType glyph.  See
   *     also `maxPoints`.
   *
   *   maxCompositeContours ::
   *     The maximum number of contours in a composite TrueType glyph.  See
   *     also `maxContours`.
   *
   *   maxZones ::
   *     The maximum number of zones used for glyph hinting.
   *
   *   maxTwilightPoints ::
   *     The maximum number of points in the twilight zone used for glyph
   *     hinting.
   *
   *   maxStorage ::
   *     The maximum number of elements in the storage area used for glyph
   *     hinting.
   *
   *   maxFunctionDefs ::
   *     The maximum number of function definitions in the TrueType bytecode
   *     for this font.
   *
   *   maxInstructionDefs ::
   *     The maximum number of instruction definitions in the TrueType
   *     bytecode for this font.
   *
   *   maxStackElements ::
   *     The maximum number of stack elements used during bytecode
   *     interpretation.
   *
   *   maxSizeOfInstructions ::
   *     The maximum number of TrueType opcodes used for glyph hinting.
   *
   *   maxComponentElements ::
   *     The maximum number of simple (i.e., non-composite) glyphs in a
   *     composite glyph.
   *
   *   maxComponentDepth ::
   *     The maximum nesting depth of composite glyphs.
   *
   * @note:
   *   This structure is only used during font loading.
   */
  typedef struct  TT_MaxProfile_
  {
    FT_Fixed   version;
    FT_UShort  numGlyphs;
    FT_UShort  maxPoints;
    FT_UShort  maxContours;
    FT_UShort  maxCompositePoints;
    FT_UShort  maxCompositeContours;
    FT_UShort  maxZones;
    FT_UShort  maxTwilightPoints;
    FT_UShort  maxStorage;
    FT_UShort  maxFunctionDefs;
    FT_UShort  maxInstructionDefs;
    FT_UShort  maxStackElements;
    FT_UShort  maxSizeOfInstructions;
    FT_UShort  maxComponentElements;
    FT_UShort  maxComponentDepth;

  } TT_MaxProfile;

  /**************************************************************************
   *
   * @enum:
   *   FT_Sfnt_Tag
   *
   * @description:
   *   An enumeration to specify indices of SFNT tables loaded and parsed by
   *   FreeType during initialization of an SFNT font.  Used in the
   *   @FT_Get_Sfnt_Table API function.
   *
   * @values:
   *   FT_SFNT_HEAD ::
   *     To access the font's @TT_Header structure.
   *
   *   FT_SFNT_MAXP ::
   *     To access the font's @TT_MaxProfile structure.
   *
   *   FT_SFNT_OS2 ::
   *     To access the font's @TT_OS2 structure.
   *
   *   FT_SFNT_HHEA ::
   *     To access the font's @TT_HoriHeader structure.
   *
   *   FT_SFNT_VHEA ::
   *     To access the font's @TT_VertHeader structure.
   *
   *   FT_SFNT_POST ::
   *     To access the font's @TT_Postscript structure.
   *
   *   FT_SFNT_PCLT ::
   *     To access the font's @TT_PCLT structure.
   */
  typedef enum  FT_Sfnt_Tag_
  {
    FT_SFNT_HEAD,
    FT_SFNT_MAXP,
    FT_SFNT_OS2,
    FT_SFNT_HHEA,
    FT_SFNT_VHEA,
    FT_SFNT_POST,
    FT_SFNT_PCLT,

    FT_SFNT_MAX

  } FT_Sfnt_Tag;

  /* these constants are deprecated; use the corresponding `FT_Sfnt_Tag` */
  /* values instead                                                      */
#define ft_sfnt_head  FT_SFNT_HEAD
#define ft_sfnt_maxp  FT_SFNT_MAXP
#define ft_sfnt_os2   FT_SFNT_OS2
#define ft_sfnt_hhea  FT_SFNT_HHEA
#define ft_sfnt_vhea  FT_SFNT_VHEA
#define ft_sfnt_post  FT_SFNT_POST
#define ft_sfnt_pclt  FT_SFNT_PCLT

  /**************************************************************************
   *
   * @function:
   *   FT_Get_Sfnt_Table
   *
   * @description:
   *   Return a pointer to a given SFNT table stored within a face.
   *
   * @input:
   *   face ::
   *     A handle to the source.
   *
   *   tag ::
   *     The index of the SFNT table.
   *
   * @return:
   *   A type-less pointer to the table.  This will be `NULL` in case of
   *   error, or if the corresponding table was not found **OR** loaded from
   *   the file.
   *
   *   Use a typecast according to `tag` to access the structure elements.
   *
   * @note:
   *   The table is owned by the face object and disappears with it.
   *
   *   This function is only useful to access SFNT tables that are loaded by
   *   the sfnt, truetype, and opentype drivers.  See @FT_Sfnt_Tag for a
   *   list.
   *
   * @example:
   *   Here is an example demonstrating access to the 'vhea' table.
   *
   *   ```
   *     TT_VertHeader*  vert_header;
   *
   *
   *     vert_header =
   *       (TT_VertHeader*)FT_Get_Sfnt_Table( face, FT_SFNT_VHEA );
   *   ```
   */
  FT_EXPORT( void* )
  FT_Get_Sfnt_Table( FT_Face      face,
                     FT_Sfnt_Tag  tag );

  /**************************************************************************
   *
   * @function:
   *   FT_Load_Sfnt_Table
   *
   * @description:
   *   Load any SFNT font table into client memory.
   *
   * @input:
   *   face ::
   *     A handle to the source face.
   *
   *   tag ::
   *     The four-byte tag of the table to load.  Use value~0 if you want to
   *     access the whole font file.  Otherwise, you can use one of the
   *     definitions found in the @FT_TRUETYPE_TAGS_H file, or forge a new
   *     one with @FT_MAKE_TAG.
   *
   *   offset ::
   *     The starting offset in the table (or file if tag~==~0).
   *
   * @output:
   *   buffer ::
   *     The target buffer address.  The client must ensure that the memory
   *     array is big enough to hold the data.
   *
   * @inout:
   *   length ::
   *     If the `length` parameter is `NULL`, try to load the whole table.
   *     Return an error code if it fails.
   *
   *     Else, if `*length` is~0, exit immediately while returning the
   *     table's (or file) full size in it.
   *
   *     Else the number of bytes to read from the table or file, from the
   *     starting offset.
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   If you need to determine the table's length you should first call this
   *   function with `*length` set to~0, as in the following example:
   *
   *   ```
   *     FT_ULong  length = 0;
   *
   *
   *     error = FT_Load_Sfnt_Table( face, tag, 0, NULL, &length );
   *     if ( error ) { ... table does not exist ... }
   *
   *     buffer = malloc( length );
   *     if ( buffer == NULL ) { ... not enough memory ... }
   *
   *     error = FT_Load_Sfnt_Table( face, tag, 0, buffer, &length );
   *     if ( error ) { ... could not load table ... }
   *   ```
   *
   *   Note that structures like @TT_Header or @TT_OS2 can't be used with
   *   this function; they are limited to @FT_Get_Sfnt_Table.  Reason is that
   *   those structures depend on the processor architecture, with varying
   *   size (e.g. 32bit vs. 64bit) or order (big endian vs. little endian).
   *
   */
  FT_EXPORT( FT_Error )
  FT_Load_Sfnt_Table( FT_Face    face,
                      FT_ULong   tag,
                      FT_Long    offset,
                      FT_Byte*   buffer,
                      FT_ULong*  length );

  /**************************************************************************
   *
   * @function:
   *   FT_Sfnt_Table_Info
   *
   * @description:
   *   Return information on an SFNT table.
   *
   * @input:
   *   face ::
   *     A handle to the source face.
   *
   *   table_index ::
   *     The index of an SFNT table.  The function returns
   *     FT_Err_Table_Missing for an invalid value.
   *
   * @inout:
   *   tag ::
   *     The name tag of the SFNT table.  If the value is `NULL`,
   *     `table_index` is ignored, and `length` returns the number of SFNT
   *     tables in the font.
   *
   * @output:
   *   length ::
   *     The length of the SFNT table (or the number of SFNT tables,
   *     depending on `tag`).
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   While parsing fonts, FreeType handles SFNT tables with length zero as
   *   missing.
   *
   */
  FT_EXPORT( FT_Error )
  FT_Sfnt_Table_Info( FT_Face    face,
                      FT_UInt    table_index,
                      FT_ULong  *tag,
                      FT_ULong  *length );

  /**************************************************************************
   *
   * @function:
   *   FT_Get_CMap_Language_ID
   *
   * @description:
   *   Return cmap language ID as specified in the OpenType standard.
   *   Definitions of language ID values are in file @FT_TRUETYPE_IDS_H.
   *
   * @input:
   *   charmap ::
   *     The target charmap.
   *
   * @return:
   *   The language ID of `charmap`.  If `charmap` doesn't belong to an SFNT
   *   face, just return~0 as the default value.
   *
   *   For a format~14 cmap (to access Unicode IVS), the return value is
   *   0xFFFFFFFF.
   */
  FT_EXPORT( FT_ULong )
  FT_Get_CMap_Language_ID( FT_CharMap  charmap );

  /**************************************************************************
   *
   * @function:
   *   FT_Get_CMap_Format
   *
   * @description:
   *   Return the format of an SFNT 'cmap' table.
   *
   * @input:
   *   charmap ::
   *     The target charmap.
   *
   * @return:
   *   The format of `charmap`.  If `charmap` doesn't belong to an SFNT face,
   *   return -1.
   */
  FT_EXPORT( FT_Long )
  FT_Get_CMap_Format( FT_CharMap  charmap );

  /* */

FT_END_HEADER

#endif /* TTTABLES_H_ */

/* END */