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