Threads with FreeType
=====================


The  FreeType  engine  can  now  be compiled  in  thread-safe  mode.
Because  we want  to  keep the  engine  small and  fast, the  thread
protection is simple.   This file gives an overview  of what you can
do, and what you should strictly never do.


How to enable thread-safe support?

A. You  must have a  valid replacement for the  file "lib/ttmutex.c"
   which calls your system's API to create, lock and release mutexes
   or semaphores.  The current implementation is a dummy and doesn't
   do anything.

B. You      must     re-define      the      configuration     macro
   TT_CONFIG_OPTION_THREAD_SAFE   located   in   ttconfig.h.    Then
   recompile.


IMPORTANT NOTE:

  If two threads create and use their own TT_Engine, they can freely
  call  the library concurrently  on each  of them  (as well  as all
  their  related  objects), even  in  the  non-threaded build.   The
  following remarks only apply to concurrent requests performed on a
  single TT_Engine shared by multiple threads.


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

- What you can do:

  With the exceptions listed below (in "What you can't do"), you can
  call all  API functions  concurrently with two  different threads.
  This includes:

    Creating two or more faces from the same engine
    (i.e., concurrent calls to TT_Open_Face()/TT_Open_Collection())

    Creating two or more instances from the same face object
    (i.e., concurrent calls to TT_New_Instance())

    Creating two or more glyph containers from the same face object
    (i.e., concurrent calls to TT_New_Glyph())

    The same holds for destruction of objects.

    Load  two or  more  glyphs  concurrently for  the  same face  or
    instance
    (i.e., concurrent TT_Load_Glyph() calls)

    Render two or more glyphs at the same time, in the same engine
    (i.e., calling TT_Get_Glyph_Bitmap()/TT_Get_Glyph_Pixmap() or 
    TT_Get_Outline_Bitmap()/TT_GetOutline_Pixmap() concurrently)

    NOTE: the  scan-line converter  can only render  one glyph  at a
          time,  for  a   given  TT_Engine.   Concurrent  calls  are
          synchronized through a mutex, though.

          If  you  really, _really_,  need  to  generate bitmaps  or
          pixmaps concurrently, create  an additional engine and use
          it   with  TT_Get_Outline_Bitmap()/TT_Get_Outline_Pixmap()
          (you don't  need to create  any object in it,  the outline
          can come from any source too).

          This is, however, not recommended (it works perfectly, but
          this  could change  in  the future  for various  technical
          reasons).


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

- What you cannot do:

  - You shouldn't try to delete  an object while still using it with
    another thread.  The engine  doesn't protect you from stupidity!
    For example, these concurrent calls:

      TT_Close_Face( face );
      TT_Get_Glyph_Bitmap( glyph, &bitmap );

    will act unexpectedly if the glyph is a child of the face (i.e.,
    was created with TT_New_Glyph( face, &glyph ))
                                   ^^^^
                                 same face

    Here are some other examples:

      TT_Get_Glyph_Outline( glyph1, ... )
      TT_Load_Glyph( instance, glyph1, ... )

    or

      TT_Get_Outline_BBox( outline, &bbox )
      TT_Transform_Outline( outline )

    etc.

    You get the  idea: Only the face and  instances are protected --
    glyph containers and outlines should be thread-specific.


  - You  shouldn't initialize extensions  in an  engine concurrently
    (which is what every mere mortal will do anyway :-)



That's about it. Now enjoy the lib ;-)

- David


PS: See the  'MT-Note' and  'MT-Safe'  remarks  in ttapi.c  for more
    detailed information on each specific function.


--- END ---
