libraries/freetype-2.0.5/include/freetype/ftcache.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftcache.h                                                              */
   4 /*                                                                         */
   5 /*    FreeType Cache subsystem.                                            */
   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   /*************************************************************************/
  61
  62
  63   /*************************************************************************/
  64   /*************************************************************************/
  65   /*************************************************************************/
  66   /*****                                                               *****/
  67   /*****                    BASIC TYPE DEFINITIONS                     *****/
  68   /*****                                                               *****/
  69   /*************************************************************************/
  70   /*************************************************************************/
  71   /*************************************************************************/
  72
  73
  74   /*************************************************************************/
  75   /*                                                                       */
  76   /* <Type>                                                                */
  77   /*    FTC_FaceID                                                         */
  78   /*                                                                       */
  79   /* <Description>                                                         */
  80   /*    A generic pointer type that is used to identity face objects.  The */
  81   /*    contents of such objects is application-dependent.                 */
  82   /*                                                                       */
  83   typedef FT_Pointer  FTC_FaceID;
  84
  85
  86   /*************************************************************************/
  87   /*                                                                       */
  88   /* <FuncType>                                                            */
  89   /*    FTC_Face_Requester                                                 */
  90   /*                                                                       */
  91   /* <Description>                                                         */
  92   /*    A callback function provided by client applications.  It is used   */
  93   /*    to translate a given FTC_FaceID into a new valid FT_Face object.   */
  94   /*                                                                       */
  95   /* <Input>                                                               */
  96   /*    face_id :: The face ID to resolve.                                 */
  97   /*                                                                       */
  98   /*    library :: A handle to a FreeType library object.                  */
  99   /*                                                                       */
 100   /*    data    :: Application-provided request data.                      */
 101   /*                                                                       */
 102   /* <Output>                                                              */
 103   /*    aface   :: A new FT_Face handle.                                   */
 104   /*                                                                       */
 105   /* <Return>                                                              */
 106   /*    FreeType error code.  0 means success.                             */
 107   /*                                                                       */
 108   /* <Note>                                                                */
 109   /*    The face requester should not perform funny things on the returned */
 110   /*    face object, like creating a new FT_Size for it, or setting a      */
 111   /*    transformation through FT_Set_Transform()!                         */
 112   /*                                                                       */
 113   typedef FT_Error
 114   (*FTC_Face_Requester)( FTC_FaceID  face_id,
 115                          FT_Library  library,
 116                          FT_Pointer  request_data,
 117                          FT_Face*    aface );
 118
 119
 120   /*************************************************************************/
 121   /*                                                                       */
 122   /* <Struct>                                                              */
 123   /*    FTC_FontRec                                                        */
 124   /*                                                                       */
 125   /* <Description>                                                         */
 126   /*    A simple structure used to describe a given `font' to the cache    */
 127   /*    manager.  Note that a `font' is the combination of a given face    */
 128   /*    with a given character size.                                       */
 129   /*                                                                       */
 130   /* <Fields>                                                              */
 131   /*    face_id    :: The ID of the face to use.                           */
 132   /*                                                                       */
 133   /*    pix_width  :: The character width in integer pixels.               */
 134   /*                                                                       */
 135   /*    pix_height :: The character height in integer pixels.              */
 136   /*                                                                       */
 137   typedef struct  FTC_FontRec_
 138   {
 139     FTC_FaceID  face_id;
 140     FT_UShort   pix_width;
 141     FT_UShort   pix_height;
 142
 143   } FTC_FontRec;
 144
 145
 146   /*************************************************************************/
 147   /*                                                                       */
 148   /* <Type>                                                                */
 149   /*    FTC_Font                                                           */
 150   /*                                                                       */
 151   /* <Description>                                                         */
 152   /*    A simple handle to a FTC_FontRec structure.                        */
 153   /*                                                                       */
 154   typedef FTC_FontRec*  FTC_Font;
 155
 156
 157   /*************************************************************************/
 158   /*************************************************************************/
 159   /*************************************************************************/
 160   /*****                                                               *****/
 161   /*****                      CACHE MANAGER OBJECT                     *****/
 162   /*****                                                               *****/
 163   /*************************************************************************/
 164   /*************************************************************************/
 165   /*************************************************************************/
 166
 167
 168   /*************************************************************************/
 169   /*                                                                       */
 170   /* <Type>                                                                */
 171   /*    FTC_Manager                                                        */
 172   /*                                                                       */
 173   /* <Description>                                                         */
 174   /*    This object is used to cache one or more FT_Face objects, along    */
 175   /*    with corresponding FT_Size objects.                                */
 176   /*                                                                       */
 177   typedef struct FTC_ManagerRec_*  FTC_Manager;
 178
 179
 180   /*************************************************************************/
 181   /*                                                                       */
 182   /* <Function>                                                            */
 183   /*    FTC_Manager_New                                                    */
 184   /*                                                                       */
 185   /* <Description>                                                         */
 186   /*    Creates a new cache manager.                                       */
 187   /*                                                                       */
 188   /* <Input>                                                               */
 189   /*    library   :: The parent FreeType library handle to use.            */
 190   /*                                                                       */
 191   /*    max_faces :: Maximum number of faces to keep alive in manager.     */
 192   /*                 Use 0 for defaults.                                   */
 193   /*                                                                       */
 194   /*    max_sizes :: Maximum number of sizes to keep alive in manager.     */
 195   /*                 Use 0 for defaults.                                   */
 196   /*                                                                       */
 197   /*    max_bytes :: Maximum number of bytes to use for cached data.       */
 198   /*                 Use 0 for defaults.                                   */
 199   /*                                                                       */
 200   /*    requester :: An application-provided callback used to translate    */
 201   /*                 face IDs into real FT_Face objects.                   */
 202   /*                                                                       */
 203   /*    req_data  :: A generic pointer that is passed to the requester     */
 204   /*                 each time it is called (see FTC_Face_Requester)       */
 205   /*                                                                       */
 206   /* <Output>                                                              */
 207   /*    amanager  :: A handle to a new manager object.  0 in case of       */
 208   /*                 failure.                                              */
 209   /*                                                                       */
 210   /* <Return>                                                              */
 211   /*    FreeType error code.  0 means success.                             */
 212   /*                                                                       */
 213   FT_EXPORT( FT_Error )
 214   FTC_Manager_New( FT_Library          library,
 215                    FT_UInt             max_faces,
 216                    FT_UInt             max_sizes,
 217                    FT_ULong            max_bytes,
 218                    FTC_Face_Requester  requester,
 219                    FT_Pointer          req_data,
 220                    FTC_Manager        *amanager );
 221
 222
 223   /*************************************************************************/
 224   /*                                                                       */
 225   /* <Function>                                                            */
 226   /*    FTC_Manager_Reset                                                  */
 227   /*                                                                       */
 228   /* <Description>                                                         */
 229   /*    Empties a given cache manager.  This simply gets rid of all the    */
 230   /*    currently cached FT_Face & FT_Size objects within the manager.     */
 231   /*                                                                       */
 232   /* <InOut>                                                               */
 233   /*    manager :: A handle to the manager.                                */
 234   /*                                                                       */
 235   FT_EXPORT( void )
 236   FTC_Manager_Reset( FTC_Manager  manager );
 237
 238
 239   /*************************************************************************/
 240   /*                                                                       */
 241   /* <Function>                                                            */
 242   /*    FTC_Manager_Done                                                   */
 243   /*                                                                       */
 244   /* <Description>                                                         */
 245   /*    Destroys a given manager after emptying it.                        */
 246   /*                                                                       */
 247   /* <Input>                                                               */
 248   /*    manager :: A handle to the target cache manager object.            */
 249   /*                                                                       */
 250   FT_EXPORT( void )
 251   FTC_Manager_Done( FTC_Manager  manager );
 252
 253
 254   /*************************************************************************/
 255   /*                                                                       */
 256   /* <Function>                                                            */
 257   /*    FTC_Manager_Lookup_Face                                            */
 258   /*                                                                       */
 259   /* <Description>                                                         */
 260   /*    Retrieves the FT_Face object that corresponds to a given face ID   */
 261   /*    through a cache manager.                                           */
 262   /*                                                                       */
 263   /* <Input>                                                               */
 264   /*    manager :: A handle to the cache manager.                          */
 265   /*                                                                       */
 266   /*    face_id :: The ID of the face object.                              */
 267   /*                                                                       */
 268   /* <Output>                                                              */
 269   /*    aface   :: A handle to the face object.                            */
 270   /*                                                                       */
 271   /* <Return>                                                              */
 272   /*    FreeType error code.  0 means success.                             */
 273   /*                                                                       */
 274   /* <Note>                                                                */
 275   /*    The returned FT_Face object is always owned by the manager.  You   */
 276   /*    should never try to discard it yourself.                           */
 277   /*                                                                       */
 278   /*    The FT_Face object doesn't necessarily have a current size object  */
 279   /*    (i.e., face->size can be 0).  If you need a specific `font size',  */
 280   /*    use FTC_Manager_Lookup_Size() instead.                             */
 281   /*                                                                       */
 282   /*    Never change the face's transformation matrix (i.e., never call    */
 283   /*    the FT_Set_Transform() function) on a returned face!  If you need  */
 284   /*    to transform glyphs, do it yourself after glyph loading.           */
 285   /*                                                                       */
 286   FT_EXPORT( FT_Error )
 287   FTC_Manager_Lookup_Face( FTC_Manager  manager,
 288                            FTC_FaceID   face_id,
 289                            FT_Face     *aface );
 290
 291
 292   /*************************************************************************/
 293   /*                                                                       */
 294   /* <Function>                                                            */
 295   /*    FTC_Manager_Lookup_Size                                            */
 296   /*                                                                       */
 297   /* <Description>                                                         */
 298   /*    Retrieves the FT_Face & FT_Size objects that correspond to a given */
 299   /*    FTC_SizeID.                                                        */
 300   /*                                                                       */
 301   /* <Input>                                                               */
 302   /*    manager :: A handle to the cache manager.                          */
 303   /*                                                                       */
 304   /*    size_id :: The ID of the `font size' to use.                       */
 305   /*                                                                       */
 306   /* <Output>                                                              */
 307   /*    aface   :: A pointer to the handle of the face object.  Set it to  */
 308   /*               zero if you don't need it.                              */
 309   /*                                                                       */
 310   /*    asize   :: A pointer to the handle of the size object.  Set it to  */
 311   /*               zero if you don't need it.                              */
 312   /*                                                                       */
 313   /* <Return>                                                              */
 314   /*    FreeType error code.  0 means success.                             */
 315   /*                                                                       */
 316   /* <Note>                                                                */
 317   /*    The returned FT_Face object is always owned by the manager.  You   */
 318   /*    should never try to discard it yourself.                           */
 319   /*                                                                       */
 320   /*    Never change the face's transformation matrix (i.e., never call    */
 321   /*    the FT_Set_Transform() function) on a returned face!  If you need  */
 322   /*    to transform glyphs, do it yourself after glyph loading.           */
 323   /*                                                                       */
 324   /*    Similarly, the returned FT_Size object is always owned by the      */
 325   /*    manager.  You should never try to discard it, and never change its */
 326   /*    settings with FT_Set_Pixel_Sizes() or FT_Set_Char_Size()!          */
 327   /*                                                                       */
 328   /*    The returned size object is the face's current size, which means   */
 329   /*    that you can call FT_Load_Glyph() with the face if you need to.    */
 330   /*                                                                       */
 331   FT_EXPORT( FT_Error )
 332   FTC_Manager_Lookup_Size( FTC_Manager  manager,
 333                            FTC_Font     font,
 334                            FT_Face     *aface,
 335                            FT_Size     *asize );
 336
 337
 338   /* a cache class is used to describe a unique cache type to the manager */
 339   typedef struct FTC_Cache_Class_  FTC_Cache_Class;
 340   typedef struct FTC_CacheRec_*    FTC_Cache;
 341
 342
 343   /* this must be used internally for the moment */
 344   FT_EXPORT( FT_Error )
 345   FTC_Manager_Register_Cache( FTC_Manager       manager,
 346                               FTC_Cache_Class*  clazz,
 347                               FTC_Cache        *acache );
 348
 349
 350   /* */
 351
 352
 353 FT_END_HEADER
 354
 355 #endif /* __FTCACHE_H__ */
 356
 357
 358 /* END */