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 */ 235