|
1 /***************************************************************************/ |
|
2 /* */ |
|
3 /* ftcache.h */ |
|
4 /* */ |
|
5 /* FreeType Cache subsystem (specification). */ |
|
6 /* */ |
|
7 /* Copyright 1996-2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010 by */ |
|
8 /* David Turner, Robert Wilhelm, and Werner Lemberg. */ |
|
9 /* */ |
|
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. */ |
|
15 /* */ |
|
16 /***************************************************************************/ |
|
17 |
|
18 |
|
19 #ifndef __FTCACHE_H__ |
|
20 #define __FTCACHE_H__ |
|
21 |
|
22 |
|
23 #include <ft2build.h> |
|
24 #include FT_GLYPH_H |
|
25 |
|
26 |
|
27 FT_BEGIN_HEADER |
|
28 |
|
29 |
|
30 /************************************************************************* |
|
31 * |
|
32 * <Section> |
|
33 * cache_subsystem |
|
34 * |
|
35 * <Title> |
|
36 * Cache Sub-System |
|
37 * |
|
38 * <Abstract> |
|
39 * How to cache face, size, and glyph data with FreeType~2. |
|
40 * |
|
41 * <Description> |
|
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. |
|
46 * |
|
47 * Note that all types and functions begin with the `FTC_' prefix. |
|
48 * |
|
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: |
|
52 * |
|
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. |
|
57 * |
|
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 |
|
64 * face. |
|
65 * |
|
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 |
|
69 * possible. |
|
70 * |
|
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. |
|
74 * |
|
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 |
|
79 * or even crashes. |
|
80 * |
|
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. |
|
85 * |
|
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. |
|
89 * |
|
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. |
|
93 * |
|
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). |
|
99 * |
|
100 * We hope to also provide a kerning cache in the near future. |
|
101 * |
|
102 * |
|
103 * <Order> |
|
104 * FTC_Manager |
|
105 * FTC_FaceID |
|
106 * FTC_Face_Requester |
|
107 * |
|
108 * FTC_Manager_New |
|
109 * FTC_Manager_Reset |
|
110 * FTC_Manager_Done |
|
111 * FTC_Manager_LookupFace |
|
112 * FTC_Manager_LookupSize |
|
113 * FTC_Manager_RemoveFaceID |
|
114 * |
|
115 * FTC_Node |
|
116 * FTC_Node_Unref |
|
117 * |
|
118 * FTC_ImageCache |
|
119 * FTC_ImageCache_New |
|
120 * FTC_ImageCache_Lookup |
|
121 * |
|
122 * FTC_SBit |
|
123 * FTC_SBitCache |
|
124 * FTC_SBitCache_New |
|
125 * FTC_SBitCache_Lookup |
|
126 * |
|
127 * FTC_CMapCache |
|
128 * FTC_CMapCache_New |
|
129 * FTC_CMapCache_Lookup |
|
130 * |
|
131 *************************************************************************/ |
|
132 |
|
133 |
|
134 /*************************************************************************/ |
|
135 /*************************************************************************/ |
|
136 /*************************************************************************/ |
|
137 /***** *****/ |
|
138 /***** BASIC TYPE DEFINITIONS *****/ |
|
139 /***** *****/ |
|
140 /*************************************************************************/ |
|
141 /*************************************************************************/ |
|
142 /*************************************************************************/ |
|
143 |
|
144 |
|
145 /************************************************************************* |
|
146 * |
|
147 * @type: FTC_FaceID |
|
148 * |
|
149 * @description: |
|
150 * An opaque pointer type that is used to identity face objects. The |
|
151 * contents of such objects is application-dependent. |
|
152 * |
|
153 * These pointers are typically used to point to a user-defined |
|
154 * structure containing a font file path, and face index. |
|
155 * |
|
156 * @note: |
|
157 * Never use NULL as a valid @FTC_FaceID. |
|
158 * |
|
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 |
|
161 * @FT_Face objects. |
|
162 * |
|
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 |
|
166 * function. |
|
167 * |
|
168 * Failure to do so will result in incorrect behaviour or even |
|
169 * memory leaks and crashes. |
|
170 */ |
|
171 typedef FT_Pointer FTC_FaceID; |
|
172 |
|
173 |
|
174 /************************************************************************ |
|
175 * |
|
176 * @functype: |
|
177 * FTC_Face_Requester |
|
178 * |
|
179 * @description: |
|
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. |
|
183 * |
|
184 * <Input> |
|
185 * face_id :: |
|
186 * The face ID to resolve. |
|
187 * |
|
188 * library :: |
|
189 * A handle to a FreeType library object. |
|
190 * |
|
191 * req_data :: |
|
192 * Application-provided request data (see note below). |
|
193 * |
|
194 * <Output> |
|
195 * aface :: |
|
196 * A new @FT_Face handle. |
|
197 * |
|
198 * <Return> |
|
199 * FreeType error code. 0~means success. |
|
200 * |
|
201 * <Note> |
|
202 * The third parameter `req_data' is the same as the one passed by the |
|
203 * client when @FTC_Manager_New is called. |
|
204 * |
|
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! |
|
208 */ |
|
209 typedef FT_Error |
|
210 (*FTC_Face_Requester)( FTC_FaceID face_id, |
|
211 FT_Library library, |
|
212 FT_Pointer request_data, |
|
213 FT_Face* aface ); |
|
214 |
|
215 /* */ |
|
216 |
|
217 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS |
|
218 |
|
219 /* these macros are incompatible with LLP64, should not be used */ |
|
220 |
|
221 #define FT_POINTER_TO_ULONG( p ) ( (FT_ULong)(FT_Pointer)(p) ) |
|
222 |
|
223 #define FTC_FACE_ID_HASH( i ) \ |
|
224 ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \ |
|
225 ( FT_POINTER_TO_ULONG( i ) << 7 ) ) ) |
|
226 |
|
227 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */ |
|
228 |
|
229 /*************************************************************************/ |
|
230 /*************************************************************************/ |
|
231 /*************************************************************************/ |
|
232 /***** *****/ |
|
233 /***** CACHE MANAGER OBJECT *****/ |
|
234 /***** *****/ |
|
235 /*************************************************************************/ |
|
236 /*************************************************************************/ |
|
237 /*************************************************************************/ |
|
238 |
|
239 |
|
240 /*************************************************************************/ |
|
241 /* */ |
|
242 /* <Type> */ |
|
243 /* FTC_Manager */ |
|
244 /* */ |
|
245 /* <Description> */ |
|
246 /* This object corresponds to one instance of the cache-subsystem. */ |
|
247 /* It is used to cache one or more @FT_Face objects, along with */ |
|
248 /* corresponding @FT_Size objects. */ |
|
249 /* */ |
|
250 /* The manager intentionally limits the total number of opened */ |
|
251 /* @FT_Face and @FT_Size objects to control memory usage. See the */ |
|
252 /* `max_faces' and `max_sizes' parameters of @FTC_Manager_New. */ |
|
253 /* */ |
|
254 /* The manager is also used to cache `nodes' of various types while */ |
|
255 /* limiting their total memory usage. */ |
|
256 /* */ |
|
257 /* All limitations are enforced by keeping lists of managed objects */ |
|
258 /* in most-recently-used order, and flushing old nodes to make room */ |
|
259 /* for new ones. */ |
|
260 /* */ |
|
261 typedef struct FTC_ManagerRec_* FTC_Manager; |
|
262 |
|
263 |
|
264 /*************************************************************************/ |
|
265 /* */ |
|
266 /* <Type> */ |
|
267 /* FTC_Node */ |
|
268 /* */ |
|
269 /* <Description> */ |
|
270 /* An opaque handle to a cache node object. Each cache node is */ |
|
271 /* reference-counted. A node with a count of~0 might be flushed */ |
|
272 /* out of a full cache whenever a lookup request is performed. */ |
|
273 /* */ |
|
274 /* If you look up nodes, you have the ability to `acquire' them, */ |
|
275 /* i.e., to increment their reference count. This will prevent the */ |
|
276 /* node from being flushed out of the cache until you explicitly */ |
|
277 /* `release' it (see @FTC_Node_Unref). */ |
|
278 /* */ |
|
279 /* See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup. */ |
|
280 /* */ |
|
281 typedef struct FTC_NodeRec_* FTC_Node; |
|
282 |
|
283 |
|
284 /*************************************************************************/ |
|
285 /* */ |
|
286 /* <Function> */ |
|
287 /* FTC_Manager_New */ |
|
288 /* */ |
|
289 /* <Description> */ |
|
290 /* Create a new cache manager. */ |
|
291 /* */ |
|
292 /* <Input> */ |
|
293 /* library :: The parent FreeType library handle to use. */ |
|
294 /* */ |
|
295 /* max_faces :: Maximum number of opened @FT_Face objects managed by */ |
|
296 /* this cache instance. Use~0 for defaults. */ |
|
297 /* */ |
|
298 /* max_sizes :: Maximum number of opened @FT_Size objects managed by */ |
|
299 /* this cache instance. Use~0 for defaults. */ |
|
300 /* */ |
|
301 /* max_bytes :: Maximum number of bytes to use for cached data nodes. */ |
|
302 /* Use~0 for defaults. Note that this value does not */ |
|
303 /* account for managed @FT_Face and @FT_Size objects. */ |
|
304 /* */ |
|
305 /* requester :: An application-provided callback used to translate */ |
|
306 /* face IDs into real @FT_Face objects. */ |
|
307 /* */ |
|
308 /* req_data :: A generic pointer that is passed to the requester */ |
|
309 /* each time it is called (see @FTC_Face_Requester). */ |
|
310 /* */ |
|
311 /* <Output> */ |
|
312 /* amanager :: A handle to a new manager object. 0~in case of */ |
|
313 /* failure. */ |
|
314 /* */ |
|
315 /* <Return> */ |
|
316 /* FreeType error code. 0~means success. */ |
|
317 /* */ |
|
318 FT_EXPORT( FT_Error ) |
|
319 FTC_Manager_New( FT_Library library, |
|
320 FT_UInt max_faces, |
|
321 FT_UInt max_sizes, |
|
322 FT_ULong max_bytes, |
|
323 FTC_Face_Requester requester, |
|
324 FT_Pointer req_data, |
|
325 FTC_Manager *amanager ); |
|
326 |
|
327 |
|
328 /*************************************************************************/ |
|
329 /* */ |
|
330 /* <Function> */ |
|
331 /* FTC_Manager_Reset */ |
|
332 /* */ |
|
333 /* <Description> */ |
|
334 /* Empty a given cache manager. This simply gets rid of all the */ |
|
335 /* currently cached @FT_Face and @FT_Size objects within the manager. */ |
|
336 /* */ |
|
337 /* <InOut> */ |
|
338 /* manager :: A handle to the manager. */ |
|
339 /* */ |
|
340 FT_EXPORT( void ) |
|
341 FTC_Manager_Reset( FTC_Manager manager ); |
|
342 |
|
343 |
|
344 /*************************************************************************/ |
|
345 /* */ |
|
346 /* <Function> */ |
|
347 /* FTC_Manager_Done */ |
|
348 /* */ |
|
349 /* <Description> */ |
|
350 /* Destroy a given manager after emptying it. */ |
|
351 /* */ |
|
352 /* <Input> */ |
|
353 /* manager :: A handle to the target cache manager object. */ |
|
354 /* */ |
|
355 FT_EXPORT( void ) |
|
356 FTC_Manager_Done( FTC_Manager manager ); |
|
357 |
|
358 |
|
359 /*************************************************************************/ |
|
360 /* */ |
|
361 /* <Function> */ |
|
362 /* FTC_Manager_LookupFace */ |
|
363 /* */ |
|
364 /* <Description> */ |
|
365 /* Retrieve the @FT_Face object that corresponds to a given face ID */ |
|
366 /* through a cache manager. */ |
|
367 /* */ |
|
368 /* <Input> */ |
|
369 /* manager :: A handle to the cache manager. */ |
|
370 /* */ |
|
371 /* face_id :: The ID of the face object. */ |
|
372 /* */ |
|
373 /* <Output> */ |
|
374 /* aface :: A handle to the face object. */ |
|
375 /* */ |
|
376 /* <Return> */ |
|
377 /* FreeType error code. 0~means success. */ |
|
378 /* */ |
|
379 /* <Note> */ |
|
380 /* The returned @FT_Face object is always owned by the manager. You */ |
|
381 /* should never try to discard it yourself. */ |
|
382 /* */ |
|
383 /* The @FT_Face object doesn't necessarily have a current size object */ |
|
384 /* (i.e., face->size can be 0). If you need a specific `font size', */ |
|
385 /* use @FTC_Manager_LookupSize instead. */ |
|
386 /* */ |
|
387 /* Never change the face's transformation matrix (i.e., never call */ |
|
388 /* the @FT_Set_Transform function) on a returned face! If you need */ |
|
389 /* to transform glyphs, do it yourself after glyph loading. */ |
|
390 /* */ |
|
391 /* When you perform a lookup, out-of-memory errors are detected */ |
|
392 /* _within_ the lookup and force incremental flushes of the cache */ |
|
393 /* until enough memory is released for the lookup to succeed. */ |
|
394 /* */ |
|
395 /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */ |
|
396 /* already been completely flushed, and still no memory was available */ |
|
397 /* for the operation. */ |
|
398 /* */ |
|
399 FT_EXPORT( FT_Error ) |
|
400 FTC_Manager_LookupFace( FTC_Manager manager, |
|
401 FTC_FaceID face_id, |
|
402 FT_Face *aface ); |
|
403 |
|
404 |
|
405 /*************************************************************************/ |
|
406 /* */ |
|
407 /* <Struct> */ |
|
408 /* FTC_ScalerRec */ |
|
409 /* */ |
|
410 /* <Description> */ |
|
411 /* A structure used to describe a given character size in either */ |
|
412 /* pixels or points to the cache manager. See */ |
|
413 /* @FTC_Manager_LookupSize. */ |
|
414 /* */ |
|
415 /* <Fields> */ |
|
416 /* face_id :: The source face ID. */ |
|
417 /* */ |
|
418 /* width :: The character width. */ |
|
419 /* */ |
|
420 /* height :: The character height. */ |
|
421 /* */ |
|
422 /* pixel :: A Boolean. If 1, the `width' and `height' fields are */ |
|
423 /* interpreted as integer pixel character sizes. */ |
|
424 /* Otherwise, they are expressed as 1/64th of points. */ |
|
425 /* */ |
|
426 /* x_res :: Only used when `pixel' is value~0 to indicate the */ |
|
427 /* horizontal resolution in dpi. */ |
|
428 /* */ |
|
429 /* y_res :: Only used when `pixel' is value~0 to indicate the */ |
|
430 /* vertical resolution in dpi. */ |
|
431 /* */ |
|
432 /* <Note> */ |
|
433 /* This type is mainly used to retrieve @FT_Size objects through the */ |
|
434 /* cache manager. */ |
|
435 /* */ |
|
436 typedef struct FTC_ScalerRec_ |
|
437 { |
|
438 FTC_FaceID face_id; |
|
439 FT_UInt width; |
|
440 FT_UInt height; |
|
441 FT_Int pixel; |
|
442 FT_UInt x_res; |
|
443 FT_UInt y_res; |
|
444 |
|
445 } FTC_ScalerRec; |
|
446 |
|
447 |
|
448 /*************************************************************************/ |
|
449 /* */ |
|
450 /* <Struct> */ |
|
451 /* FTC_Scaler */ |
|
452 /* */ |
|
453 /* <Description> */ |
|
454 /* A handle to an @FTC_ScalerRec structure. */ |
|
455 /* */ |
|
456 typedef struct FTC_ScalerRec_* FTC_Scaler; |
|
457 |
|
458 |
|
459 /*************************************************************************/ |
|
460 /* */ |
|
461 /* <Function> */ |
|
462 /* FTC_Manager_LookupSize */ |
|
463 /* */ |
|
464 /* <Description> */ |
|
465 /* Retrieve the @FT_Size object that corresponds to a given */ |
|
466 /* @FTC_ScalerRec pointer through a cache manager. */ |
|
467 /* */ |
|
468 /* <Input> */ |
|
469 /* manager :: A handle to the cache manager. */ |
|
470 /* */ |
|
471 /* scaler :: A scaler handle. */ |
|
472 /* */ |
|
473 /* <Output> */ |
|
474 /* asize :: A handle to the size object. */ |
|
475 /* */ |
|
476 /* <Return> */ |
|
477 /* FreeType error code. 0~means success. */ |
|
478 /* */ |
|
479 /* <Note> */ |
|
480 /* The returned @FT_Size object is always owned by the manager. You */ |
|
481 /* should never try to discard it by yourself. */ |
|
482 /* */ |
|
483 /* You can access the parent @FT_Face object simply as `size->face' */ |
|
484 /* if you need it. Note that this object is also owned by the */ |
|
485 /* manager. */ |
|
486 /* */ |
|
487 /* <Note> */ |
|
488 /* When you perform a lookup, out-of-memory errors are detected */ |
|
489 /* _within_ the lookup and force incremental flushes of the cache */ |
|
490 /* until enough memory is released for the lookup to succeed. */ |
|
491 /* */ |
|
492 /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */ |
|
493 /* already been completely flushed, and still no memory is available */ |
|
494 /* for the operation. */ |
|
495 /* */ |
|
496 FT_EXPORT( FT_Error ) |
|
497 FTC_Manager_LookupSize( FTC_Manager manager, |
|
498 FTC_Scaler scaler, |
|
499 FT_Size *asize ); |
|
500 |
|
501 |
|
502 /*************************************************************************/ |
|
503 /* */ |
|
504 /* <Function> */ |
|
505 /* FTC_Node_Unref */ |
|
506 /* */ |
|
507 /* <Description> */ |
|
508 /* Decrement a cache node's internal reference count. When the count */ |
|
509 /* reaches 0, it is not destroyed but becomes eligible for subsequent */ |
|
510 /* cache flushes. */ |
|
511 /* */ |
|
512 /* <Input> */ |
|
513 /* node :: The cache node handle. */ |
|
514 /* */ |
|
515 /* manager :: The cache manager handle. */ |
|
516 /* */ |
|
517 FT_EXPORT( void ) |
|
518 FTC_Node_Unref( FTC_Node node, |
|
519 FTC_Manager manager ); |
|
520 |
|
521 |
|
522 /************************************************************************* |
|
523 * |
|
524 * @function: |
|
525 * FTC_Manager_RemoveFaceID |
|
526 * |
|
527 * @description: |
|
528 * A special function used to indicate to the cache manager that |
|
529 * a given @FTC_FaceID is no longer valid, either because its |
|
530 * content changed, or because it was deallocated or uninstalled. |
|
531 * |
|
532 * @input: |
|
533 * manager :: |
|
534 * The cache manager handle. |
|
535 * |
|
536 * face_id :: |
|
537 * The @FTC_FaceID to be removed. |
|
538 * |
|
539 * @note: |
|
540 * This function flushes all nodes from the cache corresponding to this |
|
541 * `face_id', with the exception of nodes with a non-null reference |
|
542 * count. |
|
543 * |
|
544 * Such nodes are however modified internally so as to never appear |
|
545 * in later lookups with the same `face_id' value, and to be immediately |
|
546 * destroyed when released by all their users. |
|
547 * |
|
548 */ |
|
549 FT_EXPORT( void ) |
|
550 FTC_Manager_RemoveFaceID( FTC_Manager manager, |
|
551 FTC_FaceID face_id ); |
|
552 |
|
553 |
|
554 /*************************************************************************/ |
|
555 /* */ |
|
556 /* <Section> */ |
|
557 /* cache_subsystem */ |
|
558 /* */ |
|
559 /*************************************************************************/ |
|
560 |
|
561 /************************************************************************* |
|
562 * |
|
563 * @type: |
|
564 * FTC_CMapCache |
|
565 * |
|
566 * @description: |
|
567 * An opaque handle used to model a charmap cache. This cache is to |
|
568 * hold character codes -> glyph indices mappings. |
|
569 * |
|
570 */ |
|
571 typedef struct FTC_CMapCacheRec_* FTC_CMapCache; |
|
572 |
|
573 |
|
574 /************************************************************************* |
|
575 * |
|
576 * @function: |
|
577 * FTC_CMapCache_New |
|
578 * |
|
579 * @description: |
|
580 * Create a new charmap cache. |
|
581 * |
|
582 * @input: |
|
583 * manager :: |
|
584 * A handle to the cache manager. |
|
585 * |
|
586 * @output: |
|
587 * acache :: |
|
588 * A new cache handle. NULL in case of error. |
|
589 * |
|
590 * @return: |
|
591 * FreeType error code. 0~means success. |
|
592 * |
|
593 * @note: |
|
594 * Like all other caches, this one will be destroyed with the cache |
|
595 * manager. |
|
596 * |
|
597 */ |
|
598 FT_EXPORT( FT_Error ) |
|
599 FTC_CMapCache_New( FTC_Manager manager, |
|
600 FTC_CMapCache *acache ); |
|
601 |
|
602 |
|
603 /************************************************************************ |
|
604 * |
|
605 * @function: |
|
606 * FTC_CMapCache_Lookup |
|
607 * |
|
608 * @description: |
|
609 * Translate a character code into a glyph index, using the charmap |
|
610 * cache. |
|
611 * |
|
612 * @input: |
|
613 * cache :: |
|
614 * A charmap cache handle. |
|
615 * |
|
616 * face_id :: |
|
617 * The source face ID. |
|
618 * |
|
619 * cmap_index :: |
|
620 * The index of the charmap in the source face. Any negative value |
|
621 * means to use the cache @FT_Face's default charmap. |
|
622 * |
|
623 * char_code :: |
|
624 * The character code (in the corresponding charmap). |
|
625 * |
|
626 * @return: |
|
627 * Glyph index. 0~means `no glyph'. |
|
628 * |
|
629 */ |
|
630 FT_EXPORT( FT_UInt ) |
|
631 FTC_CMapCache_Lookup( FTC_CMapCache cache, |
|
632 FTC_FaceID face_id, |
|
633 FT_Int cmap_index, |
|
634 FT_UInt32 char_code ); |
|
635 |
|
636 |
|
637 /*************************************************************************/ |
|
638 /* */ |
|
639 /* <Section> */ |
|
640 /* cache_subsystem */ |
|
641 /* */ |
|
642 /*************************************************************************/ |
|
643 |
|
644 |
|
645 /*************************************************************************/ |
|
646 /*************************************************************************/ |
|
647 /*************************************************************************/ |
|
648 /***** *****/ |
|
649 /***** IMAGE CACHE OBJECT *****/ |
|
650 /***** *****/ |
|
651 /*************************************************************************/ |
|
652 /*************************************************************************/ |
|
653 /*************************************************************************/ |
|
654 |
|
655 |
|
656 /************************************************************************* |
|
657 * |
|
658 * @struct: |
|
659 * FTC_ImageTypeRec |
|
660 * |
|
661 * @description: |
|
662 * A structure used to model the type of images in a glyph cache. |
|
663 * |
|
664 * @fields: |
|
665 * face_id :: |
|
666 * The face ID. |
|
667 * |
|
668 * width :: |
|
669 * The width in pixels. |
|
670 * |
|
671 * height :: |
|
672 * The height in pixels. |
|
673 * |
|
674 * flags :: |
|
675 * The load flags, as in @FT_Load_Glyph. |
|
676 * |
|
677 */ |
|
678 typedef struct FTC_ImageTypeRec_ |
|
679 { |
|
680 FTC_FaceID face_id; |
|
681 FT_Int width; |
|
682 FT_Int height; |
|
683 FT_Int32 flags; |
|
684 |
|
685 } FTC_ImageTypeRec; |
|
686 |
|
687 |
|
688 /************************************************************************* |
|
689 * |
|
690 * @type: |
|
691 * FTC_ImageType |
|
692 * |
|
693 * @description: |
|
694 * A handle to an @FTC_ImageTypeRec structure. |
|
695 * |
|
696 */ |
|
697 typedef struct FTC_ImageTypeRec_* FTC_ImageType; |
|
698 |
|
699 |
|
700 /* */ |
|
701 |
|
702 |
|
703 #define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \ |
|
704 ( (d1)->face_id == (d2)->face_id && \ |
|
705 (d1)->width == (d2)->width && \ |
|
706 (d1)->flags == (d2)->flags ) |
|
707 |
|
708 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS |
|
709 |
|
710 /* this macro is incompatible with LLP64, should not be used */ |
|
711 |
|
712 #define FTC_IMAGE_TYPE_HASH( d ) \ |
|
713 (FT_UFast)( FTC_FACE_ID_HASH( (d)->face_id ) ^ \ |
|
714 ( (d)->width << 8 ) ^ (d)->height ^ \ |
|
715 ( (d)->flags << 4 ) ) |
|
716 |
|
717 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */ |
|
718 |
|
719 |
|
720 /*************************************************************************/ |
|
721 /* */ |
|
722 /* <Type> */ |
|
723 /* FTC_ImageCache */ |
|
724 /* */ |
|
725 /* <Description> */ |
|
726 /* A handle to an glyph image cache object. They are designed to */ |
|
727 /* hold many distinct glyph images while not exceeding a certain */ |
|
728 /* memory threshold. */ |
|
729 /* */ |
|
730 typedef struct FTC_ImageCacheRec_* FTC_ImageCache; |
|
731 |
|
732 |
|
733 /*************************************************************************/ |
|
734 /* */ |
|
735 /* <Function> */ |
|
736 /* FTC_ImageCache_New */ |
|
737 /* */ |
|
738 /* <Description> */ |
|
739 /* Create a new glyph image cache. */ |
|
740 /* */ |
|
741 /* <Input> */ |
|
742 /* manager :: The parent manager for the image cache. */ |
|
743 /* */ |
|
744 /* <Output> */ |
|
745 /* acache :: A handle to the new glyph image cache object. */ |
|
746 /* */ |
|
747 /* <Return> */ |
|
748 /* FreeType error code. 0~means success. */ |
|
749 /* */ |
|
750 FT_EXPORT( FT_Error ) |
|
751 FTC_ImageCache_New( FTC_Manager manager, |
|
752 FTC_ImageCache *acache ); |
|
753 |
|
754 |
|
755 /*************************************************************************/ |
|
756 /* */ |
|
757 /* <Function> */ |
|
758 /* FTC_ImageCache_Lookup */ |
|
759 /* */ |
|
760 /* <Description> */ |
|
761 /* Retrieve a given glyph image from a glyph image cache. */ |
|
762 /* */ |
|
763 /* <Input> */ |
|
764 /* cache :: A handle to the source glyph image cache. */ |
|
765 /* */ |
|
766 /* type :: A pointer to a glyph image type descriptor. */ |
|
767 /* */ |
|
768 /* gindex :: The glyph index to retrieve. */ |
|
769 /* */ |
|
770 /* <Output> */ |
|
771 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */ |
|
772 /* failure. */ |
|
773 /* */ |
|
774 /* anode :: Used to return the address of of the corresponding cache */ |
|
775 /* node after incrementing its reference count (see note */ |
|
776 /* below). */ |
|
777 /* */ |
|
778 /* <Return> */ |
|
779 /* FreeType error code. 0~means success. */ |
|
780 /* */ |
|
781 /* <Note> */ |
|
782 /* The returned glyph is owned and managed by the glyph image cache. */ |
|
783 /* Never try to transform or discard it manually! You can however */ |
|
784 /* create a copy with @FT_Glyph_Copy and modify the new one. */ |
|
785 /* */ |
|
786 /* If `anode' is _not_ NULL, it receives the address of the cache */ |
|
787 /* node containing the glyph image, after increasing its reference */ |
|
788 /* count. This ensures that the node (as well as the @FT_Glyph) will */ |
|
789 /* always be kept in the cache until you call @FTC_Node_Unref to */ |
|
790 /* `release' it. */ |
|
791 /* */ |
|
792 /* If `anode' is NULL, the cache node is left unchanged, which means */ |
|
793 /* that the @FT_Glyph could be flushed out of the cache on the next */ |
|
794 /* call to one of the caching sub-system APIs. Don't assume that it */ |
|
795 /* is persistent! */ |
|
796 /* */ |
|
797 FT_EXPORT( FT_Error ) |
|
798 FTC_ImageCache_Lookup( FTC_ImageCache cache, |
|
799 FTC_ImageType type, |
|
800 FT_UInt gindex, |
|
801 FT_Glyph *aglyph, |
|
802 FTC_Node *anode ); |
|
803 |
|
804 |
|
805 /*************************************************************************/ |
|
806 /* */ |
|
807 /* <Function> */ |
|
808 /* FTC_ImageCache_LookupScaler */ |
|
809 /* */ |
|
810 /* <Description> */ |
|
811 /* A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec */ |
|
812 /* to specify the face ID and its size. */ |
|
813 /* */ |
|
814 /* <Input> */ |
|
815 /* cache :: A handle to the source glyph image cache. */ |
|
816 /* */ |
|
817 /* scaler :: A pointer to a scaler descriptor. */ |
|
818 /* */ |
|
819 /* load_flags :: The corresponding load flags. */ |
|
820 /* */ |
|
821 /* gindex :: The glyph index to retrieve. */ |
|
822 /* */ |
|
823 /* <Output> */ |
|
824 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */ |
|
825 /* failure. */ |
|
826 /* */ |
|
827 /* anode :: Used to return the address of of the corresponding */ |
|
828 /* cache node after incrementing its reference count */ |
|
829 /* (see note below). */ |
|
830 /* */ |
|
831 /* <Return> */ |
|
832 /* FreeType error code. 0~means success. */ |
|
833 /* */ |
|
834 /* <Note> */ |
|
835 /* The returned glyph is owned and managed by the glyph image cache. */ |
|
836 /* Never try to transform or discard it manually! You can however */ |
|
837 /* create a copy with @FT_Glyph_Copy and modify the new one. */ |
|
838 /* */ |
|
839 /* If `anode' is _not_ NULL, it receives the address of the cache */ |
|
840 /* node containing the glyph image, after increasing its reference */ |
|
841 /* count. This ensures that the node (as well as the @FT_Glyph) will */ |
|
842 /* always be kept in the cache until you call @FTC_Node_Unref to */ |
|
843 /* `release' it. */ |
|
844 /* */ |
|
845 /* If `anode' is NULL, the cache node is left unchanged, which means */ |
|
846 /* that the @FT_Glyph could be flushed out of the cache on the next */ |
|
847 /* call to one of the caching sub-system APIs. Don't assume that it */ |
|
848 /* is persistent! */ |
|
849 /* */ |
|
850 /* Calls to @FT_Set_Char_Size and friends have no effect on cached */ |
|
851 /* glyphs; you should always use the FreeType cache API instead. */ |
|
852 /* */ |
|
853 FT_EXPORT( FT_Error ) |
|
854 FTC_ImageCache_LookupScaler( FTC_ImageCache cache, |
|
855 FTC_Scaler scaler, |
|
856 FT_ULong load_flags, |
|
857 FT_UInt gindex, |
|
858 FT_Glyph *aglyph, |
|
859 FTC_Node *anode ); |
|
860 |
|
861 |
|
862 /*************************************************************************/ |
|
863 /* */ |
|
864 /* <Type> */ |
|
865 /* FTC_SBit */ |
|
866 /* */ |
|
867 /* <Description> */ |
|
868 /* A handle to a small bitmap descriptor. See the @FTC_SBitRec */ |
|
869 /* structure for details. */ |
|
870 /* */ |
|
871 typedef struct FTC_SBitRec_* FTC_SBit; |
|
872 |
|
873 |
|
874 /*************************************************************************/ |
|
875 /* */ |
|
876 /* <Struct> */ |
|
877 /* FTC_SBitRec */ |
|
878 /* */ |
|
879 /* <Description> */ |
|
880 /* A very compact structure used to describe a small glyph bitmap. */ |
|
881 /* */ |
|
882 /* <Fields> */ |
|
883 /* width :: The bitmap width in pixels. */ |
|
884 /* */ |
|
885 /* height :: The bitmap height in pixels. */ |
|
886 /* */ |
|
887 /* left :: The horizontal distance from the pen position to the */ |
|
888 /* left bitmap border (a.k.a. `left side bearing', or */ |
|
889 /* `lsb'). */ |
|
890 /* */ |
|
891 /* top :: The vertical distance from the pen position (on the */ |
|
892 /* baseline) to the upper bitmap border (a.k.a. `top */ |
|
893 /* side bearing'). The distance is positive for upwards */ |
|
894 /* y~coordinates. */ |
|
895 /* */ |
|
896 /* format :: The format of the glyph bitmap (monochrome or gray). */ |
|
897 /* */ |
|
898 /* max_grays :: Maximum gray level value (in the range 1 to~255). */ |
|
899 /* */ |
|
900 /* pitch :: The number of bytes per bitmap line. May be positive */ |
|
901 /* or negative. */ |
|
902 /* */ |
|
903 /* xadvance :: The horizontal advance width in pixels. */ |
|
904 /* */ |
|
905 /* yadvance :: The vertical advance height in pixels. */ |
|
906 /* */ |
|
907 /* buffer :: A pointer to the bitmap pixels. */ |
|
908 /* */ |
|
909 typedef struct FTC_SBitRec_ |
|
910 { |
|
911 FT_Byte width; |
|
912 FT_Byte height; |
|
913 FT_Char left; |
|
914 FT_Char top; |
|
915 |
|
916 FT_Byte format; |
|
917 FT_Byte max_grays; |
|
918 FT_Short pitch; |
|
919 FT_Char xadvance; |
|
920 FT_Char yadvance; |
|
921 |
|
922 FT_Byte* buffer; |
|
923 |
|
924 } FTC_SBitRec; |
|
925 |
|
926 |
|
927 /*************************************************************************/ |
|
928 /* */ |
|
929 /* <Type> */ |
|
930 /* FTC_SBitCache */ |
|
931 /* */ |
|
932 /* <Description> */ |
|
933 /* A handle to a small bitmap cache. These are special cache objects */ |
|
934 /* used to store small glyph bitmaps (and anti-aliased pixmaps) in a */ |
|
935 /* much more efficient way than the traditional glyph image cache */ |
|
936 /* implemented by @FTC_ImageCache. */ |
|
937 /* */ |
|
938 typedef struct FTC_SBitCacheRec_* FTC_SBitCache; |
|
939 |
|
940 |
|
941 /*************************************************************************/ |
|
942 /* */ |
|
943 /* <Function> */ |
|
944 /* FTC_SBitCache_New */ |
|
945 /* */ |
|
946 /* <Description> */ |
|
947 /* Create a new cache to store small glyph bitmaps. */ |
|
948 /* */ |
|
949 /* <Input> */ |
|
950 /* manager :: A handle to the source cache manager. */ |
|
951 /* */ |
|
952 /* <Output> */ |
|
953 /* acache :: A handle to the new sbit cache. NULL in case of error. */ |
|
954 /* */ |
|
955 /* <Return> */ |
|
956 /* FreeType error code. 0~means success. */ |
|
957 /* */ |
|
958 FT_EXPORT( FT_Error ) |
|
959 FTC_SBitCache_New( FTC_Manager manager, |
|
960 FTC_SBitCache *acache ); |
|
961 |
|
962 |
|
963 /*************************************************************************/ |
|
964 /* */ |
|
965 /* <Function> */ |
|
966 /* FTC_SBitCache_Lookup */ |
|
967 /* */ |
|
968 /* <Description> */ |
|
969 /* Look up a given small glyph bitmap in a given sbit cache and */ |
|
970 /* `lock' it to prevent its flushing from the cache until needed. */ |
|
971 /* */ |
|
972 /* <Input> */ |
|
973 /* cache :: A handle to the source sbit cache. */ |
|
974 /* */ |
|
975 /* type :: A pointer to the glyph image type descriptor. */ |
|
976 /* */ |
|
977 /* gindex :: The glyph index. */ |
|
978 /* */ |
|
979 /* <Output> */ |
|
980 /* sbit :: A handle to a small bitmap descriptor. */ |
|
981 /* */ |
|
982 /* anode :: Used to return the address of of the corresponding cache */ |
|
983 /* node after incrementing its reference count (see note */ |
|
984 /* below). */ |
|
985 /* */ |
|
986 /* <Return> */ |
|
987 /* FreeType error code. 0~means success. */ |
|
988 /* */ |
|
989 /* <Note> */ |
|
990 /* The small bitmap descriptor and its bit buffer are owned by the */ |
|
991 /* cache and should never be freed by the application. They might */ |
|
992 /* as well disappear from memory on the next cache lookup, so don't */ |
|
993 /* treat them as persistent data. */ |
|
994 /* */ |
|
995 /* The descriptor's `buffer' field is set to~0 to indicate a missing */ |
|
996 /* glyph bitmap. */ |
|
997 /* */ |
|
998 /* If `anode' is _not_ NULL, it receives the address of the cache */ |
|
999 /* node containing the bitmap, after increasing its reference count. */ |
|
1000 /* This ensures that the node (as well as the image) will always be */ |
|
1001 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */ |
|
1002 /* */ |
|
1003 /* If `anode' is NULL, the cache node is left unchanged, which means */ |
|
1004 /* that the bitmap could be flushed out of the cache on the next */ |
|
1005 /* call to one of the caching sub-system APIs. Don't assume that it */ |
|
1006 /* is persistent! */ |
|
1007 /* */ |
|
1008 FT_EXPORT( FT_Error ) |
|
1009 FTC_SBitCache_Lookup( FTC_SBitCache cache, |
|
1010 FTC_ImageType type, |
|
1011 FT_UInt gindex, |
|
1012 FTC_SBit *sbit, |
|
1013 FTC_Node *anode ); |
|
1014 |
|
1015 |
|
1016 /*************************************************************************/ |
|
1017 /* */ |
|
1018 /* <Function> */ |
|
1019 /* FTC_SBitCache_LookupScaler */ |
|
1020 /* */ |
|
1021 /* <Description> */ |
|
1022 /* A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec */ |
|
1023 /* to specify the face ID and its size. */ |
|
1024 /* */ |
|
1025 /* <Input> */ |
|
1026 /* cache :: A handle to the source sbit cache. */ |
|
1027 /* */ |
|
1028 /* scaler :: A pointer to the scaler descriptor. */ |
|
1029 /* */ |
|
1030 /* load_flags :: The corresponding load flags. */ |
|
1031 /* */ |
|
1032 /* gindex :: The glyph index. */ |
|
1033 /* */ |
|
1034 /* <Output> */ |
|
1035 /* sbit :: A handle to a small bitmap descriptor. */ |
|
1036 /* */ |
|
1037 /* anode :: Used to return the address of of the corresponding */ |
|
1038 /* cache node after incrementing its reference count */ |
|
1039 /* (see note below). */ |
|
1040 /* */ |
|
1041 /* <Return> */ |
|
1042 /* FreeType error code. 0~means success. */ |
|
1043 /* */ |
|
1044 /* <Note> */ |
|
1045 /* The small bitmap descriptor and its bit buffer are owned by the */ |
|
1046 /* cache and should never be freed by the application. They might */ |
|
1047 /* as well disappear from memory on the next cache lookup, so don't */ |
|
1048 /* treat them as persistent data. */ |
|
1049 /* */ |
|
1050 /* The descriptor's `buffer' field is set to~0 to indicate a missing */ |
|
1051 /* glyph bitmap. */ |
|
1052 /* */ |
|
1053 /* If `anode' is _not_ NULL, it receives the address of the cache */ |
|
1054 /* node containing the bitmap, after increasing its reference count. */ |
|
1055 /* This ensures that the node (as well as the image) will always be */ |
|
1056 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */ |
|
1057 /* */ |
|
1058 /* If `anode' is NULL, the cache node is left unchanged, which means */ |
|
1059 /* that the bitmap could be flushed out of the cache on the next */ |
|
1060 /* call to one of the caching sub-system APIs. Don't assume that it */ |
|
1061 /* is persistent! */ |
|
1062 /* */ |
|
1063 FT_EXPORT( FT_Error ) |
|
1064 FTC_SBitCache_LookupScaler( FTC_SBitCache cache, |
|
1065 FTC_Scaler scaler, |
|
1066 FT_ULong load_flags, |
|
1067 FT_UInt gindex, |
|
1068 FTC_SBit *sbit, |
|
1069 FTC_Node *anode ); |
|
1070 |
|
1071 |
|
1072 /* */ |
|
1073 |
|
1074 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS |
|
1075 |
|
1076 /*@***********************************************************************/ |
|
1077 /* */ |
|
1078 /* <Struct> */ |
|
1079 /* FTC_FontRec */ |
|
1080 /* */ |
|
1081 /* <Description> */ |
|
1082 /* A simple structure used to describe a given `font' to the cache */ |
|
1083 /* manager. Note that a `font' is the combination of a given face */ |
|
1084 /* with a given character size. */ |
|
1085 /* */ |
|
1086 /* <Fields> */ |
|
1087 /* face_id :: The ID of the face to use. */ |
|
1088 /* */ |
|
1089 /* pix_width :: The character width in integer pixels. */ |
|
1090 /* */ |
|
1091 /* pix_height :: The character height in integer pixels. */ |
|
1092 /* */ |
|
1093 typedef struct FTC_FontRec_ |
|
1094 { |
|
1095 FTC_FaceID face_id; |
|
1096 FT_UShort pix_width; |
|
1097 FT_UShort pix_height; |
|
1098 |
|
1099 } FTC_FontRec; |
|
1100 |
|
1101 |
|
1102 /* */ |
|
1103 |
|
1104 |
|
1105 #define FTC_FONT_COMPARE( f1, f2 ) \ |
|
1106 ( (f1)->face_id == (f2)->face_id && \ |
|
1107 (f1)->pix_width == (f2)->pix_width && \ |
|
1108 (f1)->pix_height == (f2)->pix_height ) |
|
1109 |
|
1110 /* this macro is incompatible with LLP64, should not be used */ |
|
1111 #define FTC_FONT_HASH( f ) \ |
|
1112 (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \ |
|
1113 ((f)->pix_width << 8) ^ \ |
|
1114 ((f)->pix_height) ) |
|
1115 |
|
1116 typedef FTC_FontRec* FTC_Font; |
|
1117 |
|
1118 |
|
1119 FT_EXPORT( FT_Error ) |
|
1120 FTC_Manager_Lookup_Face( FTC_Manager manager, |
|
1121 FTC_FaceID face_id, |
|
1122 FT_Face *aface ); |
|
1123 |
|
1124 FT_EXPORT( FT_Error ) |
|
1125 FTC_Manager_Lookup_Size( FTC_Manager manager, |
|
1126 FTC_Font font, |
|
1127 FT_Face *aface, |
|
1128 FT_Size *asize ); |
|
1129 |
|
1130 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */ |
|
1131 |
|
1132 |
|
1133 /* */ |
|
1134 |
|
1135 FT_END_HEADER |
|
1136 |
|
1137 #endif /* __FTCACHE_H__ */ |
|
1138 |
|
1139 |
|
1140 /* END */ |