1 /***************************************************************************/
5 /* FreeType Cache subsystem (specification). */
7 /* Copyright 1996-2001, 2002, 2003, 2004 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 /***************************************************************************/
19 /*************************************************************************/
20 /*************************************************************************/
21 /*************************************************************************/
22 /*************************************************************************/
23 /*************************************************************************/
25 /********* WARNING, THIS IS BETA CODE. *********/
27 /*************************************************************************/
28 /*************************************************************************/
29 /*************************************************************************/
30 /*************************************************************************/
31 /*************************************************************************/
45 /*************************************************************************/
51 /* Cache Sub-System */
54 /* How to cache face, size, and glyph data with FreeType 2. */
57 /* This section describes the FreeType 2 cache sub-system which is */
63 /* FTC_Face_Requester */
66 /* FTC_Manager_Reset */
67 /* FTC_Manager_Done */
68 /* FTC_Manager_LookupFace */
69 /* FTC_Manager_LookupSize */
70 /* FTC_Manager_RemoveFaceID */
77 /* FTC_ImageCache_New */
78 /* FTC_ImageCache_Lookup */
82 /* FTC_SBitCache_New */
83 /* FTC_SBitCache_Lookup */
86 /* FTC_CMapCache_New */
87 /* FTC_CMapCache_Lookup */
89 /*************************************************************************/
92 /*************************************************************************/
93 /*************************************************************************/
94 /*************************************************************************/
96 /***** BASIC TYPE DEFINITIONS *****/
98 /*************************************************************************/
99 /*************************************************************************/
100 /*************************************************************************/
103 /*************************************************************************/
109 /* An opaque pointer type that is used to identity face objects. The */
110 /* contents of such objects is application-dependent. */
112 typedef struct FTC_FaceIDRec_* FTC_FaceID;
115 /*************************************************************************/
118 /* FTC_Face_Requester */
121 /* A callback function provided by client applications. It is used */
122 /* to translate a given @FTC_FaceID into a new valid @FT_Face object. */
125 /* face_id :: The face ID to resolve. */
127 /* library :: A handle to a FreeType library object. */
129 /* data :: Application-provided request data. */
132 /* aface :: A new @FT_Face handle. */
135 /* FreeType error code. 0 means success. */
138 /* The face requester should not perform funny things on the returned */
139 /* face object, like creating a new @FT_Size for it, or setting a */
140 /* transformation through @FT_Set_Transform! */
143 (*FTC_Face_Requester)( FTC_FaceID face_id,
145 FT_Pointer request_data,
149 /*************************************************************************/
155 /* A simple structure used to describe a given `font' to the cache */
156 /* manager. Note that a `font' is the combination of a given face */
157 /* with a given character size. */
160 /* face_id :: The ID of the face to use. */
162 /* pix_width :: The character width in integer pixels. */
164 /* pix_height :: The character height in integer pixels. */
166 typedef struct FTC_FontRec_
170 FT_UShort pix_height;
178 #define FTC_FONT_COMPARE( f1, f2 ) \
179 ( (f1)->face_id == (f2)->face_id && \
180 (f1)->pix_width == (f2)->pix_width && \
181 (f1)->pix_height == (f2)->pix_height )
183 #define FT_POINTER_TO_ULONG( p ) ((FT_ULong)(FT_Pointer)(p))
185 #define FTC_FACE_ID_HASH( i ) \
186 ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \
187 ( FT_POINTER_TO_ULONG( i ) << 7 ) ) )
189 #define FTC_FONT_HASH( f ) \
190 (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \
191 ((f)->pix_width << 8) ^ \
195 /*************************************************************************/
201 /* A simple handle to an @FTC_FontRec structure. */
203 typedef FTC_FontRec* FTC_Font;
206 /*************************************************************************/
207 /*************************************************************************/
208 /*************************************************************************/
210 /***** CACHE MANAGER OBJECT *****/
212 /*************************************************************************/
213 /*************************************************************************/
214 /*************************************************************************/
217 /*************************************************************************/
223 /* This object is used to cache one or more @FT_Face objects, along */
224 /* with corresponding @FT_Size objects. */
226 typedef struct FTC_ManagerRec_* FTC_Manager;
229 /*************************************************************************/
235 /* An opaque handle to a cache node object. Each cache node is */
236 /* reference-counted. A node with a count of 0 might be flushed */
237 /* out of a full cache whenever a lookup request is performed. */
239 /* If you lookup nodes, you have the ability to "acquire" them, i.e., */
240 /* to increment their reference count. This will prevent the node */
241 /* from being flushed out of the cache until you explicitly "release" */
242 /* it (see @FTC_Node_Unref). */
244 /* See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup. */
246 typedef struct FTC_NodeRec_* FTC_Node;
249 /*************************************************************************/
252 /* FTC_Manager_New */
255 /* Creates a new cache manager. */
258 /* library :: The parent FreeType library handle to use. */
260 /* max_bytes :: Maximum number of bytes to use for cached data. */
261 /* Use 0 for defaults. */
263 /* requester :: An application-provided callback used to translate */
264 /* face IDs into real @FT_Face objects. */
266 /* req_data :: A generic pointer that is passed to the requester */
267 /* each time it is called (see @FTC_Face_Requester). */
270 /* amanager :: A handle to a new manager object. 0 in case of */
274 /* FreeType error code. 0 means success. */
276 FT_EXPORT( FT_Error )
277 FTC_Manager_New( FT_Library library,
281 FTC_Face_Requester requester,
283 FTC_Manager *amanager );
286 /*************************************************************************/
289 /* FTC_Manager_Reset */
292 /* Empties a given cache manager. This simply gets rid of all the */
293 /* currently cached @FT_Face and @FT_Size objects within the manager. */
296 /* manager :: A handle to the manager. */
299 FTC_Manager_Reset( FTC_Manager manager );
302 /*************************************************************************/
305 /* FTC_Manager_Done */
308 /* Destroys a given manager after emptying it. */
311 /* manager :: A handle to the target cache manager object. */
314 FTC_Manager_Done( FTC_Manager manager );
317 /*************************************************************************/
320 /* FTC_Manager_LookupFace */
323 /* Retrieves the @FT_Face object that corresponds to a given face ID */
324 /* through a cache manager. */
327 /* manager :: A handle to the cache manager. */
329 /* face_id :: The ID of the face object. */
332 /* aface :: A handle to the face object. */
335 /* FreeType error code. 0 means success. */
338 /* The returned @FT_Face object is always owned by the manager. You */
339 /* should never try to discard it yourself. */
341 /* The @FT_Face object doesn't necessarily have a current size object */
342 /* (i.e., face->size can be 0). If you need a specific `font size', */
343 /* use @FTC_Manager_LookupSize instead. */
345 /* Never change the face's transformation matrix (i.e., never call */
346 /* the @FT_Set_Transform function) on a returned face! If you need */
347 /* to transform glyphs, do it yourself after glyph loading. */
349 FT_EXPORT( FT_Error )
350 FTC_Manager_LookupFace( FTC_Manager manager,
355 /*************************************************************************/
361 /* A structure used to describe a given character size in either */
362 /* pixels or points to the cache manager. See */
363 /* @FTC_Manager_LookupSize. */
366 /* face_id :: The source face ID. */
368 /* width :: The character width. */
370 /* height :: The character height. */
372 /* pixel :: A Boolean. If TRUE, the `width' and `height' fields */
373 /* are interpreted as integer pixel character sizes. */
374 /* Otherwise, they are expressed as 1/64th of points. */
376 /* x_res :: Only used when `pixel' is FALSE to indicate the */
377 /* horizontal resolution in dpi. */
379 /* y_res :: Only used when `pixel' is FALSE to indicate the */
380 /* vertical resolution in dpi. */
383 /* This type is mainly used to retrieve @FT_Size objects through the */
386 typedef struct FTC_ScalerRec_
395 } FTC_ScalerRec, *FTC_Scaler;
398 /*************************************************************************/
401 /* FTC_Manager_LookupSize */
404 /* Retrieve the @FT_Size object that corresponds to a given */
405 /* @FTC_Scaler through a cache manager. */
408 /* manager :: A handle to the cache manager. */
410 /* scaler :: A scaler handle. */
413 /* asize :: A handle to the size object. */
416 /* FreeType error code. 0 means success. */
419 /* The returned @FT_Size object is always owned by the manager. You */
420 /* should never try to discard it by yourself. */
422 /* You can access the parent @FT_Face object simply as `size->face' */
423 /* if you need it. Note that this object is also owned by the */
426 FT_EXPORT( FT_Error )
427 FTC_Manager_LookupSize( FTC_Manager manager,
432 /*************************************************************************/
438 /* Decrement a cache node's internal reference count. When the count */
439 /* reaches 0, it is not destroyed but becomes eligible for subsequent */
443 /* node :: The cache node handle. */
445 /* manager :: The cache manager handle. */
448 FTC_Node_Unref( FTC_Node node,
449 FTC_Manager manager );
452 /* remove all nodes belonging to a given face_id */
454 FTC_Manager_RemoveFaceID( FTC_Manager manager,
455 FTC_FaceID face_id );
458 /*************************************************************************/
461 /* cache_subsystem */
463 /*************************************************************************/
465 /************************************************************************
471 * An opaque handle used to manager a charmap cache. This cache is
472 * to hold character codes -> glyph indices mappings.
474 typedef struct FTC_CMapCacheRec_* FTC_CMapCache;
477 /*************************************************************************/
480 /* FTC_CMapCache_New */
483 /* Create a new charmap cache. */
486 /* manager :: A handle to the cache manager. */
489 /* acache :: A new cache handle. NULL in case of error. */
492 /* FreeType error code. 0 means success. */
495 /* Like all other caches, this one will be destroyed with the cache */
498 FT_EXPORT( FT_Error )
499 FTC_CMapCache_New( FTC_Manager manager,
500 FTC_CMapCache *acache );
503 /*************************************************************************/
506 /* FTC_CMapCache_Lookup */
509 /* Translate a character code into a glyph index, using the charmap */
513 /* cache :: A charmap cache handle. */
515 /* face_id :: The source face ID. */
517 /* cmap_index :: The index of the charmap in the source face. */
519 /* char_code :: The character code (in the corresponding charmap). */
522 /* Glyph index. 0 means `no glyph'. */
525 FTC_CMapCache_Lookup( FTC_CMapCache cache,
528 FT_UInt32 char_code );
531 /*************************************************************************/
534 /* cache_subsystem */
536 /*************************************************************************/
539 /*************************************************************************/
540 /*************************************************************************/
541 /*************************************************************************/
543 /***** IMAGE CACHE OBJECT *****/
545 /*************************************************************************/
546 /*************************************************************************/
547 /*************************************************************************/
549 typedef struct FTC_ImageTypeRec_
558 typedef struct FTC_ImageTypeRec_* FTC_ImageType;
562 #define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \
563 ( FTC_FONT_COMPARE( &(d1)->font, &(d2)->font ) && \
564 (d1)->flags == (d2)->flags )
566 #define FTC_IMAGE_TYPE_HASH( d ) \
567 (FT_UFast)( FTC_FONT_HASH( &(d)->font ) ^ \
568 ( (d)->flags << 4 ) )
571 /*************************************************************************/
577 /* A handle to an glyph image cache object. They are designed to */
578 /* hold many distinct glyph images while not exceeding a certain */
579 /* memory threshold. */
581 typedef struct FTC_ImageCacheRec_* FTC_ImageCache;
584 /*************************************************************************/
587 /* FTC_ImageCache_New */
590 /* Creates a new glyph image cache. */
593 /* manager :: The parent manager for the image cache. */
596 /* acache :: A handle to the new glyph image cache object. */
599 /* FreeType error code. 0 means success. */
601 FT_EXPORT( FT_Error )
602 FTC_ImageCache_New( FTC_Manager manager,
603 FTC_ImageCache *acache );
606 /*************************************************************************/
609 /* FTC_ImageCache_Lookup */
612 /* Retrieves a given glyph image from a glyph image cache. */
615 /* cache :: A handle to the source glyph image cache. */
617 /* type :: A pointer to a glyph image type descriptor. */
619 /* gindex :: The glyph index to retrieve. */
622 /* aglyph :: The corresponding @FT_Glyph object. 0 in case of */
625 /* anode :: Used to return the address of of the corresponding cache */
626 /* node after incrementing its reference count (see note */
630 /* FreeType error code. 0 means success. */
633 /* The returned glyph is owned and managed by the glyph image cache. */
634 /* Never try to transform or discard it manually! You can however */
635 /* create a copy with @FT_Glyph_Copy and modify the new one. */
637 /* If `anode' is _not_ NULL, it receives the address of the cache */
638 /* node containing the glyph image, after increasing its reference */
639 /* count. This ensures that the node (as well as the FT_Glyph) will */
640 /* always be kept in the cache until you call @FTC_Node_Unref to */
643 /* If `anode' is NULL, the cache node is left unchanged, which means */
644 /* that the FT_Glyph could be flushed out of the cache on the next */
645 /* call to one of the caching sub-system APIs. Don't assume that it */
648 FT_EXPORT( FT_Error )
649 FTC_ImageCache_Lookup( FTC_ImageCache cache,
656 /*************************************************************************/
662 /* A handle to a small bitmap descriptor. See the @FTC_SBitRec */
663 /* structure for details. */
665 typedef struct FTC_SBitRec_* FTC_SBit;
668 /*************************************************************************/
674 /* A very compact structure used to describe a small glyph bitmap. */
677 /* width :: The bitmap width in pixels. */
679 /* height :: The bitmap height in pixels. */
681 /* left :: The horizontal distance from the pen position to the */
682 /* left bitmap border (a.k.a. `left side bearing', or */
685 /* top :: The vertical distance from the pen position (on the */
686 /* baseline) to the upper bitmap border (a.k.a. `top */
687 /* side bearing'). The distance is positive for upwards */
690 /* format :: The format of the glyph bitmap (monochrome or gray). */
692 /* max_grays :: Maximum gray level value (in the range 1 to 255). */
694 /* pitch :: The number of bytes per bitmap line. May be positive */
697 /* xadvance :: The horizontal advance width in pixels. */
699 /* yadvance :: The vertical advance height in pixels. */
701 /* buffer :: A pointer to the bitmap pixels. */
703 typedef struct FTC_SBitRec_
721 /*************************************************************************/
727 /* A handle to a small bitmap cache. These are special cache objects */
728 /* used to store small glyph bitmaps (and anti-aliased pixmaps) in a */
729 /* much more efficient way than the traditional glyph image cache */
730 /* implemented by @FTC_ImageCache. */
732 typedef struct FTC_SBitCacheRec_* FTC_SBitCache;
735 /*************************************************************************/
738 /* FTC_SBitCache_New */
741 /* Creates a new cache to store small glyph bitmaps. */
744 /* manager :: A handle to the source cache manager. */
747 /* acache :: A handle to the new sbit cache. NULL in case of error. */
750 /* FreeType error code. 0 means success. */
752 FT_EXPORT( FT_Error )
753 FTC_SBitCache_New( FTC_Manager manager,
754 FTC_SBitCache *acache );
757 /*************************************************************************/
760 /* FTC_SBitCache_Lookup */
763 /* Looks up a given small glyph bitmap in a given sbit cache and */
764 /* `lock' it to prevent its flushing from the cache until needed. */
767 /* cache :: A handle to the source sbit cache. */
769 /* type :: A pointer to the glyph image type descriptor. */
771 /* gindex :: The glyph index. */
774 /* sbit :: A handle to a small bitmap descriptor. */
776 /* anode :: Used to return the address of of the corresponding cache */
777 /* node after incrementing its reference count (see note */
781 /* FreeType error code. 0 means success. */
784 /* The small bitmap descriptor and its bit buffer are owned by the */
785 /* cache and should never be freed by the application. They might */
786 /* as well disappear from memory on the next cache lookup, so don't */
787 /* treat them as persistent data. */
789 /* The descriptor's `buffer' field is set to 0 to indicate a missing */
792 /* If `anode' is _not_ NULL, it receives the address of the cache */
793 /* node containing the bitmap, after increasing its reference count. */
794 /* This ensures that the node (as well as the image) will always be */
795 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */
797 /* If `anode' is NULL, the cache node is left unchanged, which means */
798 /* that the bitmap could be flushed out of the cache on the next */
799 /* call to one of the caching sub-system APIs. Don't assume that it */
802 FT_EXPORT( FT_Error )
803 FTC_SBitCache_Lookup( FTC_SBitCache cache,
814 #endif /* __FTCACHE_H__ */