vrshoot
view libs/ft2static/freetype/ftcache.h @ 0:b2f14e535253
initial commit
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Sat, 01 Feb 2014 19:58:19 +0200 |
| parents | |
| children |
line source
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 /***************************************************************************/
19 #ifndef __FTCACHE_H__
20 #define __FTCACHE_H__
23 #include <ft2build.h>
24 #include FT_GLYPH_H
27 FT_BEGIN_HEADER
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 *************************************************************************/
134 /*************************************************************************/
135 /*************************************************************************/
136 /*************************************************************************/
137 /***** *****/
138 /***** BASIC TYPE DEFINITIONS *****/
139 /***** *****/
140 /*************************************************************************/
141 /*************************************************************************/
142 /*************************************************************************/
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;
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 );
215 /* */
217 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
219 /* these macros are incompatible with LLP64, should not be used */
221 #define FT_POINTER_TO_ULONG( p ) ( (FT_ULong)(FT_Pointer)(p) )
223 #define FTC_FACE_ID_HASH( i ) \
224 ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \
225 ( FT_POINTER_TO_ULONG( i ) << 7 ) ) )
227 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */
229 /*************************************************************************/
230 /*************************************************************************/
231 /*************************************************************************/
232 /***** *****/
233 /***** CACHE MANAGER OBJECT *****/
234 /***** *****/
235 /*************************************************************************/
236 /*************************************************************************/
237 /*************************************************************************/
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;
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;
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 );
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 );
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 );
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 );
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;
445 } FTC_ScalerRec;
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;
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 );
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 );
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 );
554 /*************************************************************************/
555 /* */
556 /* <Section> */
557 /* cache_subsystem */
558 /* */
559 /*************************************************************************/
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;
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 );
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 );
637 /*************************************************************************/
638 /* */
639 /* <Section> */
640 /* cache_subsystem */
641 /* */
642 /*************************************************************************/
645 /*************************************************************************/
646 /*************************************************************************/
647 /*************************************************************************/
648 /***** *****/
649 /***** IMAGE CACHE OBJECT *****/
650 /***** *****/
651 /*************************************************************************/
652 /*************************************************************************/
653 /*************************************************************************/
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;
685 } FTC_ImageTypeRec;
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;
700 /* */
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 )
708 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
710 /* this macro is incompatible with LLP64, should not be used */
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 ) )
717 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */
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;
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 );
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 );
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 );
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;
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;
916 FT_Byte format;
917 FT_Byte max_grays;
918 FT_Short pitch;
919 FT_Char xadvance;
920 FT_Char yadvance;
922 FT_Byte* buffer;
924 } FTC_SBitRec;
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;
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 );
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 );
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 );
1072 /* */
1074 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
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;
1099 } FTC_FontRec;
1102 /* */
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 )
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) )
1116 typedef FTC_FontRec* FTC_Font;
1119 FT_EXPORT( FT_Error )
1120 FTC_Manager_Lookup_Face( FTC_Manager manager,
1121 FTC_FaceID face_id,
1122 FT_Face *aface );
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 );
1130 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */
1133 /* */
1135 FT_END_HEADER
1137 #endif /* __FTCACHE_H__ */
1140 /* END */