ReactOS 0.4.15-dev-7906-g1b85a5f
ftcache.h
Go to the documentation of this file.
1/***************************************************************************/
2/* */
3/* ftcache.h */
4/* */
5/* FreeType Cache subsystem (specification). */
6/* */
7/* Copyright 1996-2018 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
27FT_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 that 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 req_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 /* <Type> */
232 /* FTC_Manager */
233 /* */
234 /* <Description> */
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 /* <Type> */
256 /* FTC_Node */
257 /* */
258 /* <Description> */
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 /* <Function> */
276 /* FTC_Manager_New */
277 /* */
278 /* <Description> */
279 /* Create a new cache manager. */
280 /* */
281 /* <Input> */
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 /* <Output> */
301 /* amanager :: A handle to a new manager object. 0~in case of */
302 /* failure. */
303 /* */
304 /* <Return> */
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 /* <Function> */
320 /* FTC_Manager_Reset */
321 /* */
322 /* <Description> */
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 /* <InOut> */
327 /* manager :: A handle to the manager. */
328 /* */
329 FT_EXPORT( void )
330 FTC_Manager_Reset( FTC_Manager manager );
331
332
333 /*************************************************************************/
334 /* */
335 /* <Function> */
336 /* FTC_Manager_Done */
337 /* */
338 /* <Description> */
339 /* Destroy a given manager after emptying it. */
340 /* */
341 /* <Input> */
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 /* <Function> */
351 /* FTC_Manager_LookupFace */
352 /* */
353 /* <Description> */
354 /* Retrieve the @FT_Face object that corresponds to a given face ID */
355 /* through a cache manager. */
356 /* */
357 /* <Input> */
358 /* manager :: A handle to the cache manager. */
359 /* */
360 /* face_id :: The ID of the face object. */
361 /* */
362 /* <Output> */
363 /* aface :: A handle to the face object. */
364 /* */
365 /* <Return> */
366 /* FreeType error code. 0~means success. */
367 /* */
368 /* <Note> */
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 /* <Struct> */
397 /* FTC_ScalerRec */
398 /* */
399 /* <Description> */
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 /* <Fields> */
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 /* <Note> */
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 /* <Struct> */
440 /* FTC_Scaler */
441 /* */
442 /* <Description> */
443 /* A handle to an @FTC_ScalerRec structure. */
444 /* */
445 typedef struct FTC_ScalerRec_* FTC_Scaler;
446
447
448 /*************************************************************************/
449 /* */
450 /* <Function> */
451 /* FTC_Manager_LookupSize */
452 /* */
453 /* <Description> */
454 /* Retrieve the @FT_Size object that corresponds to a given */
455 /* @FTC_ScalerRec pointer through a cache manager. */
456 /* */
457 /* <Input> */
458 /* manager :: A handle to the cache manager. */
459 /* */
460 /* scaler :: A scaler handle. */
461 /* */
462 /* <Output> */
463 /* asize :: A handle to the size object. */
464 /* */
465 /* <Return> */
466 /* FreeType error code. 0~means success. */
467 /* */
468 /* <Note> */
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 /* <Note> */
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 /* <Function> */
494 /* FTC_Node_Unref */
495 /* */
496 /* <Description> */
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 /* <Input> */
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 * @type:
546 * FTC_CMapCache
547 *
548 * @description:
549 * An opaque handle used to model a charmap cache. This cache is to
550 * hold character codes -> glyph indices mappings.
551 *
552 */
553 typedef struct FTC_CMapCacheRec_* FTC_CMapCache;
554
555
556 /*************************************************************************
557 *
558 * @function:
559 * FTC_CMapCache_New
560 *
561 * @description:
562 * Create a new charmap cache.
563 *
564 * @input:
565 * manager ::
566 * A handle to the cache manager.
567 *
568 * @output:
569 * acache ::
570 * A new cache handle. NULL in case of error.
571 *
572 * @return:
573 * FreeType error code. 0~means success.
574 *
575 * @note:
576 * Like all other caches, this one will be destroyed with the cache
577 * manager.
578 *
579 */
580 FT_EXPORT( FT_Error )
581 FTC_CMapCache_New( FTC_Manager manager,
582 FTC_CMapCache *acache );
583
584
585 /************************************************************************
586 *
587 * @function:
588 * FTC_CMapCache_Lookup
589 *
590 * @description:
591 * Translate a character code into a glyph index, using the charmap
592 * cache.
593 *
594 * @input:
595 * cache ::
596 * A charmap cache handle.
597 *
598 * face_id ::
599 * The source face ID.
600 *
601 * cmap_index ::
602 * The index of the charmap in the source face. Any negative value
603 * means to use the cache @FT_Face's default charmap.
604 *
605 * char_code ::
606 * The character code (in the corresponding charmap).
607 *
608 * @return:
609 * Glyph index. 0~means `no glyph'.
610 *
611 */
612 FT_EXPORT( FT_UInt )
613 FTC_CMapCache_Lookup( FTC_CMapCache cache,
614 FTC_FaceID face_id,
615 FT_Int cmap_index,
616 FT_UInt32 char_code );
617
618
619 /*************************************************************************/
620 /*************************************************************************/
621 /*************************************************************************/
622 /***** *****/
623 /***** IMAGE CACHE OBJECT *****/
624 /***** *****/
625 /*************************************************************************/
626 /*************************************************************************/
627 /*************************************************************************/
628
629
630 /*************************************************************************
631 *
632 * @struct:
633 * FTC_ImageTypeRec
634 *
635 * @description:
636 * A structure used to model the type of images in a glyph cache.
637 *
638 * @fields:
639 * face_id ::
640 * The face ID.
641 *
642 * width ::
643 * The width in pixels.
644 *
645 * height ::
646 * The height in pixels.
647 *
648 * flags ::
649 * The load flags, as in @FT_Load_Glyph.
650 *
651 */
652 typedef struct FTC_ImageTypeRec_
653 {
654 FTC_FaceID face_id;
655 FT_UInt width;
656 FT_UInt height;
657 FT_Int32 flags;
658
659 } FTC_ImageTypeRec;
660
661
662 /*************************************************************************
663 *
664 * @type:
665 * FTC_ImageType
666 *
667 * @description:
668 * A handle to an @FTC_ImageTypeRec structure.
669 *
670 */
671 typedef struct FTC_ImageTypeRec_* FTC_ImageType;
672
673
674 /* */
675
676
677#define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \
678 ( (d1)->face_id == (d2)->face_id && \
679 (d1)->width == (d2)->width && \
680 (d1)->flags == (d2)->flags )
681
682
683 /*************************************************************************/
684 /* */
685 /* <Type> */
686 /* FTC_ImageCache */
687 /* */
688 /* <Description> */
689 /* A handle to a glyph image cache object. They are designed to */
690 /* hold many distinct glyph images while not exceeding a certain */
691 /* memory threshold. */
692 /* */
693 typedef struct FTC_ImageCacheRec_* FTC_ImageCache;
694
695
696 /*************************************************************************/
697 /* */
698 /* <Function> */
699 /* FTC_ImageCache_New */
700 /* */
701 /* <Description> */
702 /* Create a new glyph image cache. */
703 /* */
704 /* <Input> */
705 /* manager :: The parent manager for the image cache. */
706 /* */
707 /* <Output> */
708 /* acache :: A handle to the new glyph image cache object. */
709 /* */
710 /* <Return> */
711 /* FreeType error code. 0~means success. */
712 /* */
713 FT_EXPORT( FT_Error )
714 FTC_ImageCache_New( FTC_Manager manager,
715 FTC_ImageCache *acache );
716
717
718 /*************************************************************************/
719 /* */
720 /* <Function> */
721 /* FTC_ImageCache_Lookup */
722 /* */
723 /* <Description> */
724 /* Retrieve a given glyph image from a glyph image cache. */
725 /* */
726 /* <Input> */
727 /* cache :: A handle to the source glyph image cache. */
728 /* */
729 /* type :: A pointer to a glyph image type descriptor. */
730 /* */
731 /* gindex :: The glyph index to retrieve. */
732 /* */
733 /* <Output> */
734 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */
735 /* failure. */
736 /* */
737 /* anode :: Used to return the address of the corresponding cache */
738 /* node after incrementing its reference count (see note */
739 /* below). */
740 /* */
741 /* <Return> */
742 /* FreeType error code. 0~means success. */
743 /* */
744 /* <Note> */
745 /* The returned glyph is owned and managed by the glyph image cache. */
746 /* Never try to transform or discard it manually! You can however */
747 /* create a copy with @FT_Glyph_Copy and modify the new one. */
748 /* */
749 /* If `anode' is _not_ NULL, it receives the address of the cache */
750 /* node containing the glyph image, after increasing its reference */
751 /* count. This ensures that the node (as well as the @FT_Glyph) will */
752 /* always be kept in the cache until you call @FTC_Node_Unref to */
753 /* `release' it. */
754 /* */
755 /* If `anode' is NULL, the cache node is left unchanged, which means */
756 /* that the @FT_Glyph could be flushed out of the cache on the next */
757 /* call to one of the caching sub-system APIs. Don't assume that it */
758 /* is persistent! */
759 /* */
760 FT_EXPORT( FT_Error )
761 FTC_ImageCache_Lookup( FTC_ImageCache cache,
762 FTC_ImageType type,
763 FT_UInt gindex,
764 FT_Glyph *aglyph,
765 FTC_Node *anode );
766
767
768 /*************************************************************************/
769 /* */
770 /* <Function> */
771 /* FTC_ImageCache_LookupScaler */
772 /* */
773 /* <Description> */
774 /* A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec */
775 /* to specify the face ID and its size. */
776 /* */
777 /* <Input> */
778 /* cache :: A handle to the source glyph image cache. */
779 /* */
780 /* scaler :: A pointer to a scaler descriptor. */
781 /* */
782 /* load_flags :: The corresponding load flags. */
783 /* */
784 /* gindex :: The glyph index to retrieve. */
785 /* */
786 /* <Output> */
787 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */
788 /* failure. */
789 /* */
790 /* anode :: Used to return the address of the corresponding */
791 /* cache node after incrementing its reference count */
792 /* (see note below). */
793 /* */
794 /* <Return> */
795 /* FreeType error code. 0~means success. */
796 /* */
797 /* <Note> */
798 /* The returned glyph is owned and managed by the glyph image cache. */
799 /* Never try to transform or discard it manually! You can however */
800 /* create a copy with @FT_Glyph_Copy and modify the new one. */
801 /* */
802 /* If `anode' is _not_ NULL, it receives the address of the cache */
803 /* node containing the glyph image, after increasing its reference */
804 /* count. This ensures that the node (as well as the @FT_Glyph) will */
805 /* always be kept in the cache until you call @FTC_Node_Unref to */
806 /* `release' it. */
807 /* */
808 /* If `anode' is NULL, the cache node is left unchanged, which means */
809 /* that the @FT_Glyph could be flushed out of the cache on the next */
810 /* call to one of the caching sub-system APIs. Don't assume that it */
811 /* is persistent! */
812 /* */
813 /* Calls to @FT_Set_Char_Size and friends have no effect on cached */
814 /* glyphs; you should always use the FreeType cache API instead. */
815 /* */
816 FT_EXPORT( FT_Error )
817 FTC_ImageCache_LookupScaler( FTC_ImageCache cache,
818 FTC_Scaler scaler,
819 FT_ULong load_flags,
820 FT_UInt gindex,
821 FT_Glyph *aglyph,
822 FTC_Node *anode );
823
824
825 /*************************************************************************/
826 /* */
827 /* <Type> */
828 /* FTC_SBit */
829 /* */
830 /* <Description> */
831 /* A handle to a small bitmap descriptor. See the @FTC_SBitRec */
832 /* structure for details. */
833 /* */
834 typedef struct FTC_SBitRec_* FTC_SBit;
835
836
837 /*************************************************************************/
838 /* */
839 /* <Struct> */
840 /* FTC_SBitRec */
841 /* */
842 /* <Description> */
843 /* A very compact structure used to describe a small glyph bitmap. */
844 /* */
845 /* <Fields> */
846 /* width :: The bitmap width in pixels. */
847 /* */
848 /* height :: The bitmap height in pixels. */
849 /* */
850 /* left :: The horizontal distance from the pen position to the */
851 /* left bitmap border (a.k.a. `left side bearing', or */
852 /* `lsb'). */
853 /* */
854 /* top :: The vertical distance from the pen position (on the */
855 /* baseline) to the upper bitmap border (a.k.a. `top */
856 /* side bearing'). The distance is positive for upwards */
857 /* y~coordinates. */
858 /* */
859 /* format :: The format of the glyph bitmap (monochrome or gray). */
860 /* */
861 /* max_grays :: Maximum gray level value (in the range 1 to~255). */
862 /* */
863 /* pitch :: The number of bytes per bitmap line. May be positive */
864 /* or negative. */
865 /* */
866 /* xadvance :: The horizontal advance width in pixels. */
867 /* */
868 /* yadvance :: The vertical advance height in pixels. */
869 /* */
870 /* buffer :: A pointer to the bitmap pixels. */
871 /* */
872 typedef struct FTC_SBitRec_
873 {
874 FT_Byte width;
875 FT_Byte height;
876 FT_Char left;
877 FT_Char top;
878
879 FT_Byte format;
880 FT_Byte max_grays;
881 FT_Short pitch;
882 FT_Char xadvance;
883 FT_Char yadvance;
884
885 FT_Byte* buffer;
886
887 } FTC_SBitRec;
888
889
890 /*************************************************************************/
891 /* */
892 /* <Type> */
893 /* FTC_SBitCache */
894 /* */
895 /* <Description> */
896 /* A handle to a small bitmap cache. These are special cache objects */
897 /* used to store small glyph bitmaps (and anti-aliased pixmaps) in a */
898 /* much more efficient way than the traditional glyph image cache */
899 /* implemented by @FTC_ImageCache. */
900 /* */
901 typedef struct FTC_SBitCacheRec_* FTC_SBitCache;
902
903
904 /*************************************************************************/
905 /* */
906 /* <Function> */
907 /* FTC_SBitCache_New */
908 /* */
909 /* <Description> */
910 /* Create a new cache to store small glyph bitmaps. */
911 /* */
912 /* <Input> */
913 /* manager :: A handle to the source cache manager. */
914 /* */
915 /* <Output> */
916 /* acache :: A handle to the new sbit cache. NULL in case of error. */
917 /* */
918 /* <Return> */
919 /* FreeType error code. 0~means success. */
920 /* */
921 FT_EXPORT( FT_Error )
922 FTC_SBitCache_New( FTC_Manager manager,
923 FTC_SBitCache *acache );
924
925
926 /*************************************************************************/
927 /* */
928 /* <Function> */
929 /* FTC_SBitCache_Lookup */
930 /* */
931 /* <Description> */
932 /* Look up a given small glyph bitmap in a given sbit cache and */
933 /* `lock' it to prevent its flushing from the cache until needed. */
934 /* */
935 /* <Input> */
936 /* cache :: A handle to the source sbit cache. */
937 /* */
938 /* type :: A pointer to the glyph image type descriptor. */
939 /* */
940 /* gindex :: The glyph index. */
941 /* */
942 /* <Output> */
943 /* sbit :: A handle to a small bitmap descriptor. */
944 /* */
945 /* anode :: Used to return the address of the corresponding cache */
946 /* node after incrementing its reference count (see note */
947 /* below). */
948 /* */
949 /* <Return> */
950 /* FreeType error code. 0~means success. */
951 /* */
952 /* <Note> */
953 /* The small bitmap descriptor and its bit buffer are owned by the */
954 /* cache and should never be freed by the application. They might */
955 /* as well disappear from memory on the next cache lookup, so don't */
956 /* treat them as persistent data. */
957 /* */
958 /* The descriptor's `buffer' field is set to~0 to indicate a missing */
959 /* glyph bitmap. */
960 /* */
961 /* If `anode' is _not_ NULL, it receives the address of the cache */
962 /* node containing the bitmap, after increasing its reference count. */
963 /* This ensures that the node (as well as the image) will always be */
964 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */
965 /* */
966 /* If `anode' is NULL, the cache node is left unchanged, which means */
967 /* that the bitmap could be flushed out of the cache on the next */
968 /* call to one of the caching sub-system APIs. Don't assume that it */
969 /* is persistent! */
970 /* */
971 FT_EXPORT( FT_Error )
972 FTC_SBitCache_Lookup( FTC_SBitCache cache,
973 FTC_ImageType type,
974 FT_UInt gindex,
975 FTC_SBit *sbit,
976 FTC_Node *anode );
977
978
979 /*************************************************************************/
980 /* */
981 /* <Function> */
982 /* FTC_SBitCache_LookupScaler */
983 /* */
984 /* <Description> */
985 /* A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec */
986 /* to specify the face ID and its size. */
987 /* */
988 /* <Input> */
989 /* cache :: A handle to the source sbit cache. */
990 /* */
991 /* scaler :: A pointer to the scaler descriptor. */
992 /* */
993 /* load_flags :: The corresponding load flags. */
994 /* */
995 /* gindex :: The glyph index. */
996 /* */
997 /* <Output> */
998 /* sbit :: A handle to a small bitmap descriptor. */
999 /* */
1000 /* anode :: Used to return the address of the corresponding */
1001 /* cache node after incrementing its reference count */
1002 /* (see note below). */
1003 /* */
1004 /* <Return> */
1005 /* FreeType error code. 0~means success. */
1006 /* */
1007 /* <Note> */
1008 /* The small bitmap descriptor and its bit buffer are owned by the */
1009 /* cache and should never be freed by the application. They might */
1010 /* as well disappear from memory on the next cache lookup, so don't */
1011 /* treat them as persistent data. */
1012 /* */
1013 /* The descriptor's `buffer' field is set to~0 to indicate a missing */
1014 /* glyph bitmap. */
1015 /* */
1016 /* If `anode' is _not_ NULL, it receives the address of the cache */
1017 /* node containing the bitmap, after increasing its reference count. */
1018 /* This ensures that the node (as well as the image) will always be */
1019 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */
1020 /* */
1021 /* If `anode' is NULL, the cache node is left unchanged, which means */
1022 /* that the bitmap could be flushed out of the cache on the next */
1023 /* call to one of the caching sub-system APIs. Don't assume that it */
1024 /* is persistent! */
1025 /* */
1026 FT_EXPORT( FT_Error )
1027 FTC_SBitCache_LookupScaler( FTC_SBitCache cache,
1028 FTC_Scaler scaler,
1029 FT_ULong load_flags,
1030 FT_UInt gindex,
1031 FTC_SBit *sbit,
1032 FTC_Node *anode );
1033
1034 /* */
1035
1036
1037FT_END_HEADER
1038
1039#endif /* FTCACHE_H_ */
1040
1041
1042/* END */
library
FT_Library library
Definition: cffdrivr.c:654
FTC_SBitCache_LookupScaler
FTC_SBitCache_LookupScaler(FTC_SBitCache cache, FTC_Scaler scaler, FT_ULong load_flags, FT_UInt gindex, FTC_SBit *sbit, FTC_Node *anode)
Definition: ftcbasic.c:566
FTC_Manager_Done
FTC_Manager_Done(FTC_Manager manager)
Definition: ftcmanag.c:417
FTC_Face_Requester
FT_Error(* FTC_Face_Requester)(FTC_FaceID face_id, FT_Library library, FT_Pointer req_data, FT_Face *aface)
Definition: ftcache.h:210
FTC_ImageType
struct FTC_ImageTypeRec_ * FTC_ImageType
Definition: ftcache.h:671
FTC_ImageCache
struct FTC_ImageCacheRec_ * FTC_ImageCache
Definition: ftcache.h:693
FTC_SBit
struct FTC_SBitRec_ * FTC_SBit
Definition: ftcache.h:834
FTC_SBitCache
struct FTC_SBitCacheRec_ * FTC_SBitCache
Definition: ftcache.h:901
FTC_ImageCache_Lookup
FTC_ImageCache_Lookup(FTC_ImageCache cache, FTC_ImageType type, FT_UInt gindex, FT_Glyph *aglyph, FTC_Node *anode)
Definition: ftcbasic.c:284
FTC_ScalerRec
struct FTC_ScalerRec_ FTC_ScalerRec
FTC_Manager_RemoveFaceID
FTC_Manager_RemoveFaceID(FTC_Manager manager, FTC_FaceID face_id)
Definition: ftcmanag.c:670
FTC_FaceID
FT_BEGIN_HEADER typedef FT_Pointer FTC_FaceID
Definition: ftcache.h:171
FTC_Node
struct FTC_NodeRec_ * FTC_Node
Definition: ftcache.h:270
FTC_SBitCache_Lookup
FTC_SBitCache_Lookup(FTC_SBitCache cache, FTC_ImageType type, FT_UInt gindex, FTC_SBit *sbit, FTC_Node *anode)
Definition: ftcbasic.c:484
FTC_Manager_LookupFace
FTC_Manager_LookupFace(FTC_Manager manager, FTC_FaceID face_id, FT_Face *aface)
Definition: ftcmanag.c:310
FTC_CMapCache_Lookup
FTC_CMapCache_Lookup(FTC_CMapCache cache, FTC_FaceID face_id, FT_Int cmap_index, FT_UInt32 char_code)
Definition: ftccmap.c:231
FTC_SBitCache_New
FTC_SBitCache_New(FTC_Manager manager, FTC_SBitCache *acache)
Definition: ftcbasic.c:473
FTC_Node_Unref
FTC_Node_Unref(FTC_Node node, FTC_Manager manager)
Definition: ftcmanag.c:694
FTC_Manager_Reset
FTC_Manager_Reset(FTC_Manager manager)
Definition: ftcmanag.c:457
FTC_ImageTypeRec
struct FTC_ImageTypeRec_ FTC_ImageTypeRec
FTC_CMapCache_New
FTC_CMapCache_New(FTC_Manager manager, FTC_CMapCache *acache)
Definition: ftccmap.c:219
FTC_SBitRec
struct FTC_SBitRec_ FTC_SBitRec
FTC_ImageCache_LookupScaler
FTC_ImageCache_LookupScaler(FTC_ImageCache cache, FTC_Scaler scaler, FT_ULong load_flags, FT_UInt gindex, FT_Glyph *aglyph, FTC_Node *anode)
Definition: ftcbasic.c:364
FTC_Manager_LookupSize
FTC_Manager_LookupSize(FTC_Manager manager, FTC_Scaler scaler, FT_Size *asize)
Definition: ftcmanag.c:183
FTC_CMapCache
struct FTC_CMapCacheRec_ * FTC_CMapCache
Definition: ftcache.h:553
FTC_Scaler
struct FTC_ScalerRec_ * FTC_Scaler
Definition: ftcache.h:445
FTC_Manager
struct FTC_ManagerRec_ * FTC_Manager
Definition: ftcache.h:250
FTC_Manager_New
FTC_Manager_New(FT_Library library, FT_UInt max_faces, FT_UInt max_sizes, FT_ULong max_bytes, FTC_Face_Requester requester, FT_Pointer req_data, FTC_Manager *amanager)
Definition: ftcmanag.c:355
FTC_ImageCache_New
FTC_ImageCache_New(FTC_Manager manager, FTC_ImageCache *acache)
Definition: ftcbasic.c:273
FT_EXPORT
#define FT_EXPORT(x)
Definition: ftconfig.h:461
FT_END_HEADER
#define FT_END_HEADER
Definition: ftheader.h:54
FT_BEGIN_HEADER
#define FT_BEGIN_HEADER
Definition: ftheader.h:36
FT_Char
signed char FT_Char
Definition: fttypes.h:143
FT_ULong
unsigned long FT_ULong
Definition: fttypes.h:253
FT_Byte
unsigned char FT_Byte
Definition: fttypes.h:154
FT_Error
int FT_Error
Definition: fttypes.h:300
FT_Short
signed short FT_Short
Definition: fttypes.h:198
FT_UInt
unsigned int FT_UInt
Definition: fttypes.h:231
FT_Int
signed int FT_Int
Definition: fttypes.h:220
type
GLuint GLuint GLsizei GLenum type
Definition: gl.h:1545
FTC_ImageTypeRec_
Definition: ftcache.h:653
FTC_ImageTypeRec_::height
FT_UInt height
Definition: ftcache.h:656
FTC_ImageTypeRec_::flags
FT_Int32 flags
Definition: ftcache.h:657
FTC_ImageTypeRec_::face_id
FTC_FaceID face_id
Definition: ftcache.h:654
FTC_ImageTypeRec_::width
FT_UInt width
Definition: ftcache.h:655
FTC_ManagerRec_
Definition: ftcmanag.h:92
FTC_NodeRec_
Definition: ftccache.h:59
FTC_SBitRec_
Definition: ftcache.h:873
FTC_SBitRec_::pitch
FT_Short pitch
Definition: ftcache.h:881
FTC_SBitRec_::format
FT_Byte format
Definition: ftcache.h:879
FTC_SBitRec_::top
FT_Char top
Definition: ftcache.h:877
FTC_SBitRec_::xadvance
FT_Char xadvance
Definition: ftcache.h:882
FTC_SBitRec_::height
FT_Byte height
Definition: ftcache.h:875
FTC_SBitRec_::width
FT_Byte width
Definition: ftcache.h:874
FTC_SBitRec_::max_grays
FT_Byte max_grays
Definition: ftcache.h:880
FTC_SBitRec_::yadvance
FT_Char yadvance
Definition: ftcache.h:883
FTC_SBitRec_::buffer
FT_Byte * buffer
Definition: ftcache.h:885
FTC_SBitRec_::left
FT_Char left
Definition: ftcache.h:876
FTC_ScalerRec_
Definition: ftcache.h:426
FTC_ScalerRec_::width
FT_UInt width
Definition: ftcache.h:428
FTC_ScalerRec_::x_res
FT_UInt x_res
Definition: ftcache.h:431
FTC_ScalerRec_::face_id
FTC_FaceID face_id
Definition: ftcache.h:427
FTC_ScalerRec_::height
FT_UInt height
Definition: ftcache.h:429
FTC_ScalerRec_::pixel
FT_Int pixel
Definition: ftcache.h:430
FTC_ScalerRec_::y_res
FT_UInt y_res
Definition: ftcache.h:432
FT_FaceRec_
Definition: freetype.h:1069
FT_GlyphRec_
Definition: ftglyph.h:109
FT_LibraryRec_
Definition: ftobjs.h:917
FT_SizeRec_
Definition: freetype.h:1674
cache
Definition: cache.c:49
node
Definition: dlist.c:348