1 /**************************************************************************** 2 * 3 * autohint.h 4 * 5 * High-level `autohint' module-specific interface (specification). 6 * 7 * Copyright 1996-2018 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 34 * clarify 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 42 * hints 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 49 * performing fast computations for both global and glyph hints. 50 * However, we might be interested in introducing more complex and 51 * powerful algorithms in the future, like the one described in the John 52 * D. Hobby paper, which 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 56 * memory usage, it is a good idea to be able to avoid recomputing 57 * global hints 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 66 * to cache these too, you are simply in need of a new font format, 67 * where all this information could be stored within the font file and 68 * decoded on the fly. 69 * 70 */ 71 72 73 #include <ft2build.h> 74 #include FT_FREETYPE_H 75 76 77 FT_BEGIN_HEADER 78 79 80 typedef struct FT_AutoHinterRec_ *FT_AutoHinter; 81 82 83 /************************************************************************** 84 * 85 * @functype: 86 * FT_AutoHinter_GlobalGetFunc 87 * 88 * @description: 89 * Retrieve the global hints computed for a given face object. The 90 * resulting data is dissociated from the face and will survive a 91 * call to FT_Done_Face(). It must be discarded through the API 92 * FT_AutoHinter_GlobalDoneFunc(). 93 * 94 * @input: 95 * hinter :: 96 * A handle to the source auto-hinter. 97 * 98 * face :: 99 * A handle to the source face object. 100 * 101 * @output: 102 * global_hints :: 103 * A typeless pointer to the global hints. 104 * 105 * global_len :: 106 * The size in bytes of the global hints. 107 */ 108 typedef void 109 (*FT_AutoHinter_GlobalGetFunc)( FT_AutoHinter hinter, 110 FT_Face face, 111 void** global_hints, 112 long* global_len ); 113 114 115 /************************************************************************** 116 * 117 * @functype: 118 * FT_AutoHinter_GlobalDoneFunc 119 * 120 * @description: 121 * Discard the global hints retrieved through 122 * FT_AutoHinter_GlobalGetFunc(). This is the only way these hints 123 * are freed from memory. 124 * 125 * @input: 126 * hinter :: 127 * A handle to the auto-hinter module. 128 * 129 * global :: 130 * A pointer to retrieved global hints to discard. 131 */ 132 typedef void 133 (*FT_AutoHinter_GlobalDoneFunc)( FT_AutoHinter hinter, 134 void* global ); 135 136 137 /************************************************************************** 138 * 139 * @functype: 140 * FT_AutoHinter_GlobalResetFunc 141 * 142 * @description: 143 * This function is used to recompute the global metrics in a given 144 * font. This is useful when global font data changes (e.g. Multiple 145 * Masters fonts where blend coordinates change). 146 * 147 * @input: 148 * hinter :: 149 * A handle to the source auto-hinter. 150 * 151 * face :: 152 * A handle to the face. 153 */ 154 typedef void 155 (*FT_AutoHinter_GlobalResetFunc)( FT_AutoHinter hinter, 156 FT_Face face ); 157 158 159 /************************************************************************** 160 * 161 * @functype: 162 * FT_AutoHinter_GlyphLoadFunc 163 * 164 * @description: 165 * This function is used to load, scale, and automatically hint a 166 * glyph from a given face. 167 * 168 * @input: 169 * face :: 170 * A handle to the face. 171 * 172 * glyph_index :: 173 * The glyph index. 174 * 175 * load_flags :: 176 * The load flags. 177 * 178 * @note: 179 * This function is capable of loading composite glyphs by hinting 180 * each sub-glyph independently (which improves quality). 181 * 182 * It will call the font driver with @FT_Load_Glyph, with 183 * @FT_LOAD_NO_SCALE set. 184 */ 185 typedef FT_Error 186 (*FT_AutoHinter_GlyphLoadFunc)( FT_AutoHinter hinter, 187 FT_GlyphSlot slot, 188 FT_Size size, 189 FT_UInt glyph_index, 190 FT_Int32 load_flags ); 191 192 193 /************************************************************************** 194 * 195 * @struct: 196 * FT_AutoHinter_InterfaceRec 197 * 198 * @description: 199 * The auto-hinter module's interface. 200 */ 201 typedef struct FT_AutoHinter_InterfaceRec_ 202 { 203 FT_AutoHinter_GlobalResetFunc reset_face; 204 FT_AutoHinter_GlobalGetFunc get_global_hints; 205 FT_AutoHinter_GlobalDoneFunc done_global_hints; 206 FT_AutoHinter_GlyphLoadFunc load_glyph; 207 208 } FT_AutoHinter_InterfaceRec, *FT_AutoHinter_Interface; 209 210 211 #define FT_DEFINE_AUTOHINTER_INTERFACE( \ 212 class_, \ 213 reset_face_, \ 214 get_global_hints_, \ 215 done_global_hints_, \ 216 load_glyph_ ) \ 217 FT_CALLBACK_TABLE_DEF \ 218 const FT_AutoHinter_InterfaceRec class_ = \ 219 { \ 220 reset_face_, \ 221 get_global_hints_, \ 222 done_global_hints_, \ 223 load_glyph_ \ 224 }; 225 226 227 FT_END_HEADER 228 229 #endif /* AUTOHINT_H_ */ 230 231 232 /* END */ 233