Commit 81d02dbc04145e0b39e399c8ec6d2e43dc2ac98e
2000-05-05T01:37:32
finally a auto-hinter module interface I'm satisfied with, it's now time to change other font drivers to take advantage of it :-)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179
diff --git a/src/shared/autohint.h b/src/shared/autohint.h
index 5257ca0..288d1e4 100644
--- a/src/shared/autohint.h
+++ b/src/shared/autohint.h
@@ -22,51 +22,132 @@
#ifndef AUTOHINT_H
#define AUTOHINT_H
+ /***************************************************************************
+ *
+ * A small technical note regarding automatic hinting in order to clarify
+ * this module interface.
+ *
+ * An automatic hinter might compute two kinds of data for a given face:
+ *
+ * - global hints: usually some metrics that describe global properties
+ * of the face. It is computed by scanning more or less
+ * agressively the glyphs in the face, and thus can be
+ * very slow to compute (even if the size of global hints
+ * is really small)
+ *
+ * - glyph hints: these describe some important features of the glyph
+ * outline, as well as how to align them. They are generally
+ * much faster to compute than global hints.
+ *
+ * The current FreeType auto-hinter does a pretty good job while performing
+ * fast computations for both global and glyph hints. However, we might be
+ * interested in introducing more complex and powerful algorithms in the
+ * future, like the one described in the John D. Hobby paper, which
+ * unfortunately require a lot more horsepower.
+ *
+ * Because a sufficiently sophisticated font management system would
+ * typically implement a LRU cache of opened face objects to reduce memory
+ * usage, it is a good idea to be able to avoid recomputing global hints
+ * every time the same face is re-opened.
+ *
+ * We thus provide the ability to cache global hints outside of the face
+ * object, in order to speed up font re-opening time. Of course, this
+ * feature is purely optional, so most client programs won't even notice
+ * it :o)
+ *
+ * I initially though that it'd be a good idea to cache the glyph hints too,
+ * however, if my general idea now is that if you really need to cache these
+ * too, you're simply in need of a new font format, where all this information
+ * could be stored within the font file and decoded on the fly :-)
+ *
+ */
+
#include <freetype.h>
+ typedef struct FT_AutoHinterRec_ *FT_AutoHinter;
+
/***********************************************************************
*
* <FuncType>
- * FT_AutoHinter_Init_Func
+ * FT_AutoHinter_Get_Global_Func
*
* <Description>
- * Each face can have its own auto-hinter object. This function
- * is used to initialise it. Its role is to perform a few statistics
- * on the face's content in order to compute global metrics like
- * blue zones and standard width/heights.
+ * Retrieve the global hints computed for a given face object
+ * the resulting data is dissociated from the face and will survive
+ * a call to FT_Done_Face. It must be discarded through the API
+ * FT_AutoHinter_Done_Global_Func.
*
* <Input>
- * face :: handle to the face.
+ * hinter :: handle to source auto-hinter
+ * face :: handle to source face object
*
- * <Note>
- * this function will call FT_Load_Glyph several times in order to
- * compute various statistics on the face's glyphs. This means that
- * the face handle must be valid when calling it.
+ * <Output>
+ * global_hints :: typeless pointer to the global hints
+ * global_len :: size in bytes of global hints
*
- * This function set the "hinter" and "hinter_len" fields of 'face'.
*/
- typedef FT_Error (*FT_AutoHinter_Init_Func)( FT_Face face );
+ typedef void (*FT_AutoHinter_Get_Global_Func)( FT_AutoHinter hinter,
+ FT_Face face,
+ void* *global_hints,
+ long *global_len );
+ /***********************************************************************
+ *
+ * <FuncType>
+ * FT_AutoHinter_Done_Global_Func
+ *
+ * <Description>
+ * Discards the global hints retrieved through
+ * FT_AutoHinter_Get_Global_Func. This is the only way these hints
+ * are freed from memory.
+ *
+ * <Input>
+ * hinter :: handle to auto-hinter module
+ * global :: pointer to retrieved global hints to discard
+ */
+ typedef void (*FT_AutoHinter_Done_Global_Func)( FT_AutoHinter hinter,
+ void* global );
/***********************************************************************
*
* <FuncType>
- * FT_AutoHinter_Done_Func
+ * FT_AutoHinter_Init_Func
*
* <Description>
- * Each face can have its own auto-hinter object. This function
- * is used to finalise and destroy it.
+ * Compute or set the global hints for a given face object.
*
* <Input>
- * face :: handle to the face.
+ * hinter :: handle to source auto-hinter module
+ * face :: handle to target face object.
+ * global_hints :: typeless pointer to global hints. If 0, the
+ * hints are computed for the face
*
* <Note>
- * This function clears the "hinter" and "hinter_len" fields of
- * "face". However, the face object is still valid and can be used
- * to load un-hinted glyphs..
+ * it is up to client applications to ensure that the global hints
+ * were retrieved for the same face object. Strange results may occur
+ * otherwise..
+ *
+ */
+ typedef FT_Error (*FT_AutoHinter_Init_Func)( FT_AutoHinter hinter,
+ FT_Face face,
+ void* global_hints );
+
+ /***********************************************************************
+ *
+ * <FuncType>
+ * FT_AutoHinter_Done_Func
+ *
+ * <Description>
+ * Discards the global hints for a given face..
+ *
+ * <Input>
+ * hinter :: handle to source auto-hinter module
+ * face :: handle to target face object.
*
*/
- typedef void (*FT_AutoHinter_Done_Func)( FT_Face face );
+ typedef FT_Error (*FT_AutoHinter_Done_Func)( FT_AutoHinter hinter,
+ FT_Face face );
+
/***********************************************************************
@@ -93,7 +174,7 @@
*/
typedef FT_Error (*FT_AutoHinter_Load_Func)( FT_Face face,
FT_UInt glyph_index,
- FT_ULong load_flags );
+ FT_ULong load_flags );
/***********************************************************************
*
@@ -109,9 +190,11 @@
FT_AutoHinter_Init_Func init_autohinter;
FT_AutoHinter_Done_Func done_autohinter;
FT_AutoHinter_Load_Func load_glyph;
+
+ FT_AutoHinter_Get_Global_Func get_global_hints;
+ FT_AutoHinter_Done_Global_Func done_global_hints;
} FT_AutoHinter_Interface;
#endif /* AUTOHINT_H */
-