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