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 structure, 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 ;-)


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


--- end of threads.txt ---