FreeType 1.31.1

docs/threads.txt

@@ -0,0 +1,117 @@
+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 ---