kmx git

               The FreeType 2 cache sub-system explained
                        (c) 2000 David Turner

            -----------------------------------------------

Introduction :
--------------

  this document describes the caching sub-system that comes
  with the FreeType library, version 2.0. Note that unlike
  the rest of the library, this code is still in beta stage
  and might still suffer slight changes in the future.

  Its basic design shouldn't evolve though and is explained
  in this paper.


I. Requirements and Design Goals:
---------------------------------

  The FT2 cache sub-system was designed to implement caching
  of glyph images. However, it is extremely flexible and can
  be easily extended to cache other kind of data like metrics,
  character maps, coverage tables, etc..


II. Base Concepts:
------------------

 1. The cache manager object:

   at the heart of the caching sub-system is a single object
   called the "cache manager". It is used to deal with FT_Face
   and FT_Size objects, as well as to manager a LRU list of
   abstract "cache nodes".

   a. caching FT_Face and FT_Size objects:

     each FT_Face object created by FreeType 2 can take from
     a few hundred bytes to several tens of kilobytes, depending
     on the original font's file format as well as its content.

     there is no easy way to compute the size of a given FT_Face
     object, so it's always a good idea to assume that it is
     large and to want to limit the number of live face objects
     as much as possible.

     similarly, each FT_Face can have one or more FT_Size childs,
     whose byte size depends heavily on the font format.

     the first purpose of the cache manager is to provide a
     small cache for FT_Face and FT_Size objects. Basically,
     an application can use it as follows:

       - each font face is described to the cache manager
         through a typeless pointer, called a FTC_FaceID.

         the cache manager itself doesn't interpret or use
         the value of FTC_FaceIDs directly. Rather, it passes
         them to a user-provided function called a
         "face requester". see the defintion of the
         FTC_Face_Requester type in <freetype/ftcache.h>
         for details..

         the face requester is in charge of translating a given
         face into into a real new FT_Face object that is
         returned to the cache manager. The latter will keep
         the face object alive as long as it needs to.

         the face requester is unique and must be passed
         to the function named FTC_Manager_New used to
         create/initialise a new cache manager.


       - to lookup a given FT_Face, call the function
         FTC_Manager_Lookup_Face as in the following code:

              FTC_Manager_Lookup_Face( manager,
                                       face_id,
                                       &face );

         if the corresponding FT_Face object is kept in
         the cache manager's list, it will be returned
         directly. Otherwise, this function will call
         the user-provided face requester to create
         a new FT_Face object, add it to the manager's
         list to finally return it.

         FT_Face objects are always destroyed by the cache
         manager. An application that uses the cache
         sub-system should never call FT_Done_Face !!

       - to lookup a given FT_Size and FT_Face, call the
         function FTC_Manager_Lookup_Size, as in:

              FTC_Manager_Lookup_Size( manager,
                                       ftc_font,
                                       &face,
                                       &size );

         where "ftc_font" is a pointer to a FTC_Font descriptor
         (a structure containing a FTC_FaceIDs and character
          dimensions corresponding to the desired FT_Size).

         note that the function returns both a FT_Face and
         a FT_Size object. You don't need to call
         FTC_Manager_Lookup_Face before it !!

         also note that returned FT_Size objects are always
         destroyed by the cache manager. A client application
         that uses it should never call FT_Done_Size !!


     the big advantage of using FTC_FaceIDs is that is
     makes the caching sub-system completely independent
     of the way font files are installed / listed / managed
     in your application. In most implementations, a FTC_FaceID
     is really a pointer to an application-specific structure
     that describe the source font file + face index.


    b - manage a MRU list of abstract "cache nodes":

     the second role of the cache manager is to hold and manager
     a list of abstract "cache nodes". The list is always sorted
     in most-recently-used order. The manager always ensure that
     the total size of nodes in memory doesn't over-reach a
     certain threshold, by eliminating "old" nodes when
     necessary.

     the cache manager doesn't know much about the cache nodes:

       - it knows how to move them in its list
       - it knows how to destroy them when they're too old
       - it knows how to "size" them (i.e. compute their byte
         size in memory)


 2. Cache objects:

   the cache manager doesn't create new cache nodes however, this
   is the charge of what are called "cache objects".

   Basically, each cache object is in charge of managing cache
   nodes of a certain type. Its role is to:

     - provide a simple description of its cache nodes to the
       manager (i.e. through a FTC_CacheNode_Class structure)

     - provide a high-level API that can be called by client
       applications to lookup cache nodes of the corresponding
       type.

       this function usually creates new nodes when they're not
       available yet.

     - also, and even though this is completely transparent to
       the applications and the cache manager, each cache object
       manages "node sets", where each set contains cache nodes
       usually correspond to the same font face + font size.


   For example, the cache sub-system currently comes with two
   distinct cache classes:

     - a FTC_Image_Cache, which is used to cache FT_Glyph images
       (with one FT_Glyph per cache node).


     - a FTC_SBit_Cache, which is used to cache small glyph bitmaps
       ("sbit" means "embedded bitmaps" in digital typography).


   the small bitmaps glyph is useful because storing one glyph
   image per cache node isn't memory efficient when the data
   associated to each node is very small. Indeed, each cache
   node has a minimal size of 20 bytes, which is huge when
   your data is an 8x8 monochrome bitmap :-)

   Hence, a FTC_SBit_Cache is capable of storing several
   contiguous sbits in a single cache node, resulting in much
   higher cached glyphs / total cache size.

   an application can lookup a FT_Glyph image with a FTC_Image_Cache
   by calling:

        error = FTC_Image_Cache_Lookup( image_cache,
                                        ftc_font,
                                        glyph_index,
                                        &ft_glyph );

   or a FTC_SBit (small bitmap descriptor) by calling:

       error = FTC_SBit_Cache_Lookup( sbit_cache,
                                      ftc_font,
                                      glyph_index,
                                      &ftc_sbit );

III. Extending the cache sub-system:

 It is possible to extend the current cache sub-system by
 providing your own cache class and register it in the cache
 manager. That might be useful to cache other kind of data
 in the sub-system, like glyph metrics (without images),
   
 To do it, you'll need to read the cache sub-system public
 header files rather heavily :-) Fortunately, they're pretty
 well commented and should guide you to your goal.

 Note that the cache sub-system already provides two "abstract
 cache" classes that can be re-used by your own implementation:


 1. The abstract "FTC_GlyphCache" class:

   this code is used to implement an abstract "glyph cache",
   i.e. one that simply maps one glyph data per cache node.

   it is sub-classed by FTC_Image_Cache, whose implementation
   only consists in simple code to store a FT_Glyph in each
   cache node.

   you could sub-class it in your application to store glyph
   images in a different format, for example.

   see the files <freetype/cache/ftcglyph.h> and
   "src/cache/ftcglyph.h" for details.


 2. The abstract "FTC_ChunkCache" class:

   this code is used to implement an abstract "glyph chunk cache".
   it's very similar to a FTC_GlyphCache, except that it is capable
   of storing several glyph-specific elements per cache node.

   it is sub-classed by FTC_SBit_Cache, whose implementation
   only consists in code to store a FTC_SBitRec record in each
   node element.

   you could sub-class it in your application to store small
   glyph data, like metrics, glyph names, wathever.

   see the files <freetype/cache/ftcchunk.h> and
   "src/cache/ftcchunk.h" for details..


  Note that the two abstract caches are rather complex because
  they use "glyph sets". Each glyph set corresponds to a single
  font face + font size combination. both caches are also
  glyph-specific, though it is perfectly possible to use
  broader selection criterion, here are a few examples:

    - caching language coverage maps corresponding to
      a given font face + language combination

    - caching charmaps, layout tables, and other global
      data..

    - caching (font_face + font_size) specific "latin1"
      ascender + descender


  as you can see, a lot is possible with this design :-)
kc3-lang/freetype/docs/cache/cache.txt

Commit

docs/cache/cache.txt
