include/freetype/internal/autohint.h

   1 /****************************************************************************
   2  *
   3  * autohint.h
   4  *
   5  *   High-level 'autohint' module-specific interface (specification).
   6  *
   7  * Copyright (C) 1996-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   /**************************************************************************
  20    *
  21    * The auto-hinter is used to load and automatically hint glyphs if a
  22    * format-specific hinter isn't available.
  23    *
  24    */
  25
  26
  27 #ifndef AUTOHINT_H_
  28 #define AUTOHINT_H_
  29
  30
  31   /**************************************************************************
  32    *
  33    * A small technical note regarding automatic hinting in order to clarify
  34    * this module interface.
  35    *
  36    * An automatic hinter might compute two kinds of data for a given face:
  37    *
  38    * - global hints: Usually some metrics that describe global properties
  39    *                 of the face.  It is computed by scanning more or less
  40    *                 aggressively the glyphs in the face, and thus can be
  41    *                 very slow to compute (even if the size of global hints
  42    *                 is really small).
  43    *
  44    * - glyph hints: These describe some important features of the glyph
  45    *                 outline, as well as how to align them.  They are
  46    *                 generally much faster to compute than global hints.
  47    *
  48    * The current FreeType auto-hinter does a pretty good job while performing
  49    * fast computations for both global and glyph hints.  However, we might be
  50    * interested in introducing more complex and powerful algorithms in the
  51    * future, like the one described in the John D. Hobby paper, which
  52    * unfortunately requires a lot more horsepower.
  53    *
  54    * Because a sufficiently sophisticated font management system would
  55    * typically implement an LRU cache of opened face objects to reduce memory
  56    * usage, it is a good idea to be able to avoid recomputing global hints
  57    * every time the same face is re-opened.
  58    *
  59    * We thus provide the ability to cache global hints outside of the face
  60    * object, in order to speed up font re-opening time.  Of course, this
  61    * feature is purely optional, so most client programs won't even notice
  62    * it.
  63    *
  64    * I initially thought that it would be a good idea to cache the glyph
  65    * hints too.  However, my general idea now is that if you really need to
  66    * cache these too, you are simply in need of a new font format, where all
  67    * this information could be stored within the font file and decoded on the
  68    * fly.
  69    *
  70    */
  71
  72
  73 #include <freetype/freetype.h>
  74
  75
  76 FT_BEGIN_HEADER
  77
  78
  79   typedef struct FT_AutoHinterRec_  *FT_AutoHinter;
  80
  81
  82   /**************************************************************************
  83    *
  84    * @functype:
  85    *   FT_AutoHinter_GlobalGetFunc
  86    *
  87    * @description:
  88    *   Retrieve the global hints computed for a given face object.  The
  89    *   resulting data is dissociated from the face and will survive a call to
  90    *   FT_Done_Face().  It must be discarded through the API
  91    *   FT_AutoHinter_GlobalDoneFunc().
  92    *
  93    * @input:
  94    *   hinter ::
  95    *     A handle to the source auto-hinter.
  96    *
  97    *   face ::
  98    *     A handle to the source face object.
  99    *
 100    * @output:
 101    *   global_hints ::
 102    *     A typeless pointer to the global hints.
 103    *
 104    *   global_len ::
 105    *     The size in bytes of the global hints.
 106    */
 107   typedef void
 108   (*FT_AutoHinter_GlobalGetFunc)( FT_AutoHinter  hinter,
 109                                   FT_Face        face,
 110                                   void**         global_hints,
 111                                   long*          global_len );
 112
 113
 114   /**************************************************************************
 115    *
 116    * @functype:
 117    *   FT_AutoHinter_GlobalDoneFunc
 118    *
 119    * @description:
 120    *   Discard the global hints retrieved through
 121    *   FT_AutoHinter_GlobalGetFunc().  This is the only way these hints are
 122    *   freed from memory.
 123    *
 124    * @input:
 125    *   hinter ::
 126    *     A handle to the auto-hinter module.
 127    *
 128    *   global ::
 129    *     A pointer to retrieved global hints to discard.
 130    */
 131   typedef void
 132   (*FT_AutoHinter_GlobalDoneFunc)( FT_AutoHinter  hinter,
 133                                    void*          global );
 134
 135
 136   /**************************************************************************
 137    *
 138    * @functype:
 139    *   FT_AutoHinter_GlobalResetFunc
 140    *
 141    * @description:
 142    *   This function is used to recompute the global metrics in a given font.
 143    *   This is useful when global font data changes (e.g. Multiple Masters
 144    *   fonts where blend coordinates change).
 145    *
 146    * @input:
 147    *   hinter ::
 148    *     A handle to the source auto-hinter.
 149    *
 150    *   face ::
 151    *     A handle to the face.
 152    */
 153   typedef void
 154   (*FT_AutoHinter_GlobalResetFunc)( FT_AutoHinter  hinter,
 155                                     FT_Face        face );
 156
 157
 158   /**************************************************************************
 159    *
 160    * @functype:
 161    *   FT_AutoHinter_GlyphLoadFunc
 162    *
 163    * @description:
 164    *   This function is used to load, scale, and automatically hint a glyph
 165    *   from a given face.
 166    *
 167    * @input:
 168    *   face ::
 169    *     A handle to the face.
 170    *
 171    *   glyph_index ::
 172    *     The glyph index.
 173    *
 174    *   load_flags ::
 175    *     The load flags.
 176    *
 177    * @note:
 178    *   This function is capable of loading composite glyphs by hinting each
 179    *   sub-glyph independently (which improves quality).
 180    *
 181    *   It will call the font driver with @FT_Load_Glyph, with
 182    *   @FT_LOAD_NO_SCALE set.
 183    */
 184   typedef FT_Error
 185   (*FT_AutoHinter_GlyphLoadFunc)( FT_AutoHinter  hinter,
 186                                   FT_GlyphSlot   slot,
 187                                   FT_Size        size,
 188                                   FT_UInt        glyph_index,
 189                                   FT_Int32       load_flags );
 190
 191
 192   /**************************************************************************
 193    *
 194    * @struct:
 195    *   FT_AutoHinter_InterfaceRec
 196    *
 197    * @description:
 198    *   The auto-hinter module's interface.
 199    */
 200   typedef struct  FT_AutoHinter_InterfaceRec_
 201   {
 202     FT_AutoHinter_GlobalResetFunc  reset_face;
 203     FT_AutoHinter_GlobalGetFunc    get_global_hints;
 204     FT_AutoHinter_GlobalDoneFunc   done_global_hints;
 205     FT_AutoHinter_GlyphLoadFunc    load_glyph;
 206
 207   } FT_AutoHinter_InterfaceRec, *FT_AutoHinter_Interface;
 208
 209
 210 #define FT_DECLARE_AUTOHINTER_INTERFACE( class_ )            \
 211   FT_CALLBACK_TABLE const FT_AutoHinter_InterfaceRec  class_;
 212
 213 #define FT_DEFINE_AUTOHINTER_INTERFACE(       \
 214           class_,                             \
 215           reset_face_,                        \
 216           get_global_hints_,                  \
 217           done_global_hints_,                 \
 218           load_glyph_ )                       \
 219   FT_CALLBACK_TABLE_DEF                       \
 220   const FT_AutoHinter_InterfaceRec  class_ =  \
 221   {                                           \
 222     reset_face_,                              \
 223     get_global_hints_,                        \
 224     done_global_hints_,                       \
 225     load_glyph_                               \
 226   };
 227
 228
 229 FT_END_HEADER
 230
 231 #endif /* AUTOHINT_H_ */
 232
 233
 234 /* END */