PageRenderTime 47ms CodeModel.GetById 21ms app.highlight 18ms RepoModel.GetById 1ms app.codeStats 0ms

/src/freetype/include/freetype/ftcache.h

https://bitbucket.org/cabalistic/ogredeps/
C++ Header | 1140 lines | 158 code | 112 blank | 870 comment | 10 complexity | e59d874da1dab559aebb794a9784a5d3 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

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

Large files files are truncated, but you can click here to view the full file