XFA: merge patch from CL 815103002
[pdfium.git] / third_party / freetype / include / ftcache.h
1 /***************************************************************************/
2 /*                                                                         */
3 /*  ftcache.h                                                              */
4 /*                                                                         */
5 /*    FreeType Cache subsystem (specification).                            */
6 /*                                                                         */
7 /*  Copyright 1996-2008, 2010, 2013, 2014 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 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    */
171   typedef FT_Pointer  FTC_FaceID;
172
173
174   /************************************************************************
175    *
176    * @functype:
177    *   FTC_Face_Requester
178    *
179    * @description:
180    *   A callback function provided by client applications.  It is used by
181    *   the cache manager to translate a given @FTC_FaceID into a new valid
182    *   @FT_Face object, on demand.
183    *
184    * <Input>
185    *   face_id ::
186    *     The face ID to resolve.
187    *
188    *   library ::
189    *     A handle to a FreeType library object.
190    *
191    *   req_data ::
192    *     Application-provided request data (see note below).
193    *
194    * <Output>
195    *   aface ::
196    *     A new @FT_Face handle.
197    *
198    * <Return>
199    *   FreeType error code.  0~means success.
200    *
201    * <Note>
202    *   The third parameter `req_data' is the same as the one passed by the
203    *   client when @FTC_Manager_New is called.
204    *
205    *   The face requester should not perform funny things on the returned
206    *   face object, like creating a new @FT_Size for it, or setting a
207    *   transformation through @FT_Set_Transform!
208    */
209   typedef FT_Error
210   (*FTC_Face_Requester)( FTC_FaceID  face_id,
211                          FT_Library  library,
212                          FT_Pointer  req_data,
213                          FT_Face*    aface );
214
215   /* */
216
217
218   /*************************************************************************/
219   /*************************************************************************/
220   /*************************************************************************/
221   /*****                                                               *****/
222   /*****                      CACHE MANAGER OBJECT                     *****/
223   /*****                                                               *****/
224   /*************************************************************************/
225   /*************************************************************************/
226   /*************************************************************************/
227
228
229   /*************************************************************************/
230   /*                                                                       */
231   /* <Type>                                                                */
232   /*    FTC_Manager                                                        */
233   /*                                                                       */
234   /* <Description>                                                         */
235   /*    This object corresponds to one instance of the cache-subsystem.    */
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   /*                                                                       */
307   FT_EXPORT( FT_Error )
308   FTC_Manager_New( FT_Library          library,
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   /*                                                                       */
388   FT_EXPORT( FT_Error )
389   FTC_Manager_LookupFace( FTC_Manager  manager,
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   {
427     FTC_FaceID  face_id;
428     FT_UInt     width;
429     FT_UInt     height;
430     FT_Int      pixel;
431     FT_UInt     x_res;
432     FT_UInt     y_res;
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   /*                                                                       */
485   FT_EXPORT( FT_Error )
486   FTC_Manager_LookupSize( FTC_Manager  manager,
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 )
507   FTC_Node_Unref( FTC_Node     node,
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 )
539   FTC_Manager_RemoveFaceID( FTC_Manager  manager,
540                             FTC_FaceID   face_id );
541
542
543   /*************************************************************************/
544   /*                                                                       */
545   /* <Section>                                                             */
546   /*    cache_subsystem                                                    */
547   /*                                                                       */
548   /*************************************************************************/
549
550   /*************************************************************************
551    *
552    * @type:
553    *   FTC_CMapCache
554    *
555    * @description:
556    *   An opaque handle used to model a charmap cache.  This cache is to
557    *   hold character codes -> glyph indices mappings.
558    *
559    */
560   typedef struct FTC_CMapCacheRec_*  FTC_CMapCache;
561
562
563   /*************************************************************************
564    *
565    * @function:
566    *   FTC_CMapCache_New
567    *
568    * @description:
569    *   Create a new charmap cache.
570    *
571    * @input:
572    *   manager ::
573    *     A handle to the cache manager.
574    *
575    * @output:
576    *   acache ::
577    *     A new cache handle.  NULL in case of error.
578    *
579    * @return:
580    *   FreeType error code.  0~means success.
581    *
582    * @note:
583    *   Like all other caches, this one will be destroyed with the cache
584    *   manager.
585    *
586    */
587   FT_EXPORT( FT_Error )
588   FTC_CMapCache_New( FTC_Manager     manager,
589                      FTC_CMapCache  *acache );
590
591
592   /************************************************************************
593    *
594    * @function:
595    *   FTC_CMapCache_Lookup
596    *
597    * @description:
598    *   Translate a character code into a glyph index, using the charmap
599    *   cache.
600    *
601    * @input:
602    *   cache ::
603    *     A charmap cache handle.
604    *
605    *   face_id ::
606    *     The source face ID.
607    *
608    *   cmap_index ::
609    *     The index of the charmap in the source face.  Any negative value
610    *     means to use the cache @FT_Face's default charmap.
611    *
612    *   char_code ::
613    *     The character code (in the corresponding charmap).
614    *
615    * @return:
616    *    Glyph index.  0~means `no glyph'.
617    *
618    */
619   FT_EXPORT( FT_UInt )
620   FTC_CMapCache_Lookup( FTC_CMapCache  cache,
621                         FTC_FaceID     face_id,
622                         FT_Int         cmap_index,
623                         FT_UInt32      char_code );
624
625
626   /*************************************************************************/
627   /*                                                                       */
628   /* <Section>                                                             */
629   /*    cache_subsystem                                                    */
630   /*                                                                       */
631   /*************************************************************************/
632
633
634   /*************************************************************************/
635   /*************************************************************************/
636   /*************************************************************************/
637   /*****                                                               *****/
638   /*****                       IMAGE CACHE OBJECT                      *****/
639   /*****                                                               *****/
640   /*************************************************************************/
641   /*************************************************************************/
642   /*************************************************************************/
643
644
645   /*************************************************************************
646    *
647    * @struct:
648    *   FTC_ImageTypeRec
649    *
650    * @description:
651    *   A structure used to model the type of images in a glyph cache.
652    *
653    * @fields:
654    *   face_id ::
655    *     The face ID.
656    *
657    *   width ::
658    *     The width in pixels.
659    *
660    *   height ::
661    *     The height in pixels.
662    *
663    *   flags ::
664    *     The load flags, as in @FT_Load_Glyph.
665    *
666    */
667   typedef struct  FTC_ImageTypeRec_
668   {
669     FTC_FaceID  face_id;
670     FT_Int      width;
671     FT_Int      height;
672     FT_Int32    flags;
673
674   } FTC_ImageTypeRec;
675
676
677   /*************************************************************************
678    *
679    * @type:
680    *   FTC_ImageType
681    *
682    * @description:
683    *   A handle to an @FTC_ImageTypeRec structure.
684    *
685    */
686   typedef struct FTC_ImageTypeRec_*  FTC_ImageType;
687
688
689   /* */
690
691
692 #define FTC_IMAGE_TYPE_COMPARE( d1, d2 )      \
693           ( (d1)->face_id == (d2)->face_id && \
694             (d1)->width   == (d2)->width   && \
695             (d1)->flags   == (d2)->flags   )
696
697
698   /*************************************************************************/
699   /*                                                                       */
700   /* <Type>                                                                */
701   /*    FTC_ImageCache                                                     */
702   /*                                                                       */
703   /* <Description>                                                         */
704   /*    A handle to a glyph image cache object.  They are designed to      */
705   /*    hold many distinct glyph images while not exceeding a certain      */
706   /*    memory threshold.                                                  */
707   /*                                                                       */
708   typedef struct FTC_ImageCacheRec_*  FTC_ImageCache;
709
710
711   /*************************************************************************/
712   /*                                                                       */
713   /* <Function>                                                            */
714   /*    FTC_ImageCache_New                                                 */
715   /*                                                                       */
716   /* <Description>                                                         */
717   /*    Create a new glyph image cache.                                    */
718   /*                                                                       */
719   /* <Input>                                                               */
720   /*    manager :: The parent manager for the image cache.                 */
721   /*                                                                       */
722   /* <Output>                                                              */
723   /*    acache  :: A handle to the new glyph image cache object.           */
724   /*                                                                       */
725   /* <Return>                                                              */
726   /*    FreeType error code.  0~means success.                             */
727   /*                                                                       */
728   FT_EXPORT( FT_Error )
729   FTC_ImageCache_New( FTC_Manager      manager,
730                       FTC_ImageCache  *acache );
731
732
733   /*************************************************************************/
734   /*                                                                       */
735   /* <Function>                                                            */
736   /*    FTC_ImageCache_Lookup                                              */
737   /*                                                                       */
738   /* <Description>                                                         */
739   /*    Retrieve a given glyph image from a glyph image cache.             */
740   /*                                                                       */
741   /* <Input>                                                               */
742   /*    cache  :: A handle to the source glyph image cache.                */
743   /*                                                                       */
744   /*    type   :: A pointer to a glyph image type descriptor.              */
745   /*                                                                       */
746   /*    gindex :: The glyph index to retrieve.                             */
747   /*                                                                       */
748   /* <Output>                                                              */
749   /*    aglyph :: The corresponding @FT_Glyph object.  0~in case of        */
750   /*              failure.                                                 */
751   /*                                                                       */
752   /*    anode  :: Used to return the address of of the corresponding cache */
753   /*              node after incrementing its reference count (see note    */
754   /*              below).                                                  */
755   /*                                                                       */
756   /* <Return>                                                              */
757   /*    FreeType error code.  0~means success.                             */
758   /*                                                                       */
759   /* <Note>                                                                */
760   /*    The returned glyph is owned and managed by the glyph image cache.  */
761   /*    Never try to transform or discard it manually!  You can however    */
762   /*    create a copy with @FT_Glyph_Copy and modify the new one.          */
763   /*                                                                       */
764   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
765   /*    node containing the glyph image, after increasing its reference    */
766   /*    count.  This ensures that the node (as well as the @FT_Glyph) will */
767   /*    always be kept in the cache until you call @FTC_Node_Unref to      */
768   /*    `release' it.                                                      */
769   /*                                                                       */
770   /*    If `anode' is NULL, the cache node is left unchanged, which means  */
771   /*    that the @FT_Glyph could be flushed out of the cache on the next   */
772   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
773   /*    is persistent!                                                     */
774   /*                                                                       */
775   FT_EXPORT( FT_Error )
776   FTC_ImageCache_Lookup( FTC_ImageCache  cache,
777                          FTC_ImageType   type,
778                          FT_UInt         gindex,
779                          FT_Glyph       *aglyph,
780                          FTC_Node       *anode );
781
782
783   /*************************************************************************/
784   /*                                                                       */
785   /* <Function>                                                            */
786   /*    FTC_ImageCache_LookupScaler                                        */
787   /*                                                                       */
788   /* <Description>                                                         */
789   /*    A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec    */
790   /*    to specify the face ID and its size.                               */
791   /*                                                                       */
792   /* <Input>                                                               */
793   /*    cache      :: A handle to the source glyph image cache.            */
794   /*                                                                       */
795   /*    scaler     :: A pointer to a scaler descriptor.                    */
796   /*                                                                       */
797   /*    load_flags :: The corresponding load flags.                        */
798   /*                                                                       */
799   /*    gindex     :: The glyph index to retrieve.                         */
800   /*                                                                       */
801   /* <Output>                                                              */
802   /*    aglyph     :: The corresponding @FT_Glyph object.  0~in case of    */
803   /*                  failure.                                             */
804   /*                                                                       */
805   /*    anode      :: Used to return the address of of the corresponding   */
806   /*                  cache node after incrementing its reference count    */
807   /*                  (see note below).                                    */
808   /*                                                                       */
809   /* <Return>                                                              */
810   /*    FreeType error code.  0~means success.                             */
811   /*                                                                       */
812   /* <Note>                                                                */
813   /*    The returned glyph is owned and managed by the glyph image cache.  */
814   /*    Never try to transform or discard it manually!  You can however    */
815   /*    create a copy with @FT_Glyph_Copy and modify the new one.          */
816   /*                                                                       */
817   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
818   /*    node containing the glyph image, after increasing its reference    */
819   /*    count.  This ensures that the node (as well as the @FT_Glyph) will */
820   /*    always be kept in the cache until you call @FTC_Node_Unref to      */
821   /*    `release' it.                                                      */
822   /*                                                                       */
823   /*    If `anode' is NULL, the cache node is left unchanged, which means  */
824   /*    that the @FT_Glyph could be flushed out of the cache on the next   */
825   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
826   /*    is persistent!                                                     */
827   /*                                                                       */
828   /*    Calls to @FT_Set_Char_Size and friends have no effect on cached    */
829   /*    glyphs; you should always use the FreeType cache API instead.      */
830   /*                                                                       */
831   FT_EXPORT( FT_Error )
832   FTC_ImageCache_LookupScaler( FTC_ImageCache  cache,
833                                FTC_Scaler      scaler,
834                                FT_ULong        load_flags,
835                                FT_UInt         gindex,
836                                FT_Glyph       *aglyph,
837                                FTC_Node       *anode );
838
839
840   /*************************************************************************/
841   /*                                                                       */
842   /* <Type>                                                                */
843   /*    FTC_SBit                                                           */
844   /*                                                                       */
845   /* <Description>                                                         */
846   /*    A handle to a small bitmap descriptor.  See the @FTC_SBitRec       */
847   /*    structure for details.                                             */
848   /*                                                                       */
849   typedef struct FTC_SBitRec_*  FTC_SBit;
850
851
852   /*************************************************************************/
853   /*                                                                       */
854   /* <Struct>                                                              */
855   /*    FTC_SBitRec                                                        */
856   /*                                                                       */
857   /* <Description>                                                         */
858   /*    A very compact structure used to describe a small glyph bitmap.    */
859   /*                                                                       */
860   /* <Fields>                                                              */
861   /*    width     :: The bitmap width in pixels.                           */
862   /*                                                                       */
863   /*    height    :: The bitmap height in pixels.                          */
864   /*                                                                       */
865   /*    left      :: The horizontal distance from the pen position to the  */
866   /*                 left bitmap border (a.k.a. `left side bearing', or    */
867   /*                 `lsb').                                               */
868   /*                                                                       */
869   /*    top       :: The vertical distance from the pen position (on the   */
870   /*                 baseline) to the upper bitmap border (a.k.a. `top     */
871   /*                 side bearing').  The distance is positive for upwards */
872   /*                 y~coordinates.                                        */
873   /*                                                                       */
874   /*    format    :: The format of the glyph bitmap (monochrome or gray).  */
875   /*                                                                       */
876   /*    max_grays :: Maximum gray level value (in the range 1 to~255).     */
877   /*                                                                       */
878   /*    pitch     :: The number of bytes per bitmap line.  May be positive */
879   /*                 or negative.                                          */
880   /*                                                                       */
881   /*    xadvance  :: The horizontal advance width in pixels.               */
882   /*                                                                       */
883   /*    yadvance  :: The vertical advance height in pixels.                */
884   /*                                                                       */
885   /*    buffer    :: A pointer to the bitmap pixels.                       */
886   /*                                                                       */
887   typedef struct  FTC_SBitRec_
888   {
889     FT_Byte   width;
890     FT_Byte   height;
891     FT_Char   left;
892     FT_Char   top;
893
894     FT_Byte   format;
895     FT_Byte   max_grays;
896     FT_Short  pitch;
897     FT_Char   xadvance;
898     FT_Char   yadvance;
899
900     FT_Byte*  buffer;
901
902   } FTC_SBitRec;
903
904
905   /*************************************************************************/
906   /*                                                                       */
907   /* <Type>                                                                */
908   /*    FTC_SBitCache                                                      */
909   /*                                                                       */
910   /* <Description>                                                         */
911   /*    A handle to a small bitmap cache.  These are special cache objects */
912   /*    used to store small glyph bitmaps (and anti-aliased pixmaps) in a  */
913   /*    much more efficient way than the traditional glyph image cache     */
914   /*    implemented by @FTC_ImageCache.                                    */
915   /*                                                                       */
916   typedef struct FTC_SBitCacheRec_*  FTC_SBitCache;
917
918
919   /*************************************************************************/
920   /*                                                                       */
921   /* <Function>                                                            */
922   /*    FTC_SBitCache_New                                                  */
923   /*                                                                       */
924   /* <Description>                                                         */
925   /*    Create a new cache to store small glyph bitmaps.                   */
926   /*                                                                       */
927   /* <Input>                                                               */
928   /*    manager :: A handle to the source cache manager.                   */
929   /*                                                                       */
930   /* <Output>                                                              */
931   /*    acache  :: A handle to the new sbit cache.  NULL in case of error. */
932   /*                                                                       */
933   /* <Return>                                                              */
934   /*    FreeType error code.  0~means success.                             */
935   /*                                                                       */
936   FT_EXPORT( FT_Error )
937   FTC_SBitCache_New( FTC_Manager     manager,
938                      FTC_SBitCache  *acache );
939
940
941   /*************************************************************************/
942   /*                                                                       */
943   /* <Function>                                                            */
944   /*    FTC_SBitCache_Lookup                                               */
945   /*                                                                       */
946   /* <Description>                                                         */
947   /*    Look up a given small glyph bitmap in a given sbit cache and       */
948   /*    `lock' it to prevent its flushing from the cache until needed.     */
949   /*                                                                       */
950   /* <Input>                                                               */
951   /*    cache  :: A handle to the source sbit cache.                       */
952   /*                                                                       */
953   /*    type   :: A pointer to the glyph image type descriptor.            */
954   /*                                                                       */
955   /*    gindex :: The glyph index.                                         */
956   /*                                                                       */
957   /* <Output>                                                              */
958   /*    sbit   :: A handle to a small bitmap descriptor.                   */
959   /*                                                                       */
960   /*    anode  :: Used to return the address of of the corresponding cache */
961   /*              node after incrementing its reference count (see note    */
962   /*              below).                                                  */
963   /*                                                                       */
964   /* <Return>                                                              */
965   /*    FreeType error code.  0~means success.                             */
966   /*                                                                       */
967   /* <Note>                                                                */
968   /*    The small bitmap descriptor and its bit buffer are owned by the    */
969   /*    cache and should never be freed by the application.  They might    */
970   /*    as well disappear from memory on the next cache lookup, so don't   */
971   /*    treat them as persistent data.                                     */
972   /*                                                                       */
973   /*    The descriptor's `buffer' field is set to~0 to indicate a missing  */
974   /*    glyph bitmap.                                                      */
975   /*                                                                       */
976   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
977   /*    node containing the bitmap, after increasing its reference count.  */
978   /*    This ensures that the node (as well as the image) will always be   */
979   /*    kept in the cache until you call @FTC_Node_Unref to `release' it.  */
980   /*                                                                       */
981   /*    If `anode' is NULL, the cache node is left unchanged, which means  */
982   /*    that the bitmap could be flushed out of the cache on the next      */
983   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
984   /*    is persistent!                                                     */
985   /*                                                                       */
986   FT_EXPORT( FT_Error )
987   FTC_SBitCache_Lookup( FTC_SBitCache    cache,
988                         FTC_ImageType    type,
989                         FT_UInt          gindex,
990                         FTC_SBit        *sbit,
991                         FTC_Node        *anode );
992
993
994   /*************************************************************************/
995   /*                                                                       */
996   /* <Function>                                                            */
997   /*    FTC_SBitCache_LookupScaler                                         */
998   /*                                                                       */
999   /* <Description>                                                         */
1000   /*    A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec     */
1001   /*    to specify the face ID and its size.                               */
1002   /*                                                                       */
1003   /* <Input>                                                               */
1004   /*    cache      :: A handle to the source sbit cache.                   */
1005   /*                                                                       */
1006   /*    scaler     :: A pointer to the scaler descriptor.                  */
1007   /*                                                                       */
1008   /*    load_flags :: The corresponding load flags.                        */
1009   /*                                                                       */
1010   /*    gindex     :: The glyph index.                                     */
1011   /*                                                                       */
1012   /* <Output>                                                              */
1013   /*    sbit       :: A handle to a small bitmap descriptor.               */
1014   /*                                                                       */
1015   /*    anode      :: Used to return the address of of the corresponding   */
1016   /*                  cache node after incrementing its reference count    */
1017   /*                  (see note below).                                    */
1018   /*                                                                       */
1019   /* <Return>                                                              */
1020   /*    FreeType error code.  0~means success.                             */
1021   /*                                                                       */
1022   /* <Note>                                                                */
1023   /*    The small bitmap descriptor and its bit buffer are owned by the    */
1024   /*    cache and should never be freed by the application.  They might    */
1025   /*    as well disappear from memory on the next cache lookup, so don't   */
1026   /*    treat them as persistent data.                                     */
1027   /*                                                                       */
1028   /*    The descriptor's `buffer' field is set to~0 to indicate a missing  */
1029   /*    glyph bitmap.                                                      */
1030   /*                                                                       */
1031   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
1032   /*    node containing the bitmap, after increasing its reference count.  */
1033   /*    This ensures that the node (as well as the image) will always be   */
1034   /*    kept in the cache until you call @FTC_Node_Unref to `release' it.  */
1035   /*                                                                       */
1036   /*    If `anode' is NULL, the cache node is left unchanged, which means  */
1037   /*    that the bitmap could be flushed out of the cache on the next      */
1038   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
1039   /*    is persistent!                                                     */
1040   /*                                                                       */
1041   FT_EXPORT( FT_Error )
1042   FTC_SBitCache_LookupScaler( FTC_SBitCache  cache,
1043                               FTC_Scaler     scaler,
1044                               FT_ULong       load_flags,
1045                               FT_UInt        gindex,
1046                               FTC_SBit      *sbit,
1047                               FTC_Node      *anode );
1048
1049   /* */
1050
1051
1052 FT_END_HEADER
1053
1054 #endif /* __FTCACHE_H__ */
1055
1056
1057 /* END */