]>
Commit | Line | Data |
---|---|---|
7407ac7f BB |
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 */ |