1 /***************************************************************************/
5 /* FreeType Cache subsystem (specification). */
7 /* Copyright 1996-2008, 2010, 2013 by */
8 /* David Turner, Robert Wilhelm, and Werner Lemberg. */
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. */
16 /***************************************************************************/
30 /*************************************************************************
39 * How to cache face, size, and glyph data with FreeType~2.
42 * This section describes the FreeType~2 cache sub-system, which is used
43 * to limit the number of concurrently opened @FT_Face and @FT_Size
44 * objects, as well as caching information like character maps and glyph
45 * images while limiting their maximum memory usage.
47 * Note that all types and functions begin with the `FTC_' prefix.
49 * The cache is highly portable and thus doesn't know anything about the
50 * fonts installed on your system, or how to access them. This implies
51 * the following scheme:
53 * First, available or installed font faces are uniquely identified by
54 * @FTC_FaceID values, provided to the cache by the client. Note that
55 * the cache only stores and compares these values, and doesn't try to
56 * interpret them in any way.
58 * Second, the cache calls, only when needed, a client-provided function
59 * to convert an @FTC_FaceID into a new @FT_Face object. The latter is
60 * then completely managed by the cache, including its termination
61 * through @FT_Done_Face. To monitor termination of face objects, the
62 * finalizer callback in the `generic' field of the @FT_Face object can
63 * be used, which might also be used to store the @FTC_FaceID of the
66 * Clients are free to map face IDs to anything else. The most simple
67 * usage is to associate them to a (pathname,face_index) pair that is
68 * used to call @FT_New_Face. However, more complex schemes are also
71 * Note that for the cache to work correctly, the face ID values must be
72 * *persistent*, which means that the contents they point to should not
73 * change at runtime, or that their value should not become invalid.
75 * If this is unavoidable (e.g., when a font is uninstalled at runtime),
76 * you should call @FTC_Manager_RemoveFaceID as soon as possible, to let
77 * the cache get rid of any references to the old @FTC_FaceID it may
78 * keep internally. Failure to do so will lead to incorrect behaviour
81 * To use the cache, start with calling @FTC_Manager_New to create a new
82 * @FTC_Manager object, which models a single cache instance. You can
83 * then look up @FT_Face and @FT_Size objects with
84 * @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively.
86 * If you want to use the charmap caching, call @FTC_CMapCache_New, then
87 * later use @FTC_CMapCache_Lookup to perform the equivalent of
88 * @FT_Get_Char_Index, only much faster.
90 * If you want to use the @FT_Glyph caching, call @FTC_ImageCache, then
91 * later use @FTC_ImageCache_Lookup to retrieve the corresponding
92 * @FT_Glyph objects from the cache.
94 * If you need lots of small bitmaps, it is much more memory efficient
95 * to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup. This
96 * returns @FTC_SBitRec structures, which are used to store small
97 * bitmaps directly. (A small bitmap is one whose metrics and
98 * dimensions all fit into 8-bit integers).
100 * We hope to also provide a kerning cache in the near future.
111 * FTC_Manager_LookupFace
112 * FTC_Manager_LookupSize
113 * FTC_Manager_RemoveFaceID
120 * FTC_ImageCache_Lookup
125 * FTC_SBitCache_Lookup
129 * FTC_CMapCache_Lookup
131 *************************************************************************/
134 /*************************************************************************/
135 /*************************************************************************/
136 /*************************************************************************/
138 /***** BASIC TYPE DEFINITIONS *****/
140 /*************************************************************************/
141 /*************************************************************************/
142 /*************************************************************************/
145 /*************************************************************************
150 * An opaque pointer type that is used to identity face objects. The
151 * contents of such objects is application-dependent.
153 * These pointers are typically used to point to a user-defined
154 * structure containing a font file path, and face index.
157 * Never use NULL as a valid @FTC_FaceID.
159 * Face IDs are passed by the client to the cache manager, which calls,
160 * when needed, the @FTC_Face_Requester to translate them into new
163 * If the content of a given face ID changes at runtime, or if the value
164 * becomes invalid (e.g., when uninstalling a font), you should
165 * immediately call @FTC_Manager_RemoveFaceID before any other cache
168 * Failure to do so will result in incorrect behaviour or even
169 * memory leaks and crashes.
171 typedef FT_Pointer FTC_FaceID
;
174 /************************************************************************
180 * A callback function provided by client applications. It is used by
181 * the cache manager to translate a given @FTC_FaceID into a new valid
182 * @FT_Face object, on demand.
186 * The face ID to resolve.
189 * A handle to a FreeType library object.
192 * Application-provided request data (see note below).
196 * A new @FT_Face handle.
199 * FreeType error code. 0~means success.
202 * The third parameter `req_data' is the same as the one passed by the
203 * client when @FTC_Manager_New is called.
205 * The face requester should not perform funny things on the returned
206 * face object, like creating a new @FT_Size for it, or setting a
207 * transformation through @FT_Set_Transform!
210 (*FTC_Face_Requester
)( FTC_FaceID face_id
,
212 FT_Pointer request_data
,
218 /*************************************************************************/
219 /*************************************************************************/
220 /*************************************************************************/
222 /***** CACHE MANAGER OBJECT *****/
224 /*************************************************************************/
225 /*************************************************************************/
226 /*************************************************************************/
229 /*************************************************************************/
235 /* This object corresponds to one instance of the cache-subsystem. */
236 /* It is used to cache one or more @FT_Face objects, along with */
237 /* corresponding @FT_Size objects. */
239 /* The manager intentionally limits the total number of opened */
240 /* @FT_Face and @FT_Size objects to control memory usage. See the */
241 /* `max_faces' and `max_sizes' parameters of @FTC_Manager_New. */
243 /* The manager is also used to cache `nodes' of various types while */
244 /* limiting their total memory usage. */
246 /* All limitations are enforced by keeping lists of managed objects */
247 /* in most-recently-used order, and flushing old nodes to make room */
250 typedef struct FTC_ManagerRec_
* FTC_Manager
;
253 /*************************************************************************/
259 /* An opaque handle to a cache node object. Each cache node is */
260 /* reference-counted. A node with a count of~0 might be flushed */
261 /* out of a full cache whenever a lookup request is performed. */
263 /* If you look up nodes, you have the ability to `acquire' them, */
264 /* i.e., to increment their reference count. This will prevent the */
265 /* node from being flushed out of the cache until you explicitly */
266 /* `release' it (see @FTC_Node_Unref). */
268 /* See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup. */
270 typedef struct FTC_NodeRec_
* FTC_Node
;
273 /*************************************************************************/
276 /* FTC_Manager_New */
279 /* Create a new cache manager. */
282 /* library :: The parent FreeType library handle to use. */
284 /* max_faces :: Maximum number of opened @FT_Face objects managed by */
285 /* this cache instance. Use~0 for defaults. */
287 /* max_sizes :: Maximum number of opened @FT_Size objects managed by */
288 /* this cache instance. Use~0 for defaults. */
290 /* max_bytes :: Maximum number of bytes to use for cached data nodes. */
291 /* Use~0 for defaults. Note that this value does not */
292 /* account for managed @FT_Face and @FT_Size objects. */
294 /* requester :: An application-provided callback used to translate */
295 /* face IDs into real @FT_Face objects. */
297 /* req_data :: A generic pointer that is passed to the requester */
298 /* each time it is called (see @FTC_Face_Requester). */
301 /* amanager :: A handle to a new manager object. 0~in case of */
305 /* FreeType error code. 0~means success. */
307 FT_EXPORT( FT_Error
)
308 FTC_Manager_New( FT_Library library
,
312 FTC_Face_Requester requester
,
314 FTC_Manager
*amanager
);
317 /*************************************************************************/
320 /* FTC_Manager_Reset */
323 /* Empty a given cache manager. This simply gets rid of all the */
324 /* currently cached @FT_Face and @FT_Size objects within the manager. */
327 /* manager :: A handle to the manager. */
330 FTC_Manager_Reset( FTC_Manager manager
);
333 /*************************************************************************/
336 /* FTC_Manager_Done */
339 /* Destroy a given manager after emptying it. */
342 /* manager :: A handle to the target cache manager object. */
345 FTC_Manager_Done( FTC_Manager manager
);
348 /*************************************************************************/
351 /* FTC_Manager_LookupFace */
354 /* Retrieve the @FT_Face object that corresponds to a given face ID */
355 /* through a cache manager. */
358 /* manager :: A handle to the cache manager. */
360 /* face_id :: The ID of the face object. */
363 /* aface :: A handle to the face object. */
366 /* FreeType error code. 0~means success. */
369 /* The returned @FT_Face object is always owned by the manager. You */
370 /* should never try to discard it yourself. */
372 /* The @FT_Face object doesn't necessarily have a current size object */
373 /* (i.e., face->size can be~0). If you need a specific `font size', */
374 /* use @FTC_Manager_LookupSize instead. */
376 /* Never change the face's transformation matrix (i.e., never call */
377 /* the @FT_Set_Transform function) on a returned face! If you need */
378 /* to transform glyphs, do it yourself after glyph loading. */
380 /* When you perform a lookup, out-of-memory errors are detected */
381 /* _within_ the lookup and force incremental flushes of the cache */
382 /* until enough memory is released for the lookup to succeed. */
384 /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */
385 /* already been completely flushed, and still no memory was available */
386 /* for the operation. */
388 FT_EXPORT( FT_Error
)
389 FTC_Manager_LookupFace( FTC_Manager manager
,
394 /*************************************************************************/
400 /* A structure used to describe a given character size in either */
401 /* pixels or points to the cache manager. See */
402 /* @FTC_Manager_LookupSize. */
405 /* face_id :: The source face ID. */
407 /* width :: The character width. */
409 /* height :: The character height. */
411 /* pixel :: A Boolean. If 1, the `width' and `height' fields are */
412 /* interpreted as integer pixel character sizes. */
413 /* Otherwise, they are expressed as 1/64th of points. */
415 /* x_res :: Only used when `pixel' is value~0 to indicate the */
416 /* horizontal resolution in dpi. */
418 /* y_res :: Only used when `pixel' is value~0 to indicate the */
419 /* vertical resolution in dpi. */
422 /* This type is mainly used to retrieve @FT_Size objects through the */
425 typedef struct FTC_ScalerRec_
437 /*************************************************************************/
443 /* A handle to an @FTC_ScalerRec structure. */
445 typedef struct FTC_ScalerRec_
* FTC_Scaler
;
448 /*************************************************************************/
451 /* FTC_Manager_LookupSize */
454 /* Retrieve the @FT_Size object that corresponds to a given */
455 /* @FTC_ScalerRec pointer through a cache manager. */
458 /* manager :: A handle to the cache manager. */
460 /* scaler :: A scaler handle. */
463 /* asize :: A handle to the size object. */
466 /* FreeType error code. 0~means success. */
469 /* The returned @FT_Size object is always owned by the manager. You */
470 /* should never try to discard it by yourself. */
472 /* You can access the parent @FT_Face object simply as `size->face' */
473 /* if you need it. Note that this object is also owned by the */
477 /* When you perform a lookup, out-of-memory errors are detected */
478 /* _within_ the lookup and force incremental flushes of the cache */
479 /* until enough memory is released for the lookup to succeed. */
481 /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */
482 /* already been completely flushed, and still no memory is available */
483 /* for the operation. */
485 FT_EXPORT( FT_Error
)
486 FTC_Manager_LookupSize( FTC_Manager manager
,
491 /*************************************************************************/
497 /* Decrement a cache node's internal reference count. When the count */
498 /* reaches 0, it is not destroyed but becomes eligible for subsequent */
502 /* node :: The cache node handle. */
504 /* manager :: The cache manager handle. */
507 FTC_Node_Unref( FTC_Node node
,
508 FTC_Manager manager
);
511 /*************************************************************************
514 * FTC_Manager_RemoveFaceID
517 * A special function used to indicate to the cache manager that
518 * a given @FTC_FaceID is no longer valid, either because its
519 * content changed, or because it was deallocated or uninstalled.
523 * The cache manager handle.
526 * The @FTC_FaceID to be removed.
529 * This function flushes all nodes from the cache corresponding to this
530 * `face_id', with the exception of nodes with a non-null reference
533 * Such nodes are however modified internally so as to never appear
534 * in later lookups with the same `face_id' value, and to be immediately
535 * destroyed when released by all their users.
539 FTC_Manager_RemoveFaceID( FTC_Manager manager
,
540 FTC_FaceID face_id
);
543 /*************************************************************************/
546 /* cache_subsystem */
548 /*************************************************************************/
550 /*************************************************************************
556 * An opaque handle used to model a charmap cache. This cache is to
557 * hold character codes -> glyph indices mappings.
560 typedef struct FTC_CMapCacheRec_
* FTC_CMapCache
;
563 /*************************************************************************
569 * Create a new charmap cache.
573 * A handle to the cache manager.
577 * A new cache handle. NULL in case of error.
580 * FreeType error code. 0~means success.
583 * Like all other caches, this one will be destroyed with the cache
587 FT_EXPORT( FT_Error
)
588 FTC_CMapCache_New( FTC_Manager manager
,
589 FTC_CMapCache
*acache
);
592 /************************************************************************
595 * FTC_CMapCache_Lookup
598 * Translate a character code into a glyph index, using the charmap
603 * A charmap cache handle.
606 * The source face ID.
609 * The index of the charmap in the source face. Any negative value
610 * means to use the cache @FT_Face's default charmap.
613 * The character code (in the corresponding charmap).
616 * Glyph index. 0~means `no glyph'.
620 FTC_CMapCache_Lookup( FTC_CMapCache cache
,
623 FT_UInt32 char_code
);
626 /*************************************************************************/
629 /* cache_subsystem */
631 /*************************************************************************/
634 /*************************************************************************/
635 /*************************************************************************/
636 /*************************************************************************/
638 /***** IMAGE CACHE OBJECT *****/
640 /*************************************************************************/
641 /*************************************************************************/
642 /*************************************************************************/
645 /*************************************************************************
651 * A structure used to model the type of images in a glyph cache.
658 * The width in pixels.
661 * The height in pixels.
664 * The load flags, as in @FT_Load_Glyph.
667 typedef struct FTC_ImageTypeRec_
677 /*************************************************************************
683 * A handle to an @FTC_ImageTypeRec structure.
686 typedef struct FTC_ImageTypeRec_
* FTC_ImageType
;
692 #define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \
693 ( (d1)->face_id == (d2)->face_id && \
694 (d1)->width == (d2)->width && \
695 (d1)->flags == (d2)->flags )
698 /*************************************************************************/
704 /* A handle to a glyph image cache object. They are designed to */
705 /* hold many distinct glyph images while not exceeding a certain */
706 /* memory threshold. */
708 typedef struct FTC_ImageCacheRec_
* FTC_ImageCache
;
711 /*************************************************************************/
714 /* FTC_ImageCache_New */
717 /* Create a new glyph image cache. */
720 /* manager :: The parent manager for the image cache. */
723 /* acache :: A handle to the new glyph image cache object. */
726 /* FreeType error code. 0~means success. */
728 FT_EXPORT( FT_Error
)
729 FTC_ImageCache_New( FTC_Manager manager
,
730 FTC_ImageCache
*acache
);
733 /*************************************************************************/
736 /* FTC_ImageCache_Lookup */
739 /* Retrieve a given glyph image from a glyph image cache. */
742 /* cache :: A handle to the source glyph image cache. */
744 /* type :: A pointer to a glyph image type descriptor. */
746 /* gindex :: The glyph index to retrieve. */
749 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */
752 /* anode :: Used to return the address of of the corresponding cache */
753 /* node after incrementing its reference count (see note */
757 /* FreeType error code. 0~means success. */
760 /* The returned glyph is owned and managed by the glyph image cache. */
761 /* Never try to transform or discard it manually! You can however */
762 /* create a copy with @FT_Glyph_Copy and modify the new one. */
764 /* If `anode' is _not_ NULL, it receives the address of the cache */
765 /* node containing the glyph image, after increasing its reference */
766 /* count. This ensures that the node (as well as the @FT_Glyph) will */
767 /* always be kept in the cache until you call @FTC_Node_Unref to */
770 /* If `anode' is NULL, the cache node is left unchanged, which means */
771 /* that the @FT_Glyph could be flushed out of the cache on the next */
772 /* call to one of the caching sub-system APIs. Don't assume that it */
775 FT_EXPORT( FT_Error
)
776 FTC_ImageCache_Lookup( FTC_ImageCache cache
,
783 /*************************************************************************/
786 /* FTC_ImageCache_LookupScaler */
789 /* A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec */
790 /* to specify the face ID and its size. */
793 /* cache :: A handle to the source glyph image cache. */
795 /* scaler :: A pointer to a scaler descriptor. */
797 /* load_flags :: The corresponding load flags. */
799 /* gindex :: The glyph index to retrieve. */
802 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */
805 /* anode :: Used to return the address of of the corresponding */
806 /* cache node after incrementing its reference count */
807 /* (see note below). */
810 /* FreeType error code. 0~means success. */
813 /* The returned glyph is owned and managed by the glyph image cache. */
814 /* Never try to transform or discard it manually! You can however */
815 /* create a copy with @FT_Glyph_Copy and modify the new one. */
817 /* If `anode' is _not_ NULL, it receives the address of the cache */
818 /* node containing the glyph image, after increasing its reference */
819 /* count. This ensures that the node (as well as the @FT_Glyph) will */
820 /* always be kept in the cache until you call @FTC_Node_Unref to */
823 /* If `anode' is NULL, the cache node is left unchanged, which means */
824 /* that the @FT_Glyph could be flushed out of the cache on the next */
825 /* call to one of the caching sub-system APIs. Don't assume that it */
828 /* Calls to @FT_Set_Char_Size and friends have no effect on cached */
829 /* glyphs; you should always use the FreeType cache API instead. */
831 FT_EXPORT( FT_Error
)
832 FTC_ImageCache_LookupScaler( FTC_ImageCache cache
,
840 /*************************************************************************/
846 /* A handle to a small bitmap descriptor. See the @FTC_SBitRec */
847 /* structure for details. */
849 typedef struct FTC_SBitRec_
* FTC_SBit
;
852 /*************************************************************************/
858 /* A very compact structure used to describe a small glyph bitmap. */
861 /* width :: The bitmap width in pixels. */
863 /* height :: The bitmap height in pixels. */
865 /* left :: The horizontal distance from the pen position to the */
866 /* left bitmap border (a.k.a. `left side bearing', or */
869 /* top :: The vertical distance from the pen position (on the */
870 /* baseline) to the upper bitmap border (a.k.a. `top */
871 /* side bearing'). The distance is positive for upwards */
874 /* format :: The format of the glyph bitmap (monochrome or gray). */
876 /* max_grays :: Maximum gray level value (in the range 1 to~255). */
878 /* pitch :: The number of bytes per bitmap line. May be positive */
881 /* xadvance :: The horizontal advance width in pixels. */
883 /* yadvance :: The vertical advance height in pixels. */
885 /* buffer :: A pointer to the bitmap pixels. */
887 typedef struct FTC_SBitRec_
905 /*************************************************************************/
911 /* A handle to a small bitmap cache. These are special cache objects */
912 /* used to store small glyph bitmaps (and anti-aliased pixmaps) in a */
913 /* much more efficient way than the traditional glyph image cache */
914 /* implemented by @FTC_ImageCache. */
916 typedef struct FTC_SBitCacheRec_
* FTC_SBitCache
;
919 /*************************************************************************/
922 /* FTC_SBitCache_New */
925 /* Create a new cache to store small glyph bitmaps. */
928 /* manager :: A handle to the source cache manager. */
931 /* acache :: A handle to the new sbit cache. NULL in case of error. */
934 /* FreeType error code. 0~means success. */
936 FT_EXPORT( FT_Error
)
937 FTC_SBitCache_New( FTC_Manager manager
,
938 FTC_SBitCache
*acache
);
941 /*************************************************************************/
944 /* FTC_SBitCache_Lookup */
947 /* Look up a given small glyph bitmap in a given sbit cache and */
948 /* `lock' it to prevent its flushing from the cache until needed. */
951 /* cache :: A handle to the source sbit cache. */
953 /* type :: A pointer to the glyph image type descriptor. */
955 /* gindex :: The glyph index. */
958 /* sbit :: A handle to a small bitmap descriptor. */
960 /* anode :: Used to return the address of of the corresponding cache */
961 /* node after incrementing its reference count (see note */
965 /* FreeType error code. 0~means success. */
968 /* The small bitmap descriptor and its bit buffer are owned by the */
969 /* cache and should never be freed by the application. They might */
970 /* as well disappear from memory on the next cache lookup, so don't */
971 /* treat them as persistent data. */
973 /* The descriptor's `buffer' field is set to~0 to indicate a missing */
976 /* If `anode' is _not_ NULL, it receives the address of the cache */
977 /* node containing the bitmap, after increasing its reference count. */
978 /* This ensures that the node (as well as the image) will always be */
979 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */
981 /* If `anode' is NULL, the cache node is left unchanged, which means */
982 /* that the bitmap could be flushed out of the cache on the next */
983 /* call to one of the caching sub-system APIs. Don't assume that it */
986 FT_EXPORT( FT_Error
)
987 FTC_SBitCache_Lookup( FTC_SBitCache cache
,
994 /*************************************************************************/
997 /* FTC_SBitCache_LookupScaler */
1000 /* A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec */
1001 /* to specify the face ID and its size. */
1004 /* cache :: A handle to the source sbit cache. */
1006 /* scaler :: A pointer to the scaler descriptor. */
1008 /* load_flags :: The corresponding load flags. */
1010 /* gindex :: The glyph index. */
1013 /* sbit :: A handle to a small bitmap descriptor. */
1015 /* anode :: Used to return the address of of the corresponding */
1016 /* cache node after incrementing its reference count */
1017 /* (see note below). */
1020 /* FreeType error code. 0~means success. */
1023 /* The small bitmap descriptor and its bit buffer are owned by the */
1024 /* cache and should never be freed by the application. They might */
1025 /* as well disappear from memory on the next cache lookup, so don't */
1026 /* treat them as persistent data. */
1028 /* The descriptor's `buffer' field is set to~0 to indicate a missing */
1031 /* If `anode' is _not_ NULL, it receives the address of the cache */
1032 /* node containing the bitmap, after increasing its reference count. */
1033 /* This ensures that the node (as well as the image) will always be */
1034 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */
1036 /* If `anode' is NULL, the cache node is left unchanged, which means */
1037 /* that the bitmap could be flushed out of the cache on the next */
1038 /* call to one of the caching sub-system APIs. Don't assume that it */
1039 /* is persistent! */
1041 FT_EXPORT( FT_Error
)
1042 FTC_SBitCache_LookupScaler( FTC_SBitCache cache
,
1044 FT_ULong load_flags
,
1054 #endif /* __FTCACHE_H__ */