1 /***************************************************************************/
5 /* FreeType Cache subsystem (specification). */
7 /* Copyright 1996-2001 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_Lookup_Face */
67 /* FTC_Manager_Lookup_Size */
76 /* FTC_ImageCache_New */
77 /* FTC_ImageCache_Lookup */
81 /* FTC_SBitCache_New */
82 /* FTC_SBitCache_Lookup */
87 /* FTC_Image_Cache_Lookup */
90 /* FTC_SBit_Cache_Lookup */
92 /*************************************************************************/
95 /*************************************************************************/
96 /*************************************************************************/
97 /*************************************************************************/
99 /***** BASIC TYPE DEFINITIONS *****/
101 /*************************************************************************/
102 /*************************************************************************/
103 /*************************************************************************/
106 /*************************************************************************/
112 /* A generic pointer type that is used to identity face objects. The */
113 /* contents of such objects is application-dependent. */
115 typedef FT_Pointer FTC_FaceID;
118 /*************************************************************************/
121 /* FTC_Face_Requester */
124 /* A callback function provided by client applications. It is used */
125 /* to translate a given @FTC_FaceID into a new valid @FT_Face object. */
128 /* face_id :: The face ID to resolve. */
130 /* library :: A handle to a FreeType library object. */
132 /* data :: Application-provided request data. */
135 /* aface :: A new @FT_Face handle. */
138 /* FreeType error code. 0 means success. */
141 /* The face requester should not perform funny things on the returned */
142 /* face object, like creating a new @FT_Size for it, or setting a */
143 /* transformation through @FT_Set_Transform! */
146 (*FTC_Face_Requester)( FTC_FaceID face_id,
148 FT_Pointer request_data,
152 /*************************************************************************/
158 /* A simple structure used to describe a given `font' to the cache */
159 /* manager. Note that a `font' is the combination of a given face */
160 /* with a given character size. */
163 /* face_id :: The ID of the face to use. */
165 /* pix_width :: The character width in integer pixels. */
167 /* pix_height :: The character height in integer pixels. */
169 typedef struct FTC_FontRec_
173 FT_UShort pix_height;
181 #define FTC_FONT_COMPARE( f1, f2 ) \
182 ( (f1)->face_id == (f2)->face_id && \
183 (f1)->pix_width == (f2)->pix_width && \
184 (f1)->pix_height == (f2)->pix_height )
186 #define FT_POINTER_TO_ULONG( p ) ((FT_ULong)(FT_Pointer)(p))
188 #define FTC_FACE_ID_HASH( i ) \
189 ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \
190 ( FT_POINTER_TO_ULONG( i ) << 7 ) ) )
192 #define FTC_FONT_HASH( f ) \
193 (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \
194 ((f)->pix_width << 8) ^ \
198 /*************************************************************************/
204 /* A simple handle to an @FTC_FontRec structure. */
206 typedef FTC_FontRec* FTC_Font;
209 /*************************************************************************/
210 /*************************************************************************/
211 /*************************************************************************/
213 /***** CACHE MANAGER OBJECT *****/
215 /*************************************************************************/
216 /*************************************************************************/
217 /*************************************************************************/
220 /*************************************************************************/
226 /* This object is used to cache one or more @FT_Face objects, along */
227 /* with corresponding @FT_Size objects. */
229 typedef struct FTC_ManagerRec_* FTC_Manager;
232 /*************************************************************************/
238 /* An opaque handle to a cache node object. Each cache node is */
239 /* reference-counted. A node with a count of 0 might be flushed */
240 /* out of a full cache whenever a lookup request is performed. */
242 /* If you lookup nodes, you have the ability to "acquire" them, i.e., */
243 /* to increment their reference count. This will prevent the node */
244 /* from being flushed out of the cache until you explicitly "release" */
245 /* it (see @FTC_Node_Release). */
247 /* See also @FTC_BitsetCache_Lookup and @FTC_ImageCache_Lookup. */
249 typedef struct FTC_NodeRec_* FTC_Node;
252 /*************************************************************************/
255 /* FTC_Manager_New */
258 /* Creates a new cache manager. */
261 /* library :: The parent FreeType library handle to use. */
263 /* max_faces :: Maximum number of faces to keep alive in manager. */
264 /* Use 0 for defaults. */
266 /* max_sizes :: Maximum number of sizes to keep alive in manager. */
267 /* Use 0 for defaults. */
269 /* max_bytes :: Maximum number of bytes to use for cached data. */
270 /* Use 0 for defaults. */
272 /* requester :: An application-provided callback used to translate */
273 /* face IDs into real @FT_Face objects. */
275 /* req_data :: A generic pointer that is passed to the requester */
276 /* each time it is called (see @FTC_Face_Requester). */
279 /* amanager :: A handle to a new manager object. 0 in case of */
283 /* FreeType error code. 0 means success. */
285 FT_EXPORT( FT_Error )
286 FTC_Manager_New( FT_Library library,
290 FTC_Face_Requester requester,
292 FTC_Manager *amanager );
295 /*************************************************************************/
298 /* FTC_Manager_Reset */
301 /* Empties a given cache manager. This simply gets rid of all the */
302 /* currently cached @FT_Face and @FT_Size objects within the manager. */
305 /* manager :: A handle to the manager. */
308 FTC_Manager_Reset( FTC_Manager manager );
311 /*************************************************************************/
314 /* FTC_Manager_Done */
317 /* Destroys a given manager after emptying it. */
320 /* manager :: A handle to the target cache manager object. */
323 FTC_Manager_Done( FTC_Manager manager );
326 /*************************************************************************/
329 /* FTC_Manager_Lookup_Face */
332 /* Retrieves the @FT_Face object that corresponds to a given face ID */
333 /* through a cache manager. */
336 /* manager :: A handle to the cache manager. */
338 /* face_id :: The ID of the face object. */
341 /* aface :: A handle to the face object. */
344 /* FreeType error code. 0 means success. */
347 /* The returned @FT_Face object is always owned by the manager. You */
348 /* should never try to discard it yourself. */
350 /* The @FT_Face object doesn't necessarily have a current size object */
351 /* (i.e., face->size can be 0). If you need a specific `font size', */
352 /* use @FTC_Manager_Lookup_Size instead. */
354 /* Never change the face's transformation matrix (i.e., never call */
355 /* the @FT_Set_Transform function) on a returned face! If you need */
356 /* to transform glyphs, do it yourself after glyph loading. */
358 FT_EXPORT( FT_Error )
359 FTC_Manager_Lookup_Face( FTC_Manager manager,
364 /*************************************************************************/
367 /* FTC_Manager_Lookup_Size */
370 /* Retrieves the @FT_Face and @FT_Size objects that correspond to a */
371 /* given @FTC_SizeID. */
374 /* manager :: A handle to the cache manager. */
376 /* size_id :: The ID of the `font size' to use. */
379 /* aface :: A pointer to the handle of the face object. Set it to */
380 /* zero if you don't need it. */
382 /* asize :: A pointer to the handle of the size object. Set it to */
383 /* zero if you don't need it. */
386 /* FreeType error code. 0 means success. */
389 /* The returned @FT_Face object is always owned by the manager. You */
390 /* should never try to discard it yourself. */
392 /* Never change the face's transformation matrix (i.e., never call */
393 /* the @FT_Set_Transform function) on a returned face! If you need */
394 /* to transform glyphs, do it yourself after glyph loading. */
396 /* Similarly, the returned @FT_Size object is always owned by the */
397 /* manager. You should never try to discard it, and never change its */
398 /* settings with @FT_Set_Pixel_Sizes or @FT_Set_Char_Size! */
400 /* The returned size object is the face's current size, which means */
401 /* that you can call @FT_Load_Glyph with the face if you need to. */
403 FT_EXPORT( FT_Error )
404 FTC_Manager_Lookup_Size( FTC_Manager manager,
412 #endif /* __FTCACHE_H__ */