1 /****************************************************************************
2 *
3 * ftcache.h
4 *
5 * FreeType Cache subsystem (specification).
6 *
7 * Copyright (C) 1996-2023 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 <freetype/ftglyph.h>
24
25
26 FT_BEGIN_HEADER
27
28
29 /**************************************************************************
30 *
31 * @section:
32 * cache_subsystem
33 *
34 * @title:
35 * Cache Sub-System
36 *
37 * @abstract:
38 * How to cache face, size, and glyph data with FreeType~2.
39 *
40 * @description:
41 * This section describes the FreeType~2 cache sub-system, which is used
42 * to limit the number of concurrently opened @FT_Face and @FT_Size
43 * objects, as well as caching information like character maps and glyph
44 * images while limiting their maximum memory usage.
45 *
46 * Note that all types and functions begin with the `FTC_` prefix rather
47 * than the usual `FT_` prefix in the rest of FreeType.
48 *
49 * The cache is highly portable and, thus, doesn't know anything about
50 * the fonts installed on your system, or how to access them. Therefore,
51 * it requires the following.
52 *
53 * * @FTC_FaceID, an arbitrary non-zero value that uniquely identifies
54 * available or installed font faces, has to be provided to the
55 * cache by the client. Note that the cache only stores and compares
56 * these values and doesn't try to interpret them in any way, but they
57 * have to be persistent on the client side.
58 *
59 * * @FTC_Face_Requester, a method to convert an @FTC_FaceID into a new
60 * @FT_Face object when necessary, has to be provided to the cache by
61 * the client. The @FT_Face object is completely managed by the cache,
62 * including its termination through @FT_Done_Face. To monitor
63 * termination of face objects, the finalizer callback in the `generic`
64 * field of the @FT_Face object can be used, which might also be used
65 * to store the @FTC_FaceID of the face.
66 *
67 * Clients are free to map face IDs to anything useful. The most simple
68 * usage is, for example, to associate them to a `{pathname,face_index}`
69 * pair that is then used by @FTC_Face_Requester to call @FT_New_Face.
70 * However, more complex schemes are also possible.
71 *
72 * Note that for the cache to work correctly, the face ID values must be
73 * **persistent**, which means that the contents they point to should not
74 * change at runtime, or that their value should not become invalid.
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 in @FTC_Face_Requester.
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, and
85 * use them in any FreeType work stream. You can also cache other
86 * FreeType objects as follows.
87 *
88 * * If you want to use the charmap caching, call @FTC_CMapCache_New,
89 * then later use @FTC_CMapCache_Lookup to perform the equivalent of
90 * @FT_Get_Char_Index, only much faster.
91 *
92 * * If you want to use the @FT_Glyph caching, call @FTC_ImageCache_New,
93 * then later use @FTC_ImageCache_Lookup to retrieve the corresponding
94 * @FT_Glyph objects from the cache.
95 *
96 * * If you need lots of small bitmaps, it is much more memory-efficient
97 * to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup. This
98 * returns @FTC_SBitRec structures, which are used to store small
99 * bitmaps directly. (A small bitmap is one whose metrics and
100 * dimensions all fit into 8-bit integers).
101 *
102 * @order:
103 * FTC_Manager
104 * FTC_FaceID
105 * FTC_Face_Requester
106 *
107 * FTC_Manager_New
108 * FTC_Manager_Reset
109 * FTC_Manager_Done
110 * FTC_Manager_LookupFace
111 * FTC_Manager_LookupSize
112 * FTC_Manager_RemoveFaceID
113 *
114 * FTC_Node
115 * FTC_Node_Unref
116 *
117 * FTC_ImageCache
118 * FTC_ImageCache_New
119 * FTC_ImageCache_Lookup
120 *
121 * FTC_SBit
122 * FTC_SBitCache
123 * FTC_SBitCache_New
124 * FTC_SBitCache_Lookup
125 *
126 * FTC_CMapCache
127 * FTC_CMapCache_New
128 * FTC_CMapCache_Lookup
129 *
130 *************************************************************************/
131
132
133 /*************************************************************************/
134 /*************************************************************************/
135 /*************************************************************************/
136 /***** *****/
137 /***** BASIC TYPE DEFINITIONS *****/
138 /***** *****/
139 /*************************************************************************/
140 /*************************************************************************/
141 /*************************************************************************/
142
143
144 /**************************************************************************
145 *
146 * @type:
147 * 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 structure
154 * 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 memory
169 * 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. It is
236 * used to cache one or more @FT_Face objects, along with corresponding
237 * @FT_Size objects.
238 *
239 * The manager intentionally limits the total number of opened @FT_Face
240 * and @FT_Size objects to control memory usage. See the `max_faces` and
241 * `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 in
247 * most-recently-used order, and flushing old nodes to make room for new
248 * 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 out of a
261 * full cache whenever a lookup request is performed.
262 *
263 * If you look up nodes, you have the ability to 'acquire' them, i.e., to
264 * increment their reference count. This will prevent the node from
265 * being flushed out of the cache until you explicitly 'release' it (see
266 * @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 ::
283 * The parent FreeType library handle to use.
284 *
285 * max_faces ::
286 * Maximum number of opened @FT_Face objects managed by this cache
287 * instance. Use~0 for defaults.
288 *
289 * max_sizes ::
290 * Maximum number of opened @FT_Size objects managed by this cache
291 * instance. Use~0 for defaults.
292 *
293 * max_bytes ::
294 * Maximum number of bytes to use for cached data nodes. Use~0 for
295 * defaults. Note that this value does not account for managed
296 * @FT_Face and @FT_Size objects.
297 *
298 * requester ::
299 * An application-provided callback used to translate face IDs into
300 * real @FT_Face objects.
301 *
302 * req_data ::
303 * A generic pointer that is passed to the requester each time it is
304 * called (see @FTC_Face_Requester).
305 *
306 * @output:
307 * amanager ::
308 * A handle to a new manager object. 0~in case of failure.
309 *
310 * @return:
311 * FreeType error code. 0~means success.
312 */
313 FT_EXPORT( FT_Error )
314 FTC_Manager_New( FT_Library library,
315 FT_UInt max_faces,
316 FT_UInt max_sizes,
317 FT_ULong max_bytes,
318 FTC_Face_Requester requester,
319 FT_Pointer req_data,
320 FTC_Manager *amanager );
321
322
323 /**************************************************************************
324 *
325 * @function:
326 * FTC_Manager_Reset
327 *
328 * @description:
329 * Empty a given cache manager. This simply gets rid of all the
330 * currently cached @FT_Face and @FT_Size objects within the manager.
331 *
332 * @inout:
333 * manager ::
334 * A handle to the manager.
335 */
336 FT_EXPORT( void )
337 FTC_Manager_Reset( FTC_Manager manager );
338
339
340 /**************************************************************************
341 *
342 * @function:
343 * FTC_Manager_Done
344 *
345 * @description:
346 * Destroy a given manager after emptying it.
347 *
348 * @input:
349 * manager ::
350 * A handle to the target cache manager object.
351 */
352 FT_EXPORT( void )
353 FTC_Manager_Done( FTC_Manager manager );
354
355
356 /**************************************************************************
357 *
358 * @function:
359 * FTC_Manager_LookupFace
360 *
361 * @description:
362 * Retrieve the @FT_Face object that corresponds to a given face ID
363 * through a cache manager.
364 *
365 * @input:
366 * manager ::
367 * A handle to the cache manager.
368 *
369 * face_id ::
370 * The ID of the face object.
371 *
372 * @output:
373 * aface ::
374 * 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', use
385 * @FTC_Manager_LookupSize instead.
386 *
387 * Never change the face's transformation matrix (i.e., never call the
388 * @FT_Set_Transform function) on a returned face! If you need to
389 * transform glyphs, do it yourself after glyph loading.
390 *
391 * When you perform a lookup, out-of-memory errors are detected _within_
392 * the lookup and force incremental flushes of the cache until enough
393 * memory is released for the lookup to succeed.
394 *
395 * If a lookup fails with `FT_Err_Out_Of_Memory` the cache has already
396 * been completely flushed, and still no memory was available for the
397 * operation.
398 */
399 FT_EXPORT( FT_Error )
400 FTC_Manager_LookupFace( FTC_Manager manager,
401 FTC_FaceID face_id,
402 FT_Face *aface );
403
404
405 /**************************************************************************
406 *
407 * @struct:
408 * FTC_ScalerRec
409 *
410 * @description:
411 * A structure used to describe a given character size in either pixels
412 * or points to the cache manager. See @FTC_Manager_LookupSize.
413 *
414 * @fields:
415 * face_id ::
416 * The source face ID.
417 *
418 * width ::
419 * The character width.
420 *
421 * height ::
422 * The character height.
423 *
424 * pixel ::
425 * A Boolean. If 1, the `width` and `height` fields are interpreted as
426 * integer pixel character sizes. Otherwise, they are expressed as
427 * 1/64 of points.
428 *
429 * x_res ::
430 * Only used when `pixel` is value~0 to indicate the horizontal
431 * resolution in dpi.
432 *
433 * y_res ::
434 * Only used when `pixel` is value~0 to indicate the vertical
435 * resolution in dpi.
436 *
437 * @note:
438 * This type is mainly used to retrieve @FT_Size objects through the
439 * cache manager.
440 */
441 typedef struct FTC_ScalerRec_
442 {
443 FTC_FaceID face_id;
444 FT_UInt width;
445 FT_UInt height;
446 FT_Int pixel;
447 FT_UInt x_res;
448 FT_UInt y_res;
449
450 } FTC_ScalerRec;
451
452
453 /**************************************************************************
454 *
455 * @struct:
456 * FTC_Scaler
457 *
458 * @description:
459 * A handle to an @FTC_ScalerRec structure.
460 */
461 typedef struct FTC_ScalerRec_* FTC_Scaler;
462
463
464 /**************************************************************************
465 *
466 * @function:
467 * FTC_Manager_LookupSize
468 *
469 * @description:
470 * Retrieve the @FT_Size object that corresponds to a given
471 * @FTC_ScalerRec pointer through a cache manager.
472 *
473 * @input:
474 * manager ::
475 * A handle to the cache manager.
476 *
477 * scaler ::
478 * A scaler handle.
479 *
480 * @output:
481 * asize ::
482 * A handle to the size object.
483 *
484 * @return:
485 * FreeType error code. 0~means success.
486 *
487 * @note:
488 * The returned @FT_Size object is always owned by the manager. You
489 * should never try to discard it by yourself.
490 *
491 * You can access the parent @FT_Face object simply as `size->face` if
492 * you need it. Note that this object is also owned by the manager.
493 *
494 * @note:
495 * When you perform a lookup, out-of-memory errors are detected _within_
496 * the lookup and force incremental flushes of the cache until enough
497 * memory is released for the lookup to succeed.
498 *
499 * If a lookup fails with `FT_Err_Out_Of_Memory` the cache has already
500 * been completely flushed, and still no memory is available for the
501 * operation.
502 */
503 FT_EXPORT( FT_Error )
504 FTC_Manager_LookupSize( FTC_Manager manager,
505 FTC_Scaler scaler,
506 FT_Size *asize );
507
508
509 /**************************************************************************
510 *
511 * @function:
512 * FTC_Node_Unref
513 *
514 * @description:
515 * Decrement a cache node's internal reference count. When the count
516 * reaches 0, it is not destroyed but becomes eligible for subsequent
517 * cache flushes.
518 *
519 * @input:
520 * node ::
521 * The cache node handle.
522 *
523 * manager ::
524 * The cache manager handle.
525 */
526 FT_EXPORT( void )
527 FTC_Node_Unref( FTC_Node node,
528 FTC_Manager manager );
529
530
531 /**************************************************************************
532 *
533 * @function:
534 * FTC_Manager_RemoveFaceID
535 *
536 * @description:
537 * A special function used to indicate to the cache manager that a given
538 * @FTC_FaceID is no longer valid, either because its content changed, or
539 * because it was deallocated or uninstalled.
540 *
541 * @input:
542 * manager ::
543 * The cache manager handle.
544 *
545 * face_id ::
546 * The @FTC_FaceID to be removed.
547 *
548 * @note:
549 * This function flushes all nodes from the cache corresponding to this
550 * `face_id`, with the exception of nodes with a non-null reference
551 * count.
552 *
553 * Such nodes are however modified internally so as to never appear in
554 * later lookups with the same `face_id` value, and to be immediately
555 * destroyed when released by all their users.
556 *
557 */
558 FT_EXPORT( void )
559 FTC_Manager_RemoveFaceID( FTC_Manager manager,
560 FTC_FaceID face_id );
561
562
563 /**************************************************************************
564 *
565 * @type:
566 * FTC_CMapCache
567 *
568 * @description:
569 * An opaque handle used to model a charmap cache. This cache is to hold
570 * character codes -> glyph indices mappings.
571 *
572 */
573 typedef struct FTC_CMapCacheRec_* FTC_CMapCache;
574
575
576 /**************************************************************************
577 *
578 * @function:
579 * FTC_CMapCache_New
580 *
581 * @description:
582 * Create a new charmap cache.
583 *
584 * @input:
585 * manager ::
586 * A handle to the cache manager.
587 *
588 * @output:
589 * acache ::
590 * A new cache handle. `NULL` in case of error.
591 *
592 * @return:
593 * FreeType error code. 0~means success.
594 *
595 * @note:
596 * Like all other caches, this one will be destroyed with the cache
597 * manager.
598 *
599 */
600 FT_EXPORT( FT_Error )
601 FTC_CMapCache_New( FTC_Manager manager,
602 FTC_CMapCache *acache );
603
604
605 /**************************************************************************
606 *
607 * @function:
608 * FTC_CMapCache_Lookup
609 *
610 * @description:
611 * Translate a character code into a glyph index, using the charmap
612 * cache.
613 *
614 * @input:
615 * cache ::
616 * A charmap cache handle.
617 *
618 * face_id ::
619 * The source face ID.
620 *
621 * cmap_index ::
622 * The index of the charmap in the source face. Any negative value
623 * means to use the cache @FT_Face's default charmap.
624 *
625 * char_code ::
626 * The character code (in the corresponding charmap).
627 *
628 * @return:
629 * Glyph index. 0~means 'no glyph'.
630 *
631 */
632 FT_EXPORT( FT_UInt )
633 FTC_CMapCache_Lookup( FTC_CMapCache cache,
634 FTC_FaceID face_id,
635 FT_Int cmap_index,
636 FT_UInt32 char_code );
637
638
639 /*************************************************************************/
640 /*************************************************************************/
641 /*************************************************************************/
642 /***** *****/
643 /***** IMAGE CACHE OBJECT *****/
644 /***** *****/
645 /*************************************************************************/
646 /*************************************************************************/
647 /*************************************************************************/
648
649
650 /**************************************************************************
651 *
652 * @struct:
653 * FTC_ImageTypeRec
654 *
655 * @description:
656 * A structure used to model the type of images in a glyph cache.
657 *
658 * @fields:
659 * face_id ::
660 * The face ID.
661 *
662 * width ::
663 * The width in pixels.
664 *
665 * height ::
666 * The height in pixels.
667 *
668 * flags ::
669 * The load flags, as in @FT_Load_Glyph.
670 *
671 */
672 typedef struct FTC_ImageTypeRec_
673 {
674 FTC_FaceID face_id;
675 FT_UInt width;
676 FT_UInt height;
677 FT_Int32 flags;
678
679 } FTC_ImageTypeRec;
680
681
682 /**************************************************************************
683 *
684 * @type:
685 * FTC_ImageType
686 *
687 * @description:
688 * A handle to an @FTC_ImageTypeRec structure.
689 *
690 */
691 typedef struct FTC_ImageTypeRec_* FTC_ImageType;
692
693
694 /* */
695
696
697 #define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \
698 ( (d1)->face_id == (d2)->face_id && \
699 (d1)->width == (d2)->width && \
700 (d1)->flags == (d2)->flags )
701
702
703 /**************************************************************************
704 *
705 * @type:
706 * FTC_ImageCache
707 *
708 * @description:
709 * A handle to a glyph image cache object. They are designed to hold
710 * many distinct glyph images while not exceeding a certain memory
711 * threshold.
712 */
713 typedef struct FTC_ImageCacheRec_* FTC_ImageCache;
714
715
716 /**************************************************************************
717 *
718 * @function:
719 * FTC_ImageCache_New
720 *
721 * @description:
722 * Create a new glyph image cache.
723 *
724 * @input:
725 * manager ::
726 * The parent manager for the image cache.
727 *
728 * @output:
729 * acache ::
730 * A handle to the new glyph image cache object.
731 *
732 * @return:
733 * FreeType error code. 0~means success.
734 */
735 FT_EXPORT( FT_Error )
736 FTC_ImageCache_New( FTC_Manager manager,
737 FTC_ImageCache *acache );
738
739
740 /**************************************************************************
741 *
742 * @function:
743 * FTC_ImageCache_Lookup
744 *
745 * @description:
746 * Retrieve a given glyph image from a glyph image cache.
747 *
748 * @input:
749 * cache ::
750 * A handle to the source glyph image cache.
751 *
752 * type ::
753 * A pointer to a glyph image type descriptor.
754 *
755 * gindex ::
756 * The glyph index to retrieve.
757 *
758 * @output:
759 * aglyph ::
760 * The corresponding @FT_Glyph object. 0~in case of failure.
761 *
762 * anode ::
763 * Used to return the address of the corresponding cache node after
764 * incrementing its reference count (see note below).
765 *
766 * @return:
767 * FreeType error code. 0~means success.
768 *
769 * @note:
770 * The returned glyph is owned and managed by the glyph image cache.
771 * Never try to transform or discard it manually! You can however create
772 * a copy with @FT_Glyph_Copy and modify the new one.
773 *
774 * If `anode` is _not_ `NULL`, it receives the address of the cache node
775 * containing the glyph image, after increasing its reference count.
776 * This ensures that the node (as well as the @FT_Glyph) will always be
777 * kept in the cache until you call @FTC_Node_Unref to 'release' it.
778 *
779 * If `anode` is `NULL`, the cache node is left unchanged, which means
780 * that the @FT_Glyph could be flushed out of the cache on the next call
781 * to one of the caching sub-system APIs. Don't assume that it is
782 * persistent!
783 */
784 FT_EXPORT( FT_Error )
785 FTC_ImageCache_Lookup( FTC_ImageCache cache,
786 FTC_ImageType type,
787 FT_UInt gindex,
788 FT_Glyph *aglyph,
789 FTC_Node *anode );
790
791
792 /**************************************************************************
793 *
794 * @function:
795 * FTC_ImageCache_LookupScaler
796 *
797 * @description:
798 * A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec to
799 * specify the face ID and its size.
800 *
801 * @input:
802 * cache ::
803 * A handle to the source glyph image cache.
804 *
805 * scaler ::
806 * A pointer to a scaler descriptor.
807 *
808 * load_flags ::
809 * The corresponding load flags.
810 *
811 * gindex ::
812 * The glyph index to retrieve.
813 *
814 * @output:
815 * aglyph ::
816 * The corresponding @FT_Glyph object. 0~in case of failure.
817 *
818 * anode ::
819 * Used to return the address of the corresponding cache node after
820 * incrementing its reference count (see note below).
821 *
822 * @return:
823 * FreeType error code. 0~means success.
824 *
825 * @note:
826 * The returned glyph is owned and managed by the glyph image cache.
827 * Never try to transform or discard it manually! You can however create
828 * a copy with @FT_Glyph_Copy and modify the new one.
829 *
830 * If `anode` is _not_ `NULL`, it receives the address of the cache node
831 * containing the glyph image, after increasing its reference count.
832 * This ensures that the node (as well as the @FT_Glyph) will always be
833 * kept in the cache until you call @FTC_Node_Unref to 'release' it.
834 *
835 * If `anode` is `NULL`, the cache node is left unchanged, which means
836 * that the @FT_Glyph could be flushed out of the cache on the next call
837 * to one of the caching sub-system APIs. Don't assume that it is
838 * persistent!
839 *
840 * Calls to @FT_Set_Char_Size and friends have no effect on cached
841 * glyphs; you should always use the FreeType cache API instead.
842 */
843 FT_EXPORT( FT_Error )
844 FTC_ImageCache_LookupScaler( FTC_ImageCache cache,
845 FTC_Scaler scaler,
846 FT_ULong load_flags,
847 FT_UInt gindex,
848 FT_Glyph *aglyph,
849 FTC_Node *anode );
850
851
852 /**************************************************************************
853 *
854 * @type:
855 * FTC_SBit
856 *
857 * @description:
858 * A handle to a small bitmap descriptor. See the @FTC_SBitRec structure
859 * for details.
860 */
861 typedef struct FTC_SBitRec_* FTC_SBit;
862
863
864 /**************************************************************************
865 *
866 * @struct:
867 * FTC_SBitRec
868 *
869 * @description:
870 * A very compact structure used to describe a small glyph bitmap.
871 *
872 * @fields:
873 * width ::
874 * The bitmap width in pixels.
875 *
876 * height ::
877 * The bitmap height in pixels.
878 *
879 * left ::
880 * The horizontal distance from the pen position to the left bitmap
881 * border (a.k.a. 'left side bearing', or 'lsb').
882 *
883 * top ::
884 * The vertical distance from the pen position (on the baseline) to the
885 * upper bitmap border (a.k.a. 'top side bearing'). The distance is
886 * positive for upwards y~coordinates.
887 *
888 * format ::
889 * The format of the glyph bitmap (monochrome or gray).
890 *
891 * max_grays ::
892 * Maximum gray level value (in the range 1 to~255).
893 *
894 * pitch ::
895 * The number of bytes per bitmap line. May be positive or negative.
896 *
897 * xadvance ::
898 * The horizontal advance width in pixels.
899 *
900 * yadvance ::
901 * The vertical advance height in pixels.
902 *
903 * buffer ::
904 * A pointer to the bitmap pixels.
905 */
906 typedef struct FTC_SBitRec_
907 {
908 FT_Byte width;
909 FT_Byte height;
910 FT_Char left;
911 FT_Char top;
912
913 FT_Byte format;
914 FT_Byte max_grays;
915 FT_Short pitch;
916 FT_Char xadvance;
917 FT_Char yadvance;
918
919 FT_Byte* buffer;
920
921 } FTC_SBitRec;
922
923
924 /**************************************************************************
925 *
926 * @type:
927 * FTC_SBitCache
928 *
929 * @description:
930 * A handle to a small bitmap cache. These are special cache objects
931 * used to store small glyph bitmaps (and anti-aliased pixmaps) in a much
932 * more efficient way than the traditional glyph image cache implemented
933 * by @FTC_ImageCache.
934 */
935 typedef struct FTC_SBitCacheRec_* FTC_SBitCache;
936
937
938 /**************************************************************************
939 *
940 * @function:
941 * FTC_SBitCache_New
942 *
943 * @description:
944 * Create a new cache to store small glyph bitmaps.
945 *
946 * @input:
947 * manager ::
948 * A handle to the source cache manager.
949 *
950 * @output:
951 * acache ::
952 * A handle to the new sbit cache. `NULL` in case of error.
953 *
954 * @return:
955 * FreeType error code. 0~means success.
956 */
957 FT_EXPORT( FT_Error )
958 FTC_SBitCache_New( FTC_Manager manager,
959 FTC_SBitCache *acache );
960
961
962 /**************************************************************************
963 *
964 * @function:
965 * FTC_SBitCache_Lookup
966 *
967 * @description:
968 * Look up a given small glyph bitmap in a given sbit cache and 'lock' it
969 * to prevent its flushing from the cache until needed.
970 *
971 * @input:
972 * cache ::
973 * A handle to the source sbit cache.
974 *
975 * type ::
976 * A pointer to the glyph image type descriptor.
977 *
978 * gindex ::
979 * The glyph index.
980 *
981 * @output:
982 * sbit ::
983 * A handle to a small bitmap descriptor.
984 *
985 * anode ::
986 * Used to return the address of the corresponding cache node after
987 * incrementing its reference count (see note below).
988 *
989 * @return:
990 * FreeType error code. 0~means success.
991 *
992 * @note:
993 * The small bitmap descriptor and its bit buffer are owned by the cache
994 * and should never be freed by the application. They might as well
995 * disappear from memory on the next cache lookup, so don't treat them as
996 * persistent data.
997 *
998 * The descriptor's `buffer` field is set to~0 to indicate a missing
999 * glyph bitmap.
1000 *
1001 * If `anode` is _not_ `NULL`, it receives the address of the cache node
1002 * containing the bitmap, after increasing its reference count. This
1003 * ensures that the node (as well as the image) will always be kept in
1004 * the cache until you call @FTC_Node_Unref to 'release' it.
1005 *
1006 * If `anode` is `NULL`, the cache node is left unchanged, which means
1007 * that the bitmap could be flushed out of the cache on the next call to
1008 * one of the caching sub-system APIs. Don't assume that it is
1009 * persistent!
1010 */
1011 FT_EXPORT( FT_Error )
1012 FTC_SBitCache_Lookup( FTC_SBitCache cache,
1013 FTC_ImageType type,
1014 FT_UInt gindex,
1015 FTC_SBit *sbit,
1016 FTC_Node *anode );
1017
1018
1019 /**************************************************************************
1020 *
1021 * @function:
1022 * FTC_SBitCache_LookupScaler
1023 *
1024 * @description:
1025 * A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec to
1026 * specify the face ID and its size.
1027 *
1028 * @input:
1029 * cache ::
1030 * A handle to the source sbit cache.
1031 *
1032 * scaler ::
1033 * A pointer to the scaler descriptor.
1034 *
1035 * load_flags ::
1036 * The corresponding load flags.
1037 *
1038 * gindex ::
1039 * The glyph index.
1040 *
1041 * @output:
1042 * sbit ::
1043 * A handle to a small bitmap descriptor.
1044 *
1045 * anode ::
1046 * Used to return the address of the corresponding cache node after
1047 * incrementing its reference count (see note below).
1048 *
1049 * @return:
1050 * FreeType error code. 0~means success.
1051 *
1052 * @note:
1053 * The small bitmap descriptor and its bit buffer are owned by the cache
1054 * and should never be freed by the application. They might as well
1055 * disappear from memory on the next cache lookup, so don't treat them as
1056 * persistent data.
1057 *
1058 * The descriptor's `buffer` field is set to~0 to indicate a missing
1059 * glyph bitmap.
1060 *
1061 * If `anode` is _not_ `NULL`, it receives the address of the cache node
1062 * containing the bitmap, after increasing its reference count. This
1063 * ensures that the node (as well as the image) will always be kept in
1064 * the cache until you call @FTC_Node_Unref to 'release' it.
1065 *
1066 * If `anode` is `NULL`, the cache node is left unchanged, which means
1067 * that the bitmap could be flushed out of the cache on the next call to
1068 * one of the caching sub-system APIs. Don't assume that it is
1069 * persistent!
1070 */
1071 FT_EXPORT( FT_Error )
1072 FTC_SBitCache_LookupScaler( FTC_SBitCache cache,
1073 FTC_Scaler scaler,
1074 FT_ULong load_flags,
1075 FT_UInt gindex,
1076 FTC_SBit *sbit,
1077 FTC_Node *anode );
1078
1079 /* */
1080
1081
1082 FT_END_HEADER
1083
1084 #endif /* FTCACHE_H_ */
1085
1086
1087 /* END */