git.sesse.net Git - casparcg/blob - SFML-1.6/extlibs/headers/freetype/ftcache.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftcache.h                                                              */
   4 /*                                                                         */
   5 /*    FreeType Cache subsystem (specification).                            */
   6 /*                                                                         */
   7 /*  Copyright 1996-2001, 2002, 2003, 2004 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   /*************************************************************************/
  20   /*************************************************************************/
  21   /*************************************************************************/
  22   /*************************************************************************/
  23   /*************************************************************************/
  24   /*********                                                       *********/
  25   /*********             WARNING, THIS IS BETA CODE.               *********/
  26   /*********                                                       *********/
  27   /*************************************************************************/
  28   /*************************************************************************/
  29   /*************************************************************************/
  30   /*************************************************************************/
  31   /*************************************************************************/
  32
  33
  34 #ifndef __FTCACHE_H__
  35 #define __FTCACHE_H__
  36
  37
  38 #include <ft2build.h>
  39 #include FT_GLYPH_H
  40
  41
  42 FT_BEGIN_HEADER
  43
  44
  45   /*************************************************************************/
  46   /*                                                                       */
  47   /* <Section>                                                             */
  48   /*    cache_subsystem                                                    */
  49   /*                                                                       */
  50   /* <Title>                                                               */
  51   /*    Cache Sub-System                                                   */
  52   /*                                                                       */
  53   /* <Abstract>                                                            */
  54   /*    How to cache face, size, and glyph data with FreeType 2.           */
  55   /*                                                                       */
  56   /* <Description>                                                         */
  57   /*   This section describes the FreeType 2 cache sub-system which is     */
  58   /*   still in beta.                                                      */
  59   /*                                                                       */
  60   /* <Order>                                                               */
  61   /*   FTC_Manager                                                         */
  62   /*   FTC_FaceID                                                          */
  63   /*   FTC_Face_Requester                                                  */
  64   /*                                                                       */
  65   /*   FTC_Manager_New                                                     */
  66   /*   FTC_Manager_Reset                                                   */
  67   /*   FTC_Manager_Done                                                    */
  68   /*   FTC_Manager_LookupFace                                              */
  69   /*   FTC_Manager_LookupSize                                              */
  70   /*   FTC_Manager_RemoveFaceID                                            */
  71   /*                                                                       */
  72   /*   FTC_Node                                                            */
  73   /*   FTC_Node_Unref                                                      */
  74   /*                                                                       */
  75   /*   FTC_Font                                                            */
  76   /*   FTC_ImageCache                                                      */
  77   /*   FTC_ImageCache_New                                                  */
  78   /*   FTC_ImageCache_Lookup                                               */
  79   /*                                                                       */
  80   /*   FTC_SBit                                                            */
  81   /*   FTC_SBitCache                                                       */
  82   /*   FTC_SBitCache_New                                                   */
  83   /*   FTC_SBitCache_Lookup                                                */
  84   /*                                                                       */
  85   /*   FTC_CMapCache                                                       */
  86   /*   FTC_CMapCache_New                                                   */
  87   /*   FTC_CMapCache_Lookup                                                */
  88   /*                                                                       */
  89   /*************************************************************************/
  90
  91
  92   /*************************************************************************/
  93   /*************************************************************************/
  94   /*************************************************************************/
  95   /*****                                                               *****/
  96   /*****                    BASIC TYPE DEFINITIONS                     *****/
  97   /*****                                                               *****/
  98   /*************************************************************************/
  99   /*************************************************************************/
 100   /*************************************************************************/
 101
 102
 103   /*************************************************************************/
 104   /*                                                                       */
 105   /* <Type>                                                                */
 106   /*    FTC_FaceID                                                         */
 107   /*                                                                       */
 108   /* <Description>                                                         */
 109   /*    An opaque pointer type that is used to identity face objects.  The */
 110   /*    contents of such objects is application-dependent.                 */
 111   /*                                                                       */
 112   typedef struct FTC_FaceIDRec_*  FTC_FaceID;
 113
 114
 115   /*************************************************************************/
 116   /*                                                                       */
 117   /* <FuncType>                                                            */
 118   /*    FTC_Face_Requester                                                 */
 119   /*                                                                       */
 120   /* <Description>                                                         */
 121   /*    A callback function provided by client applications.  It is used   */
 122   /*    to translate a given @FTC_FaceID into a new valid @FT_Face object. */
 123   /*                                                                       */
 124   /* <Input>                                                               */
 125   /*    face_id :: The face ID to resolve.                                 */
 126   /*                                                                       */
 127   /*    library :: A handle to a FreeType library object.                  */
 128   /*                                                                       */
 129   /*    data    :: Application-provided request data.                      */
 130   /*                                                                       */
 131   /* <Output>                                                              */
 132   /*    aface   :: A new @FT_Face handle.                                  */
 133   /*                                                                       */
 134   /* <Return>                                                              */
 135   /*    FreeType error code.  0 means success.                             */
 136   /*                                                                       */
 137   /* <Note>                                                                */
 138   /*    The face requester should not perform funny things on the returned */
 139   /*    face object, like creating a new @FT_Size for it, or setting a     */
 140   /*    transformation through @FT_Set_Transform!                          */
 141   /*                                                                       */
 142   typedef FT_Error
 143   (*FTC_Face_Requester)( FTC_FaceID  face_id,
 144                          FT_Library  library,
 145                          FT_Pointer  request_data,
 146                          FT_Face*    aface );
 147
 148
 149   /*************************************************************************/
 150   /*                                                                       */
 151   /* <Struct>                                                              */
 152   /*    FTC_FontRec                                                        */
 153   /*                                                                       */
 154   /* <Description>                                                         */
 155   /*    A simple structure used to describe a given `font' to the cache    */
 156   /*    manager.  Note that a `font' is the combination of a given face    */
 157   /*    with a given character size.                                       */
 158   /*                                                                       */
 159   /* <Fields>                                                              */
 160   /*    face_id    :: The ID of the face to use.                           */
 161   /*                                                                       */
 162   /*    pix_width  :: The character width in integer pixels.               */
 163   /*                                                                       */
 164   /*    pix_height :: The character height in integer pixels.              */
 165   /*                                                                       */
 166   typedef struct  FTC_FontRec_
 167   {
 168     FTC_FaceID  face_id;
 169     FT_UShort   pix_width;
 170     FT_UShort   pix_height;
 171
 172   } FTC_FontRec;
 173
 174
 175   /* */
 176
 177
 178 #define FTC_FONT_COMPARE( f1, f2 )                  \
 179           ( (f1)->face_id    == (f2)->face_id    && \
 180             (f1)->pix_width  == (f2)->pix_width  && \
 181             (f1)->pix_height == (f2)->pix_height )
 182
 183 #define FT_POINTER_TO_ULONG( p )  ((FT_ULong)(FT_Pointer)(p))
 184
 185 #define FTC_FACE_ID_HASH( i )                              \
 186           ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \
 187                        ( FT_POINTER_TO_ULONG( i ) << 7 ) ) )
 188
 189 #define FTC_FONT_HASH( f )                              \
 190           (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \
 191                        ((f)->pix_width << 8)          ^ \
 192                        ((f)->pix_height)              )
 193
 194
 195   /*************************************************************************/
 196   /*                                                                       */
 197   /* <Type>                                                                */
 198   /*    FTC_Font                                                           */
 199   /*                                                                       */
 200   /* <Description>                                                         */
 201   /*    A simple handle to an @FTC_FontRec structure.                      */
 202   /*                                                                       */
 203   typedef FTC_FontRec*  FTC_Font;
 204
 205
 206   /*************************************************************************/
 207   /*************************************************************************/
 208   /*************************************************************************/
 209   /*****                                                               *****/
 210   /*****                      CACHE MANAGER OBJECT                     *****/
 211   /*****                                                               *****/
 212   /*************************************************************************/
 213   /*************************************************************************/
 214   /*************************************************************************/
 215
 216
 217   /*************************************************************************/
 218   /*                                                                       */
 219   /* <Type>                                                                */
 220   /*    FTC_Manager                                                        */
 221   /*                                                                       */
 222   /* <Description>                                                         */
 223   /*    This object is used to cache one or more @FT_Face objects, along   */
 224   /*    with corresponding @FT_Size objects.                               */
 225   /*                                                                       */
 226   typedef struct FTC_ManagerRec_*  FTC_Manager;
 227
 228
 229   /*************************************************************************/
 230   /*                                                                       */
 231   /* <Type>                                                                */
 232   /*    FTC_Node                                                           */
 233   /*                                                                       */
 234   /* <Description>                                                         */
 235   /*    An opaque handle to a cache node object.  Each cache node is       */
 236   /*    reference-counted.  A node with a count of 0 might be flushed      */
 237   /*    out of a full cache whenever a lookup request is performed.        */
 238   /*                                                                       */
 239   /*    If you lookup nodes, you have the ability to "acquire" them, i.e., */
 240   /*    to increment their reference count.  This will prevent the node    */
 241   /*    from being flushed out of the cache until you explicitly "release" */
 242   /*    it (see @FTC_Node_Unref).                                          */
 243   /*                                                                       */
 244   /*    See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup.         */
 245   /*                                                                       */
 246   typedef struct FTC_NodeRec_*  FTC_Node;
 247
 248
 249   /*************************************************************************/
 250   /*                                                                       */
 251   /* <Function>                                                            */
 252   /*    FTC_Manager_New                                                    */
 253   /*                                                                       */
 254   /* <Description>                                                         */
 255   /*    Creates a new cache manager.                                       */
 256   /*                                                                       */
 257   /* <Input>                                                               */
 258   /*    library     :: The parent FreeType library handle to use.          */
 259   /*                                                                       */
 260   /*    max_bytes   :: Maximum number of bytes to use for cached data.     */
 261   /*                   Use 0 for defaults.                                 */
 262   /*                                                                       */
 263   /*    requester   :: An application-provided callback used to translate  */
 264   /*                   face IDs into real @FT_Face objects.                */
 265   /*                                                                       */
 266   /*    req_data    :: A generic pointer that is passed to the requester   */
 267   /*                   each time it is called (see @FTC_Face_Requester).   */
 268   /*                                                                       */
 269   /* <Output>                                                              */
 270   /*    amanager  :: A handle to a new manager object.  0 in case of       */
 271   /*                 failure.                                              */
 272   /*                                                                       */
 273   /* <Return>                                                              */
 274   /*    FreeType error code.  0 means success.                             */
 275   /*                                                                       */
 276   FT_EXPORT( FT_Error )
 277   FTC_Manager_New( FT_Library          library,
 278                    FT_UInt             max_faces,
 279                    FT_UInt             max_sizes,
 280                    FT_ULong            max_bytes,
 281                    FTC_Face_Requester  requester,
 282                    FT_Pointer          req_data,
 283                    FTC_Manager        *amanager );
 284
 285
 286   /*************************************************************************/
 287   /*                                                                       */
 288   /* <Function>                                                            */
 289   /*    FTC_Manager_Reset                                                  */
 290   /*                                                                       */
 291   /* <Description>                                                         */
 292   /*    Empties a given cache manager.  This simply gets rid of all the    */
 293   /*    currently cached @FT_Face and @FT_Size objects within the manager. */
 294   /*                                                                       */
 295   /* <InOut>                                                               */
 296   /*    manager :: A handle to the manager.                                */
 297   /*                                                                       */
 298   FT_EXPORT( void )
 299   FTC_Manager_Reset( FTC_Manager  manager );
 300
 301
 302   /*************************************************************************/
 303   /*                                                                       */
 304   /* <Function>                                                            */
 305   /*    FTC_Manager_Done                                                   */
 306   /*                                                                       */
 307   /* <Description>                                                         */
 308   /*    Destroys a given manager after emptying it.                        */
 309   /*                                                                       */
 310   /* <Input>                                                               */
 311   /*    manager :: A handle to the target cache manager object.            */
 312   /*                                                                       */
 313   FT_EXPORT( void )
 314   FTC_Manager_Done( FTC_Manager  manager );
 315
 316
 317   /*************************************************************************/
 318   /*                                                                       */
 319   /* <Function>                                                            */
 320   /*    FTC_Manager_LookupFace                                             */
 321   /*                                                                       */
 322   /* <Description>                                                         */
 323   /*    Retrieves the @FT_Face object that corresponds to a given face ID  */
 324   /*    through a cache manager.                                           */
 325   /*                                                                       */
 326   /* <Input>                                                               */
 327   /*    manager :: A handle to the cache manager.                          */
 328   /*                                                                       */
 329   /*    face_id :: The ID of the face object.                              */
 330   /*                                                                       */
 331   /* <Output>                                                              */
 332   /*    aface   :: A handle to the face object.                            */
 333   /*                                                                       */
 334   /* <Return>                                                              */
 335   /*    FreeType error code.  0 means success.                             */
 336   /*                                                                       */
 337   /* <Note>                                                                */
 338   /*    The returned @FT_Face object is always owned by the manager.  You  */
 339   /*    should never try to discard it yourself.                           */
 340   /*                                                                       */
 341   /*    The @FT_Face object doesn't necessarily have a current size object */
 342   /*    (i.e., face->size can be 0).  If you need a specific `font size',  */
 343   /*    use @FTC_Manager_LookupSize instead.                               */
 344   /*                                                                       */
 345   /*    Never change the face's transformation matrix (i.e., never call    */
 346   /*    the @FT_Set_Transform function) on a returned face!  If you need   */
 347   /*    to transform glyphs, do it yourself after glyph loading.           */
 348   /*                                                                       */
 349   FT_EXPORT( FT_Error )
 350   FTC_Manager_LookupFace( FTC_Manager  manager,
 351                           FTC_FaceID   face_id,
 352                           FT_Face     *aface );
 353
 354
 355   /*************************************************************************/
 356   /*                                                                       */
 357   /* <Struct>                                                              */
 358   /*    FTC_ScalerRec                                                      */
 359   /*                                                                       */
 360   /* <Description>                                                         */
 361   /*    A structure used to describe a given character size in either      */
 362   /*    pixels or points to the cache manager.  See                        */
 363   /*    @FTC_Manager_LookupSize.                                           */
 364   /*                                                                       */
 365   /* <Fields>                                                              */
 366   /*    face_id :: The source face ID.                                     */
 367   /*                                                                       */
 368   /*    width   :: The character width.                                    */
 369   /*                                                                       */
 370   /*    height  :: The character height.                                   */
 371   /*                                                                       */
 372   /*    pixel   :: A Boolean.  If TRUE, the `width' and `height' fields    */
 373   /*               are interpreted as integer pixel character sizes.       */
 374   /*               Otherwise, they are expressed as 1/64th of points.      */
 375   /*                                                                       */
 376   /*    x_res   :: Only used when `pixel' is FALSE to indicate the         */
 377   /*               horizontal resolution in dpi.                           */
 378   /*                                                                       */
 379   /*    y_res   :: Only used when `pixel' is FALSE to indicate the         */
 380   /*               vertical resolution in dpi.                             */
 381   /*                                                                       */
 382   /* <Note>                                                                */
 383   /*    This type is mainly used to retrieve @FT_Size objects through the  */
 384   /*    cache manager.                                                     */
 385   /*                                                                       */
 386   typedef struct  FTC_ScalerRec_
 387   {
 388     FTC_FaceID  face_id;
 389     FT_UInt     width;
 390     FT_UInt     height;
 391     FT_Int      pixel;
 392     FT_UInt     x_res;
 393     FT_UInt     y_res;
 394
 395   } FTC_ScalerRec, *FTC_Scaler;
 396
 397
 398   /*************************************************************************/
 399   /*                                                                       */
 400   /* <Function>                                                            */
 401   /*    FTC_Manager_LookupSize                                             */
 402   /*                                                                       */
 403   /* <Description>                                                         */
 404   /*    Retrieve the @FT_Size object that corresponds to a given           */
 405   /*    @FTC_Scaler through a cache manager.                               */
 406   /*                                                                       */
 407   /* <Input>                                                               */
 408   /*    manager :: A handle to the cache manager.                          */
 409   /*                                                                       */
 410   /*    scaler  :: A scaler handle.                                        */
 411   /*                                                                       */
 412   /* <Output>                                                              */
 413   /*    asize   :: A handle to the size object.                            */
 414   /*                                                                       */
 415   /* <Return>                                                              */
 416   /*    FreeType error code.  0 means success.                             */
 417   /*                                                                       */
 418   /* <Note>                                                                */
 419   /*    The returned @FT_Size object is always owned by the manager.  You  */
 420   /*    should never try to discard it by yourself.                        */
 421   /*                                                                       */
 422   /*    You can access the parent @FT_Face object simply as `size->face'   */
 423   /*    if you need it.  Note that this object is also owned by the        */
 424   /*    manager.                                                           */
 425   /*                                                                       */
 426   FT_EXPORT( FT_Error )
 427   FTC_Manager_LookupSize( FTC_Manager  manager,
 428                           FTC_Scaler   scaler,
 429                           FT_Size     *asize );
 430
 431
 432   /*************************************************************************/
 433   /*                                                                       */
 434   /* <Function>                                                            */
 435   /*    FTC_Node_Unref                                                     */
 436   /*                                                                       */
 437   /* <Description>                                                         */
 438   /*    Decrement a cache node's internal reference count.  When the count */
 439   /*    reaches 0, it is not destroyed but becomes eligible for subsequent */
 440   /*    cache flushes.                                                     */
 441   /*                                                                       */
 442   /* <Input>                                                               */
 443   /*    node    :: The cache node handle.                                  */
 444   /*                                                                       */
 445   /*    manager :: The cache manager handle.                               */
 446   /*                                                                       */
 447   FT_EXPORT( void )
 448   FTC_Node_Unref( FTC_Node     node,
 449                   FTC_Manager  manager );
 450
 451
 452   /* remove all nodes belonging to a given face_id */
 453   FT_EXPORT( void )
 454   FTC_Manager_RemoveFaceID( FTC_Manager  manager,
 455                             FTC_FaceID   face_id );
 456
 457
 458   /*************************************************************************/
 459   /*                                                                       */
 460   /* <Section>                                                             */
 461   /*    cache_subsystem                                                    */
 462   /*                                                                       */
 463   /*************************************************************************/
 464
 465   /************************************************************************
 466    *
 467    * @type:
 468    *    FTC_CMapCache
 469    *
 470    * @description:
 471    *    An opaque handle used to manager a charmap cache.  This cache is
 472    *    to hold character codes -> glyph indices mappings.
 473    */
 474   typedef struct FTC_CMapCacheRec_*  FTC_CMapCache;
 475
 476
 477   /*************************************************************************/
 478   /*                                                                       */
 479   /* @function:                                                            */
 480   /*    FTC_CMapCache_New                                                  */
 481   /*                                                                       */
 482   /* @description:                                                         */
 483   /*    Create a new charmap cache.                                        */
 484   /*                                                                       */
 485   /* @input:                                                               */
 486   /*    manager :: A handle to the cache manager.                          */
 487   /*                                                                       */
 488   /* @output:                                                              */
 489   /*    acache  :: A new cache handle.  NULL in case of error.             */
 490   /*                                                                       */
 491   /* @return:                                                              */
 492   /*    FreeType error code.  0 means success.                             */
 493   /*                                                                       */
 494   /* @note:                                                                */
 495   /*    Like all other caches, this one will be destroyed with the cache   */
 496   /*    manager.                                                           */
 497   /*                                                                       */
 498   FT_EXPORT( FT_Error )
 499   FTC_CMapCache_New( FTC_Manager     manager,
 500                      FTC_CMapCache  *acache );
 501
 502
 503   /*************************************************************************/
 504   /*                                                                       */
 505   /* @function:                                                            */
 506   /*    FTC_CMapCache_Lookup                                               */
 507   /*                                                                       */
 508   /* @description:                                                         */
 509   /*    Translate a character code into a glyph index, using the charmap   */
 510   /*    cache.                                                             */
 511   /*                                                                       */
 512   /* @input:                                                               */
 513   /*    cache      :: A charmap cache handle.                              */
 514   /*                                                                       */
 515   /*    face_id    :: The source face ID.                                  */
 516   /*                                                                       */
 517   /*    cmap_index :: The index of the charmap in the source face.         */
 518   /*                                                                       */
 519   /*    char_code  :: The character code (in the corresponding charmap).   */
 520   /*                                                                       */
 521   /* @return:                                                              */
 522   /*    Glyph index.  0 means `no glyph'.                                  */
 523   /*                                                                       */
 524   FT_EXPORT( FT_UInt )
 525   FTC_CMapCache_Lookup( FTC_CMapCache  cache,
 526                         FTC_FaceID     face_id,
 527                         FT_Int         cmap_index,
 528                         FT_UInt32      char_code );
 529
 530
 531   /*************************************************************************/
 532   /*                                                                       */
 533   /* <Section>                                                             */
 534   /*    cache_subsystem                                                    */
 535   /*                                                                       */
 536   /*************************************************************************/
 537
 538
 539   /*************************************************************************/
 540   /*************************************************************************/
 541   /*************************************************************************/
 542   /*****                                                               *****/
 543   /*****                       IMAGE CACHE OBJECT                      *****/
 544   /*****                                                               *****/
 545   /*************************************************************************/
 546   /*************************************************************************/
 547   /*************************************************************************/
 548
 549   typedef struct  FTC_ImageTypeRec_
 550   {
 551     FTC_FaceID   face_id;
 552     FT_Int       width;
 553     FT_Int       height;
 554     FT_Int32     flags;
 555
 556   } FTC_ImageTypeRec;
 557
 558   typedef struct FTC_ImageTypeRec_*   FTC_ImageType;
 559
 560  /* */
 561
 562 #define FTC_IMAGE_TYPE_COMPARE( d1, d2 )                    \
 563           ( FTC_FONT_COMPARE( &(d1)->font, &(d2)->font ) && \
 564             (d1)->flags == (d2)->flags                   )
 565
 566 #define FTC_IMAGE_TYPE_HASH( d )                    \
 567           (FT_UFast)( FTC_FONT_HASH( &(d)->font ) ^ \
 568                       ( (d)->flags << 4 )         )
 569
 570
 571   /*************************************************************************/
 572   /*                                                                       */
 573   /* <Type>                                                                */
 574   /*    FTC_ImageCache                                                     */
 575   /*                                                                       */
 576   /* <Description>                                                         */
 577   /*    A handle to an glyph image cache object.  They are designed to     */
 578   /*    hold many distinct glyph images while not exceeding a certain      */
 579   /*    memory threshold.                                                  */
 580   /*                                                                       */
 581   typedef struct FTC_ImageCacheRec_*  FTC_ImageCache;
 582
 583
 584   /*************************************************************************/
 585   /*                                                                       */
 586   /* <Function>                                                            */
 587   /*    FTC_ImageCache_New                                                 */
 588   /*                                                                       */
 589   /* <Description>                                                         */
 590   /*    Creates a new glyph image cache.                                   */
 591   /*                                                                       */
 592   /* <Input>                                                               */
 593   /*    manager :: The parent manager for the image cache.                 */
 594   /*                                                                       */
 595   /* <Output>                                                              */
 596   /*    acache  :: A handle to the new glyph image cache object.           */
 597   /*                                                                       */
 598   /* <Return>                                                              */
 599   /*    FreeType error code.  0 means success.                             */
 600   /*                                                                       */
 601   FT_EXPORT( FT_Error )
 602   FTC_ImageCache_New( FTC_Manager      manager,
 603                       FTC_ImageCache  *acache );
 604
 605
 606   /*************************************************************************/
 607   /*                                                                       */
 608   /* <Function>                                                            */
 609   /*    FTC_ImageCache_Lookup                                              */
 610   /*                                                                       */
 611   /* <Description>                                                         */
 612   /*    Retrieves a given glyph image from a glyph image cache.            */
 613   /*                                                                       */
 614   /* <Input>                                                               */
 615   /*    cache  :: A handle to the source glyph image cache.                */
 616   /*                                                                       */
 617   /*    type   :: A pointer to a glyph image type descriptor.              */
 618   /*                                                                       */
 619   /*    gindex :: The glyph index to retrieve.                             */
 620   /*                                                                       */
 621   /* <Output>                                                              */
 622   /*    aglyph :: The corresponding @FT_Glyph object.  0 in case of        */
 623   /*              failure.                                                 */
 624   /*                                                                       */
 625   /*    anode  :: Used to return the address of of the corresponding cache */
 626   /*              node after incrementing its reference count (see note    */
 627   /*              below).                                                  */
 628   /*                                                                       */
 629   /* <Return>                                                              */
 630   /*    FreeType error code.  0 means success.                             */
 631   /*                                                                       */
 632   /* <Note>                                                                */
 633   /*    The returned glyph is owned and managed by the glyph image cache.  */
 634   /*    Never try to transform or discard it manually!  You can however    */
 635   /*    create a copy with @FT_Glyph_Copy and modify the new one.          */
 636   /*                                                                       */
 637   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
 638   /*    node containing the glyph image, after increasing its reference    */
 639   /*    count.  This ensures that the node (as well as the FT_Glyph) will  */
 640   /*    always be kept in the cache until you call @FTC_Node_Unref to      */
 641   /*    `release' it.                                                      */
 642   /*                                                                       */
 643   /*    If `anode' is NULL, the cache node is left unchanged, which means  */
 644   /*    that the FT_Glyph could be flushed out of the cache on the next    */
 645   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
 646   /*    is persistent!                                                     */
 647   /*                                                                       */
 648   FT_EXPORT( FT_Error )
 649   FTC_ImageCache_Lookup( FTC_ImageCache  cache,
 650                          FTC_ImageType   type,
 651                          FT_UInt         gindex,
 652                          FT_Glyph       *aglyph,
 653                          FTC_Node       *anode );
 654
 655
 656   /*************************************************************************/
 657   /*                                                                       */
 658   /* <Type>                                                                */
 659   /*    FTC_SBit                                                           */
 660   /*                                                                       */
 661   /* <Description>                                                         */
 662   /*    A handle to a small bitmap descriptor.  See the @FTC_SBitRec       */
 663   /*    structure for details.                                             */
 664   /*                                                                       */
 665   typedef struct FTC_SBitRec_*  FTC_SBit;
 666
 667
 668   /*************************************************************************/
 669   /*                                                                       */
 670   /* <Struct>                                                              */
 671   /*    FTC_SBitRec                                                        */
 672   /*                                                                       */
 673   /* <Description>                                                         */
 674   /*    A very compact structure used to describe a small glyph bitmap.    */
 675   /*                                                                       */
 676   /* <Fields>                                                              */
 677   /*    width     :: The bitmap width in pixels.                           */
 678   /*                                                                       */
 679   /*    height    :: The bitmap height in pixels.                          */
 680   /*                                                                       */
 681   /*    left      :: The horizontal distance from the pen position to the  */
 682   /*                 left bitmap border (a.k.a. `left side bearing', or    */
 683   /*                 `lsb').                                               */
 684   /*                                                                       */
 685   /*    top       :: The vertical distance from the pen position (on the   */
 686   /*                 baseline) to the upper bitmap border (a.k.a. `top     */
 687   /*                 side bearing').  The distance is positive for upwards */
 688   /*                 Y coordinates.                                        */
 689   /*                                                                       */
 690   /*    format    :: The format of the glyph bitmap (monochrome or gray).  */
 691   /*                                                                       */
 692   /*    max_grays :: Maximum gray level value (in the range 1 to 255).     */
 693   /*                                                                       */
 694   /*    pitch     :: The number of bytes per bitmap line.  May be positive */
 695   /*                 or negative.                                          */
 696   /*                                                                       */
 697   /*    xadvance  :: The horizontal advance width in pixels.               */
 698   /*                                                                       */
 699   /*    yadvance  :: The vertical advance height in pixels.                */
 700   /*                                                                       */
 701   /*    buffer    :: A pointer to the bitmap pixels.                       */
 702   /*                                                                       */
 703   typedef struct  FTC_SBitRec_
 704   {
 705     FT_Byte   width;
 706     FT_Byte   height;
 707     FT_Char   left;
 708     FT_Char   top;
 709
 710     FT_Byte   format;
 711     FT_Byte   max_grays;
 712     FT_Short  pitch;
 713     FT_Char   xadvance;
 714     FT_Char   yadvance;
 715
 716     FT_Byte*  buffer;
 717
 718   } FTC_SBitRec;
 719
 720
 721   /*************************************************************************/
 722   /*                                                                       */
 723   /* <Type>                                                                */
 724   /*    FTC_SBitCache                                                      */
 725   /*                                                                       */
 726   /* <Description>                                                         */
 727   /*    A handle to a small bitmap cache.  These are special cache objects */
 728   /*    used to store small glyph bitmaps (and anti-aliased pixmaps) in a  */
 729   /*    much more efficient way than the traditional glyph image cache     */
 730   /*    implemented by @FTC_ImageCache.                                    */
 731   /*                                                                       */
 732   typedef struct FTC_SBitCacheRec_*  FTC_SBitCache;
 733
 734
 735   /*************************************************************************/
 736   /*                                                                       */
 737   /* <Function>                                                            */
 738   /*    FTC_SBitCache_New                                                  */
 739   /*                                                                       */
 740   /* <Description>                                                         */
 741   /*    Creates a new cache to store small glyph bitmaps.                  */
 742   /*                                                                       */
 743   /* <Input>                                                               */
 744   /*    manager :: A handle to the source cache manager.                   */
 745   /*                                                                       */
 746   /* <Output>                                                              */
 747   /*    acache  :: A handle to the new sbit cache.  NULL in case of error. */
 748   /*                                                                       */
 749   /* <Return>                                                              */
 750   /*    FreeType error code.  0 means success.                             */
 751   /*                                                                       */
 752   FT_EXPORT( FT_Error )
 753   FTC_SBitCache_New( FTC_Manager     manager,
 754                      FTC_SBitCache  *acache );
 755
 756
 757   /*************************************************************************/
 758   /*                                                                       */
 759   /* <Function>                                                            */
 760   /*    FTC_SBitCache_Lookup                                               */
 761   /*                                                                       */
 762   /* <Description>                                                         */
 763   /*    Looks up a given small glyph bitmap in a given sbit cache and      */
 764   /*    `lock' it to prevent its flushing from the cache until needed.     */
 765   /*                                                                       */
 766   /* <Input>                                                               */
 767   /*    cache  :: A handle to the source sbit cache.                       */
 768   /*                                                                       */
 769   /*    type   :: A pointer to the glyph image type descriptor.            */
 770   /*                                                                       */
 771   /*    gindex :: The glyph index.                                         */
 772   /*                                                                       */
 773   /* <Output>                                                              */
 774   /*    sbit   :: A handle to a small bitmap descriptor.                   */
 775   /*                                                                       */
 776   /*    anode  :: Used to return the address of of the corresponding cache */
 777   /*              node after incrementing its reference count (see note    */
 778   /*              below).                                                  */
 779   /*                                                                       */
 780   /* <Return>                                                              */
 781   /*    FreeType error code.  0 means success.                             */
 782   /*                                                                       */
 783   /* <Note>                                                                */
 784   /*    The small bitmap descriptor and its bit buffer are owned by the    */
 785   /*    cache and should never be freed by the application.  They might    */
 786   /*    as well disappear from memory on the next cache lookup, so don't   */
 787   /*    treat them as persistent data.                                     */
 788   /*                                                                       */
 789   /*    The descriptor's `buffer' field is set to 0 to indicate a missing  */
 790   /*    glyph bitmap.                                                      */
 791   /*                                                                       */
 792   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
 793   /*    node containing the bitmap, after increasing its reference count.  */
 794   /*    This ensures that the node (as well as the image) will always be   */
 795   /*    kept in the cache until you call @FTC_Node_Unref to `release' it.  */
 796   /*                                                                       */
 797   /*    If `anode' is NULL, the cache node is left unchanged, which means  */
 798   /*    that the bitmap could be flushed out of the cache on the next      */
 799   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
 800   /*    is persistent!                                                     */
 801   /*                                                                       */
 802   FT_EXPORT( FT_Error )
 803   FTC_SBitCache_Lookup( FTC_SBitCache    cache,
 804                         FTC_ImageType    type,
 805                         FT_UInt          gindex,
 806                         FTC_SBit        *sbit,
 807                         FTC_Node        *anode );
 808
 809
 810  /* */
 811
 812 FT_END_HEADER
 813
 814 #endif /* __FTCACHE_H__ */
 815
 816
 817 /* END */