include/freetype/ftadvanc.h

   1 /****************************************************************************
   2  *
   3  * ftadvanc.h
   4  *
   5  *   Quick computation of advance widths (specification only).
   6  *
   7  * Copyright (C) 2008-2023 by
   8  * David Turner, Robert Wilhelm, and Werner Lemberg.
   9  *
  10  * This file is part of the FreeType project, and may only be used,
  11  * modified, and distributed under the terms of the FreeType project
  12  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
  13  * this file you indicate that you have read the license and
  14  * understand and accept it fully.
  15  *
  16  */
  17
  18
  19 #ifndef FTADVANC_H_
  20 #define FTADVANC_H_
  21
  22
  23 #include <freetype/freetype.h>
  24
  25 #ifdef FREETYPE_H
  26 #error "freetype.h of FreeType 1 has been loaded!"
  27 #error "Please fix the directory search order for header files"
  28 #error "so that freetype.h of FreeType 2 is found first."
  29 #endif
  30
  31
  32 FT_BEGIN_HEADER
  33
  34
  35   /**************************************************************************
  36    *
  37    * @section:
  38    *   quick_advance
  39    *
  40    * @title:
  41    *   Quick retrieval of advance values
  42    *
  43    * @abstract:
  44    *   Retrieve horizontal and vertical advance values without processing
  45    *   glyph outlines, if possible.
  46    *
  47    * @description:
  48    *   This section contains functions to quickly extract advance values
  49    *   without handling glyph outlines, if possible.
  50    *
  51    * @order:
  52    *   FT_Get_Advance
  53    *   FT_Get_Advances
  54    *
  55    */
  56
  57
  58   /**************************************************************************
  59    *
  60    * @enum:
  61    *   FT_ADVANCE_FLAG_FAST_ONLY
  62    *
  63    * @description:
  64    *   A bit-flag to be OR-ed with the `flags` parameter of the
  65    *   @FT_Get_Advance and @FT_Get_Advances functions.
  66    *
  67    *   If set, it indicates that you want these functions to fail if the
  68    *   corresponding hinting mode or font driver doesn't allow for very quick
  69    *   advance computation.
  70    *
  71    *   Typically, glyphs that are either unscaled, unhinted, bitmapped, or
  72    *   light-hinted can have their advance width computed very quickly.
  73    *
  74    *   Normal and bytecode hinted modes that require loading, scaling, and
  75    *   hinting of the glyph outline, are extremely slow by comparison.
  76    */
  77 #define FT_ADVANCE_FLAG_FAST_ONLY  0x20000000L
  78
  79
  80   /**************************************************************************
  81    *
  82    * @function:
  83    *   FT_Get_Advance
  84    *
  85    * @description:
  86    *   Retrieve the advance value of a given glyph outline in an @FT_Face.
  87    *
  88    * @input:
  89    *   face ::
  90    *     The source @FT_Face handle.
  91    *
  92    *   gindex ::
  93    *     The glyph index.
  94    *
  95    *   load_flags ::
  96    *     A set of bit flags similar to those used when calling
  97    *     @FT_Load_Glyph, used to determine what kind of advances you need.
  98    *
  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 */