src/third_party/freetype2/src/include/freetype/ftcache.h

   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
  27 FT_BEGIN_HEADER
  28
  29
  30   /*************************************************************************
  31    *
  32    * <Section>
  33    *    cache_subsystem
  34    *
  35    * <Title>
  36    *    Cache Sub-System
  37    *
  38    * <Abstract>
  39    *    How to cache face, size, and glyph data with FreeType~2.
  40    *
  41    * <Description>
  42    *   This section describes the FreeType~2 cache sub-system, which is used
  43    *   to limit the number of concurrently opened @FT_Face and @FT_Size
  44    *   objects, as well as caching information like character maps and glyph
  45    *   images while limiting their maximum memory usage.
  46    *
  47    *   Note that all types and functions begin with the `FTC_' prefix.
  48    *
  49    *   The cache is highly portable and thus doesn't know anything about the
  50    *   fonts installed on your system, or how to access them.  This implies
  51    *   the following scheme:
  52    *
  53    *   First, available or installed font faces are uniquely identified by
  54    *   @FTC_FaceID values, provided to the cache by the client.  Note that
  55    *   the cache only stores and compares these values, and doesn't try to
  56    *   interpret them in any way.
  57    *
  58    *   Second, the cache calls, only when needed, a client-provided function
  59    *   to convert an @FTC_FaceID into a new @FT_Face object.  The latter is
  60    *   then completely managed by the cache, including its termination
  61    *   through @FT_Done_Face.  To monitor termination of face objects, the
  62    *   finalizer callback in the `generic' field of the @FT_Face object can
  63    *   be used, which might also be used to store the @FTC_FaceID of the
  64    *   face.
  65    *
  66    *   Clients are free to map face IDs to anything else.  The most simple
  67    *   usage is to associate them to a (pathname,face_index) pair that is
  68    *   used to call @FT_New_Face.  However, more complex schemes are also
  69    *   possible.
  70    *
  71    *   Note that for the cache to work correctly, the face ID values must be
  72    *   *persistent*, which means that the contents they point to should not
  73    *   change at runtime, or that their value should not become invalid.
  74    *
  75    *   If this is unavoidable (e.g., when a font is uninstalled at runtime),
  76    *   you should call @FTC_Manager_RemoveFaceID as soon as possible, to let
  77    *   the cache get rid of any references to the old @FTC_FaceID it may
  78    *   keep internally.  Failure to do so will lead to incorrect behaviour
  79    *   or even crashes.
  80    *
  81    *   To use the cache, start with calling @FTC_Manager_New to create a new
  82    *   @FTC_Manager object, which models a single cache instance.  You can
  83    *   then look up @FT_Face and @FT_Size objects with
  84    *   @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively.
  85    *
  86    *   If you want to use the charmap caching, call @FTC_CMapCache_New, then
  87    *   later use @FTC_CMapCache_Lookup to perform the equivalent of
  88    *   @FT_Get_Char_Index, only much faster.
  89    *
  90    *   If you want to use the @FT_Glyph caching, call @FTC_ImageCache, then
  91    *   later use @FTC_ImageCache_Lookup to retrieve the corresponding
  92    *   @FT_Glyph objects from the cache.
  93    *
  94    *   If you need lots of small bitmaps, it is much more memory efficient
  95    *   to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup.  This
  96    *   returns @FTC_SBitRec structures, which are used to store small
  97    *   bitmaps directly.  (A small bitmap is one whose metrics and
  98    *   dimensions all fit into 8-bit integers).
  99    *
 100    *   We hope to also provide a kerning cache in the near future.
 101    *
 102    *
 103    * <Order>
 104    *   FTC_Manager
 105    *   FTC_FaceID
 106    *   FTC_Face_Requester
 107    *
 108    *   FTC_Manager_New
 109    *   FTC_Manager_Reset
 110    *   FTC_Manager_Done
 111    *   FTC_Manager_LookupFace
 112    *   FTC_Manager_LookupSize
 113    *   FTC_Manager_RemoveFaceID
 114    *
 115    *   FTC_Node
 116    *   FTC_Node_Unref
 117    *
 118    *   FTC_ImageCache
 119    *   FTC_ImageCache_New
 120    *   FTC_ImageCache_Lookup
 121    *
 122    *   FTC_SBit
 123    *   FTC_SBitCache
 124    *   FTC_SBitCache_New
 125    *   FTC_SBitCache_Lookup
 126    *
 127    *   FTC_CMapCache
 128    *   FTC_CMapCache_New
 129    *   FTC_CMapCache_Lookup
 130    *
 131    *************************************************************************/
 132
 133
 134   /*************************************************************************/
 135   /*************************************************************************/
 136   /*************************************************************************/
 137   /*****                                                               *****/
 138   /*****                    BASIC TYPE DEFINITIONS                     *****/
 139   /*****                                                               *****/
 140   /*************************************************************************/
 141   /*************************************************************************/
 142   /*************************************************************************/
 143
 144
 145   /*************************************************************************
 146    *
 147    * @type: FTC_FaceID
 148    *
 149    * @description:
 150    *   An opaque pointer type that is used to identity face objects.  The
 151    *   contents of such objects is application-dependent.
 152    *
 153    *   These pointers are typically used to point to a user-defined
 154    *   structure containing a font file path, and face index.
 155    *
 156    * @note:
 157    *   Never use NULL as a valid @FTC_FaceID.
 158    *
 159    *   Face IDs are passed by the client to the cache manager, 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 the new sbit cache.  NULL in case of error. */
 954   /*                                                                       */
 955   /* <Return>                                                              */
 956   /*    FreeType error code.  0~means success.                             */
 957   /*                                                                       */
 958   FT_EXPORT( FT_Error )
 959   FTC_SBitCache_New( FTC_Manager     manager,
 960                      FTC_SBitCache  *acache );
 961
 962
 963   /*************************************************************************/
 964   /*                                                                       */
 965   /* <Function>                                                            */
 966   /*    FTC_SBitCache_Lookup                                               */
 967   /*                                                                       */
 968   /* <Description>                                                         */
 969   /*    Look up a given small glyph bitmap in a given sbit cache and       */
 970   /*    `lock' it to prevent its flushing from the cache until needed.     */
 971   /*                                                                       */
 972   /* <Input>                                                               */
 973   /*    cache  :: A handle to the source sbit cache.                       */
 974   /*                                                                       */
 975   /*    type   :: A pointer to the glyph image type descriptor.            */
 976   /*                                                                       */
 977   /*    gindex :: The glyph index.                                         */
 978   /*                                                                       */
 979   /* <Output>                                                              */
 980   /*    sbit   :: A handle to a small bitmap descriptor.                   */
 981   /*                                                                       */
 982   /*    anode  :: Used to return the address of of the corresponding cache */
 983   /*              node after incrementing its reference count (see note    */
 984   /*              below).                                                  */
 985   /*                                                                       */
 986   /* <Return>                                                              */
 987   /*    FreeType error code.  0~means success.                             */
 988   /*                                                                       */
 989   /* <Note>                                                                */
 990   /*    The small bitmap descriptor and its bit buffer are owned by the    */
 991   /*    cache and should never be freed by the application.  They might    */
 992   /*    as well disappear from memory on the next cache lookup, so don't   */
 993   /*    treat them as persistent data.                                     */
 994   /*                                                                       */
 995   /*    The descriptor's `buffer' field is set to~0 to indicate a missing  */
 996   /*    glyph bitmap.                                                      */
 997   /*                                                                       */
 998   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
 999   /*    node containing the bitmap, after increasing its reference count.  */
1000   /*    This ensures that the node (as well as the image) will always be   */
1001   /*    kept in the cache until you call @FTC_Node_Unref to `release' it.  */
1002   /*                                                                       */
1003   /*    If `anode' is NULL, the cache node is left unchanged, which means  */
1004   /*    that the bitmap could be flushed out of the cache on the next      */
1005   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
1006   /*    is persistent!                                                     */
1007   /*                                                                       */
1008   FT_EXPORT( FT_Error )
1009   FTC_SBitCache_Lookup( FTC_SBitCache    cache,
1010                         FTC_ImageType    type,
1011                         FT_UInt          gindex,
1012                         FTC_SBit        *sbit,
1013                         FTC_Node        *anode );
1014
1015
1016   /*************************************************************************/
1017   /*                                                                       */
1018   /* <Function>                                                            */
1019   /*    FTC_SBitCache_LookupScaler                                         */
1020   /*                                                                       */
1021   /* <Description>                                                         */
1022   /*    A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec     */
1023   /*    to specify the face ID and its size.                               */
1024   /*                                                                       */
1025   /* <Input>                                                               */
1026   /*    cache      :: A handle to the source sbit cache.                   */
1027   /*                                                                       */
1028   /*    scaler     :: A pointer to the scaler descriptor.                  */
1029   /*                                                                       */
1030   /*    load_flags :: The corresponding load flags.                        */
1031   /*                                                                       */
1032   /*    gindex     :: The glyph index.                                     */
1033   /*                                                                       */
1034   /* <Output>                                                              */
1035   /*    sbit       :: A handle to a small bitmap descriptor.               */
1036   /*                                                                       */
1037   /*    anode      :: Used to return the address of of the corresponding   */
1038   /*                  cache node after incrementing its reference count    */
1039   /*                  (see note below).                                    */
1040   /*                                                                       */
1041   /* <Return>                                                              */
1042   /*    FreeType error code.  0~means success.                             */
1043   /*                                                                       */
1044   /* <Note>                                                                */
1045   /*    The small bitmap descriptor and its bit buffer are owned by the    */
1046   /*    cache and should never be freed by the application.  They might    */
1047   /*    as well disappear from memory on the next cache lookup, so don't   */
1048   /*    treat them as persistent data.                                     */
1049   /*                                                                       */
1050   /*    The descriptor's `buffer' field is set to~0 to indicate a missing  */
1051   /*    glyph bitmap.                                                      */
1052   /*                                                                       */
1053   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
1054   /*    node containing the bitmap, after increasing its reference count.  */
1055   /*    This ensures that the node (as well as the image) will always be   */
1056   /*    kept in the cache until you call @FTC_Node_Unref to `release' it.  */
1057   /*                                                                       */
1058   /*    If `anode' is NULL, the cache node is left unchanged, which means  */
1059   /*    that the bitmap could be flushed out of the cache on the next      */
1060   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
1061   /*    is persistent!                                                     */
1062   /*                                                                       */
1063   FT_EXPORT( FT_Error )
1064   FTC_SBitCache_LookupScaler( FTC_SBitCache  cache,
1065                               FTC_Scaler     scaler,
1066                               FT_ULong       load_flags,
1067                               FT_UInt        gindex,
1068                               FTC_SBit      *sbit,
1069                               FTC_Node      *anode );
1070
1071
1072  /* */
1073
1074 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
1075
1076   /*@***********************************************************************/
1077   /*                                                                       */
1078   /* <Struct>                                                              */
1079   /*    FTC_FontRec                                                        */
1080   /*                                                                       */
1081   /* <Description>                                                         */
1082   /*    A simple structure used to describe a given `font' to the cache    */
1083   /*    manager.  Note that a `font' is the combination of a given face    */
1084   /*    with a given character size.                                       */
1085   /*                                                                       */
1086   /* <Fields>                                                              */
1087   /*    face_id    :: The ID of the face to use.                           */
1088   /*                                                                       */
1089   /*    pix_width  :: The character width in integer pixels.               */
1090   /*                                                                       */
1091   /*    pix_height :: The character height in integer pixels.              */
1092   /*                                                                       */
1093   typedef struct  FTC_FontRec_
1094   {
1095     FTC_FaceID  face_id;
1096     FT_UShort   pix_width;
1097     FT_UShort   pix_height;
1098
1099   } FTC_FontRec;
1100
1101
1102   /* */
1103
1104
1105 #define FTC_FONT_COMPARE( f1, f2 )                  \
1106           ( (f1)->face_id    == (f2)->face_id    && \
1107             (f1)->pix_width  == (f2)->pix_width  && \
1108             (f1)->pix_height == (f2)->pix_height )
1109
1110   /* this macro is incompatible with LLP64, should not be used */
1111 #define FTC_FONT_HASH( f )                              \
1112           (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \
1113                        ((f)->pix_width << 8)          ^ \
1114                        ((f)->pix_height)              )
1115
1116   typedef FTC_FontRec*  FTC_Font;
1117
1118
1119   FT_EXPORT( FT_Error )
1120   FTC_Manager_Lookup_Face( FTC_Manager  manager,
1121                            FTC_FaceID   face_id,
1122                            FT_Face     *aface );
1123
1124   FT_EXPORT( FT_Error )
1125   FTC_Manager_Lookup_Size( FTC_Manager  manager,
1126                            FTC_Font     font,
1127                            FT_Face     *aface,
1128                            FT_Size     *asize );
1129
1130 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */
1131
1132
1133  /* */
1134
1135 FT_END_HEADER
1136
1137 #endif /* __FTCACHE_H__ */
1138
1139
1140 /* END */