include/freetype/ftcache.h

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