source: trunk/poppler/freetype2/include/freetype/ftcache.h @ 274

Last change on this file since 274 was 262, checked in by Eugene Romanenko, 13 years ago

PDF plugin: freetype library updated to version 2.3.8

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