16
16
/***************************************************************************/
19
/*************************************************************************/
20
/*************************************************************************/
21
/*************************************************************************/
22
/*************************************************************************/
23
/*************************************************************************/
25
/********* WARNING, THIS IS BETA CODE. *********/
27
/*************************************************************************/
28
/*************************************************************************/
29
/*************************************************************************/
30
/*************************************************************************/
31
/*************************************************************************/
34
19
#ifndef __FTCACHE_H__
35
20
#define __FTCACHE_H__
45
/*************************************************************************/
51
/* Cache Sub-System */
54
/* How to cache face, size, and glyph data with FreeType 2. */
57
/* This section describes the FreeType 2 cache sub-system which is */
63
/* FTC_Face_Requester */
66
/* FTC_Manager_Reset */
67
/* FTC_Manager_Done */
68
/* FTC_Manager_LookupFace */
69
/* FTC_Manager_LookupSize */
70
/* FTC_Manager_RemoveFaceID */
77
/* FTC_ImageCache_New */
78
/* FTC_ImageCache_Lookup */
82
/* FTC_SBitCache_New */
83
/* FTC_SBitCache_Lookup */
86
/* FTC_CMapCache_New */
87
/* FTC_CMapCache_Lookup */
89
/*************************************************************************/
30
/*************************************************************************
39
* How to cache face, size, and glyph data with FreeType 2.
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.
47
* Note that all types and functions begin with the `FTC_' prefix.
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:
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.
58
* Second, the cache calls, only when needed, a client-provided function
59
* to convert a @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.
63
* Clients are free to map face IDs to anything else. The most simple
64
* usage is to associate them to a (pathname,face_index) pair that is
65
* used to call @FT_New_Face. However, more complex schemes are also
68
* Note that for the cache to work correctly, the face ID values must be
69
* *persistent*, which means that the contents they point to should not
70
* change at runtime, or that their value should not become invalid.
72
* If this is unavoidable (e.g., when a font is uninstalled at runtime),
73
* you should call @FTC_Manager_RemoveFaceID as soon as possible, to let
74
* the cache get rid of any references to the old @FTC_FaceID it may
75
* keep internally. Failure to do so will lead to incorrect behaviour
78
* To use the cache, start with calling @FTC_Manager_New to create a new
79
* @FTC_Manager object, which models a single cache instance. You can
80
* then look up @FT_Face and @FT_Size objects with
81
* @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively.
83
* If you want to use the charmap caching, call @FTC_CMapCache_New, then
84
* later use @FTC_CMapCache_Lookup to perform the equivalent of
85
* @FT_Get_Char_Index, only much faster.
87
* If you want to use the @FT_Glyph caching, call @FTC_ImageCache, then
88
* later use @FTC_ImageCache_Lookup to retrieve the corresponding
89
* @FT_Glyph objects from the cache.
91
* If you need lots of small bitmaps, it is much more memory efficient
92
* to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup. This
93
* returns @FTC_SBitRec structures, which are used to store small
94
* bitmaps directly. (A small bitmap is one whose metrics and
95
* dimensions all fit into 8-bit integers).
97
* We hope to also provide a kerning cache in the near future.
108
* FTC_Manager_LookupFace
109
* FTC_Manager_LookupSize
110
* FTC_Manager_RemoveFaceID
117
* FTC_ImageCache_Lookup
122
* FTC_SBitCache_Lookup
126
* FTC_CMapCache_Lookup
128
*************************************************************************/
92
131
/*************************************************************************/
100
139
/*************************************************************************/
103
/*************************************************************************/
109
/* An opaque pointer type that is used to identity face objects. The */
110
/* contents of such objects is application-dependent. */
142
/*************************************************************************
147
* An opaque pointer type that is used to identity face objects. The
148
* contents of such objects is application-dependent.
150
* These pointers are typically used to point to a user-defined
151
* structure containing a font file path, and face index.
154
* Never use NULL as a valid @FTC_FaceID.
156
* Face IDs are passed by the client to the cache manager, which calls,
157
* when needed, the @FTC_Face_Requester to translate them into new
160
* If the content of a given face ID changes at runtime, or if the value
161
* becomes invalid (e.g., when uninstalling a font), you should
162
* immediately call @FTC_Manager_RemoveFaceID before any other cache
165
* Failure to do so will result in incorrect behaviour or even
166
* memory leaks and crashes.
112
168
typedef struct FTC_FaceIDRec_* FTC_FaceID;
115
/*************************************************************************/
118
/* FTC_Face_Requester */
121
/* A callback function provided by client applications. It is used */
122
/* to translate a given @FTC_FaceID into a new valid @FT_Face object. */
125
/* face_id :: The face ID to resolve. */
127
/* library :: A handle to a FreeType library object. */
129
/* data :: Application-provided request data. */
132
/* aface :: A new @FT_Face handle. */
135
/* FreeType error code. 0 means success. */
138
/* The face requester should not perform funny things on the returned */
139
/* face object, like creating a new @FT_Size for it, or setting a */
140
/* transformation through @FT_Set_Transform! */
171
/************************************************************************
177
* A callback function provided by client applications. It is used by
178
* the cache manager to translate a given @FTC_FaceID into a new valid
179
* @FT_Face object, on demand.
183
* The face ID to resolve.
186
* A handle to a FreeType library object.
189
* Application-provided request data (see note below).
193
* A new @FT_Face handle.
196
* FreeType error code. 0 means success.
199
* The third parameter `req_data' is the same as the one passed by the
200
* client when @FTC_Manager_New is called.
202
* The face requester should not perform funny things on the returned
203
* face object, like creating a new @FT_Size for it, or setting a
204
* transformation through @FT_Set_Transform!
143
207
(*FTC_Face_Requester)( FTC_FaceID face_id,
144
208
FT_Library library,
145
209
FT_Pointer request_data,
146
210
FT_Face* aface );
149
/*************************************************************************/
155
/* A simple structure used to describe a given `font' to the cache */
156
/* manager. Note that a `font' is the combination of a given face */
157
/* with a given character size. */
160
/* face_id :: The ID of the face to use. */
162
/* pix_width :: The character width in integer pixels. */
164
/* pix_height :: The character height in integer pixels. */
166
typedef struct FTC_FontRec_
170
FT_UShort pix_height;
178
#define FTC_FONT_COMPARE( f1, f2 ) \
179
( (f1)->face_id == (f2)->face_id && \
180
(f1)->pix_width == (f2)->pix_width && \
181
(f1)->pix_height == (f2)->pix_height )
183
#define FT_POINTER_TO_ULONG( p ) ((FT_ULong)(FT_Pointer)(p))
185
#define FTC_FACE_ID_HASH( i ) \
186
((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \
214
#define FT_POINTER_TO_ULONG( p ) ( (FT_ULong)(FT_Pointer)(p) )
216
#define FTC_FACE_ID_HASH( i ) \
217
((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \
187
218
( FT_POINTER_TO_ULONG( i ) << 7 ) ) )
189
#define FTC_FONT_HASH( f ) \
190
(FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \
191
((f)->pix_width << 8) ^ \
195
/*************************************************************************/
201
/* A simple handle to an @FTC_FontRec structure. */
203
typedef FTC_FontRec* FTC_Font;
206
221
/*************************************************************************/
207
222
/*************************************************************************/
220
235
/* FTC_Manager */
222
237
/* <Description> */
223
/* This object is used to cache one or more @FT_Face objects, along */
224
/* with corresponding @FT_Size objects. */
238
/* This object corresponds to one instance of the cache-subsystem. */
239
/* It is used to cache one or more @FT_Face objects, along with */
240
/* corresponding @FT_Size objects. */
242
/* The manager intentionally limits the total number of opened */
243
/* @FT_Face and @FT_Size objects to control memory usage. See the */
244
/* `max_faces' and `max_sizes' parameters of @FTC_Manager_New. */
246
/* The manager is also used to cache `nodes' of various types while */
247
/* limiting their total memory usage. */
249
/* All limitations are enforced by keeping lists of managed objects */
250
/* in most-recently-used order, and flushing old nodes to make room */
226
253
typedef struct FTC_ManagerRec_* FTC_Manager;
255
282
/* Creates a new cache manager. */
258
/* library :: The parent FreeType library handle to use. */
260
/* max_bytes :: Maximum number of bytes to use for cached data. */
261
/* Use 0 for defaults. */
263
/* requester :: An application-provided callback used to translate */
264
/* face IDs into real @FT_Face objects. */
266
/* req_data :: A generic pointer that is passed to the requester */
267
/* each time it is called (see @FTC_Face_Requester). */
285
/* library :: The parent FreeType library handle to use. */
287
/* max_faces :: Maximum number of opened @FT_Face objects managed by */
288
/* this cache instance. Use 0 for defaults. */
290
/* max_sizes :: Maximum number of opened @FT_Size objects managed by */
291
/* this cache instance. Use 0 for defaults. */
293
/* max_bytes :: Maximum number of bytes to use for cached data nodes. */
294
/* Use 0 for defaults. Note that this value does not */
295
/* account for managed @FT_Face and @FT_Size objects. */
297
/* requester :: An application-provided callback used to translate */
298
/* face IDs into real @FT_Face objects. */
300
/* req_data :: A generic pointer that is passed to the requester */
301
/* each time it is called (see @FTC_Face_Requester). */
270
304
/* amanager :: A handle to a new manager object. 0 in case of */
449
500
FTC_Manager manager );
452
/* remove all nodes belonging to a given face_id */
503
/*************************************************************************
506
* FTC_Manager_RemoveFaceID
509
* A special function used to indicate to the cache manager that
510
* a given @FTC_FaceID is no longer valid, either because its
511
* content changed, or because it was deallocated or uninstalled.
515
* The cache manager handle.
518
* The @FTC_FaceID to be removed.
521
* This function flushes all nodes from the cache corresponding to this
522
* `face_id', with the exception of nodes with a non-null reference
525
* Such nodes are however modified internally so as to never appear
526
* in later lookups with the same `face_id' value, and to be immediately
527
* destroyed when released by all their users.
453
530
FT_EXPORT( void )
454
531
FTC_Manager_RemoveFaceID( FTC_Manager manager,
455
532
FTC_FaceID face_id );
463
540
/*************************************************************************/
465
/************************************************************************
542
/*************************************************************************
471
* An opaque handle used to manager a charmap cache. This cache is
472
* to hold character codes -> glyph indices mappings.
548
* An opaque handle used to model a charmap cache. This cache is to
549
* hold character codes -> glyph indices mappings.
474
552
typedef struct FTC_CMapCacheRec_* FTC_CMapCache;
477
/*************************************************************************/
480
/* FTC_CMapCache_New */
483
/* Create a new charmap cache. */
486
/* manager :: A handle to the cache manager. */
489
/* acache :: A new cache handle. NULL in case of error. */
492
/* FreeType error code. 0 means success. */
495
/* Like all other caches, this one will be destroyed with the cache */
555
/*************************************************************************
561
* Create a new charmap cache.
565
* A handle to the cache manager.
569
* A new cache handle. NULL in case of error.
572
* FreeType error code. 0 means success.
575
* Like all other caches, this one will be destroyed with the cache
498
579
FT_EXPORT( FT_Error )
499
580
FTC_CMapCache_New( FTC_Manager manager,
500
581
FTC_CMapCache *acache );
503
/*************************************************************************/
506
/* FTC_CMapCache_Lookup */
509
/* Translate a character code into a glyph index, using the charmap */
513
/* cache :: A charmap cache handle. */
515
/* face_id :: The source face ID. */
517
/* cmap_index :: The index of the charmap in the source face. */
519
/* char_code :: The character code (in the corresponding charmap). */
522
/* Glyph index. 0 means `no glyph'. */
584
/************************************************************************
587
* FTC_CMapCache_Lookup
590
* Translate a character code into a glyph index, using the charmap
595
* A charmap cache handle.
598
* The source face ID.
601
* The index of the charmap in the source face.
604
* The character code (in the corresponding charmap).
607
* Glyph index. 0 means `no glyph'.
524
610
FT_EXPORT( FT_UInt )
525
611
FTC_CMapCache_Lookup( FTC_CMapCache cache,
526
612
FTC_FaceID face_id,
546
632
/*************************************************************************/
547
633
/*************************************************************************/
636
/*************************************************************************
642
* A structure used to model the type of images in a glyph cache.
649
* The width in pixels.
652
* The height in pixels.
655
* The load flags, as in @FT_Load_Glyph.
549
658
typedef struct FTC_ImageTypeRec_
556
665
} FTC_ImageTypeRec;
558
typedef struct FTC_ImageTypeRec_* FTC_ImageType;
562
#define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \
563
( FTC_FONT_COMPARE( &(d1)->font, &(d2)->font ) && \
564
(d1)->flags == (d2)->flags )
566
#define FTC_IMAGE_TYPE_HASH( d ) \
567
(FT_UFast)( FTC_FONT_HASH( &(d)->font ) ^ \
568
( (d)->flags << 4 ) )
668
/*************************************************************************
674
* A handle to an @FTC_ImageTypeRec structure.
677
typedef struct FTC_ImageTypeRec_* FTC_ImageType;
683
#define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \
684
( (d1)->face_id == (d2)->face_id && \
685
(d1)->width == (d2)->width && \
686
(d1)->flags == (d2)->flags )
688
#define FTC_IMAGE_TYPE_HASH( d ) \
689
(FT_UFast)( FTC_FACE_ID_HASH( (d)->face_id ) ^ \
690
( (d)->width << 8 ) ^ (d)->height ^ \
691
( (d)->flags << 4 ) )
571
694
/*************************************************************************/
935
#ifdef FT_CONFIG_OPTION_OLD_INTERNALS
937
/*@***********************************************************************/
943
/* A simple structure used to describe a given `font' to the cache */
944
/* manager. Note that a `font' is the combination of a given face */
945
/* with a given character size. */
948
/* face_id :: The ID of the face to use. */
950
/* pix_width :: The character width in integer pixels. */
952
/* pix_height :: The character height in integer pixels. */
954
typedef struct FTC_FontRec_
958
FT_UShort pix_height;
966
#define FTC_FONT_COMPARE( f1, f2 ) \
967
( (f1)->face_id == (f2)->face_id && \
968
(f1)->pix_width == (f2)->pix_width && \
969
(f1)->pix_height == (f2)->pix_height )
971
#define FTC_FONT_HASH( f ) \
972
(FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \
973
((f)->pix_width << 8) ^ \
976
typedef FTC_FontRec* FTC_Font;
979
FT_EXPORT( FT_Error )
980
FTC_Manager_Lookup_Face( FTC_Manager manager,
984
FT_EXPORT( FT_Error )
985
FTC_Manager_Lookup_Size( FTC_Manager manager,
990
#endif /* FT_CONFIG_OPTION_OLD_INTERNALS */
814
997
#endif /* __FTCACHE_H__ */
added
removed
src/3rdparty/freetype/include/freetype/ftcache.h
