Visualization Library 2.0.0-b5

A lightweight C++ OpenGL middleware for 2D/3D graphics

VL     Star     Watch     Fork     Issue

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

Visualization Library 2.0.0-b5 Reference Documentation

Updated on Mon Feb 10 2020 02:44:39.

© Copyright Michele Bosi. All rights reserved.