| ... |
... |
@@ -43,60 +43,61 @@ FT_BEGIN_HEADER |
|
43
|
43
|
* objects, as well as caching information like character maps and glyph
|
|
44
|
44
|
* images while limiting their maximum memory usage.
|
|
45
|
45
|
*
|
|
46
|
|
- * Note that all types and functions begin with the `FTC_` prefix.
|
|
47
|
|
- *
|
|
48
|
|
- * The cache is highly portable and thus doesn't know anything about the
|
|
49
|
|
- * fonts installed on your system, or how to access them. This implies
|
|
50
|
|
- * the following scheme:
|
|
51
|
|
- *
|
|
52
|
|
- * First, available or installed font faces are uniquely identified by
|
|
53
|
|
- * @FTC_FaceID values, provided to the cache by the client. Note that
|
|
54
|
|
- * the cache only stores and compares these values, and doesn't try to
|
|
55
|
|
- * interpret them in any way.
|
|
56
|
|
- *
|
|
57
|
|
- * Second, the cache calls, only when needed, a client-provided function
|
|
58
|
|
- * to convert an @FTC_FaceID into a new @FT_Face object. The latter is
|
|
59
|
|
- * then completely managed by the cache, including its termination
|
|
60
|
|
- * through @FT_Done_Face. To monitor termination of face objects, the
|
|
61
|
|
- * finalizer callback in the `generic` field of the @FT_Face object can
|
|
62
|
|
- * be used, which might also be used to store the @FTC_FaceID of the
|
|
63
|
|
- * face.
|
|
64
|
|
- *
|
|
65
|
|
- * Clients are free to map face IDs to anything else. The most simple
|
|
66
|
|
- * usage is to associate them to a (pathname,face_index) pair that is
|
|
67
|
|
- * used to call @FT_New_Face. However, more complex schemes are also
|
|
68
|
|
- * possible.
|
|
|
46
|
+ * Note that all types and functions begin with the `FTC_` prefix rather
|
|
|
47
|
+ * than the usual `FT_` prefix int the rest of FreeType.
|
|
|
48
|
+ *
|
|
|
49
|
+ * The cache is highly portable and, thus, doesn't know anything about
|
|
|
50
|
+ * the fonts installed on your system, or how to access them. Therefore,
|
|
|
51
|
+ * it requires the following:
|
|
|
52
|
+ *
|
|
|
53
|
+ * * @FTC_FaceID, an arbitrary non-zero value, that uniquely identifies
|
|
|
54
|
+ * available or installed font faces, has to be provided to the
|
|
|
55
|
+ * cache by the client. Note that the cache only stores and compares
|
|
|
56
|
+ * these values, and doesn't try to interpret them in any way but they
|
|
|
57
|
+ * have to be persistent on the client side.
|
|
|
58
|
+ *
|
|
|
59
|
+ * * @FTC_Face_Requester, a method to convert an @FTC_FaceID into a new
|
|
|
60
|
+ * @FT_Face object, when necessary, has to be provided to the cache by
|
|
|
61
|
+ * the client. The @FT_Face object is completely managed by the cache,
|
|
|
62
|
+ * including its termination through @FT_Done_Face. To monitor
|
|
|
63
|
+ * termination of face objects, the finalizer callback in the `generic`
|
|
|
64
|
+ * field of the @FT_Face object can be used, which might also be used
|
|
|
65
|
+ * to store the @FTC_FaceID of the face.
|
|
|
66
|
+ *
|
|
|
67
|
+ * Clients are free to map face IDs to anything useful. The most simple
|
|
|
68
|
+ * usage is, for example, to associate them to a {pathname,face_index}
|
|
|
69
|
+ * pair that is then used by @FTC_Face_Requester to call @FT_New_Face.
|
|
|
70
|
+ * However, more complex schemes are also possible.
|
|
69
|
71
|
*
|
|
70
|
72
|
* Note that for the cache to work correctly, the face ID values must be
|
|
71
|
73
|
* **persistent**, which means that the contents they point to should not
|
|
72
|
74
|
* change at runtime, or that their value should not become invalid.
|
|
73
|
|
- *
|
|
74
|
75
|
* If this is unavoidable (e.g., when a font is uninstalled at runtime),
|
|
75
|
76
|
* you should call @FTC_Manager_RemoveFaceID as soon as possible, to let
|
|
76
|
77
|
* the cache get rid of any references to the old @FTC_FaceID it may keep
|
|
77
|
78
|
* internally. Failure to do so will lead to incorrect behaviour or even
|
|
78
|
|
- * crashes.
|
|
|
79
|
+ * crashes in @FTC_Face_Requester.
|
|
79
|
80
|
*
|
|
80
|
81
|
* To use the cache, start with calling @FTC_Manager_New to create a new
|
|
81
|
82
|
* @FTC_Manager object, which models a single cache instance. You can
|
|
82
|
83
|
* then look up @FT_Face and @FT_Size objects with
|
|
83
|
|
- * @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively.
|
|
84
|
|
- *
|
|
85
|
|
- * If you want to use the charmap caching, call @FTC_CMapCache_New, then
|
|
86
|
|
- * later use @FTC_CMapCache_Lookup to perform the equivalent of
|
|
87
|
|
- * @FT_Get_Char_Index, only much faster.
|
|
88
|
|
- *
|
|
89
|
|
- * If you want to use the @FT_Glyph caching, call @FTC_ImageCache_New,
|
|
90
|
|
- * then later use @FTC_ImageCache_Lookup to retrieve the corresponding
|
|
91
|
|
- * @FT_Glyph objects from the cache.
|
|
92
|
|
- *
|
|
93
|
|
- * If you need lots of small bitmaps, it is much more memory efficient to
|
|
94
|
|
- * call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup. This
|
|
95
|
|
- * returns @FTC_SBitRec structures, which are used to store small bitmaps
|
|
96
|
|
- * directly. (A small bitmap is one whose metrics and dimensions all fit
|
|
97
|
|
- * into 8-bit integers).
|
|
98
|
|
- *
|
|
99
|
|
- * We hope to also provide a kerning cache in the near future.
|
|
|
84
|
+ * @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively, and
|
|
|
85
|
+ * use them in any FreeType work stream. You can also cache other
|
|
|
86
|
+ * FreeType objects as follows:
|
|
|
87
|
+ *
|
|
|
88
|
+ * * If you want to use the charmap caching, call @FTC_CMapCache_New,
|
|
|
89
|
+ * then later use @FTC_CMapCache_Lookup to perform the equivalent of
|
|
|
90
|
+ * @FT_Get_Char_Index, only much faster.
|
|
|
91
|
+ *
|
|
|
92
|
+ * * If you want to use the @FT_Glyph caching, call @FTC_ImageCache_New,
|
|
|
93
|
+ * then later use @FTC_ImageCache_Lookup to retrieve the corresponding
|
|
|
94
|
+ * @FT_Glyph objects from the cache.
|
|
|
95
|
+ *
|
|
|
96
|
+ * * If you need lots of small bitmaps, it is much more memory efficient
|
|
|
97
|
+ * to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup. This
|
|
|
98
|
+ * returns @FTC_SBitRec structures, which are used to store small
|
|
|
99
|
+ * bitmaps directly. (A small bitmap is one whose metrics and
|
|
|
100
|
+ * dimensions all fit into 8-bit integers).
|
|
100
|
101
|
*
|
|
101
|
102
|
*
|
|
102
|
103
|
* @order:
|