lib/freetype/include/freetype/ftcache.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftcache.h                                                              */
   4 /*                                                                         */
   5 /*    FreeType Cache subsystem (specification).                            */
   6 /*                                                                         */
   7 /*  Copyright 1996-2001 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   /*   stile in beta.                                                      */
  59   /*                                                                       */
  60   /* <Order>                                                               */
  61   /*   FTC_Manager                                                         */
  62   /*   FTC_FaceID                                                          */
  63   /*   FTC_Face_Requester                                                  */
  64   /*                                                                       */
  65   /*   FTC_Manager_New                                                     */
  66   /*   FTC_Manager_Lookup_Face                                             */
  67   /*   FTC_Manager_Lookup_Size                                             */
  68   /*                                                                       */
  69   /*   FTC_Node                                                            */
  70   /*   FTC_Node_Ref                                                        */
  71   /*   FTC_Node_Unref                                                      */
  72   /*                                                                       */
  73   /*   FTC_Font                                                            */
  74   /*   FTC_ImageDesc                                                       */
  75   /*   FTC_ImageCache                                                      */
  76   /*   FTC_ImageCache_New                                                  */
  77   /*   FTC_ImageCache_Lookup                                               */
  78   /*                                                                       */
  79   /*   FTC_SBit                                                            */
  80   /*   FTC_SBitCache                                                       */
  81   /*   FTC_SBitCache_New                                                   */
  82   /*   FTC_SBitCache_Lookup                                                */
  83   /*                                                                       */
  84   /*                                                                       */
  85   /*   FTC_Image_Desc                                                      */
  86   /*   FTC_Image_Cache                                                     */
  87   /*   FTC_Image_Cache_Lookup                                              */
  88   /*                                                                       */
  89   /*   FTC_SBit_Cache                                                      */
  90   /*   FTC_SBit_Cache_Lookup                                               */
  91   /*                                                                       */
  92   /*************************************************************************/
  93
  94
  95   /*************************************************************************/
  96   /*************************************************************************/
  97   /*************************************************************************/
  98   /*****                                                               *****/
  99   /*****                    BASIC TYPE DEFINITIONS                     *****/
 100   /*****                                                               *****/
 101   /*************************************************************************/
 102   /*************************************************************************/
 103   /*************************************************************************/
 104
 105
 106   /*************************************************************************/
 107   /*                                                                       */
 108   /* <Type>                                                                */
 109   /*    FTC_FaceID                                                         */
 110   /*                                                                       */
 111   /* <Description>                                                         */
 112   /*    A generic pointer type that is used to identity face objects.  The */
 113   /*    contents of such objects is application-dependent.                 */
 114   /*                                                                       */
 115   typedef FT_Pointer  FTC_FaceID;
 116
 117
 118   /*************************************************************************/
 119   /*                                                                       */
 120   /* <FuncType>                                                            */
 121   /*    FTC_Face_Requester                                                 */
 122   /*                                                                       */
 123   /* <Description>                                                         */
 124   /*    A callback function provided by client applications.  It is used   */
 125   /*    to translate a given @FTC_FaceID into a new valid @FT_Face object. */
 126   /*                                                                       */
 127   /* <Input>                                                               */
 128   /*    face_id :: The face ID to resolve.                                 */
 129   /*                                                                       */
 130   /*    library :: A handle to a FreeType library object.                  */
 131   /*                                                                       */
 132   /*    data    :: Application-provided request data.                      */
 133   /*                                                                       */
 134   /* <Output>                                                              */
 135   /*    aface   :: A new @FT_Face handle.                                  */
 136   /*                                                                       */
 137   /* <Return>                                                              */
 138   /*    FreeType error code.  0 means success.                             */
 139   /*                                                                       */
 140   /* <Note>                                                                */
 141   /*    The face requester should not perform funny things on the returned */
 142   /*    face object, like creating a new @FT_Size for it, or setting a     */
 143   /*    transformation through @FT_Set_Transform!                          */
 144   /*                                                                       */
 145   typedef FT_Error
 146   (*FTC_Face_Requester)( FTC_FaceID  face_id,
 147                          FT_Library  library,
 148                          FT_Pointer  request_data,
 149                          FT_Face*    aface );
 150
 151
 152   /*************************************************************************/
 153   /*                                                                       */
 154   /* <Struct>                                                              */
 155   /*    FTC_FontRec                                                        */
 156   /*                                                                       */
 157   /* <Description>                                                         */
 158   /*    A simple structure used to describe a given `font' to the cache    */
 159   /*    manager.  Note that a `font' is the combination of a given face    */
 160   /*    with a given character size.                                       */
 161   /*                                                                       */
 162   /* <Fields>                                                              */
 163   /*    face_id    :: The ID of the face to use.                           */
 164   /*                                                                       */
 165   /*    pix_width  :: The character width in integer pixels.               */
 166   /*                                                                       */
 167   /*    pix_height :: The character height in integer pixels.              */
 168   /*                                                                       */
 169   typedef struct  FTC_FontRec_
 170   {
 171     FTC_FaceID  face_id;
 172     FT_UShort   pix_width;
 173     FT_UShort   pix_height;
 174
 175   } FTC_FontRec;
 176
 177
 178   /* */
 179
 180
 181 #define FTC_FONT_COMPARE( f1, f2 )                  \
 182           ( (f1)->face_id    == (f2)->face_id    && \
 183             (f1)->pix_width  == (f2)->pix_width  && \
 184             (f1)->pix_height == (f2)->pix_height )
 185
 186 #define FT_POINTER_TO_ULONG( p )  ((FT_ULong)(FT_Pointer)(p))
 187
 188 #define FTC_FACE_ID_HASH( i )                              \
 189           ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \
 190                        ( FT_POINTER_TO_ULONG( i ) << 7 ) ) )
 191
 192 #define FTC_FONT_HASH( f )                              \
 193           (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \
 194                        ((f)->pix_width << 8)          ^ \
 195                        ((f)->pix_height)              )
 196
 197
 198   /*************************************************************************/
 199   /*                                                                       */
 200   /* <Type>                                                                */
 201   /*    FTC_Font                                                           */
 202   /*                                                                       */
 203   /* <Description>                                                         */
 204   /*    A simple handle to an @FTC_FontRec structure.                      */
 205   /*                                                                       */
 206   typedef FTC_FontRec*  FTC_Font;
 207
 208
 209   /*************************************************************************/
 210   /*************************************************************************/
 211   /*************************************************************************/
 212   /*****                                                               *****/
 213   /*****                      CACHE MANAGER OBJECT                     *****/
 214   /*****                                                               *****/
 215   /*************************************************************************/
 216   /*************************************************************************/
 217   /*************************************************************************/
 218
 219
 220   /*************************************************************************/
 221   /*                                                                       */
 222   /* <Type>                                                                */
 223   /*    FTC_Manager                                                        */
 224   /*                                                                       */
 225   /* <Description>                                                         */
 226   /*    This object is used to cache one or more @FT_Face objects, along   */
 227   /*    with corresponding @FT_Size objects.                               */
 228   /*                                                                       */
 229   typedef struct FTC_ManagerRec_*  FTC_Manager;
 230
 231
 232   /*************************************************************************/
 233   /*                                                                       */
 234   /* <Type>                                                                */
 235   /*    FTC_Node                                                           */
 236   /*                                                                       */
 237   /* <Description>                                                         */
 238   /*    An opaque handle to a cache node object.  Each cache node is       */
 239   /*    reference-counted.  A node with a count of 0 might be flushed      */
 240   /*    out of a full cache whenever a lookup request is performed.        */
 241   /*                                                                       */
 242   /*    If you lookup nodes, you have the ability to "acquire" them, i.e., */
 243   /*    to increment their reference count.  This will prevent the node    */
 244   /*    from being flushed out of the cache until you explicitly "release" */
 245   /*    it (see @FTC_Node_Release).                                        */
 246   /*                                                                       */
 247   /*    See also @FTC_BitsetCache_Lookup and @FTC_ImageCache_Lookup.       */
 248   /*                                                                       */
 249   typedef struct FTC_NodeRec_*  FTC_Node;
 250
 251
 252   /*************************************************************************/
 253   /*                                                                       */
 254   /* <Function>                                                            */
 255   /*    FTC_Manager_New                                                    */
 256   /*                                                                       */
 257   /* <Description>                                                         */
 258   /*    Creates a new cache manager.                                       */
 259   /*                                                                       */
 260   /* <Input>                                                               */
 261   /*    library   :: The parent FreeType library handle to use.            */
 262   /*                                                                       */
 263   /*    max_faces :: Maximum number of faces to keep alive in manager.     */
 264   /*                 Use 0 for defaults.                                   */
 265   /*                                                                       */
 266   /*    max_sizes :: Maximum number of sizes to keep alive in manager.     */
 267   /*                 Use 0 for defaults.                                   */
 268   /*                                                                       */
 269   /*    max_bytes :: Maximum number of bytes to use for cached data.       */
 270   /*                 Use 0 for defaults.                                   */
 271   /*                                                                       */
 272   /*    requester :: An application-provided callback used to translate    */
 273   /*                 face IDs into real @FT_Face objects.                  */
 274   /*                                                                       */
 275   /*    req_data  :: A generic pointer that is passed to the requester     */
 276   /*                 each time it is called (see @FTC_Face_Requester).     */
 277   /*                                                                       */
 278   /* <Output>                                                              */
 279   /*    amanager  :: A handle to a new manager object.  0 in case of       */
 280   /*                 failure.                                              */
 281   /*                                                                       */
 282   /* <Return>                                                              */
 283   /*    FreeType error code.  0 means success.                             */
 284   /*                                                                       */
 285   FT_EXPORT( FT_Error )
 286   FTC_Manager_New( FT_Library          library,
 287                    FT_UInt             max_faces,
 288                    FT_UInt             max_sizes,
 289                    FT_ULong            max_bytes,
 290                    FTC_Face_Requester  requester,
 291                    FT_Pointer          req_data,
 292                    FTC_Manager        *amanager );
 293
 294
 295   /*************************************************************************/
 296   /*                                                                       */
 297   /* <Function>                                                            */
 298   /*    FTC_Manager_Reset                                                  */
 299   /*                                                                       */
 300   /* <Description>                                                         */
 301   /*    Empties a given cache manager.  This simply gets rid of all the    */
 302   /*    currently cached @FT_Face and @FT_Size objects within the manager. */
 303   /*                                                                       */
 304   /* <InOut>                                                               */
 305   /*    manager :: A handle to the manager.                                */
 306   /*                                                                       */
 307   FT_EXPORT( void )
 308   FTC_Manager_Reset( FTC_Manager  manager );
 309
 310
 311   /*************************************************************************/
 312   /*                                                                       */
 313   /* <Function>                                                            */
 314   /*    FTC_Manager_Done                                                   */
 315   /*                                                                       */
 316   /* <Description>                                                         */
 317   /*    Destroys a given manager after emptying it.                        */
 318   /*                                                                       */
 319   /* <Input>                                                               */
 320   /*    manager :: A handle to the target cache manager object.            */
 321   /*                                                                       */
 322   FT_EXPORT( void )
 323   FTC_Manager_Done( FTC_Manager  manager );
 324
 325
 326   /*************************************************************************/
 327   /*                                                                       */
 328   /* <Function>                                                            */
 329   /*    FTC_Manager_Lookup_Face                                            */
 330   /*                                                                       */
 331   /* <Description>                                                         */
 332   /*    Retrieves the @FT_Face object that corresponds to a given face ID  */
 333   /*    through a cache manager.                                           */
 334   /*                                                                       */
 335   /* <Input>                                                               */
 336   /*    manager :: A handle to the cache manager.                          */
 337   /*                                                                       */
 338   /*    face_id :: The ID of the face object.                              */
 339   /*                                                                       */
 340   /* <Output>                                                              */
 341   /*    aface   :: A handle to the face object.                            */
 342   /*                                                                       */
 343   /* <Return>                                                              */
 344   /*    FreeType error code.  0 means success.                             */
 345   /*                                                                       */
 346   /* <Note>                                                                */
 347   /*    The returned @FT_Face object is always owned by the manager.  You  */
 348   /*    should never try to discard it yourself.                           */
 349   /*                                                                       */
 350   /*    The @FT_Face object doesn't necessarily have a current size object */
 351   /*    (i.e., face->size can be 0).  If you need a specific `font size',  */
 352   /*    use @FTC_Manager_Lookup_Size instead.                              */
 353   /*                                                                       */
 354   /*    Never change the face's transformation matrix (i.e., never call    */
 355   /*    the @FT_Set_Transform function) on a returned face!  If you need   */
 356   /*    to transform glyphs, do it yourself after glyph loading.           */
 357   /*                                                                       */
 358   FT_EXPORT( FT_Error )
 359   FTC_Manager_Lookup_Face( FTC_Manager  manager,
 360                            FTC_FaceID   face_id,
 361                            FT_Face     *aface );
 362
 363
 364   /*************************************************************************/
 365   /*                                                                       */
 366   /* <Function>                                                            */
 367   /*    FTC_Manager_Lookup_Size                                            */
 368   /*                                                                       */
 369   /* <Description>                                                         */
 370   /*    Retrieves the @FT_Face and @FT_Size objects that correspond to a   */
 371   /*    given @FTC_SizeID.                                                 */
 372   /*                                                                       */
 373   /* <Input>                                                               */
 374   /*    manager :: A handle to the cache manager.                          */
 375   /*                                                                       */
 376   /*    size_id :: The ID of the `font size' to use.                       */
 377   /*                                                                       */
 378   /* <Output>                                                              */
 379   /*    aface   :: A pointer to the handle of the face object.  Set it to  */
 380   /*               zero if you don't need it.                              */
 381   /*                                                                       */
 382   /*    asize   :: A pointer to the handle of the size object.  Set it to  */
 383   /*               zero if you don't need it.                              */
 384   /*                                                                       */
 385   /* <Return>                                                              */
 386   /*    FreeType error code.  0 means success.                             */
 387   /*                                                                       */
 388   /* <Note>                                                                */
 389   /*    The returned @FT_Face object is always owned by the manager.  You  */
 390   /*    should never try to discard it yourself.                           */
 391   /*                                                                       */
 392   /*    Never change the face's transformation matrix (i.e., never call    */
 393   /*    the @FT_Set_Transform function) on a returned face!  If you need   */
 394   /*    to transform glyphs, do it yourself after glyph loading.           */
 395   /*                                                                       */
 396   /*    Similarly, the returned @FT_Size object is always owned by the     */
 397   /*    manager.  You should never try to discard it, and never change its */
 398   /*    settings with @FT_Set_Pixel_Sizes or @FT_Set_Char_Size!            */
 399   /*                                                                       */
 400   /*    The returned size object is the face's current size, which means   */
 401   /*    that you can call @FT_Load_Glyph with the face if you need to.     */
 402   /*                                                                       */
 403   FT_EXPORT( FT_Error )
 404   FTC_Manager_Lookup_Size( FTC_Manager  manager,
 405                            FTC_Font     font,
 406                            FT_Face     *aface,
 407                            FT_Size     *asize );
 408
 409
 410 FT_END_HEADER
 411
 412 #endif /* __FTCACHE_H__ */
 413
 414
 415 /* END */