1 /****************************************************************************
   2  *
   3  * ftadvanc.h
   4  *
   5  *   Quick computation of advance widths (specification only).
   6  *
   7  * Copyright (C) 2008-2019 by
   8  * David Turner, Robert Wilhelm, and Werner Lemberg.
   9  *
  10  * This file is part of the FreeType project, and may only be used,
  11  * modified, and distributed under the terms of the FreeType project
  12  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
  13  * this file you indicate that you have read the license and
  14  * understand and accept it fully.
  15  *
  16  */
  17 
  18 
  19 #ifndef FTADVANC_H_
  20 #define FTADVANC_H_
  21 
  22 
  23 #include <ft2build.h>
  24 #include FT_FREETYPE_H
  25 
  26 #ifdef FREETYPE_H
  27 #error "freetype.h of FreeType 1 has been loaded!"
  28 #error "Please fix the directory search order for header files"
  29 #error "so that freetype.h of FreeType 2 is found first."
  30 #endif
  31 
  32 
  33 FT_BEGIN_HEADER
  34 
  35 
  36   /**************************************************************************
  37    *
  38    * @section:
  39    *   quick_advance
  40    *
  41    * @title:
  42    *   Quick retrieval of advance values
  43    *
  44    * @abstract:
  45    *   Retrieve horizontal and vertical advance values without processing
  46    *   glyph outlines, if possible.
  47    *
  48    * @description:
  49    *   This section contains functions to quickly extract advance values
  50    *   without handling glyph outlines, if possible.
  51    *
  52    * @order:
  53    *   FT_Get_Advance
  54    *   FT_Get_Advances
  55    *
  56    */
  57 
  58 
  59   /**************************************************************************
  60    *
  61    * @enum:
  62    *   FT_ADVANCE_FLAG_FAST_ONLY
  63    *
  64    * @description:
  65    *   A bit-flag to be OR-ed with the `flags` parameter of the
  66    *   @FT_Get_Advance and @FT_Get_Advances functions.
  67    *
  68    *   If set, it indicates that you want these functions to fail if the
  69    *   corresponding hinting mode or font driver doesn't allow for very quick
  70    *   advance computation.
  71    *
  72    *   Typically, glyphs that are either unscaled, unhinted, bitmapped, or
  73    *   light-hinted can have their advance width computed very quickly.
  74    *
  75    *   Normal and bytecode hinted modes that require loading, scaling, and
  76    *   hinting of the glyph outline, are extremely slow by comparison.
  77    */
  78 #define FT_ADVANCE_FLAG_FAST_ONLY  0x20000000L
  79 
  80 
  81   /**************************************************************************
  82    *
  83    * @function:
  84    *   FT_Get_Advance
  85    *
  86    * @description:
  87    *   Retrieve the advance value of a given glyph outline in an @FT_Face.
  88    *
  89    * @input:
  90    *   face ::
  91    *     The source @FT_Face handle.
  92    *
  93    *   gindex ::
  94    *     The glyph index.
  95    *
  96    *   load_flags ::
  97    *     A set of bit flags similar to those used when calling
  98    *     @FT_Load_Glyph, used to determine what kind of advances you need.
  99    * @output:
 100    *   padvance ::
 101    *     The advance value.  If scaling is performed (based on the value of
 102    *     `load_flags`), the advance value is in 16.16 format.  Otherwise, it
 103    *     is in font units.
 104    *
 105    *     If @FT_LOAD_VERTICAL_LAYOUT is set, this is the vertical advance
 106    *     corresponding to a vertical layout.  Otherwise, it is the horizontal
 107    *     advance in a horizontal layout.
 108    *
 109    * @return:
 110    *   FreeType error code.  0 means success.
 111    *
 112    * @note:
 113    *   This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and if
 114    *   the corresponding font backend doesn't have a quick way to retrieve
 115    *   the advances.
 116    *
 117    *   A scaled advance is returned in 16.16 format but isn't transformed by
 118    *   the affine transformation specified by @FT_Set_Transform.
 119    */
 120   FT_EXPORT( FT_Error )
 121   FT_Get_Advance( FT_Face    face,
 122                   FT_UInt    gindex,
 123                   FT_Int32   load_flags,
 124                   FT_Fixed  *padvance );
 125 
 126 
 127   /**************************************************************************
 128    *
 129    * @function:
 130    *   FT_Get_Advances
 131    *
 132    * @description:
 133    *   Retrieve the advance values of several glyph outlines in an @FT_Face.
 134    *
 135    * @input:
 136    *   face ::
 137    *     The source @FT_Face handle.
 138    *
 139    *   start ::
 140    *     The first glyph index.
 141    *
 142    *   count ::
 143    *     The number of advance values you want to retrieve.
 144    *
 145    *   load_flags ::
 146    *     A set of bit flags similar to those used when calling
 147    *     @FT_Load_Glyph.
 148    *
 149    * @output:
 150    *   padvance ::
 151    *     The advance values.  This array, to be provided by the caller, must
 152    *     contain at least `count` elements.
 153    *
 154    *     If scaling is performed (based on the value of `load_flags`), the
 155    *     advance values are in 16.16 format.  Otherwise, they are in font
 156    *     units.
 157    *
 158    *     If @FT_LOAD_VERTICAL_LAYOUT is set, these are the vertical advances
 159    *     corresponding to a vertical layout.  Otherwise, they are the
 160    *     horizontal advances in a horizontal layout.
 161    *
 162    * @return:
 163    *   FreeType error code.  0 means success.
 164    *
 165    * @note:
 166    *   This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and if
 167    *   the corresponding font backend doesn't have a quick way to retrieve
 168    *   the advances.
 169    *
 170    *   Scaled advances are returned in 16.16 format but aren't transformed by
 171    *   the affine transformation specified by @FT_Set_Transform.
 172    */
 173   FT_EXPORT( FT_Error )
 174   FT_Get_Advances( FT_Face    face,
 175                    FT_UInt    start,
 176                    FT_UInt    count,
 177                    FT_Int32   load_flags,
 178                    FT_Fixed  *padvances );
 179 
 180   /* */
 181 
 182 
 183 FT_END_HEADER
 184 
 185 #endif /* FTADVANC_H_ */
 186 
 187 
 188 /* END */