ReactOS  0.4.14-dev-342-gdc047f9
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 
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  */
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
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  /* */
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  /* */
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  {
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  /* */
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 )
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 )
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  */
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 )
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  {
657  FT_Int32 flags;
658 
660 
661 
662  /*************************************************************************
663  *
664  * @type:
665  * FTC_ImageType
666  *
667  * @description:
668  * A handle to an @FTC_ImageTypeRec structure.
669  *
670  */
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  /* */
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  /* */
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  /* */
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  {
878 
884 
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  /* */
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  /* */
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 )
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 
1038 
1039 #endif /* FTCACHE_H_ */
1040 
1041 
1042 /* END */
FTC_CMapCache_New(FTC_Manager manager, FTC_CMapCache *acache)
Definition: ftccmap.c:219
Definition: cache.c:46
int FT_Error
Definition: fttypes.h:300
struct FTC_ScalerRec_ * FTC_Scaler
Definition: ftcache.h:445
unsigned long FT_ULong
Definition: fttypes.h:253
struct FTC_NodeRec_ * FTC_Node
Definition: ftcache.h:270
struct FTC_ScalerRec_ FTC_ScalerRec
struct FTC_CMapCacheRec_ * FTC_CMapCache
Definition: ftcache.h:553
#define FT_END_HEADER
Definition: ftheader.h:54
FT_UInt width
Definition: ftcache.h:655
signed int FT_Int
Definition: fttypes.h:220
struct FTC_ImageTypeRec_ FTC_ImageTypeRec
GLuint GLuint GLsizei GLenum type
Definition: gl.h:1545
FT_UInt height
Definition: ftcache.h:429
signed char FT_Char
Definition: fttypes.h:143
FT_Library library
Definition: cffdrivr.c:654
FTC_Manager_Reset(FTC_Manager manager)
Definition: ftcmanag.c:457
struct FTC_ImageTypeRec_ * FTC_ImageType
Definition: ftcache.h:671
FT_BEGIN_HEADER typedef FT_Pointer FTC_FaceID
Definition: ftcache.h:171
FTC_Manager_RemoveFaceID(FTC_Manager manager, FTC_FaceID face_id)
Definition: ftcmanag.c:670
FT_Short pitch
Definition: ftcache.h:881
FT_Char yadvance
Definition: ftcache.h:883
FT_Char top
Definition: ftcache.h:877
FT_Int pixel
Definition: ftcache.h:430
unsigned char FT_Byte
Definition: fttypes.h:154
#define FT_BEGIN_HEADER
Definition: ftheader.h:36
FTC_CMapCache_Lookup(FTC_CMapCache cache, FTC_FaceID face_id, FT_Int cmap_index, FT_UInt32 char_code)
Definition: ftccmap.c:231
struct FTC_ImageCacheRec_ * FTC_ImageCache
Definition: ftcache.h:693
FT_Byte width
Definition: ftcache.h:874
FT_Error(* FTC_Face_Requester)(FTC_FaceID face_id, FT_Library library, FT_Pointer req_data, FT_Face *aface)
Definition: ftcache.h:210
FT_UInt y_res
Definition: ftcache.h:432
FTC_SBitCache_Lookup(FTC_SBitCache cache, FTC_ImageType type, FT_UInt gindex, FTC_SBit *sbit, FTC_Node *anode)
Definition: ftcbasic.c:484
FT_Char left
Definition: ftcache.h:876
struct FTC_ManagerRec_ * FTC_Manager
Definition: ftcache.h:250
FT_UInt width
Definition: ftcache.h:428
FT_Byte max_grays
Definition: ftcache.h:880
FTC_FaceID face_id
Definition: ftcache.h:654
FT_Byte format
Definition: ftcache.h:879
FT_UInt x_res
Definition: ftcache.h:431
FT_Byte * buffer
Definition: ftcache.h:885
FT_Char xadvance
Definition: ftcache.h:882
struct FTC_SBitRec_ * FTC_SBit
Definition: ftcache.h:834
signed short FT_Short
Definition: fttypes.h:198
FTC_ImageCache_New(FTC_Manager manager, FTC_ImageCache *acache)
Definition: ftcbasic.c:273
FTC_SBitCache_New(FTC_Manager manager, FTC_SBitCache *acache)
Definition: ftcbasic.c:473
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_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
FT_Int32 flags
Definition: ftcache.h:657
struct FTC_SBitRec_ FTC_SBitRec
unsigned int FT_UInt
Definition: fttypes.h:231
#define FT_EXPORT(x)
Definition: ftconfig.h:461
FT_UInt height
Definition: ftcache.h:656
FTC_ImageCache_Lookup(FTC_ImageCache cache, FTC_ImageType type, FT_UInt gindex, FT_Glyph *aglyph, FTC_Node *anode)
Definition: ftcbasic.c:284
FT_Byte height
Definition: ftcache.h:875
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_Node_Unref(FTC_Node node, FTC_Manager manager)
Definition: ftcmanag.c:694
FTC_Manager_LookupSize(FTC_Manager manager, FTC_Scaler scaler, FT_Size *asize)
Definition: ftcmanag.c:183
FTC_FaceID face_id
Definition: ftcache.h:427
struct FTC_SBitCacheRec_ * FTC_SBitCache
Definition: ftcache.h:901
FTC_Manager_Done(FTC_Manager manager)
Definition: ftcmanag.c:417
FTC_Manager_LookupFace(FTC_Manager manager, FTC_FaceID face_id, FT_Face *aface)
Definition: ftcmanag.c:310
Definition: dlist.c:348